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() and any form import for that matter:

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' %}

Note

Note that you should adapt the static.html template to your needs at some point, because its purpose is to work for all projects, not to be optimal for your project.

Warning

Since 1.1.12, autocomplete_light/static.html includes autocomplete_light/_ajax_csrf.html which provides the necessary javascript to protect ajax requests. If your project already has this, then you could override autocomplete_light/_ajax_csrf.html - or just override static.html and not include that.

Quick admin integration

To enable autocomplete form widgets, you need to load:

• jQuery
• autocomplete_light/autocomplete.js
• autocomplete_light/widget.js

Optionally:

• autocomplete_light/style.css
• autocomplete_light/remote.js

A quick way to enable all this in the admin, is to replace template admin/base_site.html, ie.:

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

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

Create yourapp/autocomplete_light_registry.py, you can copy this example autocomplete registry-reference:

import autocomplete_light

from cities_light.models import City

autocomplete_light.register(City, search_fields=('search_names',),
    autocomplete_js_attributes={'placeholder': 'city name ..'})

At this point, the easiest is to use autocomplete-light’s modelform_factory shortcut directly in yourapp/admin.py, ie.:

from django.contrib import admin

import autocomplete_light

from models import Address

class AddressAdmin(admin.ModelAdmin):
    form = autocomplete_light.modelform_factory(Address)

admin.site.register(Address, AddressAdmin)

Quick form integration

Example models:

from django.db import models
from django.core import urlresolvers


class Widget(models.Model):
    city = models.ForeignKey('cities_light.city', null=True, blank=True)
    users = models.ManyToManyField('auth.user', blank=True)

    def get_absolute_url(self):
        return urlresolvers.reverse('non_admin:widget_update', args=(self.pk,))

Example forms:

from django import forms

import autocomplete_light

from models import Widget

# in the case of this example, we could just have:
# WidgetForm = autocomplete_light.modelform_factory(Widget)
# but we'll not use this shortcut


class WidgetForm(forms.ModelForm):
    class Meta:
        widgets = autocomplete_light.get_widgets_dict(Widget)
        model = Widget

Example urls:

from django.conf.urls import patterns, url
from django.views import generic

from forms import WidgetForm
from models import Widget


urlpatterns = patterns('',
    url(r'widget/add/$', generic.CreateView.as_view(
        model=Widget, form_class=WidgetForm)),
    url(r'widget/(?P<pk>\d+)/update/$', generic.UpdateView.as_view(
        model=Widget, form_class=WidgetForm), name='widget_update'),
)

Note

It is not mandatory to use url namespaces.

Example template:

<html>
    <body>
        <form method="post" action="">
            {% csrf_token %}
            {{ form.as_p }}
            <input type="submit" />
        </form>

        <script src="{{ STATIC_URL }}jquery.js" type="text/javascript"></script>
        {% include 'autocomplete_light/static.html' %}
    </body>
</html>

You can manually use autocomplete_light.ChoiceWidget or autocomplete_light.MultipleChoiceWidget for django’s ModelChoiceField and ModelMultipleChoiceField respectively.

ChoiceWidget is intended to work as a replacement for django’s Select widget, and MultipleChoiceWidget for django’s SelectMultiple.

Constructing a widget needs an Autocomplete class or registered autocomplete name.

The choice autocomplete widget renders from autocomplete_light/widget.html template.