Page models¶

Database fields¶

Each Wagtail page type is a Django model, represented in the database as a separate table.

Each page type can have its own set of fields. For example, a news article may have body text and a published date, whereas an event page may need separate fields for venue and start/finish times.

In Wagtail, you can use any Django field class. Most field classes provided by third party apps should work as well.

Wagtail also provides a couple of field classes of its own:

• RichTextField - For rich text content

• StreamField - A block-based content field (see: Freeform page content using StreamField)

For tagging, Wagtail fully supports django-taggit so we recommend using that.

Search¶

The search_fields attribute defines which fields are added to the search index and how they are indexed.

This should be a list of SearchField and FilterField objects. SearchField adds a field for full-text search. FilterField adds a field for filtering the results. A field can be indexed with both SearchField and FilterField at the same time (but only one instance of each).

In the above example, we’ve indexed body for full-text search and date for filtering.

The arguments that these field types accept are documented in indexing extra fields.

Editor panels¶

There are a few attributes for defining how the page’s fields will be arranged in the page editor interface:

• content_panels - For content, such as main body text

• promote_panels - For metadata, such as tags, thumbnail image and SEO title

• settings_panels - For settings, such as publish date

Each of these attributes is set to a list of Panel objects, which defines which fields appear on which tabs and how they are structured on each tab.

Here’s a summary of the Panel classes that Wagtail provides out of the box. See Panel types for full descriptions.

Basic

These allow editing of model fields. The FieldPanel class will choose the correct widget based on the type of the field, such as a rich text editor for RichTextField, or an image chooser for a ForeignKey to an image model. FieldPanel also provides a page chooser interface for ForeignKeys to page models, but for more fine-grained control over which page types can be chosen, PageChooserPanel provides additional configuration options.

• FieldPanel

• PageChooserPanel

Structural

These are used for structuring fields in the interface.

• MultiFieldPanel

• InlinePanel

• FieldRowPanel

Parent page / subpage type rules¶

These two attributes allow you to control where page types may be used in your site. They allow you to define rules like “blog entries may only be created under a blog index”.

Both parent and subpage types take a list of model classes or model names. Model names are of the format app_label.ModelName. If the app_label is omitted, the same app is assumed.

• parent_page_types limits which page types this type can be created under

• subpage_types limits which page types can be created under this type

By default, any page type can be created under any page type and it is not necessary to set these attributes if that’s the desired behaviour.

Setting parent_page_types to an empty list is a good way of preventing a particular page type from being created in the editor interface.

Page descriptions¶

With every Wagtail Page you are able to add a helpful description text, similar to a help_text model attribute. By adding page_description to your Page model you’ll be adding a short description that can be seen when you create a new page, edit an existing page or when you’re prompted to select a child page type.

class LandingPage(Page):

    page_description = "Use this page for converting users"

Page URLs¶

The most common method of retrieving page URLs is by using the {% pageurl %} or {% fullpageurl %} template tags. Since it’s called from a template, these automatically includes the optimizations mentioned below.

Page models also include several low-level methods for overriding or accessing page URLs.

def get_url_parts(self, *args, **kwargs):

super().get_url_parts(*args, **kwargs)

Adding a template for a page model¶

Wagtail automatically chooses a name for the template based on the app label and model class name.

Format: <app_label>/<model_name (snake cased)>.html

For example, the template for the above blog page will be: blog/blog_page.html

You just need to create a template in a location where it can be accessed with this name.

Template context¶

Wagtail renders templates with the page variable bound to the page instance being rendered. Use this to access the content of the page. For example, to get the title of the current page, use {{ page.title }}. All variables provided by context processors are also available.

class BlogIndexPage(Page):
    ...

    def get_context(self, request, *args, **kwargs):
        context = super().get_context(request, *args, **kwargs)

        # Add extra variables and return the updated context
        context['blog_entries'] = BlogPage.objects.child_of(self).live()
        return context

{{ page.title }}

{% for entry in blog_entries %}
    {{ entry.title }}
{% endfor %}

Changing the template¶

Set the template attribute on the class to use a different template file:

class BlogPage(Page):
    ...

    template = 'other_template.html'

class BlogPage(Page):
    ...

    use_other_template = models.BooleanField()

    def get_template(self, request, *args, **kwargs):
        if self.use_other_template:
            return 'blog/other_blog_page.html'

        return 'blog/blog_page.html'

class BlogPage(Page):
    ...

    ajax_template = 'other_template_fragment.html'
    template = 'other_template.html'

More control over page rendering¶

All page classes have a serve() method that internally calls the get_context and get_template methods and renders the template. This method is similar to a Django view function, taking a Django Request object and returning a Django Response object.

This method can also be overridden for complete control over page rendering.

For example, here’s a way to make a page respond with a JSON representation of itself:

from django.http import JsonResponse


class BlogPage(Page):
    ...

    def serve(self, request):
        return JsonResponse({
            'title': self.title,
            'body': self.body,
            'date': self.date,

            # Resizes the image to 300px width and gets a URL to it
            'feed_image': self.feed_image.get_rendition('width-300').url,
        })

Friendly model names¶

You can make your model names more friendly to users of Wagtail by using Django’s internal Meta class with a verbose_name, for example:

class HomePage(Page):
    ...

    class Meta:
        verbose_name = "homepage"

When users are given a choice of pages to create, the list of page types is generated by splitting your model names on each of their capital letters. Thus a HomePage model would be named “Home Page” which is a little clumsy. Defining verbose_name as in the example above would change this to read “Homepage”, which is slightly more conventional.

Page QuerySet ordering¶

Page-derived models cannot be given a default ordering by using the standard Django approach of adding an ordering attribute to the internal Meta class.

class NewsItemPage(Page):
    publication_date = models.DateField()
    ...

    class Meta:
        ordering = ('-publication_date', )  # will not work

This is because Page enforces ordering QuerySets by path. Instead, you must apply the ordering explicitly when constructing a QuerySet:

news_items = NewsItemPage.objects.live().order_by('-publication_date')

Custom Page managers¶

You can add a custom Manager to your Page class. Any custom Managers should inherit from wagtail.models.PageManager:

from django.db import models
from wagtail.models import Page, PageManager

class EventPageManager(PageManager):
    """ Custom manager for Event pages """

class EventPage(Page):
    start_date = models.DateField()

    objects = EventPageManager()

Alternately, if you only need to add extra QuerySet methods, you can inherit from wagtail.models.PageQuerySet to build a custom Manager:

from django.db import models
from django.utils import timezone
from wagtail.models import Page, PageManager, PageQuerySet

class EventPageQuerySet(PageQuerySet):
    def future(self):
        today = timezone.localtime(timezone.now()).date()
        return self.filter(start_date__gte=today)

EventPageManager = PageManager.from_queryset(EventPageQuerySet)

class EventPage(Page):
    start_date = models.DateField()

    objects = EventPageManager()