Integration with forms

The purpose of this documentation is to describe every element in a chronological manner. Because you want to know everything about this app and hack like crazy.

It is complementary with the quick documentation.

Django startup


Autodiscovery is part of the autocomplete_light.registry module:

Autodiscovery is the first thing that happens as it is called early in

autocomplete_light.registry.autodiscover fills autocomplete_light.registry.registry, which is an instance of ChannelRegistry:


As you can see, registration creates a channel if it is only passed a model. You’ll want to make your own channel class, this is what a channel looks like:


To save you some boilerplate, a couple of helpers are provided:

Page rendering

It is important to load jQuery first, and then autocomplete_light and application specific javascript, it can look like this:

<script src="" type="text/javascript"></script>
{% load autocomplete_light_tags %}
{% autocomplete_light_static %}

That said, if you only want to make a global navigation autocomplete, you only need:

<script src="" type="text/javascript"></script>
<script src="{{ STATIC_URL }}autocomplete_light/autocomplete.js" type="text/javascript"></script>

Widget in action

Widget definition

The first thing that happens is the definition of an AutocompleteWidget in a form:

Widget rendering

This is what the default widget template looks like:

{% load i18n %}
{% load autocomplete_light_tags %}

{% comment %}
The outer element is called the 'widget wrapper'. It contains some data
attributes to communicate between Python and JavaScript. And of course, it
wraps around everything the widget needs.
{% endcomment %}
<span class="autocomplete_light_widget {{ name }}" id="{{ widget.html_id }}_wrapper" 
    data-maxitems="{{ widget.max_items }}" 
    data-mincharacters="{{ widget.min_characters }}" 
    data-bootstrap="{{ widget.bootstrap }}">
    {# a text input, that is the 'autocomplete input' #}
    <input type="text" class="autocomplete" name="{{ name }}_autocomplete" id="{{ widget.html_id }}_text" value="" {{ extra_attrs }} />
    {# a hidden select, that contains the actual selected values #}
    <select style="display:none" class="valueSelect" name="{{ name }}" id="{{ widget.html_id }}" {% if widget.max_items != 1 %}multiple="multiple"{% endif %}>
        {% for value in values %}
            <option value="{{ value }}" selected="selected">{{ value }}</option>
        {% endfor %}

    {# a deck that should contain the list of selected options #}
    <ul id="{{ html_id }}_deck" class="deck" >
        {% for result in results %}
            {{ result|autocomplete_light_result_as_html:channel }}
        {% endfor %}

    {# a hidden textarea that contains some json about the channel #}
    <textarea class="json_channel" style="display:none">
        {{ json_channel }}
    {# a hidden div that serves as template for the 'remove from deck' button #}
    <div style="display:none" class="remove">
        {# This will be appended to results on the deck, it's the remove button #}

    <ul style="display:none" class="add_template">
        {% comment %}
        the contained element will be used to render options that are added to the select 
        via javascript, for example in django admin with the + sign

        The text of the option will be inserted in the html of this tag
        {% endcomment %}
        <li class="result">

Javascript initialization

deck.js initializes all widgets that have bootstrap=’normal’ (the default), as you can see:

$('.autocomplete_light_widget[data-bootstrap=normal]').each(function() {

If you want to initialize the deck yourself, set the widget or channel bootstrap to something else, say ‘yourinit’. Then, add to yourapp/static/yourapp/autocomplete_light.js something like:

$('.autocomplete_light_widget[data-bootstrap=yourinit]').each(function() {
        getValue: function(result) {
            // your own logic to get the value from an html result
            return ...;

yourapp/static/yourapp/autocomplete_light.js will be automatically collected by by autodiscover, and the script tag generated by {% autocomplete_light_static %}.

In django-cities-light source, you can see a more interresting example where two autocompletes depend on each other.

You should take a look at the code of autocomplete.js and deck.js, as it lets you override everything.

One interresting note is that the plugins (yourlabs_autocomplete and yourlabs_deck) hold a registry. Which means that:

  • calling someElement.yourlabs_deck() will instanciate a deck with the passed overrides
  • calling someElement.yourlabs_deck() again will return the deck instance for someElement

Javascript cron

deck.js includes a javascript function that is executed every two seconds. It checks each widget’s hidden select for a value that is not in the deck, and adds it to the deck if any.

This is useful for example, when an item was added to the hidden select via the ‘+’ button in django admin. But if you create items yourself in javascript and add them to the select it would work too.

Javascript events

When the autocomplete input is focused, autocomplete.js checks if there are enought caracters in the input to display an autocomplete box. If minCharacters is 0, then it would open even if the input is empty, like a normal select box.

If the autocomplete box is empty, it will fetch the channel view. The channel view will delegate the rendering of the autocomplete box to the actual channel. So that you can override anything you want directly in the channel.

Then, autocomplete.js recognizes options with a selector. By default, it is ‘.result’. This means that any element with the ‘.result’ class in the autocomplete box is considered as an option.

When an option is selected, deck.js calls it’s method getValue() and adds this value to the hidden select. Also, it will copy the result html to the deck.

When an option is removed from the deck, deck.js also removes it from the hidden select.