Custom views and URLs

For some reason, the automatically generated URLs don’t fit your architecture. Or you want/need custom URLs that are behind a more complex URL architecture. There are several points that are customizable in django-agnocomplete.

Namespace

By default, the view namespace is agnocomplete. If you want to refer to the Catalog view or any Agnocomplete view, they’re fetchable with:

from django.core.urlresolvers import reverse

reverse('agnocomplete:catalog')
reverse('agnocomplete:agnocomplete', args=['AutocompleteName'])

Nothing forces you to use the agnocomplete namespace. You can set the AGNOCOMPLETE_NAMESPACE in your settings to override this. When defining your URLs, you can then use the following:

from agnocomplete import get_namespace

urlpatters = [
    # ... some patterns
    url(
        r'^agnocomplete/',
        include('agnocomplete.urls', namespace=get_namespace())
    ),
    # Other patterns
]

You can also use the get_namespace() function to retrieve your custom URLs.

from django.core.urlresolvers import reverse
from agnocomplete import get_namespace

reverse(get_namespace() + ':catalog')
reverse(get_namespace() + ':agnocomplete', args=['AutocompleteName'])

Slugs

By default, the slugs used for URLs are using the class name. Even though you normally don’t have access to this URL by hand, you may want to customize it, simplify it, crypt it in some way. Any Agnocomplete class can have a slug class or instance property, like this:

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

So, instead of accessing this using:

/autocomplete/autocomplete/AutocompleteCustomUrl

it’ll be accessible with this much cooler URL:

/autocomplete/autocomplete/colors

Views

Let’s say you need to check permissions on a specific autocomplete, and you need it to be completely isolated from the automatic registry. Fine, you still can.

Let’s consider a simple Agnocomplete class:

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

This class doesn’t have to live in an autocomplete.py module. It doesn’t have to be registered.

Then, build an view:

from agnocomplete.views import AgnocompleteGenericView
from arandom.place import HiddenAutocomplete

class HiddenAutocompleteView(AgnocompleteGenericView):
    klass = HiddenAutocomplete

hidden_autocomplete = HiddenAutocompleteView.as_view()

Join this view with a custom URL:

url(r'^hidden/$',
    'arandom.views.hidden_autocomplete', name='hidden_autocomplete'),

That’s (almost) it. You can already call the URL /hidden and query it using the q or page_size parameter.

To make sure everything is okay, simply run your server (let’s say it’s talking on http://127.0.0.1:8000/)

curl http://127.0.0.1:8000/hidden/
{"data": []}
curl http://127.0.0.1:8000/hidden/?q=gre
{"data": [
    {"label": "Green", "value": "green"},
    {"label": "Grey", "value": "grey"}]
}

Then you can apply any access control method on your view (login_required, permission_required, etc) ; it’s like a normal view.

Using your custom view with fields

Since your Agnocomplete class is not registered in the agnocomplete registry, it can’t be used like other Agnocomplete fields, using the automatic registry URL guessing.

Here’s how to build a form which is ready to use your custom view:

from django.core.urlresolvers import reverse_lazy

class SearchCustom(forms.Form):
    search_color = fields.AgnocompleteField(
        HiddenAutocomplete(url=reverse_lazy('hidden_autocomplete')),
    )

Important

At this point, you must use reverse_lazy() to make sure that this URL will be evaluated when needed, and not before the Django applications are ready.

Final customization

In the previous case, you have to use an instance of your Agnocomplete class. Alternatively, you can override the url class property.

class HiddenAutocompleteURL(AutocompleteColor):
    query_size_min = 2
    url = '/stuff'

class HiddenAutocompleteReverseURL(AutocompleteColor):
    query_size_min = 2
    url = '/stuff'