Welcome to Wagtail’s documentation¶

Extend the HomePage model¶

Out of the box, the “home” app defines a blank HomePage model in models.py, along with a migration that creates a homepage and configures Wagtail to use it.

Edit home/models.py as follows, to add a body field to the model:

from __future__ import unicode_literals

from django.db import models

from wagtail.wagtailcore.models import Page
from wagtail.wagtailcore.fields import RichTextField
from wagtail.wagtailadmin.edit_handlers import FieldPanel


class HomePage(Page):
    body = RichTextField(blank=True)

    content_panels = Page.content_panels + [
        FieldPanel('body', classname="full")
    ]

body is defined as RichTextField, a special Wagtail field. You can use any of the Django core fields. content_panels define the capabilities and the layout of the editing interface. More on creating Page models.

Run python manage.py makemigrations, then python manage.py migrate to update the database with your model changes. You must run the above commands each time you make changes to the model definition.

You can now edit the homepage within the Wagtail admin area (go to Explorer, Homepage, then Edit) to see the new body field. Enter some text into the body field, and publish the page.

The page template now needs to be updated to reflect the changes made to the model. Wagtail uses normal Django templates to render each page type. It automatically generates a template filename from the model name by separating capital letters with underscores (e.g. HomePage becomes home_page.html). Edit home/templates/home/home_page.html to contain the following:

{% extends "base.html" %}

{% load wagtailcore_tags %}

{% block body_class %}template-homepage{% endblock %}

{% block content %}
    {{ page.body|richtext }}
{% endblock %}

{% load wagtailcore_tags %}
{{ page.body|richtext }}

<div class="rich-text">
    <p>
        <b>Welcome</b> to our new site!
    </p>
</div>

A basic blog¶

We are now ready to create a blog. To do so, run python manage.py startapp blog to create a new app in your Wagtail site.

Add the new blog app to INSTALLED_APPS in mysite/settings/base.py.

The following example defines a basic blog post model in blog/models.py:

from django.db import models

from wagtail.wagtailcore.models import Page
from wagtail.wagtailcore.fields import RichTextField
from wagtail.wagtailadmin.edit_handlers import FieldPanel
from wagtail.wagtailsearch import index


class BlogPage(Page):
    date = models.DateField("Post date")
    intro = models.CharField(max_length=250)
    body = RichTextField(blank=True)

    search_fields = Page.search_fields + (
        index.SearchField('intro'),
        index.SearchField('body'),
    )

    content_panels = Page.content_panels + [
        FieldPanel('date'),
        FieldPanel('intro'),
        FieldPanel('body', classname="full")
    ]

Create a template at blog/templates/blog/blog_page.html:

{% extends "base.html" %}

{% load wagtailcore_tags %}

{% block body_class %}template-blogpage{% endblock %}

{% block content %}
    <h1>{{ page.title }}</h1>
    <p class="meta">{{ page.date }}</p>

    <div class="intro">{{ page.intro }}</div>

    {{ page.body|richtext }}
{% endblock %}

Run python manage.py makemigrations and python manage.py migrate.

Image support¶

Wagtail provides support for images out of the box. To add them to your model:

from django.db import models

from wagtail.wagtailcore.models import Page
from wagtail.wagtailcore.fields import RichTextField
from wagtail.wagtailadmin.edit_handlers import FieldPanel
from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
from wagtail.wagtailsearch import index


class BlogPage(Page):
    main_image = models.ForeignKey(
        'wagtailimages.Image',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+'
    )
    date = models.DateField("Post date")
    intro = models.CharField(max_length=250)
    body = RichTextField(blank=True)

    search_fields = Page.search_fields + (
        index.SearchField('intro'),
        index.SearchField('body'),
    )

    content_panels = Page.content_panels + [
        FieldPanel('date'),
        ImageChooserPanel('main_image'),
        FieldPanel('intro'),
        FieldPanel('body'),
    ]

Run python manage.py makemigrations and python manage.py migrate.

Adjust your blog page template to include the image:

{% extends "base.html" %}

{% load wagtailcore_tags wagtailimages_tags %}

{% block body_class %}template-blogpage{% endblock %}

{% block content %}
    <h1>{{ page.title }}</h1>
    <p class="meta">{{ page.date }}</p>

    {% if page.main_image %}
      {% image page.main_image width-400 %}
    {% endif %}

    <div class="intro">{{ page.intro }}</div>

    {{ page.body|richtext }}
{% endblock %}

You can read more about using images in templates in the docs.

class BlogIndexPage(Page):
    intro = RichTextField(blank=True)

    content_panels = Page.content_panels + [
        FieldPanel('intro', classname="full")
    ]

{% extends "base.html" %}

{% load wagtailcore_tags %}

{% block body_class %}template-blogindexpage{% endblock %}

{% block content %}
    <h1>{{ page.title }}</h1>

    <div class="intro">{{ page.intro|richtext }}</div>
{% endblock %}

Related items¶

Let’s extend the BlogIndexPage to add related links. The related links can be BlogPages or external links. Change blog/models.py to

from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.wagtailcore.models import Page, Orderable
from wagtail.wagtailcore.fields import RichTextField
from wagtail.wagtailadmin.edit_handlers import (FieldPanel,
                                                InlinePanel,
                                                MultiFieldPanel,
                                                PageChooserPanel)
