Source

django-autocomplete / docs / handling-suggestions.rst

Full commit

Quickstart: Handling suggestions

AutoCompleteWidget can be used to offer suggestions based on the user input. Let's assume for example that we have a Form to send mails to other users:

from django import forms

class SendMail(forms.Form):
    to = forms.EmailField()
    subject = forms.CharField(required=False)
    content = forms.CharField(widget=forms.Textarea)

Using AutoComplete with the Form

Using this form the user has to manually enter the email address. With AutoCompleteWidget we can suggest an email address when the corresponding username is typed:

from django import forms
from autocomplete.widgets import AutoCompleteWidget

class SendMail(froms.Form):
    to = forms.EmailField(widget=AutoCompleteWidget('emails',
                                                    force_selection=False))
    subject = forms.CharField(required=False)
    content = forms.CharField(widget=forms.Textarea)

The string 'emails' passed as the first parameter of :class:`~autocomplete.widgets.AutoCompleteWidget` is an identifier used by autocomplete to select the correct choices-set to render.

force_selection=False tells the Widget to not force the user to select one of the displayed choices. We use this to allow the user to manually insert an email address, without selecting a suggestion.

Defining the choices-set

Now we have to register the emails choices-set editing our URLConf:

from django.conf.urls.defaults import *
from django.contrib.auth.models import User
from autocomplete.views import autocomplete

autocomplete.register(
    id = 'emails',
    queryset = User.objects.all(),
    fields = ('username', 'email'),
    limit = 5,
    key = 'email',
    label = 'email',
)

Note

Since we are using an EmailField in our Form we must set the key parameter to 'email', otherwise the Form won't validate.

In this way when the user starts typing either an username or an email address a set of suggested email addresses will show up.

We'd also like to make the suggestion nicer, displaying the first and last name of the user as well as the email address. We can do this using a formatter function.

Our choices-set becomes:

from django.conf.urls.defaults import *
from django.contrib.auth.models import User
from autocomplete.views import autocomplete

def display_suggestion(user):
    return u"%s %s <%s>" % (user.first_name, user.last_name, user.email)

autocomplete.register(
    id = 'emails',
    queryset = User.objects.all(),
    fields = ('username', 'email'),
    limit = 5,
    key = 'email',
    label = display_suggestion,
)

Registering the autocomplete view

Now edit your URLConf again and add the autocomplete view to your urls:

urlpatterns = patterns('',
    # your other urls here.
    url('^autocomplete/(\w+)/$', autocomplete, name='autocomplete'),
)

Ok. That's it. Just render the form in a template and enjoy.