Source

django-autocomplete / docs / library / widgets.rst

Full commit

:mod:`autocomplete.widgets` AutoCompleteWidget

Just as a Select widget an :class:`AutoCompleteWidget` lets the user select a choice from a dropdown box but Instead of displaying all the choices at once, the :class:`AutoCompleteWidget` requires the user to start typing some characters and then gathers, using javascript, the choices matching the user input from a remote :class:`~autocomplete.views.AutoComplete` view.

Performing smaller queries, instead of a single enormous one to get all the choices at once, significantly reduces the load of the database. Moreover it makes easier to select the right choice, because the user has not to search among a big number of options like it could happen with a Select widget.

To make an :class:`AutoCompleteWidget` work you need to:

Note

To handle relationships between models use :class:`autocomplete.fields.ModelChoiceField`. It is just like a normal ModelChoiceField but uses an :class:`AutoCompleteWidget` (by default) to render its choices.

Configuring the Media files of :class:`AutoCompleteWidget`

By default the :class:`AutoCompleteWidget` uses YUI served from http://yahooapis.com in conjunction with the js/yui_autocomplete.js provided in this package. This to not include directly YUI in Django AutoComplete, and to provide a quickly working setup. This solution, assuming you are serving js/yui_autocomplete.js from your MEDIA_URL, should work in every situation, including the admin application. However in some cases you could need to customize the Media files of the widget. For example, if you are already using YUI in your template and you don't want it to be included twice, or if you wish to use JQuery or any other javascript toolkit [1].

AutoCompleteWidget(your_params)
# uses YUI loaded from http://yahooapis.com and js/yui_autocomplete.js

class CustomYUIACWidget(AutoCompleteWidget):
    """
    This widget uses your version of YUI served directly from your
    MEDIA_URL.
    """
    class Media:
        extend = False
        js = ('js/path/to/yui.js',
              # ...
              # ...
              'js/yui_autocomplete.js')


class CustomJQueryACWidget(AutoCompleteWidget):
    """
    This widget uses files from JQuery 1.4 and JQuery UI 1.8 served from MEDIA_URL.
    """
    class Media:
        extend = False
        css = {'all': ('css/jquery-ui.css',),
               }
        js = (
            'js/jquery.min.js',
            'js/jquery-ui.min.js',
            'js/jquery_autocomplete.js')


class AnyOtherToolkitACWidget(AutoCompleteWidget):
    class Media:
        extend = False
        js = ('js/path/to/your/toolkit.js',
              # ...
              # ...
              'yourtoolkit_autocomplete.js')

Note

Remember to set extend = False in your subclass' Media, otherwise your files will be added to the default ones instead of replacing them.

Footnotes

[1]Currently this package provides only yui_autocomplete.js and jquery_autocomplete.js. If you want to use an other toolkit you will have to make the script yourself.