from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
from wagtail.wagtailsearch import index


# ...

class LinkFields(models.Model):
    link_external = models.URLField("External link", blank=True)
    link_page = models.ForeignKey(
        'wagtailcore.Page',
        null=True,
        blank=True,
        related_name='+'
    )

    @property
    def link(self):
        if self.link_page:
            return self.link_page.url
        else:
            return self.link_external

    panels = [
        FieldPanel('link_external'),
        PageChooserPanel('link_page'),
    ]

    class Meta:
        abstract = True


# Related links
class RelatedLink(LinkFields):
    title = models.CharField(max_length=255, help_text="Link title")

    panels = [
        FieldPanel('title'),
        MultiFieldPanel(LinkFields.panels, "Link"),
    ]

    class Meta:
        abstract = True


class BlogIndexPage(Page):
    intro = RichTextField(blank=True)

    content_panels = Page.content_panels + [
        FieldPanel('intro', classname="full"),
        InlinePanel('related_links', label="Related links"),
    ]


class BlogIndexRelatedLink(Orderable, RelatedLink):
    page = ParentalKey('BlogIndexPage', related_name='related_links')

Extend blog_index_page.html to show related items

{% extends "base.html" %}

{% load wagtailcore_tags %}

{% block body_class %}template-blogindexpage{% endblock %}

{% block content %}
    <h1>{{ page.title }}</h1>

    <div class="intro">{{ page.intro|richtext }}</div>

    {% if page.related_links.all %}
        <ul>
            {% for item in page.related_links.all %}
                <li><a href="{{ item.link }}">{{ item.title }}</a></li>
            {% endfor %}
        </ul>
    {% endif %}
{% endblock %}

You now have a fully working blog with featured blog posts.

Where next¶

• Read the Wagtail topics and reference documentation
• Learn how to implement StreamField for freeform page content
• Browse through the advanced topics section and read third-party tutorials

Settings¶

In your settings file, add the following apps to INSTALLED_APPS:

'wagtail.wagtailforms',
'wagtail.wagtailredirects',
'wagtail.wagtailembeds',
'wagtail.wagtailsites',
'wagtail.wagtailusers',
'wagtail.wagtailsnippets',
'wagtail.wagtaildocs',
'wagtail.wagtailimages',
'wagtail.wagtailsearch',
'wagtail.wagtailadmin',
'wagtail.wagtailcore',

'modelcluster',
'taggit',

Add the following entries to MIDDLEWARE_CLASSES:

'wagtail.wagtailcore.middleware.SiteMiddleware',
'wagtail.wagtailredirects.middleware.RedirectMiddleware',

Add a STATIC_ROOT setting, if your project does not have one already:

STATIC_ROOT = os.path.join(BASE_DIR, 'static')

Add a WAGTAIL_SITE_NAME - this will be displayed on the main dashboard of the Wagtail admin backend:

WAGTAIL_SITE_NAME = 'My Example Site'

Various other settings are available to configure Wagtail’s behaviour - see Configuring Django for Wagtail.

URL configuration¶

Now make the following additions to your urls.py file:

from wagtail.wagtailadmin import urls as wagtailadmin_urls
from wagtail.wagtaildocs import urls as wagtaildocs_urls
from wagtail.wagtailcore import urls as wagtail_urls

urlpatterns = [
    ...
    url(r'^cms/', include(wagtailadmin_urls)),
    url(r'^documents/', include(wagtaildocs_urls)),
    url(r'^pages/', include(wagtail_urls)),
    ...
]

The URL paths here can be altered as necessary to fit your project’s URL scheme.

wagtailadmin_urls provides the admin interface for Wagtail. This is separate from the Django admin interface (django.contrib.admin); Wagtail-only projects typically host the Wagtail admin at /admin/, but if this would clash with your project’s existing admin backend then an alternative path can be used, such as /cms/ here.

wagtaildocs_urls is the location from where document files will be served. This can be omitted if you do not intend to use Wagtail’s document management features.

wagtail_urls is the base location from where the pages of your Wagtail site will be served. In the above example, Wagtail will handle URLs under /pages/, leaving the root URL and other paths to be handled as normal by your Django project. If you want Wagtail to handle the entire URL space including the root URL, this can be replaced with:

url(r'', include(wagtail_urls)),

In this case, this should be placed at the end of the urlpatterns list, so that it does not override more specific URL patterns.

Finally, your project needs to be set up to serve user-uploaded files from MEDIA_ROOT. Your Django project may already have this in place, but if not, add the following snippet to urls.py:

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Note that this only works in development mode (DEBUG = True); in production, you will need to configure your web server to serve files from MEDIA_ROOT. For further details, see the Django documentation: Serving files uploaded by a user during development and Deploying static files.

With this configuration in place, you are ready to run ./manage.py migrate to create the database tables used by Wagtail.

User accounts¶

Superuser accounts receive automatic access to the Wagtail admin interface; use ./manage.py createsuperuser if you don’t already have one. Custom user models are supported, with some restrictions; Wagtail uses an extension of Django’s permissions framework, so your user model must at minimum inherit from AbstractBaseUser and PermissionsMixin.

Start developing¶

