Quick start: adding simple autocompletes¶
This tutorial guides you through the process of enabling autocomplete for a
simple form. We’ll enable autocompletion for Person
on the form of an
Order
model, i.e. we want to get autocompletion for Person
objects when
we type the person’s first or last name.
For this to work, we have to register an autocomplete for the Person
model.
The autocomplete tells autocomplete-light how to render your autocompletion and
what model fields to search in (like first_name
, last_name
, …).
When we have defined how a Person
autocompletion should look like, we have
to enable it in the Order
form. This is done by modifying the Order
form so that autocomplete-light’s special form fields are used instead of the
ones built into Django. autocomplete-light provides a handy wrapper around
Django’s modelforms which makes this a very easy thing to do.
autocomplete_light.register()
shortcut to generate and register Autocomplete classes¶
Register an Autocomplete for your model in
your_app/autocomplete_light_registry.py
, it can look like this:
import autocomplete_light.shortcuts as al
from models import Person
# This will generate a PersonAutocomplete class.
al.register(Person,
# Just like in ModelAdmin.search_fields.
search_fields=['^first_name', 'last_name'],
attrs={
# This will set the input placeholder attribute:
'placeholder': 'Other model name ?',
# This will set the yourlabs.Autocomplete.minimumCharacters
# options, the naming conversion is handled by jQuery.
'data-autocomplete-minimum-characters': 1,
},
# This will set the data-widget-maximum-values attribute on the
# widget container element, and will be set to
# yourlabs.Widget.maximumValues (jQuery handles the naming
# conversion).
widget_attrs={
'data-widget-maximum-values': 4,
# Enable modern-style widget !
'class': 'modern-style',
},
)
Note
If using Django >= 1.7, you might as well do register()
calls directly in your
AppConfig.ready()
as demonstrated in the example app:
autocomplete_light.example_apps.app_config_without_registry_file
.
AutocompleteView.get()
can proxy
PersonAutocomplete.autocomplete_html()
because PersonAutocomplete
is registered. This means that openning
/autocomplete/PersonAutocomplete/
will call
AutocompleteView.get()
which will in turn call
PersonAutocomplete.autocomplete_html()
.
Also AutocompleteView.post()
would proxy
PersonAutocomplete.post()
if it was defined. It could be useful to build
your own features like on-the-fly object creation using Javascript method
overrides like the remote autocomplete.
Warning
Note that this would make all Person
public. Fine tuning
security is explained later in this tutorial in section Overriding the queryset of a model autocomplete to secure an Autocomplete.
autocomplete_light.register()
generates an Autocomplete class, passing the extra keyword arguments like
AutocompleteModel.search_fields
to the
Python type()
function. This means that extra keyword arguments will
be used as class attributes of the generated class. An equivalent version of
the above code would be:
class PersonAutocomplete(autocomplete_light.AutocompleteModelBase):
search_fields = ['^first_name', 'last_name']
model = Person
autocomplete_light.register(PersonAutocomplete)
Note
If you wanted, you could override the default
AutocompleteModelBase
used by
autocomplete_light.register()
to generate Autocomplete
classes.
It could look like this (in your project’s urls.py
):
autocomplete_light.registry.autocomplete_model_base = YourAutocompleteModelBase
autocomplete_light.autodiscover()
Refer to the Autocomplete classes documentation for details, it is the first chapter of the the reference documentation.
autocomplete_light.modelform_factory()
shortcut to generate ModelForms in the admin¶
First, ensure that scripts are installed in the admin base template.
Then, enabling autocompletes in the admin is as simple as overriding
ModelAdmin.form
in
your_app/admin.py
. You can use the
modelform_factory()
shortcut as
such:
class OrderAdmin(admin.ModelAdmin):
# This will generate a ModelForm
form = autocomplete_light.modelform_factory(Order, fields='__all__')
admin.site.register(Order)
Refer to the Form, fields and widgets documentation for other ways of making forms, it is the second chapter of the the reference documentation.
autocomplete_light.ModelForm
to generate Autocomplete fields, the DRY way¶
First, ensure that scripts are properly installed in your template.
Then, you can use autocomplete_light.ModelForm
to replace automatic
Select
and
SelectMultiple
widgets which renders
<select>
HTML inputs by autocompletion widgets:
class OrderModelForm(autocomplete_light.ModelForm):
class Meta:
model = Order
Note that the first Autocomplete class registered for a model becomes the
default Autocomplete for that model. If you have registered several
Autocomplete classes for a given model, you probably want to use a different
Autocomplete class depending on the form using
Meta.autocomplete_names
:
class OrderModelForm(autocomplete_light.ModelForm):
class Meta:
autocomplete_names = {'company': 'PublicCompanyAutocomplete'}
model = Order
autocomplete_light.ModelForm
respects Meta.fields
and Meta.exclude
. However, you can enable or
disable autocomplete_light.ModelForm
’s behaviour in the same fashion with
Meta.autocomplete_fields
and
Meta.autocomplete_exclude
:
class OrderModelForm(autocomplete_light.ModelForm):
class Meta:
model = Order
# only enable autocompletes on 'person' and 'product' fields
autocomplete_fields = ('person', 'product')
class PersonModelForm(autocomplete_light.ModelForm):
class Meta:
model = Order
# do not make 'category' an autocomplete field
autocomplete_exclude = ('category',)
Also, it will automatically enable autocompletes on generic foreign keys and
generic many to many relations if you have at least one generic Autocomplete
class register (typically an
AutocompleteGenericBase
).
For more documentation, continue reading the reference documentation.