############# Template Tags ############# .. module:: cms.templatetags.cms_tags ***************** CMS template tags ***************** .. highlightlang:: html+django To use any of the following template tags you first need to load them at the top of your template:: {% load cms_tags %} Placeholders ============ .. templatetag:: placeholder placeholder ----------- The ``placeholder`` template tag 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" %} .. image:: /reference/images/placeholder.png :alt: a placeholder named 'content' :align: center 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 :ttag:`with` tag. For instance, if you want to re-size 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 :setting:`CMS_PLACEHOLDER_CONF` setting where you can also add extra context variables and change some other placeholder behaviour. .. important:: ``{% placeholder %}`` will only work inside the template's ``
``. .. templatetag:: static_placeholder static_placeholder ------------------ .. versionchanged:: 4.0 The ``static_placeholder`` template tag does **not** work with django CMS 4. It will be removed in a future version. .. note:: As a replacement use `django CMS Alias{{ placeholder_content }}
When used in this manner, the placeholder will not be displayed for editing when the CMS is in edit mode. See :ref:`placeholders_outside_cms` or :class:`~cms.models.fields.PlaceholderRelationField` on how to get a specific placeholder instance. .. templatetag:: render_uncached_placeholder render_uncached_placeholder =========================== The same as :ttag:`render_placeholder`, but the placeholder contents will not be cached or taken from the cache. Arguments: * :class:`~cms.models.fields.PlaceholderField` instance * ``width`` parameter for context sensitive plugins (optional) * ``language`` keyword plus ``language-code`` string to render content in the specified language (optional) * ``as`` keyword followed by ``varname`` (optional): the template tag output can be saved as a context variable for later use. Example:: {% render_uncached_placeholder mymodel_instance.my_placeholder language 'en' %} .. templatetag:: show_placeholder 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 %} .. templatetag:: show_uncached_placeholder show_uncached_placeholder ========================= The same as :ttag:`show_placeholder`, but the placeholder contents will not be cached or taken from the cache. Arguments: - ``placeholder_name`` - ``page_lookup`` (see `page_lookup`_ for more information) - ``language`` (optional) - ``site`` (optional) Example:: {% show_uncached_placeholder "footer" "footer_container_page" %} .. templatetag:: page_lookup page_lookup =========== The ``page_lookup`` argument, passed to several template tags to retrieve a page, can be of any of the following types: * :class:`str`: interpreted as the ``reverse_id`` field of the desired page, which can be set in the "Advanced" section when editing a page. * :class:`int`: interpreted as the primary key (``pk`` field) of the desired page * :class:`dict`: a dictionary containing keyword arguments to find the desired page (for instance: ``{'pk': 1}``) * :class:`~cms.models.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 template tags:: {% show_placeholder "right-column" "help" %} Help page 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 %} .. templatetag:: page_url page_url ======== Displays the URL of a page in the current language. Arguments: - ``page_lookup`` (see `page_lookup`_ for more information) - ``language`` (optional) - ``site`` (optional) - ``as var_name`` (version 3.0 or later, optional; page_url can now be used to assign the resulting URL to a context variable ``var_name``) Example:: Help page Parent page If a matching page isn't found and :setting:`django:DEBUG` is ``True``, an exception will be raised. However, if :setting:`django:DEBUG` is ``False``, an exception will not be raised. .. versionadded:: 3.0 page_url now supports the ``as`` argument. When used this way, the tag emits nothing, but sets a variable in the context with the specified name to the resulting value. When using the ``as`` argument PageNotFound exceptions are always suppressed, regardless of the setting of :setting:`django:DEBUG` and the tag will simply emit an empty string in these cases. Example:: {# Emit a 'canonical' tag when the page is displayed on an alternate url #} {% page_url request.current_page as current_url %}{% if current_url and current_url != request.get_full_path %}{% endif %} .. templatetag:: page_attribute page_attribute ============== This template tag 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"``, ``"changed_date"``, ``"changed_by"`` (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 %} .. versionadded:: 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 %}