You’re now ready to add a new app to your Django project (via ./manage.py startapp - remember to add it to INSTALLED_APPS) and set up page models, as described in Your first Wagtail site.

Note that there’s one small difference when not using the Wagtail project template: Wagtail creates an initial homepage of the basic type Page, which does not include any content fields beyond the title. You’ll probably want to replace this with your own HomePage class - when you do so, ensure that you set up a site record (under Settings / Sites in the Wagtail admin) to point to the new homepage.

An example Wagtail page model¶

This example represents a typical blog post:

from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.wagtailcore.models import Page, Orderable
from wagtail.wagtailcore.fields import RichTextField
from wagtail.wagtailadmin.edit_handlers import FieldPanel, MultiFieldPanel, InlinePanel
from wagtail.wagtailimages.edit_handlers import ImageChooserPanel
from wagtail.wagtailsearch import index


class BlogPage(Page):

    # Database fields

    body = RichTextField()
    date = models.DateField("Post date")
    feed_image = models.ForeignKey(
        'wagtailimages.Image',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+'
    )


    # Search index configuraiton

    search_fields = Page.search_fields + (
        index.SearchField('body'),
        index.FilterField('date'),
    )


    # Editor panels configuration

    content_panels = Page.content_panels + [
        FieldPanel('date'),
        FieldPanel('body', classname="full"),
        InlinePanel('related_links', label="Related links"),
    ]

    promote_panels = [
        MultiFieldPanel(Page.promote_panels, "Common page configuration"),
        ImageChooserPanel('feed_image'),
    ]


    # Parent page / subpage type rules

    parent_page_types = ['blog.BlogIndex']
    subpage_types = []


class BlogPageRelatedLink(Orderable):
    page = ParentalKey(BlogPage, related_name='related_links')
    name = models.CharField(max_length=255)
    url = models.URLField()

    panels = [
        FieldPanel('name'),
        FieldPanel('url'),
    ]

Writing page models¶

Here we’ll describe each section of the above example to help you create your own page models.

Template rendering¶

Each page model can be given an HTML template which is rendered when a user browses to a page on the site frontend. This is the simplest and most common way to get Wagtail content to end users (but not the only way).

class BlogIndexPage(Page):
    ...

    def get_context(self, request):
        context = super(BlogIndexPage, self).get_context(request)

        # 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 %}

class BlogPage(Page):
    ...

    template = 'other_template.html'

class BlogPage(Page):
    ...

    use_other_template = models.BooleanField()

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

        return 'blog/blog_page.html'

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,
        })

Inline models¶

Wagtail can nest the content of other models within the page. This is useful for creating repeated fields, such as related links or items to display in a carousel. Inline model content is also versioned with the rest of the page content.

Each inline model requires the following:

• It must inherit from wagtail.wagtailcore.models.Orderable
• It must have a ParentalKey to the parent model

from modelcluster.fields import ParentalKey

For example, the following inline model can be used to add related links (a list of name, url pairs) to the BlogPage model:

from django.db import models
from modelcluster.fields import ParentalKey
from wagtail.wagtailcore.models import Orderable


class BlogPageRelatedLink(Orderable):
    page = ParentalKey(BlogPage, related_name='related_links')
    name = models.CharField(max_length=255)
    url = models.URLField()

    panels = [
        FieldPanel('name'),
        FieldPanel('url'),
    ]

To add this to the admin interface, use the InlinePanel edit panel class:

content_panels = [
    ...

    InlinePanel('related_links', label="Related links"),
]

The first argument must match the value of the related_name attribute of the ParentalKey.

Working with pages¶

Wagtail uses Django’s multi-table inheritance feature to allow multiple page models to be used in the same tree.

Each page is added to both Wagtail’s builtin Page model as well as its user-defined model (such as the BlogPage model created earlier).

Pages can exist in Python code in two forms, an instance of Page or an instance of the page model.

When working with multiple page types together, you will typically use instances of Wagtail’s Page model, which don’t give you access to any fields specific to their type.

# Get all pages in the database
>>> from wagtail.wagtailcore.models import Page
>>> Page.objects.all()
[<Page: Homepage>, <Page: About us>, <Page: Blog>, <Page: A Blog post>, <Page: Another Blog post>]

When working with a single page type, you can work with instances of the user-defined model. These give access to all the fields available in Page, along with any user-defined fields for that type.

# Get all blog entries in the database
>>> BlogPage.objects.all()
[<BlogPage: A Blog post>, <BlogPage: Another Blog post>]

You can convert a Page object to its more specific user-defined equivalent using the .specific property. This may cause an additional database lookup.

>>> page = Page.objects.get(title="A Blog post")
>>> page
<Page: A Blog post>

# Note: the blog post is an instance of Page so we cannot access body, date or feed_image

>>> page.specific
<BlogPage: A Blog post>

Tips¶

class HomePage(Page):
    ...

    class Meta:
        verbose_name = "homepage"

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

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

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

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

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

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

    objects = EventPageManager()

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

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

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

    objects = PageManager.from_queryset(EventPageQuerySet)

Templates¶

Every type of page or “content type” in Wagtail is defined as a “model” in a file called models.py. If your site has a blog, you might have a BlogPage model and another called BlogPageListing. The names of the models are up to the Django developer.

