stoat / docs / templating.rst

Full commit


The templates you make to use with Stoat are simply Django templates that take advantage of an extra variable.

The Page Variable

When Stoat renders a template it adds a page variable to the context. This variable has a few properties you'll want to use.


The title of the page as defined in the admin interface.


A normal Django get_absolute_url method that will return the page's URL.


The page's parent.


This property contains all of the fields you've defined in STOAT_TEMPLATES, with their names lowercased and every non-letter/number replaced by an underscore.

For example: look at the following STOAT_TEMPLATES setting:

    'Default': ['default.html', [
        ['Heading',         'char'],
        ['Body',            'text'],
        ['Sidebar Heading', 'text'],
    'Product': ['pages/product.html', [
        ['Price',       'int'],
        ['Description', 'text'],
        ['Image',       'img'],
        ['Image 2',     'img'],

Here's what pages/product.html might look like:

{% extends "base.html" %}

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

    <img class="product-image" src="{{ page.fields.image }}" />
    <img class="product-image" src="{{ page.fields.image_2 }}" />

    <p class="price">Price: ${{ page.fields.price }}</p>

    {{ page.fields.description|linebreaks }}
{% endblock %}

You can use page.f as a shortcut for page.fields if you'd like to save on some typing.


Stoat contains two sets of helpers for building navigation menus in your templates: template tags and Page methods.

Every page has a show_in_nav option that determines whether they will be part of the lists returned by these helpers.

Page Methods


A list of the page's ancestors and itself. For example, imagine you have the following page layout:

About Us
+-> The Team
    +-> Jimmy
    +-> Timmy

For the "Timmy" page page.breadcrumbs will be [<About Us>, <The Team>, <Timmy>].

Each item in the list is a normal page object.

Here's an example of creating a simple list of breadcrumbs in an HTML template:

    {% for p in page.breadcrumbs %}
        <li {% if forloop.last %}class="active"{% endif %}>
            <a href="{{ p.get_absolute_url }}">{{ p.title }}</a>
            {% if not forloop.last %}
            {% endif %}
    {% endfor %}


A list of the page's siblings, including itself.


A list of the page's children.


A nested list of the page's siblings (including itself) and their children. For example, imagine the following layout:

+-> Guitars
+-> Drums

About Us
+-> Hours
+-> Return Policy

For the "Products" or "About Us" page page.nav_siblings_and_children will be:

    [<Products>, [
    [<About Us>, [
        <Return Policy>,

This property can be useful if you're trying to build a two-level navigation list (possibly with Javascript dropdowns). Here's an example of building such a list:

    {% for top_page, child_pages in page.nav_siblings_and_children %}
            <a href="{{ top_page.get_absolute_url }}">{{ top_page.title }}</a>

            {% if child_pages %}
                    {% for child_page in child_pages %}
                            <a href="{{ child_page.get_absolute_url }}">{{ child_page.title }}</a>
                    {% endfor %}
            {% endif %}
    {% endfor %}

Template Tags

To use these template tags you'll need to {% load stoat %} first.

These tags do not require that there be a Stoat page at the current URL, so you can safely use them anywhere you like.


A list of all the root pages.


A nested list of all of the root pages and their children (similar in structure to page.nav_siblings_and_children).