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