For each page model in models.py, Wagtail assumes an HTML template file exists of (almost) the same name. The Front End developer may need to create these templates themselves by refering to models.py to infer template names from the models defined therein.

To find a suitable template, Wagtail converts CamelCase names to snake_case. So for a BlogPage, a template blog_page.html will be expected. The name of the template file can be overridden per model if necessary.

Template files are assumed to exist here:

name_of_project/
    name_of_app/
        templates/
            name_of_app/
                blog_page.html
        models.py

For more information, see the Django documentation for the application directories template loader.

Static assets¶

Static files e.g CSS, JS and images are typically stored here:

name_of_project/
    name_of_app/
        static/
            name_of_app/
                css/
                js/
                images/
        models.py

(The names “css”, “js” etc aren’t important, only their position within the tree.)

Any file within the static folder should be inserted into your HTML using the {% static %} tag. More about it: Static files (tag).

Template tags & filters¶

In addition to Django’s standard tags and filters, Wagtail provides some of its own, which can be load-ed just like any other.

{% image [image] [resize-rule] %}

{% load wagtailimages_tags %}
...

{% image page.photo width-400 %}

<!-- or a square thumbnail: -->
{% image page.photo fill-80x80 %}

{% load wagtailcore_tags %}
...
{{ page.body|richtext }}

.rich-text img {
    max-width: 100%;
    height: auto;
}

.responsive-object {
    position: relative;
}

.responsive-object iframe,
.responsive-object object,
.responsive-object embed {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}

{% load wagtailcore_tags %}
...
<a href="{% pageurl page.blog_page %}">

{% load wagtailcore_tags %}
...
<a href="{% slugurl page.your_slug %}">

{% load static %}
...
<img src="{% static "name_of_app/myimage.jpg" %}" alt="My image"/>

Wagtail User Bar¶

This tag provides a contextual flyout menu for logged-in users. The menu gives editors the ability to edit the current page or add a child page, besides the options to show the page in the Wagtail page explorer or jump to the Wagtail admin dashboard. Moderators are also given the ability to accept or reject a page being previewed as part of content moderation.

{% load wagtailuserbar %}
...
{% wagtailuserbar %}

By default the User Bar appears in the bottom right of the browser window, inset from the edge. If this conflicts with your design it can be moved by passing a parameter to the template tag. These examples show you how to position the userbar in each corner of the screen:

...
{% wagtailuserbar 'top-left' %}
{% wagtailuserbar 'top-right' %}
{% wagtailuserbar 'bottom-left' %}
{% wagtailuserbar 'bottom-right' %}
...

The userbar can be positioned where it works best with your design. Alternatively, you can position it with a css rule in your own CSS files, for example:

.wagtail-userbar {
   top: 200px !important;
   left: 10px !important;
}

Varying output between preview and live¶

Sometimes you may wish to vary the template output depending on whether the page is being previewed or viewed live. For example, if you have visitor tracking code such as Google Analytics in place on your site, it’s a good idea to leave this out when previewing, so that editor activity doesn’t appear in your analytics reports. Wagtail provides a request.is_preview variable to distinguish between preview and live:

{% if not request.is_preview %}
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      ...
    </script>
{% endif %}

More control over the img tag¶

Wagtail provides two shortcuts to give greater control over the img element:

1. Adding attributes to the {% image %} tag

Extra attributes can be specified with the syntax attribute="value":

{% image page.photo width-400 class="foo" id="bar" %}

You can set a more relevant alt attribute this way, overriding the one automatically generated from the title of the image. The src, width, and height attributes can also be overridden, if necessary.

2. Generating the image “as foo” to access individual properties

Wagtail can assign the image data to another variable using Django’s as syntax:

{% image page.photo width-400 as tmp_photo %}

<img src="{{ tmp_photo.url }}" width="{{ tmp_photo.width }}"
    height="{{ tmp_photo.height }}" alt="{{ tmp_photo.alt }}" class="my-custom-class" />

This syntax exposes the underlying image Rendition (tmp_photo) to the developer. A “Rendition” contains the information specific to the way you’ve requested to format the image using the resize-rule, i.e. dimensions and source URL.

If your site defines a custom image model using AbstractImage, any additional fields you add to an image (e.g. a copyright holder) are not included in the rendition.

Therefore, if you’d added the field author to your AbstractImage in the above example, you’d access it using {{ page.photo.author }} rather than {{ tmp_photo.author }}.

(Due to the links in the database between renditions and their parent image, you could access it as {{ tmp_photo.image.author }}, but that has reduced readability.)

The attrs shortcut¶

You can also use the attrs property as a shorthand to output the attributes src, width, height and alt in one go:

<img {{ tmp_photo.attrs }} class="my-custom-class" />

Images embedded in rich text¶

The information above relates to images defined via image-specific fields in your model. However, images can also be embedded arbitrarily in Rich Text fields by the page editor (see Rich Text (HTML)).

Images embedded in Rich Text fields can’t be controlled by the template developer as easily. There are no image objects to work with, so the {% image %} template tag can’t be used. Instead, editors can choose from one of a number of image “Formats” at the point of inserting images into their text.

Wagtail comes with three pre-defined image formats, but more can be defined in Python by the developer. These formats are:

