Writing templates¶

Wagtail uses Django’s templating language. For developers new to Django, start with Django’s own template documentation: Templates

Python programmers new to Django/Wagtail may prefer more technical documentation: The Django template language: for Python programmers

You should be familiar with Django templating basics before continuing with this documentation.

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.

Page content¶

The data/content entered into each page is accessed/output through Django’s {{ double-brace }} notation. Each field from the model must be accessed by prefixing page.. e.g the page title {{ page.title }} or another field {{ page.author }}.

Additionally request. is available and contains Django’s request object.

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).

User images¶

Images uploaded to a Wagtail site by its users (as opposed to a developer’s static files, mentioned above) go into the image library and from there are added to pages via the page editor interface.

Unlike other CMSs, adding images to a page does not involve choosing a “version” of the image to use. Wagtail has no predefined image “formats” or “sizes”. Instead the template developer defines image manipulation to occur on the fly when the image is requested, via a special syntax within the template.

Images from the library must be requested using this syntax, but a developer’s static images can be added via conventional means e.g img tags. Only images from the library can be manipulated on the fly.

Read more about the image manipulation syntax here Using images in templates.

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.

Images (tag)¶

The image tag inserts an XHTML-compatible img element into the page, setting its src, width, height and alt. See also More control over the img tag.

The syntax for the image tag is thus:

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

For example:

{% load wagtailimages_tags %}
...

{% image page.photo width-400 %}

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

See Using images in templates for full documentation.

Rich text (filter)¶

This filter takes a chunk of HTML content and renders it as safe HTML in the page. Importantly, it also expands internal shorthand references to embedded images, and links made in the Wagtail editor, into fully-baked HTML ready for display.

Only fields using RichTextField need this applied in the template.

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

Responsive Embeds¶

By default, Wagtail includes embeds and images at their full width, which may overflow the bounds of the content container you’ve defined in your templates. To address this, Wagtail provides the ability to make images and embeds responsive – meaning they’ll resize to fit their container. Responsive embeds can be enabled by setting WAGTAILEMBEDS_RESPONSIVE_HTML = True in your project settings; this adds a CSS class of responsive-object and an inline padding-bottom style to the embed, to be used in conjunction with CSS such as the following:

.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%;
}

Changed in version 2.8: The WAGTAILEMBEDS_RESPONSIVE_HTML setting was added. Previous versions always added the class and style attributes.

Internal links (tag)¶

`pageurl`¶

Takes a Page object and returns a relative URL (/foo/bar/) if within the same Site as the current page, or absolute (http://example.com/foo/bar/) if not.

{% load wagtailcore_tags %}
...
<a href="{% pageurl page.get_parent %}">Back to index</a>

A fallback keyword argument can be provided - this should be a URL route name that takes no parameters, and will be used as a substitute URL when the passed page is None.

{% load wagtailcore_tags %}

{% for publication in page.related_publications.all %}
    <li>
        <a href="{% pageurl publication.detail_page fallback='coming_soon' %}">
            {{ publication.title }}
        </a>
    </li>
{% endfor %}

`slugurl`¶

Takes any slug as defined in a page’s “Promote” tab and returns the URL for the matching Page. If multiple pages exist with the same slug, the page chosen is undetermined.

Like pageurl, this will try to provide a relative link if possible, but will default to an absolute link if the Page is on a different Site. This is most useful when creating shared page furniture, e.g. top level navigation or site-wide links.

{% load wagtailcore_tags %}
...
<a href="{% slugurl 'news' %}">News index</a>

Static files (tag)¶

Used to load anything from your static files directory. Use of this tag avoids rewriting all static paths if hosting arrangements change, as they might between development and live environments.

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

Notice that the full path name is not required and the path snippet you enter only need begin with the parent app’s directory name.

Multi-site support¶

`wagtail_site`¶

Returns the Site object corresponding to the current request.

{% load wagtailcore_tags %}

{% wagtail_site as current_site %}

New in version 2.9: In previous versions, the recommended way to refer to the current site was through the request.site attribute provided by SiteMiddleware; this is now deprecated.

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