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 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.

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:

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 %}
            <table>
                {{ form.as_table }}
            </table>
            <input type="submit" />
        </form>

        <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.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.