Full width

Creates an image rendition using width-800, giving the <img> tag the CSS class full-width.

Left-aligned

Creates an image rendition using width-500, giving the <img> tag the CSS class left.

Right-aligned

Creates an image rendition using width-500, giving the <img> tag the CSS class right.

For more information about image formats, including creating your own, see Image Formats in the Rich Text Editor

Indexing¶

To make objects searchable, they must first be added to the search index. This involves configuring the models and fields that you would like to index (which is done for you for Pages, Images and Documents), and then actually inserting them into the index.

See Updating the index for information on how to keep the objects in your search index in sync with the objects in your database.

If you have created some extra fields in a subclass of Page or Image, you may want to add these new fields to the search index, so a user’s search query can match the Page or Image’s extra content. See Indexing extra fields.

If you have a custom model which doesn’t derive from Page or Image that you would like to make searchable, see Indexing custom models.

Searching¶

Wagtail provides an API for performing search queries on your models. You can also perform search queries on Django QuerySets.

See Searching.

Backends¶

Wagtail provides two backends for storing the search index and performing search queries: Elasticsearch and the database. It’s also possible to roll your own search backend.

See Backends

Snippet Models¶

Here’s an example snippet from the Wagtail demo website:

from django.db import models

from wagtail.wagtailadmin.edit_handlers import FieldPanel
from wagtail.wagtailsnippets.models import register_snippet

...

@register_snippet
class Advert(models.Model):
    url = models.URLField(null=True, blank=True)
    text = models.CharField(max_length=255)

    panels = [
        FieldPanel('url'),
        FieldPanel('text'),
    ]

    def __str__(self):              # __unicode__ on Python 2
        return self.text

The Advert model uses the basic Django model class and defines two properties: text and URL. The editing interface is very close to that provided for Page-derived models, with fields assigned in the panels property. Snippets do not use multiple tabs of fields, nor do they provide the “save as draft” or “submit for moderation” features.

@register_snippet tells Wagtail to treat the model as a snippet. The panels list defines the fields to show on the snippet editing page. It’s also important to provide a string representation of the class through def __str__(self): so that the snippet objects make sense when listed in the Wagtail admin.

Including Snippets in Template Tags¶

The simplest way to make your snippets available to templates is with a template tag. This is mostly done with vanilla Django, so perhaps reviewing Django’s documentation for django custom template tags will be more helpful. We’ll go over the basics, though, and point out any considerations to make for Wagtail.

First, add a new python file to a templatetags folder within your app. The demo website, for instance uses the path wagtaildemo/demo/templatetags/demo_tags.py. We’ll need to load some Django modules and our app’s models, and ready the register decorator:

from django import template
from demo.models import *

register = template.Library()

...

# Advert snippets
@register.inclusion_tag('demo/tags/adverts.html', takes_context=True)
def adverts(context):
    return {
        'adverts': Advert.objects.all(),
        'request': context['request'],
    }

@register.inclusion_tag() takes two variables: a template and a boolean on whether that template should be passed a request context. It’s a good idea to include request contexts in your custom template tags, since some Wagtail-specific template tags like pageurl need the context to work properly. The template tag function could take arguments and filter the adverts to return a specific model, but for brevity we’ll just use Advert.objects.all().

Here’s what’s in the template used by this template tag:

{% for advert in adverts %}
  <p>
    <a href="{{ advert.url }}">
      {{ advert.text }}
    </a>
  </p>
{% endfor %}

Then, in your own page templates, you can include your snippet template tag with:

{% load wagtailcore_tags demo_tags %}

...

{% block content %}

  ...

  {% adverts %}

{% endblock %}

Binding Pages to Snippets¶

In the above example, the list of adverts is a fixed list, displayed independently of the page content. This might be what you want for a common panel in a sidebar, say – but in other scenarios you may wish to refer to a particular snippet from within a page’s content. This can be done by defining a foreign key to the snippet model within your page model, and adding a SnippetChooserPanel to the page’s content_panels list. For example, if you wanted to be able to specify an advert to appear on BookPage:

from wagtail.wagtailsnippets.edit_handlers import SnippetChooserPanel
# ...
class BookPage(Page):
    advert = models.ForeignKey(
        'demo.Advert',
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name='+'
    )

    content_panels = Page.content_panels + [
        SnippetChooserPanel('advert'),
        # ...
    ]

The snippet could then be accessed within your template as page.advert.

To attach multiple adverts to a page, the SnippetChooserPanel can be placed on an inline child object of BookPage, rather than on BookPage itself. Here this child model is named BookPageAdvertPlacement (so called because there is one such object for each time that an advert is placed on a BookPage):

from django.db import models

from wagtail.wagtailcore.models import Page, Orderable
from wagtail.wagtailsnippets.edit_handlers import SnippetChooserPanel

from modelcluster.fields import ParentalKey

...

class BookPageAdvertPlacement(Orderable, models.Model):
    page = ParentalKey('demo.BookPage', related_name='advert_placements')
    advert = models.ForeignKey('demo.Advert', related_name='+')

    class Meta:
        verbose_name = "advert placement"
        verbose_name_plural = "advert placements"

    panels = [
        SnippetChooserPanel('advert'),
    ]

    def __str__(self):              # __unicode__ on Python 2
        return self.page.title + " -> " + self.advert.text


