Basic Usage

A Quick Example

We have a BlogPage that lets the editor select an AuthorPage page.

class AuthorPage(Page):
    pass

class BlogPage(Page):
    author = models.ForeignKey(
        'app_label.AuthorPage',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
    )

The AuthorPage would traditionally be selected with a wagtail.wagtailadmin.edit_handlers.PageChooserPanel, like the following.

content_panels = Page.content_panels + [
    PageChooserPanel('author', page_type='app_label.AuthorPage'),
]

Instead we can use AutocompletePanel.

content_panels = Page.content_panels + [
    AutocompletePanel('author'),
]

AutocompletePanel

class wagtailautocomplete.edit_handlers.AutocompletePanel(field_name, target_model='wagtailcore.Page')

AutocompletePanel takes one required argument, the field name. Optionally, you can pass a single target_model which will limit the objects an editor can select to that model — this argument can be a reference to a model class or a model string in app_label.ModelName syntax.

Note

Unlike wagtail.wagtailadmin.edit_handlers.PageChooserPanel, AutocompletePanel does not support receiving target_model as a list.

Note

AutocompletePanel does not support receiving the can_choose_root argument that wagtail.wagtailadmin.edit_handlers.PageChooserPanel does.

Multiple Selection With Clusterable Models

AutocompletePanel can also be used with a ParentalManyToManyField to provide a multiple selection widget. For example:

Note

Use content_panels when the model is inherited from Page. If it is inherited from models.Model or ClusterableModel, then we need to use panels instead of content_panels.

from django.db import models
from wagtail.core.models import Page
from modelcluster.models import ClusterableModel
from modelcluster.fields import ParentalManyToManyField

from wagtailautocomplete.edit_handlers import AutocompletePanel

class Book(ClusterableModel):
    title = models.CharField(max_length=255)


class AuthorPage(Page):
    books = ParentalManyToManyField(
        Book,
        null=True,
        related_name='authors'
    )

    content_panels = Page.content_panels + [
        AutocompletePanel('books', target_model=Book)
    ]

Note

This above screen capture also shows the availability of Wagtail Autocomplete’s “Create New” behavior. To learn more, see Customization.