Overview

Usage

Setup

Add agnocomplete to your INSTALLED_APPS.

Include the agnocomplete URLs to your urlconf:

from django.conf.urls import include, url

urlpatterns = [
    # Starting here
    url(
        r'^agnocomplete/',
        include('agnocomplete.urls', namespace='agnocomplete')),
    # ... Continuing here...
]

Build your Autocomplete classes

You’ll need to add an autocomplete.py in your target app. It’ll be automatically picked up by the agnocomplete application at startup.

These classes should be able to dig data out of your data store. In a Django application, it’ll probably be models, but it can also be a long list of strings (let’s say: the list of the US States, or the full list of the world countries).

There are two types of classes at the moment: AgnocompleteChoices and AgnocompleteModel.

Let’s take the demo example to make it clearer:

from agnocomplete.register import register
from agnocomplete.core import AgnocompleteChoices, AgnocompleteModel
from demo.models import Person


class AutocompleteColor(AgnocompleteChoices):
    choices = (
        ('green', 'Green'),
        ('gray', 'Gray'),
        ('blue', 'Blue'),
        ('grey', 'Grey'),
    )


class AutocompletePerson(AgnocompleteModel):
    model = Person
    fields = ['first_name', 'last_name']

# Registration
register(AutocompleteColor)
register(AutocompletePerson)

The AutocompleteColor is a simple choice source: a list of strings. For the sake of the demo, it’s not very long.

The AutocompletePerson will grab its data from the django model Person, and expose the fields first_name and last_name as source fields for the search.

It means that when the client code will try to search for a term, it’ll be searched in both first_name and last_name fields. These should be fields defined in your model.

And that’s it! The agnocomplete app will automatically add these two URLs to your URLs:

/agnocomplete/AutocompleteColor/
/agnocomplete/AutocompletePerson/

Want to search for the results? Use curl or any other tool to get data.

If the query is empty, it will return no result, for it’s not able to know what to search:

curl http://yourserver/agnocomplete/AutocompleteColor/
{"data": []}

curl http://yourserver/agnocomplete/AutocompletePerson/
{"data": []}

With an interesting search term:

curl http://yourserver/agnocomplete/AutocompleteColor/?q=gre
{"data": [
    {"label": "green", "value": "green"},
    {"label": "grey", "value": "grey"}
]}

curl http://yourserver/agnocomplete/AutocompletePerson/?q=ali
{
    "data": [
        {
            "label": "Alice Iñtërnâtiônàlizætiøn",
            "value": "1"
        },
        {
            "label": "Alice Inchains",
            "value": "2"
        },
        {
            "label": "Alice Obvious",
            "value": "4"
        },
        {
            "label": "Alice Galactic",
            "value": "5"
        }
    ]
}

Forms

You have two available fields ready for autocompletion. agnocomplete.fields.AgnocompleteField, for simple autocompletion lists of choices (static or unrelated to Django models) and agnocomplete.fields.AgnocompleteModelField, for Django-related models.

Example:

from django import forms
from agnocomplete import fields
from demo.autocomplete import AutocompleteColor, AutocompletePerson


class ColorPersonForm(forms.Form):
    favorite_color = fields.AgnocompleteField(AutocompleteColor)
    person = fields.AgnocompleteModelField(AutocompletePerson)

Alternatively, you can pass a full instance to your field definition, or a simple string whuch should be the name of your Agnocomplete class:

favorite_color = fields.AgnocompleteField(AutocompleteColor(page_size=5))
person = fields.AgnocompleteModelField('AutocompletePerson')

If the passed argument is the string or the class object, it’ll be instanciated using its default parameters.

The JS Side

After that, the JS side is completely up to your integration choices. JQuery-based library, Vanilla JS, whichever suits you. You don’t even have to use the custom fields provided, as long as you respect the API specs, you still can query it and use the results on your One-Page-App the way you want.

Correct targetting

Let’s imagine for a second that you’re using a (fictional) JS lib name “wowcomplete”. To add the autocomplete bit to a given control, all you need to do is:

$(document).ready(function() {
    $('my-target-id-or-class').wowcomplete();
});

The key point here is the target.

• If you use: $('select'), you may target select boxes that don’t support agnocomplete AJAX queries,... And you may miss other inputs, like text boxes (jquery-autocomplete doesn’t use selects, for example),
• If you use $('select[data-url]')? It could work also. The only problem here is if you have other select boxes using the same data-url attribute.

To handle this we’ve added a data-agnocomplete data attribute. If this attribute is present, there’s a 100% chances that your input is agnocomplete-ready.

As a consequence, the standard way to target your inputs is:

$(document).ready(function() {
    $('[data-agnocomplete]').wowcomplete();
});

Of course, if you want to use a different attribute, you can override it using the following settings:

AGNOCOMPLETE_DATA_ATTRIBUTE = 'wowcomplete'

This settings will add a data-wowcomplete attribute to all your agnocomplete-ready fields.