class BookPage(Page):
    ...

    content_panels = Page.content_panels + [
        InlinePanel('advert_placements', label="Adverts"),
        # ...
    ]

These child objects are now accessible through the page’s advert_placements property, and from there we can access the linked Advert snippet as advert. In the template for BookPage, we could include the following:

{% for advert_placement in page.advert_placements.all %}
  <p>
    <a href="{{ advert_placement.advert.url }}">
      {{ advert_placement.advert.text }}
    </a>
  </p>
{% endfor %}

Making Snippets Searchable¶

If a snippet model inherits from wagtail.wagtailsearch.index.Indexed, as described in Indexing custom models, Wagtail will automatically add a search box to the chooser interface for that snippet type. For example, the Advert snippet could be made searchable as follows:

...

from wagtail.wagtailsearch import index

...

@register_snippet
class Advert(models.Model, index.Indexed):
    url = models.URLField(null=True, blank=True)
    text = models.CharField(max_length=255)

    panels = [
        FieldPanel('url'),
        FieldPanel('text'),
    ]

    search_fields = [
        index.SearchField('text', partial_match=True),
    ]

Tagging snippets¶

Adding tags to snippets is very similar to adding tags to pages. The only difference is that taggit.manager.TaggableManager should be used in the place of ClusterTaggableManager.

from modelcluster.fields import ParentalKey
from taggit.models import TaggedItemBase
from taggit.managers import TaggableManager

class AdvertTag(TaggedItemBase):
    content_object = ParentalKey('demo.Advert', related_name='tagged_items')

@register_snippet
class Advert(models.Model):
    ...
    tags = TaggableManager(through=AdvertTag, blank=True)

    panels = [
        ...
        FieldPanel('tags'),
    ]

The documentation on tagging pages has more information on how to use tags in views.

Using StreamField¶

StreamField is a model field that can be defined within your page model like any other field:

from django.db import models

from wagtail.wagtailcore.models import Page
from wagtail.wagtailcore.fields import StreamField
from wagtail.wagtailcore import blocks
from wagtail.wagtailadmin.edit_handlers import FieldPanel, StreamFieldPanel
from wagtail.wagtailimages.blocks import ImageChooserBlock

class BlogPage(Page):
    author = models.CharField(max_length=255)
    date = models.DateField("Post date")
    body = StreamField([
        ('heading', blocks.CharBlock(classname="full title")),
        ('paragraph', blocks.RichTextBlock()),
        ('image', ImageChooserBlock()),
    ])

    content_panels = Page.content_panels + [
        FieldPanel('author'),
        FieldPanel('date'),
        StreamFieldPanel('body'),
    ]

Note: StreamField is not backwards compatible with other field types such as RichTextField. If you need to migrate an existing field to StreamField, refer to Migrating RichTextFields to StreamField.

The parameter to StreamField is a list of (name, block_type) tuples. ‘name’ is used to identify the block type within templates and the internal JSON representation (and should follow standard Python conventions for variable names: lower-case and underscores, no spaces) and ‘block_type’ should be a block definition object as described below. (Alternatively, StreamField can be passed a single StreamBlock instance - see Structural block types.)

This defines the set of available block types that can be used within this field. The author of the page is free to use these blocks as many times as desired, in any order.

Basic block types¶

All block types accept the following optional keyword arguments:

default

The default value that a new ‘empty’ block should receive.

label

The label to display in the editor interface when referring to this block - defaults to a prettified version of the block name (or, in a context where no name is assigned - such as within a ListBlock - the empty string).

icon

The name of the icon to display for this block type in the menu of available block types. For a list of icon names, see the Wagtail style guide, which can be enabled by adding wagtail.contrib.wagtailstyleguide to your project’s INSTALLED_APPS.

template

The path to a Django template that will be used to render this block on the front end. See Template rendering.

The basic block types provided by Wagtail are as follows:

blocks.ChoiceBlock(choices=[
    ('tea', 'Tea'),
    ('coffee', 'Coffee'),
], icon='cup')

class DrinksChoiceBlock(blocks.ChoiceBlock):
    choices = [
        ('tea', 'Tea'),
        ('coffee', 'Coffee'),
    ]

    class Meta:
        icon = 'cup'

Structural block types¶

In addition to the basic block types above, it is possible to define new block types made up of sub-blocks: for example, a ‘person’ block consisting of sub-blocks for first name, surname and image, or a ‘carousel’ block consisting of an unlimited number of image blocks. These structures can be nested to any depth, making it possible to have a structure containing a list, or a list of structures.

('person', blocks.StructBlock([
    ('first_name', blocks.CharBlock(required=True)),
    ('surname', blocks.CharBlock(required=True)),
    ('photo', ImageChooserBlock()),
    ('biography', blocks.RichTextBlock()),
], icon='user'))

class PersonBlock(blocks.StructBlock):
    first_name = blocks.CharBlock(required=True)
    surname = blocks.CharBlock(required=True)
    photo = ImageChooserBlock()
    biography = blocks.RichTextBlock()

    class Meta:
        icon = 'user'

