Customization

Wagtail Autocomplete provides the ability to customize the behavior of AutocompletePanel.

“Create New” Behavior

Sometimes you want users to not only be able to select pages or objects, but create new ones on the fly without leaving the object that they’re currently editing. This can be particularly useful for tag-like objects, where you want to be able to add a tag with a particular title, even if that tag doesn’t already exist in the database.

You can enable this type of behavior by defining an autocomplete_create class method on your model. This method should accept a string value and return a new saved model instance:

from django.db import models
from wagtailautocomplete.edit_handlers import AutocompletePanel


class MyModel(models.Model):
    title = models.CharField(max_length=255)

    @classmethod
    def autocomplete_create(kls: type, value: str):
        return kls.objects.create(title=value)

Custom Search Field

By default, the autocomplete widget will match input against the title field on your model. If you’re using a model that doesn’t have a title attribute, or you just want to search using a different field, you can customize which field it matches against by defining an autocomplete_search_field property on your model:

from django.db import models
from wagtailautocomplete.edit_handlers import AutocompletePanel


class MyModel(models.Model):
    my_special_field = models.CharField(max_length=255)

    autocomplete_search_field = 'my_special_field'

Warning

You will also need to define an autocomplete_label function, unless your model has a title attribute. See the section on Custom Label Display for more information.

Note

Internally Wagtail Autocomplete uses an icontains lookup to search for partial text matches. So, in the example above, if a user enters 'part' into an autocomplete field, Wagtail Autocomplete will perform the following query to find matches:

MyModel.objects.filter(my_special_field__icontains='part')

Additionally, this means that autocomplete_search_field must be a model field and cannot be an arbitrary property or method. There is also the possibility to define a custom filter function, described in Custom QuerySet Filter Function.

Custom Label Display

By default, the autocomplete widget will display the title field from a model. You can change this behavior by defining an autocomplete_label method on your model:

from django.db import models
from wagtailautocomplete.edit_handlers import AutocompletePanel


class MyModel(models.Model):
    my_special_field = models.CharField(max_length=255)

    def autocomplete_label(self):
        return self.my_special_field

Custom QuerySet Filter Function

By default, the autocomplete widget uses an icontains lookup to search for matching items of the given model. To change that behavior a custom filter function can be defined, that will be called instead of the default filtering. The function needs to return a QuerySet of the expected model.

from django.db import models
from django.db.models import QuerySet
from wagtailautocomplete.edit_handlers import AutocompletePanel


class MyModel(models.Model):
    my_special_field = models.CharField(max_length=255)

    def autocomplete_label(self):
        return self.my_special_field

    @staticmethod
    def autocomplete_custom_queryset_filter(search_term: str) -> QuerySet:
        field_name='my_special_field'
        filter_kwargs = dict()
        filter_kwargs[field_name + '__contains'] = search_term
        return MyModel.objects.filter(**filter_kwargs)