Quick start

The purpose of this documentation is to get you started as fast as possible, because your time matters and you probably have other things to worry about.

Quick install

Install the package:

pip install django-autocomplete-light
# or the development version
pip install -e git+git://github.com/yourlabs/django-autocomplete-light.git#egg=django-autocomplete-light

Add to INSTALLED_APPS: ‘autocomplete_light’

Add to urls:

url(r'autocomplete/', include('autocomplete_light.urls')),

Add before admin.autodiscover():

import autocomplete_light
autocomplete_light.autodiscover()

At this point, we’re going to assume that you have django.contrib.staticfiles working. This means that static files are automatically served with runserver, and that you have to run collectstatic when using another server (fastcgi, uwsgi, and whatnot). If you don’t use django.contrib.staticfiles, then you’re on your own to manage staticfiles.

This is an example of how you could load the javascript:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js" type="text/javascript"></script>
{% include 'autocomplete_light/static.html' %}

Quick admin integration

For AutocompleteWidget to be enabled in the admin, you should create your own admin/base_site.html template as demonstrated in test_project/templates/admin/base_site.html:

{% extends "admin/base.html" %}
{% load i18n %}

{% block footer %}
    {{ block.super }}

    <script src="{{ STATIC_URL }}jquery.js" type="text/javascript"></script>
    {% include 'autocomplete_light/static.html' %}
    {% comment %}
    Load additionnal script or style dependencies here. For instance, the
    double country/city autocomplete widget requires the countrycity deck
    bootstrap so we'll load it. But you don't need this one if you don't use
    the countrycity widget of the cities_light app.
    {% endcomment %}
    <script src="{{ STATIC_URL }}cities_light/autocomplete_light.js" type="text/javascript"></script>
{% endblock %}

Create yourapp/autocomplete_light_registry.py, assuming “Author” has a “full_name” CharField:

import autocomplete_light

from models import Author

autocomplete_light.register(Author, search_field='full_name')

See more about the channel registry in Registry.

But still, the default implementation of query_filter() is pretty trivial, you might want to customize how it will filter the queryset. See more about customizing channels in Channels basics.

Anyway, finish by setting BookAdmin.form in yourapp/admin.py:

from django.contrib import admin

import autocomplete_light

from models import Book

class BookAdmin(admin.ModelAdmin):
    # use an autocomplete for Author
    form = autocomplete_light.modelform_factory(Book)
admin.site.register(Book, BookAdmin)

Quick form integration

AutocompleteWidget is usable on ModelChoiceField and ModelMultipleChoiceField.

class autocomplete_light.widgets.AutocompleteWidget(channel_name, *args, **kwargs)

Widget suitable for ModelChoiceField and ModelMultipleChoiceField.

Example usage:

from django import forms

import autocomplete_light

from models import Author

class AuthorsForm(forms.Form):
    lead_author = forms.ModelChoiceField(Author.objects.all(), widget=
        autocomplete_light.AutocompleteWidget(
            'AuthorChannel', max_items=1))

    contributors = forms.ModelMultipleChoiceField(Author.objects.all(),
        widget=autocomplete_light.AutocompleteWidget('AuthorChannel'))

AutocompleteWidget constructor decorates SelectMultiple constructor

Arguments: channel_name – the name of the channel that this widget should use.

Keyword arguments are passed to javascript via data attributes of the autocomplete wrapper element:

max_items

The number of items that this autocomplete allows. If set to 0, then it allows any number of selected items like a multiple select, well suited for ManyToMany relations or any kind of ModelMultipleChoiceField. If set to 3 for example, then it will only allow 3 selected items. It should be set to 1 if the widget is for a ModelChoiceField or ForeignKey, in that case it would be like a normal select. Default is 0.

min_characters

The minimum number of characters before the autocomplete box shows up. If set to 2 for example, then the autocomplete box will show up when the input receives the second character, for example ‘ae’. If set to 0, then the autocomplete box will show up as soon as the input is focused, even if it’s empty, behaving like a normal select. Default is 0.

bootstrap

The name of the bootstrap kind. By default, deck.js will only initialize decks for wrappers that have data-bootstrap=”normal”. If you want to implement your own bootstrapping logic in javascript, then you set bootstrap to anything that is not “normal”. By default, its value is copied from channel.bootstrap.

placeholder

The initial value of the autocomplete input field. It can be something like ‘type your search here’. By default, it is copied from channel.placeholder.

payload

A dict of data that will be exported to JSON, and parsed into the Deck instance in javascript. It allows to pass variables from Python to Javascript.