body = StreamField([
    ('heading', blocks.CharBlock(classname="full title")),
    ('paragraph', blocks.RichTextBlock()),
    ('image', ImageChooserBlock()),
    ('person', PersonBlock()),
])

class PersonBlock(blocks.StructBlock):
    first_name = blocks.CharBlock(required=True)
    surname = blocks.CharBlock(required=True)
    photo = ImageChooserBlock()
    biography = blocks.RichTextBlock()

    class Meta:
        icon = 'user'
        form_classname = 'person-block struct-block'

('ingredients_list', blocks.ListBlock(blocks.CharBlock(label="Ingredient")))

('ingredients_list', blocks.ListBlock(blocks.StructBlock([
    ('ingredient', blocks.CharBlock(required=True)),
    ('amount', blocks.CharBlock()),
])))

('carousel', blocks.StreamBlock(
    [
        ('image', ImageChooserBlock()),
        ('quotation', blocks.StructBlock([
            ('text', blocks.TextBlock()),
            ('author', blocks.CharBlock()),
        ])),
        ('video', EmbedBlock()),
    ],
    icon='cogs'
))

class CarouselBlock(blocks.StreamBlock):
    image = ImageChooserBlock()
    quotation = blocks.StructBlock([
        ('text', blocks.TextBlock()),
        ('author', blocks.CharBlock()),
    ])
    video = EmbedBlock()

    class Meta:
        icon='cogs'

class HomePage(Page):
    carousel = StreamField(CarouselBlock())

Template rendering¶

The simplest way to render the contents of a StreamField into your template is to output it as a variable, like any other field:

{{ page.body }}

This will render each block of the stream in turn, wrapped in a <div class="block-my_block_name"> element (where my_block_name is the block name given in the StreamField definition). If you wish to provide your own HTML markup, you can instead iterate over the field’s value to access each block in turn:

<article>
  {% for block in page.body %}
    <section>{{ block }}</section>
  {% endfor %}
</article>

For more control over the rendering of specific block types, each block object provides block_type and value properties:

<article>
  {% for block in page.body %}
    {% if block.block_type == 'heading' %}
      <h1>{{ block.value }}</h1>
    {% else %}
      <section class="block-{{ block.block_type }}">
        {{ block }}
      </section>
    {% endif %}
  {% endfor %}
</article>

Each block type provides its own front-end HTML rendering mechanism, and this is used for the output of {{ block }}. For most simple block types, such as CharBlock, this will simply output the field’s value, but others will provide their own HTML markup. For example, a ListBlock will output the list of child blocks as a <ul> element (with each child wrapped in an <li> element and rendered using the child block’s own HTML rendering).

To override this with your own custom HTML rendering, you can pass a template argument to the block, giving the filename of a template file to be rendered. This is particularly useful for custom block types derived from StructBlock, as the default StructBlock rendering is simple and somewhat generic:

('person', blocks.StructBlock(
    [
        ('first_name', blocks.CharBlock(required=True)),
        ('surname', blocks.CharBlock(required=True)),
        ('photo', ImageChooserBlock()),
        ('biography', blocks.RichTextBlock()),
    ],
    template='myapp/blocks/person.html',
    icon='user'
))

Or, when defined as a subclass of StructBlock:

class PersonBlock(blocks.StructBlock):
    first_name = blocks.CharBlock(required=True)
    surname = blocks.CharBlock(required=True)
    photo = ImageChooserBlock()
    biography = blocks.RichTextBlock()

    class Meta:
        template = 'myapp/blocks/person.html'
        icon = 'user'

Within the template, the block value is accessible as the variable value:

{% load wagtailimages_tags %}

<div class="person">
  {% image value.photo width-400 %}
  <h2>{{ value.first_name }} {{ value.surname }}</h2>
  {{ value.biography }}
</div>

To pass additional context variables to the template, block subclasses can override the get_context method:

import datetime

class EventBlock(blocks.StructBlock):
    title = blocks.CharBlock(required=True)
    date = blocks.DateBlock(required=True)

    def get_context(self, value):
        context = super(EventBlock, self).get_context(value)
        context['is_happening_today'] = (value['date'] == datetime.date.today())
        return context

    class Meta:
        template = 'myapp/blocks/event.html'

In this example, the variable is_happening_today will be made available within the block template.

BoundBlocks and values¶

As you’ve seen above, it’s possible to assign a particular template for rendering a block. This can be done on any block type (not just StructBlocks), but there are some extra details to be aware of. Consider the following block definition:

class HeadingBlock(blocks.CharBlock):
    class Meta:
        template = 'blocks/heading.html'

where blocks/heading.html consists of:

<h1>{{ value }}</h1>

This gives us a block that behaves as an ordinary text field, but wraps its output in <h1> tags whenever it is rendered:

class BlogPage(Page):
    body = StreamField([
        # ...
        ('heading', HeadingBlock()),
        # ...
    ])

