<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>Templates, Tags and Filters</title>
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
:Revision: $Revision: 4224 $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="templates-tags-and-filters">
<span id="topics-templates"></span><h1 class="title">Templates, Tags and Filters</h1>
<div class="admonition-about-this-document admonition">
<p class="first admonition-title">About this document</p>
<p class="last">This document describes the templates, template tags and filters provided by
the library.</p>
</div>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#template-files" id="id2" name="id2">Template files</a><ul>
<li><a class="reference" href="#template-reference" id="id3" name="id3">Template reference</a><ul>
<li><a class="reference" href="#utils-paginator-html" id="id4" name="id4"><tt class="docutils literal"><span class="pre">utils/paginator.html</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#template-tags-and-filters" id="id5" name="id5">Template tags and filters</a><ul>
<li><a class="reference" href="#tag-reference" id="id6" name="id6">Tag reference</a><ul>
<li><a class="reference" href="#paginator" id="id7" name="id7"><tt class="docutils literal"><span class="pre">paginator</span></tt></a></li>
<li><a class="reference" href="#sitevars" id="id8" name="id8"><tt class="docutils literal"><span class="pre">sitevars</span></tt></a></li>
<li><a class="reference" href="#urlsave" id="id9" name="id9"><tt class="docutils literal"><span class="pre">urlsave</span></tt></a></li>
<li><a class="reference" href="#forward-query-param" id="id10" name="id10"><tt class="docutils literal"><span class="pre">forward_query_param</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#filter-reference" id="id11" name="id11">Filter reference</a><ul>
<li><a class="reference" href="#in-list" id="id12" name="id12"><tt class="docutils literal"><span class="pre">in_list</span></tt></a></li>
<li><a class="reference" href="#sanitize" id="id13" name="id13"><tt class="docutils literal"><span class="pre">sanitize</span></tt></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<p>See also the <a class="reference" href="modules.html">modules documentation</a>.</p>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="template-files" name="template-files">Template files</a></h1>
<p>It's possible to override any template by providing an equally named file
inside an <tt class="docutils literal"><span class="pre">utils</span></tt> subdirectory somewhere in <tt class="docutils literal"><span class="pre">TEMPLATE_DIRS</span></tt> where Django can
find it.</p>
<div class="section">
<h2><a class="toc-backref" href="#id3" id="template-reference" name="template-reference">Template reference</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id4" id="utils-paginator-html" name="utils-paginator-html"><tt class="docutils literal"><span class="pre">utils/paginator.html</span></tt></a></h3>
<p>This is the template used by the template tag <tt class="docutils literal"><span class="pre">paginator</span></tt>. The template
displays pagination links. See below for more information.</p>
</div>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="template-tags-and-filters" name="template-tags-and-filters">Template tags and filters</a></h1>
<p>Template tags and filters are defined in modules contained inside the
<tt class="docutils literal"><span class="pre">templatetags</span></tt> directory.</p>
<p>These can be loaded using <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">TAGMODULE</span> <span class="pre">%}</span></tt> in your templates.</p>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="tag-reference" name="tag-reference">Tag reference</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id7" id="paginator" name="paginator"><tt class="docutils literal"><span class="pre">paginator</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">paginator</span> <span class="pre">%}</span></tt></p>
<p>An inclusion tag, using the template <tt class="docutils literal"><span class="pre">utils/paginator.html</span></tt>.</p>
<p>This is a pagination template tag, to be used in conjunction with the default
Django <a class="reference" href="http://docs.djangoproject.com/en/dev/topics/pagination/">pagination</a> mechanism and/or object list generic views (either the
Django <a class="reference" href="http://docs.djangoproject.com/en/dev/ref/generic-views/?from=olddocs#django-views-generic-list-detail-object-list">object_list</a> built-in, or the versions provided by
<a class="reference" href="http://pypi.python.org/pypi/softwarefabrica.django.crud">softwarefabrica.django.crud</a>).</p>
<p>In addition to the context variables provided by the standard <a class="reference" href="http://docs.djangoproject.com/en/dev/ref/generic-views/?from=olddocs#django-views-generic-list-detail-object-list">object_list</a>
generic view, this adds others for use in displaying first, adjacent and last
page links.</p>
<p>Receives the optional arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">url</span></tt></dt>
<dd>passed to the template as-is, it's used to pass the base url for page
links. Defaults to the empty string.</dd>
<dt><tt class="docutils literal"><span class="pre">adjacent_pages</span></tt></dt>
<dd>number of adjacent pages to display (default is 2).</dd>
<dt><tt class="docutils literal"><span class="pre">paginator_object_name</span></tt></dt>
<dd>used to retrieve the <tt class="docutils literal"><span class="pre">django.core.paginator.Paginator</span></tt> object from the
context (default is <tt class="docutils literal"><span class="pre">'paginator'</span></tt>).</dd>
<dt><tt class="docutils literal"><span class="pre">page_object_name</span></tt></dt>
<dd>used to retrieve the <tt class="docutils literal"><span class="pre">django.core.paginator.Page</span></tt> object from the context
(default is <tt class="docutils literal"><span class="pre">'page_obj'</span></tt>).</dd>
</dl>
<p>The variables added to the context are:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">url</span></tt></dt>
<dd>same as the argument</dd>
<dt><tt class="docutils literal"><span class="pre">paginator</span></tt></dt>
<dd><tt class="docutils literal"><span class="pre">django.core.paginator.Paginator</span></tt> object</dd>
<dt><tt class="docutils literal"><span class="pre">page_obj</span></tt></dt>
<dd><tt class="docutils literal"><span class="pre">django.core.paginator.Page</span></tt> object</dd>
<dt><tt class="docutils literal"><span class="pre">page_numbers</span></tt></dt>
<dd>List of page numbers to display.</dd>
<dt><tt class="docutils literal"><span class="pre">show_first</span></tt></dt>
<dd>Boolean indicating that the first page is to be linked.</dd>
<dt><tt class="docutils literal"><span class="pre">show_last</span></tt></dt>
<dd>Boolean indicating that the last page is to be linked.</dd>
<dt><tt class="docutils literal"><span class="pre">is_paginated</span></tt></dt>
<dd><cite>From generic view</cite>. A boolean representing whether the results are paginated.</dd>
<dt><tt class="docutils literal"><span class="pre">hits</span></tt></dt>
<dd><cite>From generic view</cite>. Number of objects on the displayed page.</dd>
<dt><tt class="docutils literal"><span class="pre">results_per_page</span></tt></dt>
<dd><cite>From generic view</cite>. Number of objects per page (if paginated).</dd>
<dt><tt class="docutils literal"><span class="pre">page</span></tt></dt>
<dd><cite>From generic view</cite>. Current page number.</dd>
<dt><tt class="docutils literal"><span class="pre">pages</span></tt></dt>
<dd><cite>From generic view</cite>. Total number of pages.</dd>
<dt><tt class="docutils literal"><span class="pre">next</span></tt></dt>
<dd><cite>From generic view</cite>. The next page.</dd>
<dt><tt class="docutils literal"><span class="pre">previous</span></tt></dt>
<dd><cite>From generic view</cite>. The previous page.</dd>
<dt><tt class="docutils literal"><span class="pre">has_next</span></tt></dt>
<dd><cite>From generic view</cite>. True if there is a next page.</dd>
<dt><tt class="docutils literal"><span class="pre">has_previous</span></tt></dt>
<dd><cite>From generic view</cite>. True if there is a previous page.</dd>
<dt><tt class="docutils literal"><span class="pre">first_on_page</span></tt></dt>
<dd><cite>From generic view</cite>. The result number of the first object in the object_list (1-indexed).</dd>
<dt><tt class="docutils literal"><span class="pre">last_on_page</span></tt></dt>
<dd><cite>From generic view</cite>. The result number of the last object in the object_list (1-indexed).</dd>
<dt><tt class="docutils literal"><span class="pre">page_range</span></tt></dt>
<dd><cite>From generic view</cite>. A list of the page numbers (1-indexed).</dd>
</dl>
<p>Usage:</p>
<pre class="literal-block">
{% paginator %}
</pre>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id8" id="sitevars" name="sitevars"><tt class="docutils literal"><span class="pre">sitevars</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">sitevars</span> <span class="pre">%}</span></tt></p>
<p>Populates the template context with some variables from the project
<a class="reference" href="http://docs.djangoproject.com/en/dev/topics/settings/">settings</a>.</p>
<p>As an alternative method to this tag, it's also possible to use the <a class="reference" href="http://docs.djangoproject.com/en/dev/ref/settings/#setting-TEMPLATE_CONTEXT_PROCESSORS">template
context processor</a> <tt class="docutils literal"><span class="pre">context_vars</span></tt> provided in
<tt class="docutils literal"><span class="pre">softwarefabrica.django.utils.viewshelpers</span></tt> (see the <cite>modules documentation</cite>).</p>
<p>The variables pushed into the context are:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">basesite</span></tt></dt>
<dd>value of <tt class="docutils literal"><span class="pre">Site.objects.get_current()</span></tt> when using the <a class="reference" href="http://docs.djangoproject.com/en/dev/ref/contrib/sites/?from=olddocs">&quot;sites&quot; framework</a>,
None otherwise.</dd>
<dt><tt class="docutils literal"><span class="pre">domain</span></tt></dt>
<dd>the domain part of the <tt class="docutils literal"><span class="pre">Site</span></tt> when using the <a class="reference" href="http://docs.djangoproject.com/en/dev/ref/contrib/sites/?from=olddocs">&quot;sites&quot; framework</a>,
the empty string otherwise.</dd>
<dt><tt class="docutils literal"><span class="pre">static</span></tt></dt>
<dd>the value of <tt class="docutils literal"><span class="pre">static_media_prefix()</span></tt>, which is
<tt class="docutils literal"><span class="pre">settings.STATIC_MEDIA_PREFIX</span></tt> if defined, or in second instance
<tt class="docutils literal"><span class="pre">settings.STATIC_URL</span></tt>, or finally <tt class="docutils literal"><span class="pre">&quot;/static&quot;</span></tt> (always with the trailing
slash removed).</dd>
<dt><tt class="docutils literal"><span class="pre">upload</span></tt></dt>
<dd>value of <tt class="docutils literal"><span class="pre">settings.MEDIA_URL</span></tt></dd>
<dt><tt class="docutils literal"><span class="pre">admin</span></tt></dt>
<dd>value of <tt class="docutils literal"><span class="pre">settings.ADMIN_MEDIA_PREFIX</span></tt></dd>
<dt><tt class="docutils literal"><span class="pre">images</span></tt></dt>
<dd>same as <tt class="docutils literal"><span class="pre">static</span></tt> with a <tt class="docutils literal"><span class="pre">&quot;/images&quot;</span></tt> suffix</dd>
<dt><tt class="docutils literal"><span class="pre">js</span></tt></dt>
<dd>same as <tt class="docutils literal"><span class="pre">static</span></tt> with a <tt class="docutils literal"><span class="pre">&quot;/js&quot;</span></tt> suffix</dd>
</dl>
<p>Usage:</p>
<pre class="literal-block">
{% sitevars %}
</pre>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id9" id="urlsave" name="urlsave"><tt class="docutils literal"><span class="pre">urlsave</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">urlsave</span> <span class="pre">%}</span></tt></p>
<p>This is similar to Django <a class="reference" href="http://docs.djangoproject.com/en/dev/ref/templates/builtins/?from=olddocs#url">url</a> template tag, but it doesn't produce any
output, and saves the result into a context variable.</p>
<p>Usage:</p>
<pre class="literal-block">
{% urlsave path.to.some_view arg1,arg2,name1=value1 as myurlvar %}
</pre>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id10" id="forward-query-param" name="forward-query-param"><tt class="docutils literal"><span class="pre">forward_query_param</span></tt></a></h3>
<p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">forward_query_param</span> <span class="pre">%}</span></tt></p>
<p>Implements the <tt class="docutils literal"><span class="pre">forward_query_param</span></tt> template tag described in <a class="reference" href="http://groups.google.it/group/django-users/browse_thread/thread/29c3eb3d80e9b78a?hl=it&amp;ie=UTF-8&amp;oe=utf-8&amp;q=paging_control+django-users#df55b3715e2f8d91">Paginating complex queries</a>.
It allows to propagate values of the request <tt class="docutils literal"><span class="pre">GET</span></tt> through forms.</p>
<p>Usage:</p>
<pre class="literal-block">
{% forward_query_param &quot;MY_GET_VARIABLE&quot; %}
</pre>
<p>(to be used inside a <tt class="docutils literal"><span class="pre">&lt;form&gt;...&lt;/form&gt;</span></tt>).</p>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id11" id="filter-reference" name="filter-reference">Filter reference</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id12" id="in-list" name="in-list"><tt class="docutils literal"><span class="pre">in_list</span></tt></a></h3>
<p><strong>NOT YET PROVIDED</strong></p>
<p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">in_list</span> <span class="pre">%}</span></tt></p>
<p>Returns a boolean indicating if its first argument is present in its second
argument (typically a list or a tuple).</p>
<p>Usage:</p>
<pre class="literal-block">
{% if user|in_list:cool_people %}You're cool!{% else %}Don't lose hope :-){% endif %}
</pre>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id13" id="sanitize" name="sanitize"><tt class="docutils literal"><span class="pre">sanitize</span></tt></a></h3>
<p><strong>NOT YET PROVIDED</strong></p>
<p><tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">sanitize</span> <span class="pre">%}</span></tt></p>
<p>Returns a <em>sanitized</em> version of its argument, with dangerous HTML code
removed. Non dangerous tags (<tt class="docutils literal"><span class="pre">&lt;p&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;i&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;strong&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;b&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;u&gt;</span></tt>,
<tt class="docutils literal"><span class="pre">&lt;h1&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;h2&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;h3&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;pre&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;br&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;a&gt;</span></tt>, <tt class="docutils literal"><span class="pre">&lt;img&gt;</span></tt>), are left
in place. For <tt class="docutils literal"><span class="pre">&lt;a&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;img&gt;</span></tt> tags, the <tt class="docutils literal"><span class="pre">href</span></tt> attribute is stripped off
inline Javascript code, if any.</p>
<p>Usage:</p>
<pre class="literal-block">
{{ user_text|sanitize }}
</pre>
</div>
</div>
</div>
</div>
</body>
</html>
