.. _topics-templates:

===========================
Templates, Tags and Filters
===========================

.. admonition:: About this document

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

.. contents::
   :depth: 3

See also the `modules documentation`_.

.. _`modules documentation`: modules.html

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

It's possible to override any template by providing an equally named file
inside an ``utils`` subdirectory somewhere in ``TEMPLATE_DIRS`` where Django can
find it.

Template reference
------------------

``utils/paginator.html``
~~~~~~~~~~~~~~~~~~~~~~~~

This is the template used by the template tag ``paginator``. The template
displays pagination links. See below for more information.


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

``paginator``
~~~~~~~~~~~~~

``{% load paginator %}``

An inclusion tag, using the template ``utils/paginator.html``.

This is a pagination template tag, to be used in conjunction with the default
Django `pagination`_ mechanism and/or object list generic views (either the
Django `object_list`_ built-in, or the versions provided by
`softwarefabrica.django.crud`_).

In addition to the context variables provided by the standard `object_list`_
generic view, this adds others for use in displaying first, adjacent and last
page links.

Receives the optional arguments:

``url``
    passed to the template as-is, it's used to pass the base url for page
    links. Defaults to the empty string.

``adjacent_pages``
    number of adjacent pages to display (default is 2).

``paginator_object_name``
    used to retrieve the ``django.core.paginator.Paginator`` object from the
    context (default is ``'paginator'``).

``page_object_name``
    used to retrieve the ``django.core.paginator.Page`` object from the context
    (default is ``'page_obj'``).

The variables added to the context are:

``url``
    same as the argument

``paginator``
    ``django.core.paginator.Paginator`` object

``page_obj``
    ``django.core.paginator.Page`` object

``page_numbers``
    List of page numbers to display.

``show_first``
    Boolean indicating that the first page is to be linked.

``show_last``
    Boolean indicating that the last page is to be linked.

``is_paginated``
    `From generic view`. A boolean representing whether the results are paginated.

``hits``
    `From generic view`. Number of objects on the displayed page.

``results_per_page``
    `From generic view`. Number of objects per page (if paginated).

``page``
    `From generic view`. Current page number.

``pages``
    `From generic view`. Total number of pages.

``next``
    `From generic view`. The next page.

``previous``
    `From generic view`. The previous page.

``has_next``
    `From generic view`. True if there is a next page.

``has_previous``
    `From generic view`. True if there is a previous page.

``first_on_page``
    `From generic view`. The result number of the first object in the object_list (1-indexed).

``last_on_page``
    `From generic view`. The result number of the last object in the object_list (1-indexed).

``page_range``
    `From generic view`. A list of the page numbers (1-indexed).

Usage::

    {% paginator %}

.. _`softwarefabrica.django.crud`: http://pypi.python.org/pypi/softwarefabrica.django.crud
.. _`pagination`: http://docs.djangoproject.com/en/dev/topics/pagination/
.. _`object_list`: http://docs.djangoproject.com/en/dev/ref/generic-views/?from=olddocs#django-views-generic-list-detail-object-list

``sitevars``
~~~~~~~~~~~~

``{% load sitevars %}``

Populates the template context with some variables from the project
`settings`_.

As an alternative method to this tag, it's also possible to use the `template
context processor`_ ``context_vars`` provided in
``softwarefabrica.django.utils.viewshelpers`` (see the `modules documentation`).

The variables pushed into the context are:

``basesite``
    value of ``Site.objects.get_current()`` when using the `"sites" framework`_,
    None otherwise.

``domain``
    the domain part of the ``Site`` when using the `"sites" framework`_,
    the empty string otherwise.

``static``
    the value of ``static_media_prefix()``, which is
    ``settings.STATIC_MEDIA_PREFIX`` if defined, or in second instance
    ``settings.STATIC_URL``, or finally ``"/static"`` (always with the trailing
    slash removed).

``upload``
    value of ``settings.MEDIA_URL``

``admin``
    value of ``settings.ADMIN_MEDIA_PREFIX``

``images``
    same as ``static`` with a ``"/images"`` suffix

``js``
    same as ``static`` with a ``"/js"`` suffix

Usage::

    {% sitevars %}

.. _`settings`: http://docs.djangoproject.com/en/dev/topics/settings/
.. _`template context processor`: http://docs.djangoproject.com/en/dev/ref/settings/#setting-TEMPLATE_CONTEXT_PROCESSORS
.. _`modules documentation`: modules.html
.. _`"sites" framework`: http://docs.djangoproject.com/en/dev/ref/contrib/sites/?from=olddocs

``urlsave``
~~~~~~~~~~~

``{% load urlsave %}``

This is similar to Django `url`_ template tag, but it doesn't produce any
output, and saves the result into a context variable.

Usage::

    {% urlsave path.to.some_view arg1,arg2,name1=value1 as myurlvar %}

.. _`url`: http://docs.djangoproject.com/en/dev/ref/templates/builtins/?from=olddocs#url


``forward_query_param``
~~~~~~~~~~~~~~~~~~~~~~~

``{% load forward_query_param %}``

Implements the ``forward_query_param`` template tag described in `Paginating complex queries`_.
It allows to propagate values of the request ``GET`` through forms.

Usage::

    {% forward_query_param "MY_GET_VARIABLE" %}

(to be used inside a ``<form>...</form>``).

.. _`Paginating complex queries`: http://groups.google.it/group/django-users/browse_thread/thread/29c3eb3d80e9b78a?hl=it&ie=UTF-8&oe=utf-8&q=paging_control+django-users#df55b3715e2f8d91

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

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

**NOT YET PROVIDED**

``{% 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``
~~~~~~~~~~~~

**NOT YET PROVIDED**

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