{% for block in page.body %}
  {% if block.block_type == 'heading' %}
    {{ block }}  {# This block will output its own <h1>...</h1> tags. #}
  {% endif %}
{% endfor %}

This is a powerful feature, but it involves some complexity behind the scenes to make it work. Effectively, HeadingBlock has a double identity - logically it represents a plain Python string value, but in circumstances such as this it needs to yield a ‘magic’ object that knows its own custom HTML representation. This ‘magic’ object is an instance of BoundBlock - an object that represents the pairing of a value and its block definition. (Django developers may recognise this as the same principle behind BoundField in Django’s forms framework.)

Most of the time, you won’t need to worry about whether you’re dealing with a plain value or a BoundBlock; you can trust Wagtail to do the right thing. However, there are certain cases where the distinction becomes important. For example, consider the following setup:

class EventBlock(blocks.StructBlock):
    heading = HeadingBlock()
    description = blocks.TextBlock()
    # ...

    class Meta:
        template = 'blocks/event.html'

where blocks/event.html is:

<div class="event {% if value.heading == 'Party!' %}lots-of-balloons{% endif %}">
  {{ value.heading }}
  - {{ value.description }}
</div>

In this case, value.heading returns the plain string value, because if this weren’t the case, the comparison in {% if value.heading == 'Party!' %} would never succeed. This in turn means that {{ value.heading }} renders as the plain string, without the <h1> tags.

Interactions between BoundBlocks and plain values work according to the following rules:

{% for block in page.body %}
    {% if block.block_type == 'heading' %}
        <h2>{{ block.value }}</h2>
    {% endif %}
{% endfor %}

<div class="event {% if value.heading == 'Party!' %}lots-of-balloons{% endif %}">
    {{ value.bound_block.heading }}
    {{ value.description }}
</div>

<div class="event {% if value.heading == 'Party!' %}lots-of-balloons{% endif %}">
    <h1>{{ value.heading }}</h1>
    {{ value.description }}
</div>

class EventBlock(blocks.StructBlock):
    heading = HeadingBlock()
    description = blocks.TextBlock()
    guest_speaker = blocks.StructBlock([
        ('first_name', blocks.CharBlock()),
        ('surname', blocks.CharBlock()),
        ('photo', ImageChooserBlock()),
    ], template='blocks/speaker.html')

Custom block types¶

If you need to implement a custom UI, or handle a datatype that is not provided by Wagtail’s built-in block types (and cannot built up as a structure of existing fields), it is possible to define your own custom block types. For further guidance, refer to the source code of Wagtail’s built-in block classes.

For block types that simply wrap an existing Django form field, Wagtail provides an abstract class wagtail.wagtailcore.blocks.FieldBlock as a helper. Subclasses just need to set a field property that returns the form field object:

class IPAddressBlock(FieldBlock):
    def __init__(self, required=True, help_text=None, **kwargs):
        self.field = forms.GenericIPAddressField(required=required, help_text=help_text)
        super(IPAddressBlock, self).__init__(**kwargs)

Migrations¶

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

from django.db import models, migrations
from wagtail.wagtailcore.rich_text import RichText


def convert_to_streamfield(apps, schema_editor):
    BlogPage = apps.get_model("demo", "BlogPage")
    for page in BlogPage.objects.all():
        if page.body.raw_text and not page.body:
            page.body = [('rich_text', RichText(page.body.raw_text))]
            page.save()


def convert_to_richtext(apps, schema_editor):
    BlogPage = apps.get_model("demo", "BlogPage")
    for page in BlogPage.objects.all():
        if page.body.raw_text is None:
            raw_text = ''.join([
                child.value.source for child in page.body
                if child.block_type == 'rich_text'
            ])
            page.body = raw_text
            page.save()


class Migration(migrations.Migration):

    dependencies = [
        # leave the dependency line from the generated migration intact!
        ('demo', '0001_initial'),
    ]

    operations = [
        migrations.RunPython(
            convert_to_streamfield,
            convert_to_richtext,
        ),
    ]

Middleware (settings.py)¶

MIDDLEWARE_CLASSES = [
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.middleware.common.CommonMiddleware',
  'django.middleware.csrf.CsrfViewMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  'django.contrib.auth.middleware.SessionAuthenticationMiddleware',
  'django.contrib.messages.middleware.MessageMiddleware',
  'django.middleware.clickjacking.XFrameOptionsMiddleware',
  'django.middleware.security.SecurityMiddleware',

  'wagtail.wagtailcore.middleware.SiteMiddleware',

  'wagtail.wagtailredirects.middleware.RedirectMiddleware',
]

Wagtail requires several common Django middleware modules to work and cover basic security. Wagtail provides its own middleware to cover these tasks:

SiteMiddleware

Wagtail routes pre-defined hosts to pages within the Wagtail tree using this middleware.

RedirectMiddleware

Wagtail provides a simple interface for adding arbitrary redirects to your site and this module makes it happen.

Apps (settings.py)¶

INSTALLED_APPS = [

  'myapp',  # your own app

  'wagtail.wagtailforms',
  'wagtail.wagtailredirects',
  'wagtail.wagtailembeds',
  'wagtail.wagtailsites',
  'wagtail.wagtailusers',
  'wagtail.wagtailsnippets',
  'wagtail.wagtaildocs',
  'wagtail.wagtailimages',
  'wagtail.wagtailsearch',
  'wagtail.wagtailadmin',
  'wagtail.wagtailcore',

  'taggit',
  'modelcluster',

  'django.contrib.auth',
  'django.contrib.contenttypes',
  'django.contrib.sessions',
  'django.contrib.messages',
  'django.contrib.staticfiles',
]