.. _topics-templates:

=========
Templates
=========

.. admonition:: About this document

   This document describes the templates, template tags and filters provided by
   the library.

.. contents::
   :depth: 3

See also the `models documentation`_, `views documentation`_, and `forms documentation`_.

.. _`models documentation`: models.html
.. _`forms documentation`: forms.html
.. _`views documentation`: views.html

Template files
==============

The softwarefabrica wiki application includes all the necessary templates. These
are provided in the ``template`` directory, and in particular in its ``wiki``
subdirectory.

Templates are notoriously hard to make general enough for all the possible
uses. We've tried to provide a design simple enough to be easily understood, but
complete and functional for a real wiki project.

Almost all the templates inherit from ``wiki/base.html``, which provides a
simple two column layout, with a right sidebar containing the wiki menu. In many
cases it should be possible to customize the layout and appearance by simply
providing a custom ``wiki/base.html`` in your application, somewhere in
``TEMPLATE_DIRS`` where Django can find it.


Template tags and filters
=========================

Template tags and filters are defined in modules contained inside the
``templatetags`` directory.

These can be loaded using ``{% load TAGMODULE %}`` in your templates.

Tag reference
-------------

``last_modified_pages``
~~~~~~~~~~~~~~~~~~~~~~~

``{% load recentpages %}``

An inclusion tag, using the template ``wiki/tags/last_modified_pages.html``.
Renders the template, populating its context with ``wiki`` and ``pages``
variables.
``wiki`` is the passed ``Wiki`` instance, if passed or ``None``.
``pages`` contains the most recently modified pages, from the most to the least
recent. By default up to ten pages are reported, but the number can be passed as
a second parameter.

Usage::

    {% if wiki %}{% last_modified_pages wiki %}{% else %}{% last_modified_pages %}{% endif %}

Extended usage::

    {% last_modified_pages wiki 20 %}

``pagelink``
~~~~~~~~~~~~

``{% load pagelink %}``

An inclusion tag, using the template ``wiki/tags/pagelink.html``.
Renders the full hierarchical `absolute qualified name` for a page, with
subcompontents turned into links.

Receives two arguments, ``page`` (a ``Page`` instance) and ``no_terminal``
(``"y"`` or ``"n"``).
The template context is populated with the variables ``wiki``, ``chain``,
``no_terminal`` and ``do_terminal``.

``wiki`` is the ``Wiki`` instance for the ``Page``.
``chain`` is the list containing the page hierarchy.
``no_terminal`` is the boolean corresponding to the ``no_terminal`` parameter.
``do_terminal`` is the opposite of ``no_terminal``.

The final output could be something like::

    <a href="/Main">Main</a> | <a href="/Main%7CRecipes">Recipes</a> . Lasagne

Usage::

    {% pagelink page "y" %}

``wikilink``
~~~~~~~~~~~~

``{% load wikilink %}``

An inclusion tag, using the template ``wiki/tags/wikilink.html``.
Renders the full hierarchical `qualified name` for a ``Wiki``, with
subcompontents turned into links.

Receives two arguments, ``wiki`` (a ``Wiki`` instance) and ``no_terminal``
(``"y"`` or ``"n"``).
The template context is populated with the variables ``chain``,
``no_terminal`` and ``do_terminal``.

``chain`` is the list containing the wiki hierarchy.
``no_terminal`` is the boolean corresponding to the ``no_terminal`` parameter.
``do_terminal`` is the opposite of ``no_terminal``.

The final output could be something like::

    <a href="/Main">Main</a> | Recipes

Usage::

    {% wikilink wiki "y" %}

``wikimenu``
~~~~~~~~~~~~

``{% load wikimenu %}``

An inclusion tag, using the template ``wiki/tags/wikimenu.html``.
Renders a hierarchycal menu with ``Wiki`` instances.

The tag is called recursively from the template to generate the menu tree.

It receives one optional argument, ``current`` (a ``Wiki`` instance), and other
`service` variables used to handle the recursion.
The template context is populated with the variables ``current``, ``wikis``,
``images``, ``folderopen``, and ``folder`` (and other `service` variables).

``current`` is the currently selected ``Wiki``, or ``None``.
``wikis`` is the list of ``Wiki`` instances at the current recursion level.
``images`` is the image path on the server.
``folderopen`` is the open folder icon.
``folder`` is the close folder icon.

Usage::

    {% if wiki %}{% wikimenu wiki %}{% else %}{% wikimenu %}{% endif %}

``wikis``
~~~~~~~~~

``{% load wikis %}``

An inclusion tag, using the template ``wiki/tags/wikis.html``.
Renders the list of the most recently created wikis.

It receives one optional argument, ``num`` (default is 30), which specifies how
many objects to return.
The template context is populated with the variable ``wikis``, containing the
list of ``Wiki`` instances.

Usage::

    {% wikis %}


Filter reference
----------------

``in_list``
~~~~~~~~~~~

``{% load in_list %}``

Returns a boolean indicating if its first argument is present in its second
argument (typically a list or a tuple).

Usage::

    {% if user|in_list:cool_people %}You're cool!{% else %}Don't lose hope :-){% endif %}

``sanitize``
~~~~~~~~~~~~

``{% load sanitize %}``

Returns a *sanitized* version of its argument, with dangerous HTML code
removed. Non dangerous tags (``<p>``, ``<i>``, ``<strong>``, ``<b>``, ``<u>``,
``<h1>``, ``<h2>``, ``<h3>``, ``<pre>``, ``<br>``, ``<a>``, ``<img>``), are left
in place. For ``<a>`` and ``<img>`` tags, the ``href`` attribute is stripped off
inline Javascript code, if any.

Usage::

    {{ user_text|sanitize }}

``wiki``
~~~~~~~~

``{% load wiki %}``

Renders a ``PageContent`` text, parsing the `wiki syntax`_.

Usage::

    {{ pagecontent|wiki }}

.. _`wiki syntax`: syntax.html
