3. Template Tags

3.1. CMS templatetags

To use any of the following templatetags you first need to load them at the top of your template:

{% load cms_tags %}

3.1.1. placeholder

Changed in version 2.1: The placeholder name became case sensitive.

The placeholder templatetag defines a placeholder on a page. All placeholders in a template will be auto-detected and can be filled with plugins when editing a page that is using said template. When rendering, the content of these plugins will appear where the placeholder tag was.

Example:

{% placeholder "content" %}

If you want additional content to be displayed in case the placeholder is empty, use the or argument and an additional {% endplaceholder %} closing tag. Everything between {% placeholder "..." or %} and {% endplaceholder %} is rendered in the event that the placeholder has no plugins or the plugins do not generate any output.

Example:

{% placeholder "content" or %}There is no content.{% endplaceholder %}

If you want to add extra variables to the context of the placeholder, you should use Django’s with tag. For instance, if you want to resize images from your templates according to a context variable called width, you can pass it as follows:

{% with 320 as width %}{% placeholder "content" %}{% endwith %}

If you want the placeholder to inherit the content of a placeholder with the same name on parent pages, simply pass the inherit argument:

{% placeholder "content" inherit %}

This will walk up the page tree up until the root page and will show the first placeholder it can find with content.

It’s also possible to combine this with the or argument to show an ultimate fallback if the placeholder and none of the placeholders on parent pages have plugins that generate content:

{% placeholder "content" inherit or %}There is no spoon.{% endplaceholder %}

See also the CMS_PLACEHOLDER_CONF setting where you can also add extra context variables and change some other placeholder behavior.

3.1.2. show_placeholder

Displays a specific placeholder from a given page. This is useful if you want to have some more or less static content that is shared among many pages, such as a footer.

Arguments:

  • placeholder_name
  • page_lookup (see page_lookup for more information)
  • language (optional)
  • site (optional)

Examples:

{% show_placeholder "footer" "footer_container_page" %}
{% show_placeholder "content" request.current_page.parent_id %}
{% show_placeholder "teaser" request.current_page.get_root %}

3.1.3. page_lookup

The page_lookup argument, passed to several templatetags to retrieve a page, can be of any of the following types:

  • str: interpreted as the reverse_id field of the desired page, which can be set in the “Advanced” section when editing a page.
  • int: interpreted as the primary key (pk field) of the desired page
  • dict: a dictionary containing keyword arguments to find the desired page (for instance: {'pk': 1})
  • Page: you can also pass a page object directly, in which case there will be no database lookup.

If you know the exact page you are referring to, it is a good idea to use a reverse_id (a string used to uniquely name a page) rather than a hard-coded numeric ID in your template. For example, you might have a help page that you want to link to or display parts of on all pages. To do this, you would first open the help page in the admin interface and enter an ID (such as help) under the ‘Advanced’ tab of the form. Then you could use that reverse_id with the appropriate templatetags:

{% show_placeholder "right-column" "help" %}
<a href="{% page_url "help" %}">Help page</a>

If you are referring to a page relative to the current page, you’ll probably have to use a numeric page ID or a page object. For instance, if you want the content of the parent page to display on the current page, you can use:

{% show_placeholder "content" request.current_page.parent_id %}

Or, suppose you have a placeholder called teaser on a page that, unless a content editor has filled it with content specific to the current page, should inherit the content of its root-level ancestor:

{% placeholder "teaser" or %}
    {% show_placeholder "teaser" request.current_page.get_root %}
{% endplaceholder %}

3.1.4. show_uncached_placeholder

The same as show_placeholder, but the placeholder contents will not be cached.

Arguments:

  • placeholder_name
  • page_lookup (see page_lookup for more information)
  • language (optional)
  • site (optional)

Example:

{% show_uncached_placeholder "footer" "footer_container_page" %}

3.1.5. page_url

Displays the URL of a page in the current language.

Arguments:

Example:

<a href="{% page_url "help" %}">Help page</a>
<a href="{% page_url request.current_page.parent %}">Parent page</a>

If a matching page isn’t found and DEBUG is True, an exception will be raised. However, if DEBUG is False, an exception will not be raised. Additionally, if SEND_BROKEN_LINK_EMAILS is True and you have specified some addresses in MANAGERS, an email will be sent to those addresses to inform them of the broken link.

3.1.6. page_attribute

This templatetag is used to display an attribute of the current page in the current language.

Arguments:

  • attribute_name
  • page_lookup (optional; see page_lookup for more information)

Possible values for attribute_name are: "title", "menu_title", "page_title", "slug", "meta_description", "meta_keywords" (note that you can also supply that argument without quotes, but this is deprecated because the argument might also be a template variable).

Example:

{% page_attribute "page_title" %}

If you supply the optional page_lookup argument, you will get the page attribute from the page found by that argument.

Example:

{% page_attribute "page_title" "my_page_reverse_id" %}
{% page_attribute "page_title" request.current_page.parent_id %}
{% page_attribute "slug" request.current_page.get_root %}

New in version 2.3.2: This template tag supports the as argument. With this you can assign the result of the template tag to a new variable that you can use elsewhere in the template.

Example:

{% page_attribute "page_title" as title %}
<title>{{ title }}</title>

It even can be used in combination with the page_lookup argument.

Example:

{% page_attribute "page_title" "my_page_reverse_id" as title %}
<a href="/mypage/">{{ title }}</a>

New in version 2.4.

3.1.7. render_plugin

This templatetag is used to render child plugins of the current plugin and should be used inside plugin templates.

Arguments:

  • plugin

Plugin needs to be an instance of a plugin model.

Example:

{% load cms_tags %}
<div class="multicolumn">
{% for plugin in instance.child_plugins %}
        <div style="width: {{ plugin.width }}00px;">
        {% render_plugin plugin %}
        </div>
{% endfor %}
</div>

Normally the children of plugins can be accessed via the child_plugins atrribute of plugins. Plugins need the allow_children attribute to set to True for this to be enabled.

3.3. Toolbar Templatetags

To use any of the following templatetags you first need to load them at the top of your template:

{% load cms_toolbar %}

3.3.1. cms_toolbar

The cms_toolbar templatetag will add the required css and javascript to the sekizai blocks in the base template. The templatetag has to be placed after the <body> tag and before any {% cms_placeholder %} occurrences within your HTML.

Example:

<body>
{% cms_toolbar %}
{% placeholder "home" %}
...