Clone wiki

django-autocomplete / Documentation

Django Autocomplete Documentation


Use pip to install the last development build of Django Autocomplete.

$ pip install django-autocomplete

To install the old version:

$ pip install django-autocomplete==0.3-dev

Configuration of static files

In order to work properly Django Autocomplete needs some static files and assumes you are serving them from settings.AUTOCOMPLETE_MEDIA_PREFIX. In most cases you'll probably want to symlink or copy the files in the autocomplete/media directory to your project's MEDIA_ROOT. However if you want to customize Django Autocomplete you can replace any of these files with your own version:

File nameDescriptionNotes
js/jquery.min.jsjQuery 1.4.2 minified(1)
js/jquery-ui.min.jsjQuery UI 1.8.5 minified(1)
js/jquery_autocomplete.jsThe main javascript file, it provides the ``django.autocomplete()`` function which creates instances of the ``djangoautocomplete`` jQuery widget.(1)
css/jquery-ui.cssStylesheet of the UI Lightness jQuery theme customized with some enhancements for the admin site.
img/\*.pngImages used by the CSS theme.


(1) Strictly required files.

For example, if you copied the static files in your project's media root, your could look like this:

    AUTOCOMPLETE_MEDIA_PREFIX = '/mysite/media/autocomplete/'

Note that you should always put a trailing slash.

How it works

What Django Autocomplete does is quite simple. It defines two new widgets: AutocompleteWidget which is used for ForeignKeys and any other formfield that uses a single input to render itself; and MultipleAutocompleteWidget which is used only for ManyToMany fields. These widgets provide suggestions based on the user's input by doing an ajax call to a remote view (i.e. an autocomplete.views.AutocompleteView) that returns the entries formatted as JSON. A tipical ajax request could be:

In this example, we expect our instance of AutocompleteView to return a JSON list of cities that starts with "Rome":

    [{"id": 1, "value": "Rome", "label": "Rome, Latium, Italy"},
     {"id": 2, ...}, ...]

To generate this list the AutocompleteView checks if there is a settings object (i.e. an instance of AutocompleteSettings) associated with the path "cities" that appears into the url, and if it succeeds it will delegate the rendering to it, otherwise an Http404 will be raised.

This means you have to explicitly map one or more AutocompleteSettings objects to one or more string identifiers. You can accomplish this by calling the register method of AutocompleteView:

autocomplete_instance.register("cities", CitiesSettings)

You must make sure that this code is being executed once by django so the typical place to put this is in your project Alternatively, you can define this in separate module, let say at the same level of your project's and then in the module, import it so it can be executed. An example of this approach can be seen in tests/test_project/testapp directory of django-autocomplete package.

You will then be able to reference your autocomplete settings using their respective id, for example an AutocompleteWidget could be created as follows:

AutocompleteWidget("cities", view=autocomplete_instance)

Choosing the correct AutocompleteView

All the Django Autocomplete widgets require an AutocompleteView for pulling the entries to display.

Django Autocomplete provides a default instance of AutocompleteView to make easy to start using autocompletion on your forms. You can add the default view in your project's URLConf with:

from autocomplete.views import autocomplete

urlpatterns = patterns('',
    url(r'^autocomplete/', include(autocomplete.urls)),
    # ... other urls

It is highly recommended that you include this view only in your *project*'s URLConf, and not in any of your apps, to avoid that the same view is reachable from multiple urls. Just remember that any app in your current project could use the default AutocompleteView instance, so adding it to a specific URLConf wouldn't be appropriate.

In the case you want to distribute an app that uses Django Autocomplete but you don't want to have to tell your users to manually include the default AutocompleteView instance in their project's URLConf, you can easily create a new instance of AutocompleteView and include it in your app's URLConf:

# myapp/
from autocomplete.views import AutocompleteView

autocomplete = AutocompleteView('myapp')

# myapp/
from myapp.views import autocomplete

url('^autocomplete/', include(autocomplete.urls))

Although you shouldn't need it, you can even subclass AutocompleteView, to customize it or add some features. More likely you'll want to subclass AutocompleteSettings since it's here that most of the rendering process takes place.