<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Custom template tags and filters — Django 1.4.5 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.4.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Django 1.4.5 documentation" href="../index.html" />
<link rel="up" title="“How-to” guides" href="index.html" />
<link rel="next" title="Writing a custom storage system" href="custom-file-storage.html" />
<link rel="prev" title="Writing custom model fields" href="custom-model-fields.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.4.5 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="custom-model-fields.html" title="Writing custom model fields">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="custom-file-storage.html" title="Writing a custom storage system">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="howto-custom-template-tags">
<div class="section" id="s-custom-template-tags-and-filters">
<span id="custom-template-tags-and-filters"></span><h1>Custom template tags and filters<a class="headerlink" href="#custom-template-tags-and-filters" title="Permalink to this headline">¶</a></h1>
<p>Django’s template system comes with a wide variety of <a class="reference internal" href="../ref/templates/builtins.html"><em>built-in
tags and filters</em></a> designed to address the
presentation logic needs of your application. Nevertheless, you may
find yourself needing functionality that is not covered by the core
set of template primitives. You can extend the template engine by
defining custom tags and filters using Python, and then make them
available to your templates using the <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-load"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></tt></a> tag.</p>
<div class="section" id="s-code-layout">
<span id="code-layout"></span><h2>Code layout<a class="headerlink" href="#code-layout" title="Permalink to this headline">¶</a></h2>
<p>Custom template tags and filters must live inside a Django app. If they relate
to an existing app it makes sense to bundle them there; otherwise, you should
create a new app to hold them.</p>
<p>The app should contain a <tt class="docutils literal"><span class="pre">templatetags</span></tt> directory, at the same level as
<tt class="docutils literal"><span class="pre">models.py</span></tt>, <tt class="docutils literal"><span class="pre">views.py</span></tt>, etc. If this doesn’t already exist, create it -
don’t forget the <tt class="docutils literal"><span class="pre">__init__.py</span></tt> file to ensure the directory is treated as a
Python package.</p>
<p>Your custom tags and filters will live in a module inside the <tt class="docutils literal"><span class="pre">templatetags</span></tt>
directory. The name of the module file is the name you’ll use to load the tags
later, so be careful to pick a name that won’t clash with custom tags and
filters in another app.</p>
<p>For example, if your custom tags/filters are in a file called
<tt class="docutils literal"><span class="pre">poll_extras.py</span></tt>, your app layout might look like this:</p>
<div class="highlight-python"><pre>polls/
models.py
templatetags/
__init__.py
poll_extras.py
views.py</pre>
</div>
<p>And in your template you would use the following:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">load</span> <span class="nv">poll_extras</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>The app that contains the custom tags must be in <a class="reference internal" href="../ref/settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a> in
order for the <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-load"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></tt></a> tag to work. This is a security feature:
It allows you to host Python code for many template libraries on a single host
machine without enabling access to all of them for every Django installation.</p>
<p>There’s no limit on how many modules you put in the <tt class="docutils literal"><span class="pre">templatetags</span></tt> package.
Just keep in mind that a <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-load"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></tt></a> statement will load
tags/filters for the given Python module name, not the name of the app.</p>
<p>To be a valid tag library, the module must contain a module-level variable
named <tt class="docutils literal"><span class="pre">register</span></tt> that is a <tt class="docutils literal"><span class="pre">template.Library</span></tt> instance, in which all the
tags and filters are registered. So, near the top of your module, put the
following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">template</span>
<span class="n">register</span> <span class="o">=</span> <span class="n">template</span><span class="o">.</span><span class="n">Library</span><span class="p">()</span>
</pre></div>
</div>
<div class="admonition-behind-the-scenes admonition">
<p class="first admonition-title">Behind the scenes</p>
<p>For a ton of examples, read the source code for Django’s default filters
and tags. They’re in <tt class="docutils literal"><span class="pre">django/template/defaultfilters.py</span></tt> and
<tt class="docutils literal"><span class="pre">django/template/defaulttags.py</span></tt>, respectively.</p>
<p class="last">For more information on the <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-load"><tt class="xref std std-ttag docutils literal"><span class="pre">load</span></tt></a> tag, read its documentation.</p>
</div>
</div>
<div class="section" id="s-writing-custom-template-filters">
<span id="writing-custom-template-filters"></span><h2>Writing custom template filters<a class="headerlink" href="#writing-custom-template-filters" title="Permalink to this headline">¶</a></h2>
<p>Custom filters are just Python functions that take one or two arguments:</p>
<ul class="simple">
<li>The value of the variable (input) – not necessarily a string.</li>
<li>The value of the argument – this can have a default value, or be left
out altogether.</li>
</ul>
<p>For example, in the filter <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">var|foo:"bar"</span> <span class="pre">}}</span></tt>, the filter <tt class="docutils literal"><span class="pre">foo</span></tt> would be
passed the variable <tt class="docutils literal"><span class="pre">var</span></tt> and the argument <tt class="docutils literal"><span class="pre">"bar"</span></tt>.</p>
<p>Filter functions should always return something. They shouldn’t raise
exceptions. They should fail silently. In case of error, they should return
either the original input or an empty string – whichever makes more sense.</p>
<p>Here’s an example filter definition:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">cut</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
<span class="sd">"""Removes all values of arg from the given string"""</span>
<span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span>
</pre></div>
</div>
<p>And here’s an example of how that filter would be used:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{{</span> <span class="nv">somevariable</span><span class="o">|</span><span class="nf">cut</span><span class="s2">:"0"</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Most filters don’t take arguments. In this case, just leave the argument out of
your function. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">lower</span><span class="p">(</span><span class="n">value</span><span class="p">):</span> <span class="c"># Only one argument.</span>
<span class="sd">"""Converts a string into all lowercase"""</span>
<span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
</pre></div>
</div>
<div class="section" id="s-registering-custom-filters">
<span id="registering-custom-filters"></span><h3>Registering custom filters<a class="headerlink" href="#registering-custom-filters" title="Permalink to this headline">¶</a></h3>
<p>Once you’ve written your filter definition, you need to register it with
your <tt class="docutils literal"><span class="pre">Library</span></tt> instance, to make it available to Django’s template language:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">register</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="s">'cut'</span><span class="p">,</span> <span class="n">cut</span><span class="p">)</span>
<span class="n">register</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="s">'lower'</span><span class="p">,</span> <span class="n">lower</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">Library.filter()</span></tt> method takes two arguments:</p>
<ol class="arabic simple">
<li>The name of the filter – a string.</li>
<li>The compilation function – a Python function (not the name of the
function as a string).</li>
</ol>
<p>You can use <tt class="docutils literal"><span class="pre">register.filter()</span></tt> as a decorator instead:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.filter</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'cut'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">cut</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">arg</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span>
<span class="nd">@register.filter</span>
<span class="k">def</span> <span class="nf">lower</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
</pre></div>
</div>
<p>If you leave off the <tt class="docutils literal"><span class="pre">name</span></tt> argument, as in the second example above, Django
will use the function’s name as the filter name.</p>
<p>Finally, <tt class="docutils literal"><span class="pre">register.filter()</span></tt> also accepts two keyword arguments, <tt class="docutils literal"><span class="pre">is_safe</span></tt>
and <tt class="docutils literal"><span class="pre">needs_autoescape</span></tt>, described in <a class="reference internal" href="#filters-auto-escaping"><em>filters and auto-escaping</em></a> below.</p>
</div>
<div class="section" id="s-template-filters-that-expect-strings">
<span id="template-filters-that-expect-strings"></span><h3>Template filters that expect strings<a class="headerlink" href="#template-filters-that-expect-strings" title="Permalink to this headline">¶</a></h3>
<p>If you’re writing a template filter that only expects a string as the first
argument, you should use the decorator <tt class="docutils literal"><span class="pre">stringfilter</span></tt>. This will
convert an object to its string value before being passed to your function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">template</span>
<span class="kn">from</span> <span class="nn">django.template.defaultfilters</span> <span class="kn">import</span> <span class="n">stringfilter</span>
<span class="n">register</span> <span class="o">=</span> <span class="n">template</span><span class="o">.</span><span class="n">Library</span><span class="p">()</span>
<span class="nd">@register.filter</span>
<span class="nd">@stringfilter</span>
<span class="k">def</span> <span class="nf">lower</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
</pre></div>
</div>
<p>This way, you’ll be able to pass, say, an integer to this filter, and it
won’t cause an <tt class="docutils literal"><span class="pre">AttributeError</span></tt> (because integers don’t have <tt class="docutils literal"><span class="pre">lower()</span></tt>
methods).</p>
</div>
<div class="section" id="s-filters-and-auto-escaping">
<span id="s-filters-auto-escaping"></span><span id="filters-and-auto-escaping"></span><span id="filters-auto-escaping"></span><h3>Filters and auto-escaping<a class="headerlink" href="#filters-and-auto-escaping" title="Permalink to this headline">¶</a></h3>
<p>When writing a custom filter, give some thought to how the filter will interact
with Django’s auto-escaping behavior. Note that three types of strings can be
passed around inside the template code:</p>
<ul>
<li><p class="first"><strong>Raw strings</strong> are the native Python <tt class="docutils literal"><span class="pre">str</span></tt> or <tt class="docutils literal"><span class="pre">unicode</span></tt> types. On
output, they’re escaped if auto-escaping is in effect and presented
unchanged, otherwise.</p>
</li>
<li><p class="first"><strong>Safe strings</strong> are strings that have been marked safe from further
escaping at output time. Any necessary escaping has already been done.
They’re commonly used for output that contains raw HTML that is intended
to be interpreted as-is on the client side.</p>
<p>Internally, these strings are of type <tt class="docutils literal"><span class="pre">SafeString</span></tt> or <tt class="docutils literal"><span class="pre">SafeUnicode</span></tt>.
They share a common base class of <tt class="docutils literal"><span class="pre">SafeData</span></tt>, so you can test
for them using code like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">SafeData</span><span class="p">):</span>
<span class="c"># Do something with the "safe" string.</span>
<span class="o">...</span>
</pre></div>
</div>
</li>
<li><p class="first"><strong>Strings marked as “needing escaping”</strong> are <em>always</em> escaped on
output, regardless of whether they are in an <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-autoescape"><tt class="xref std std-ttag docutils literal"><span class="pre">autoescape</span></tt></a> block or
not. These strings are only escaped once, however, even if auto-escaping
applies.</p>
<p>Internally, these strings are of type <tt class="docutils literal"><span class="pre">EscapeString</span></tt> or
<tt class="docutils literal"><span class="pre">EscapeUnicode</span></tt>. Generally you don’t have to worry about these; they
exist for the implementation of the <a class="reference internal" href="../ref/templates/builtins.html#std:templatefilter-escape"><tt class="xref std std-tfilter docutils literal"><span class="pre">escape</span></tt></a> filter.</p>
</li>
</ul>
<p>Template filter code falls into one of two situations:</p>
<ol class="arabic">
<li><p class="first">Your filter does not introduce any HTML-unsafe characters (<tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>,
<tt class="docutils literal"><span class="pre">'</span></tt>, <tt class="docutils literal"><span class="pre">"</span></tt> or <tt class="docutils literal"><span class="pre">&</span></tt>) into the result that were not already present. In
this case, you can let Django take care of all the auto-escaping
handling for you. All you need to do is set the <tt class="docutils literal"><span class="pre">is_safe</span></tt> flag to <tt class="docutils literal"><span class="pre">True</span></tt>
when you register your filter function, like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.filter</span><span class="p">(</span><span class="n">is_safe</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">myfilter</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span>
</pre></div>
</div>
<p>This flag tells Django that if a “safe” string is passed into your
filter, the result will still be “safe” and if a non-safe string is
passed in, Django will automatically escape it, if necessary.</p>
<p>You can think of this as meaning “this filter is safe – it doesn’t
introduce any possibility of unsafe HTML.”</p>
<p>The reason <tt class="docutils literal"><span class="pre">is_safe</span></tt> is necessary is because there are plenty of
normal string operations that will turn a <tt class="docutils literal"><span class="pre">SafeData</span></tt> object back into
a normal <tt class="docutils literal"><span class="pre">str</span></tt> or <tt class="docutils literal"><span class="pre">unicode</span></tt> object and, rather than try to catch
them all, which would be very difficult, Django repairs the damage after
the filter has completed.</p>
<p>For example, suppose you have a filter that adds the string <tt class="docutils literal"><span class="pre">xx</span></tt> to
the end of any input. Since this introduces no dangerous HTML characters
to the result (aside from any that were already present), you should
mark your filter with <tt class="docutils literal"><span class="pre">is_safe</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.filter</span><span class="p">(</span><span class="n">is_safe</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">add_xx</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="s">'</span><span class="si">%s</span><span class="s">xx'</span> <span class="o">%</span> <span class="n">value</span>
</pre></div>
</div>
<p>When this filter is used in a template where auto-escaping is enabled,
Django will escape the output whenever the input is not already marked
as “safe”.</p>
<p>By default, <tt class="docutils literal"><span class="pre">is_safe</span></tt> is <tt class="docutils literal"><span class="pre">False</span></tt>, and you can omit it from any filters
where it isn’t required.</p>
<p>Be careful when deciding if your filter really does leave safe strings
as safe. If you’re <em>removing</em> characters, you might inadvertently leave
unbalanced HTML tags or entities in the result. For example, removing a
<tt class="docutils literal"><span class="pre">></span></tt> from the input might turn <tt class="docutils literal"><span class="pre"><a></span></tt> into <tt class="docutils literal"><span class="pre"><a</span></tt>, which would need to
be escaped on output to avoid causing problems. Similarly, removing a
semicolon (<tt class="docutils literal"><span class="pre">;</span></tt>) can turn <tt class="docutils literal"><span class="pre">&amp;</span></tt> into <tt class="docutils literal"><span class="pre">&amp</span></tt>, which is no longer a
valid entity and thus needs further escaping. Most cases won’t be nearly
this tricky, but keep an eye out for any problems like that when
reviewing your code.</p>
<p>Marking a filter <tt class="docutils literal"><span class="pre">is_safe</span></tt> will coerce the filter’s return value to
a string. If your filter should return a boolean or other non-string
value, marking it <tt class="docutils literal"><span class="pre">is_safe</span></tt> will probably have unintended
consequences (such as converting a boolean False to the string
‘False’).</p>
</li>
<li><p class="first">Alternatively, your filter code can manually take care of any necessary
escaping. This is necessary when you’re introducing new HTML markup into
the result. You want to mark the output as safe from further
escaping so that your HTML markup isn’t escaped further, so you’ll need
to handle the input yourself.</p>
<p>To mark the output as a safe string, use
<a class="reference internal" href="../ref/utils.html#django.utils.safestring.mark_safe" title="django.utils.safestring.mark_safe"><tt class="xref py py-func docutils literal"><span class="pre">django.utils.safestring.mark_safe()</span></tt></a>.</p>
<p>Be careful, though. You need to do more than just mark the output as
safe. You need to ensure it really <em>is</em> safe, and what you do depends on
whether auto-escaping is in effect. The idea is to write filters than
can operate in templates where auto-escaping is either on or off in
order to make things easier for your template authors.</p>
<p>In order for your filter to know the current auto-escaping state, set the
<tt class="docutils literal"><span class="pre">needs_autoescape</span></tt> flag to <tt class="docutils literal"><span class="pre">True</span></tt> when you register your filter function.
(If you don’t specify this flag, it defaults to <tt class="docutils literal"><span class="pre">False</span></tt>). This flag tells
Django that your filter function wants to be passed an extra keyword
argument, called <tt class="docutils literal"><span class="pre">autoescape</span></tt>, that is <tt class="docutils literal"><span class="pre">True</span></tt> if auto-escaping is in
effect and <tt class="docutils literal"><span class="pre">False</span></tt> otherwise.</p>
<p>For example, let’s write a filter that emphasizes the first character of
a string:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.utils.html</span> <span class="kn">import</span> <span class="n">conditional_escape</span>
<span class="kn">from</span> <span class="nn">django.utils.safestring</span> <span class="kn">import</span> <span class="n">mark_safe</span>
<span class="nd">@register.filter</span><span class="p">(</span><span class="n">needs_autoescape</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">initial_letter_filter</span><span class="p">(</span><span class="n">text</span><span class="p">,</span> <span class="n">autoescape</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="n">first</span><span class="p">,</span> <span class="n">other</span> <span class="o">=</span> <span class="n">text</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">text</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span>
<span class="k">if</span> <span class="n">autoescape</span><span class="p">:</span>
<span class="n">esc</span> <span class="o">=</span> <span class="n">conditional_escape</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">esc</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span>
<span class="n">result</span> <span class="o">=</span> <span class="s">'<strong></span><span class="si">%s</span><span class="s"></strong></span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">esc</span><span class="p">(</span><span class="n">first</span><span class="p">),</span> <span class="n">esc</span><span class="p">(</span><span class="n">other</span><span class="p">))</span>
<span class="k">return</span> <span class="n">mark_safe</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">needs_autoescape</span></tt> flag and the <tt class="docutils literal"><span class="pre">autoescape</span></tt> keyword argument mean
that our function will know whether automatic escaping is in effect when the
filter is called. We use <tt class="docutils literal"><span class="pre">autoescape</span></tt> to decide whether the input data
needs to be passed through <tt class="docutils literal"><span class="pre">django.utils.html.conditional_escape</span></tt> or not.
(In the latter case, we just use the identity function as the “escape”
function.) The <tt class="docutils literal"><span class="pre">conditional_escape()</span></tt> function is like <tt class="docutils literal"><span class="pre">escape()</span></tt> except
it only escapes input that is <strong>not</strong> a <tt class="docutils literal"><span class="pre">SafeData</span></tt> instance. If a
<tt class="docutils literal"><span class="pre">SafeData</span></tt> instance is passed to <tt class="docutils literal"><span class="pre">conditional_escape()</span></tt>, the data is
returned unchanged.</p>
<p>Finally, in the above example, we remember to mark the result as safe
so that our HTML is inserted directly into the template without further
escaping.</p>
<p>There’s no need to worry about the <tt class="docutils literal"><span class="pre">is_safe</span></tt> flag in this case
(although including it wouldn’t hurt anything). Whenever you manually
handle the auto-escaping issues and return a safe string, the
<tt class="docutils literal"><span class="pre">is_safe</span></tt> flag won’t change anything either way.</p>
</li>
</ol>
<div class="versionchanged">
<span class="title">Changed in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p><tt class="docutils literal"><span class="pre">is_safe</span></tt> and <tt class="docutils literal"><span class="pre">needs_autoescape</span></tt> used to be attributes of the filter
function; this syntax is deprecated.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.filter</span>
<span class="k">def</span> <span class="nf">myfilter</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span>
<span class="n">myfilter</span><span class="o">.</span><span class="n">is_safe</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.filter</span>
<span class="k">def</span> <span class="nf">initial_letter_filter</span><span class="p">(</span><span class="n">text</span><span class="p">,</span> <span class="n">autoescape</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="c"># ...</span>
<span class="k">return</span> <span class="n">mark_safe</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
<span class="n">initial_letter_filter</span><span class="o">.</span><span class="n">needs_autoescape</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
</div>
<div class="section" id="s-filters-and-time-zones">
<span id="s-filters-timezones"></span><span id="filters-and-time-zones"></span><span id="filters-timezones"></span><h3>Filters and time zones<a class="headerlink" href="#filters-and-time-zones" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>If you write a custom filter that operates on <tt class="xref py py-class docutils literal"><span class="pre">datetime</span></tt>
objects, you’ll usually register it with the <tt class="docutils literal"><span class="pre">expects_localtime</span></tt> flag set to
<tt class="docutils literal"><span class="pre">True</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.filter</span><span class="p">(</span><span class="n">expects_localtime</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">businesshours</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">return</span> <span class="mi">9</span> <span class="o"><=</span> <span class="n">value</span><span class="o">.</span><span class="n">hour</span> <span class="o"><</span> <span class="mi">17</span>
<span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
<span class="k">return</span> <span class="s">''</span>
</pre></div>
</div>
<p>When this flag is set, if the first argument to your filter is a time zone
aware datetime, Django will convert it to the current time zone before passing
to your filter when appropriate, according to <a class="reference internal" href="../topics/i18n/timezones.html#time-zones-in-templates"><em>rules for time zones
conversions in templates</em></a>.</p>
</div>
</div>
<div class="section" id="s-writing-custom-template-tags">
<span id="writing-custom-template-tags"></span><h2>Writing custom template tags<a class="headerlink" href="#writing-custom-template-tags" title="Permalink to this headline">¶</a></h2>
<p>Tags are more complex than filters, because tags can do anything.</p>
<div class="section" id="s-a-quick-overview">
<span id="a-quick-overview"></span><h3>A quick overview<a class="headerlink" href="#a-quick-overview" title="Permalink to this headline">¶</a></h3>
<p>Above, this document explained that the template system works in a two-step
process: compiling and rendering. To define a custom template tag, you specify
how the compilation works and how the rendering works.</p>
<p>When Django compiles a template, it splits the raw template text into
‘’nodes’‘. Each node is an instance of <tt class="docutils literal"><span class="pre">django.template.Node</span></tt> and has
a <tt class="docutils literal"><span class="pre">render()</span></tt> method. A compiled template is, simply, a list of <tt class="docutils literal"><span class="pre">Node</span></tt>
objects. When you call <tt class="docutils literal"><span class="pre">render()</span></tt> on a compiled template object, the template
calls <tt class="docutils literal"><span class="pre">render()</span></tt> on each <tt class="docutils literal"><span class="pre">Node</span></tt> in its node list, with the given context.
The results are all concatenated together to form the output of the template.</p>
<p>Thus, to define a custom template tag, you specify how the raw template tag is
converted into a <tt class="docutils literal"><span class="pre">Node</span></tt> (the compilation function), and what the node’s
<tt class="docutils literal"><span class="pre">render()</span></tt> method does.</p>
</div>
<div class="section" id="s-writing-the-compilation-function">
<span id="writing-the-compilation-function"></span><h3>Writing the compilation function<a class="headerlink" href="#writing-the-compilation-function" title="Permalink to this headline">¶</a></h3>
<p>For each template tag the template parser encounters, it calls a Python
function with the tag contents and the parser object itself. This function is
responsible for returning a <tt class="docutils literal"><span class="pre">Node</span></tt> instance based on the contents of the tag.</p>
<p>For example, let’s write a template tag, <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">current_time</span> <span class="pre">%}</span></tt>, that displays
the current date/time, formatted according to a parameter given in the tag, in
<tt class="xref py py-func docutils literal"><span class="pre">strftime()</span></tt> syntax. It’s a good idea to decide the tag syntax before
anything else. In our case, let’s say the tag should be used like this:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><p></span>The time is <span class="cp">{%</span> <span class="k">current_time</span> <span class="s2">"%Y-%m-%d %I:%M %p"</span> <span class="cp">%}</span>.<span class="nt"></p></span>
</pre></div>
</div>
<p>The parser for this function should grab the parameter and create a <tt class="docutils literal"><span class="pre">Node</span></tt>
object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">template</span>
<span class="k">def</span> <span class="nf">do_current_time</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="c"># split_contents() knows not to split quoted strings.</span>
<span class="n">tag_name</span><span class="p">,</span> <span class="n">format_string</span> <span class="o">=</span> <span class="n">token</span><span class="o">.</span><span class="n">split_contents</span><span class="p">()</span>
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag requires a single argument"</span> <span class="o">%</span> <span class="n">token</span><span class="o">.</span><span class="n">contents</span><span class="o">.</span><span class="n">split</span><span class="p">()[</span><span class="mi">0</span><span class="p">])</span>
<span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">format_string</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="n">format_string</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="ow">and</span> <span class="n">format_string</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="ow">in</span> <span class="p">(</span><span class="s">'"'</span><span class="p">,</span> <span class="s">"'"</span><span class="p">)):</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag's argument should be in quotes"</span> <span class="o">%</span> <span class="n">tag_name</span><span class="p">)</span>
<span class="k">return</span> <span class="n">CurrentTimeNode</span><span class="p">(</span><span class="n">format_string</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span>
</pre></div>
</div>
<p>Notes:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">parser</span></tt> is the template parser object. We don’t need it in this
example.</li>
<li><tt class="docutils literal"><span class="pre">token.contents</span></tt> is a string of the raw contents of the tag. In our
example, it’s <tt class="docutils literal"><span class="pre">'current_time</span> <span class="pre">"%Y-%m-%d</span> <span class="pre">%I:%M</span> <span class="pre">%p"'</span></tt>.</li>
<li>The <tt class="docutils literal"><span class="pre">token.split_contents()</span></tt> method separates the arguments on spaces
while keeping quoted strings together. The more straightforward
<tt class="docutils literal"><span class="pre">token.contents.split()</span></tt> wouldn’t be as robust, as it would naively
split on <em>all</em> spaces, including those within quoted strings. It’s a good
idea to always use <tt class="docutils literal"><span class="pre">token.split_contents()</span></tt>.</li>
<li>This function is responsible for raising
<tt class="docutils literal"><span class="pre">django.template.TemplateSyntaxError</span></tt>, with helpful messages, for
any syntax error.</li>
<li>The <tt class="docutils literal"><span class="pre">TemplateSyntaxError</span></tt> exceptions use the <tt class="docutils literal"><span class="pre">tag_name</span></tt> variable.
Don’t hard-code the tag’s name in your error messages, because that
couples the tag’s name to your function. <tt class="docutils literal"><span class="pre">token.contents.split()[0]</span></tt>
will ‘’always’’ be the name of your tag – even when the tag has no
arguments.</li>
<li>The function returns a <tt class="docutils literal"><span class="pre">CurrentTimeNode</span></tt> with everything the node needs
to know about this tag. In this case, it just passes the argument –
<tt class="docutils literal"><span class="pre">"%Y-%m-%d</span> <span class="pre">%I:%M</span> <span class="pre">%p"</span></tt>. The leading and trailing quotes from the
template tag are removed in <tt class="docutils literal"><span class="pre">format_string[1:-1]</span></tt>.</li>
<li>The parsing is very low-level. The Django developers have experimented
with writing small frameworks on top of this parsing system, using
techniques such as EBNF grammars, but those experiments made the template
engine too slow. It’s low-level because that’s fastest.</li>
</ul>
</div>
<div class="section" id="s-writing-the-renderer">
<span id="writing-the-renderer"></span><h3>Writing the renderer<a class="headerlink" href="#writing-the-renderer" title="Permalink to this headline">¶</a></h3>
<p>The second step in writing custom tags is to define a <tt class="docutils literal"><span class="pre">Node</span></tt> subclass that
has a <tt class="docutils literal"><span class="pre">render()</span></tt> method.</p>
<p>Continuing the above example, we need to define <tt class="docutils literal"><span class="pre">CurrentTimeNode</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">template</span>
<span class="kn">import</span> <span class="nn">datetime</span>
<span class="k">class</span> <span class="nc">CurrentTimeNode</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">format_string</span> <span class="o">=</span> <span class="n">format_string</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="k">return</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">format_string</span><span class="p">)</span>
</pre></div>
</div>
<p>Notes:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">__init__()</span></tt> gets the <tt class="docutils literal"><span class="pre">format_string</span></tt> from <tt class="docutils literal"><span class="pre">do_current_time()</span></tt>.
Always pass any options/parameters/arguments to a <tt class="docutils literal"><span class="pre">Node</span></tt> via its
<tt class="docutils literal"><span class="pre">__init__()</span></tt>.</li>
<li>The <tt class="docutils literal"><span class="pre">render()</span></tt> method is where the work actually happens.</li>
<li><tt class="docutils literal"><span class="pre">render()</span></tt> should never raise <tt class="docutils literal"><span class="pre">TemplateSyntaxError</span></tt> or any other
exception. It should fail silently, just as template filters should.</li>
</ul>
<p>Ultimately, this decoupling of compilation and rendering results in an
efficient template system, because a template can render multiple contexts
without having to be parsed multiple times.</p>
</div>
<div class="section" id="s-auto-escaping-considerations">
<span id="auto-escaping-considerations"></span><h3>Auto-escaping considerations<a class="headerlink" href="#auto-escaping-considerations" title="Permalink to this headline">¶</a></h3>
<p>The output from template tags is <strong>not</strong> automatically run through the
auto-escaping filters. However, there are still a couple of things you should
keep in mind when writing a template tag.</p>
<p>If the <tt class="docutils literal"><span class="pre">render()</span></tt> function of your template stores the result in a context
variable (rather than returning the result in a string), it should take care
to call <tt class="docutils literal"><span class="pre">mark_safe()</span></tt> if appropriate. When the variable is ultimately
rendered, it will be affected by the auto-escape setting in effect at the
time, so content that should be safe from further escaping needs to be marked
as such.</p>
<p>Also, if your template tag creates a new context for performing some
sub-rendering, set the auto-escape attribute to the current context’s value.
The <tt class="docutils literal"><span class="pre">__init__</span></tt> method for the <tt class="docutils literal"><span class="pre">Context</span></tt> class takes a parameter called
<tt class="docutils literal"><span class="pre">autoescape</span></tt> that you can use for this purpose. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="c"># ...</span>
<span class="n">new_context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s">'var'</span><span class="p">:</span> <span class="n">obj</span><span class="p">},</span> <span class="n">autoescape</span><span class="o">=</span><span class="n">context</span><span class="o">.</span><span class="n">autoescape</span><span class="p">)</span>
<span class="c"># ... Do something with new_context ...</span>
</pre></div>
</div>
<p>This is not a very common situation, but it’s useful if you’re rendering a
template yourself. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">template</span><span class="o">.</span><span class="n">loader</span><span class="o">.</span><span class="n">get_template</span><span class="p">(</span><span class="s">'small_fragment.html'</span><span class="p">)</span>
<span class="k">return</span> <span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({</span><span class="s">'var'</span><span class="p">:</span> <span class="n">obj</span><span class="p">},</span> <span class="n">autoescape</span><span class="o">=</span><span class="n">context</span><span class="o">.</span><span class="n">autoescape</span><span class="p">))</span>
</pre></div>
</div>
<p>If we had neglected to pass in the current <tt class="docutils literal"><span class="pre">context.autoescape</span></tt> value to our
new <tt class="docutils literal"><span class="pre">Context</span></tt> in this example, the results would have <em>always</em> been
automatically escaped, which may not be the desired behavior if the template
tag is used inside a <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-autoescape"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">autoescape</span> <span class="pre">off</span> <span class="pre">%}</span></tt></a> block.</p>
</div>
<div class="section" id="s-thread-safety-considerations">
<span id="s-template-tag-thread-safety"></span><span id="thread-safety-considerations"></span><span id="template-tag-thread-safety"></span><h3>Thread-safety considerations<a class="headerlink" href="#thread-safety-considerations" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.2:</span> <a class="reference internal" href="../releases/1.2.html"><em>Please see the release notes</em></a></div>
<p>Once a node is parsed, its <tt class="docutils literal"><span class="pre">render</span></tt> method may be called any number of times.
Since Django is sometimes run in multi-threaded environments, a single node may
be simultaneously rendering with different contexts in response to two separate
requests. Therefore, it’s important to make sure your template tags are thread
safe.</p>
<p>To make sure your template tags are thread safe, you should never store state
information on the node itself. For example, Django provides a builtin
<a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-cycle"><tt class="xref std std-ttag docutils literal"><span class="pre">cycle</span></tt></a> template tag that cycles among a list of given strings each time
it’s rendered:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">for</span> <span class="nv">o</span> <span class="k">in</span> <span class="nv">some_list</span> <span class="cp">%}</span>
<span class="nt"><tr</span> <span class="na">class=</span><span class="s">"</span><span class="cp">{%</span> <span class="k">cycle</span> <span class="s1">'row1'</span> <span class="s1">'row2'</span> <span class="cp">%}</span><span class="nt">></span>
...
<span class="nt"></tr></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>A naive implementation of <tt class="docutils literal"><span class="pre">CycleNode</span></tt> might look something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CycleNode</span><span class="p">(</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cyclevars</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">cycle_iter</span> <span class="o">=</span> <span class="n">itertools</span><span class="o">.</span><span class="n">cycle</span><span class="p">(</span><span class="n">cyclevars</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">cycle_iter</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
</pre></div>
</div>
<p>But, suppose we have two templates rendering the template snippet from above at
the same time:</p>
<ol class="arabic simple">
<li>Thread 1 performs its first loop iteration, <tt class="docutils literal"><span class="pre">CycleNode.render()</span></tt>
returns ‘row1’</li>
<li>Thread 2 performs its first loop iteration, <tt class="docutils literal"><span class="pre">CycleNode.render()</span></tt>
returns ‘row2’</li>
<li>Thread 1 performs its second loop iteration, <tt class="docutils literal"><span class="pre">CycleNode.render()</span></tt>
returns ‘row1’</li>
<li>Thread 2 performs its second loop iteration, <tt class="docutils literal"><span class="pre">CycleNode.render()</span></tt>
returns ‘row2’</li>
</ol>
<p>The CycleNode is iterating, but it’s iterating globally. As far as Thread 1
and Thread 2 are concerned, it’s always returning the same value. This is
obviously not what we want!</p>
<p>To address this problem, Django provides a <tt class="docutils literal"><span class="pre">render_context</span></tt> that’s associated
with the <tt class="docutils literal"><span class="pre">context</span></tt> of the template that is currently being rendered. The
<tt class="docutils literal"><span class="pre">render_context</span></tt> behaves like a Python dictionary, and should be used to
store <tt class="docutils literal"><span class="pre">Node</span></tt> state between invocations of the <tt class="docutils literal"><span class="pre">render</span></tt> method.</p>
<p>Let’s refactor our <tt class="docutils literal"><span class="pre">CycleNode</span></tt> implementation to use the <tt class="docutils literal"><span class="pre">render_context</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CycleNode</span><span class="p">(</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cyclevars</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">cyclevars</span> <span class="o">=</span> <span class="n">cyclevars</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="k">if</span> <span class="bp">self</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">context</span><span class="o">.</span><span class="n">render_context</span><span class="p">:</span>
<span class="n">context</span><span class="o">.</span><span class="n">render_context</span><span class="p">[</span><span class="bp">self</span><span class="p">]</span> <span class="o">=</span> <span class="n">itertools</span><span class="o">.</span><span class="n">cycle</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">cyclevars</span><span class="p">)</span>
<span class="n">cycle_iter</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="n">render_context</span><span class="p">[</span><span class="bp">self</span><span class="p">]</span>
<span class="k">return</span> <span class="n">cycle_iter</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
</pre></div>
</div>
<p>Note that it’s perfectly safe to store global information that will not change
throughout the life of the <tt class="docutils literal"><span class="pre">Node</span></tt> as an attribute. In the case of
<tt class="docutils literal"><span class="pre">CycleNode</span></tt>, the <tt class="docutils literal"><span class="pre">cyclevars</span></tt> argument doesn’t change after the <tt class="docutils literal"><span class="pre">Node</span></tt> is
instantiated, so we don’t need to put it in the <tt class="docutils literal"><span class="pre">render_context</span></tt>. But state
information that is specific to the template that is currently being rendered,
like the current iteration of the <tt class="docutils literal"><span class="pre">CycleNode</span></tt>, should be stored in the
<tt class="docutils literal"><span class="pre">render_context</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Notice how we used <tt class="docutils literal"><span class="pre">self</span></tt> to scope the <tt class="docutils literal"><span class="pre">CycleNode</span></tt> specific information
within the <tt class="docutils literal"><span class="pre">render_context</span></tt>. There may be multiple <tt class="docutils literal"><span class="pre">CycleNodes</span></tt> in a
given template, so we need to be careful not to clobber another node’s
state information. The easiest way to do this is to always use <tt class="docutils literal"><span class="pre">self</span></tt> as
the key into <tt class="docutils literal"><span class="pre">render_context</span></tt>. If you’re keeping track of several state
variables, make <tt class="docutils literal"><span class="pre">render_context[self]</span></tt> a dictionary.</p>
</div>
</div>
<div class="section" id="s-registering-the-tag">
<span id="registering-the-tag"></span><h3>Registering the tag<a class="headerlink" href="#registering-the-tag" title="Permalink to this headline">¶</a></h3>
<p>Finally, register the tag with your module’s <tt class="docutils literal"><span class="pre">Library</span></tt> instance, as explained
in “Writing custom template filters” above. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">register</span><span class="o">.</span><span class="n">tag</span><span class="p">(</span><span class="s">'current_time'</span><span class="p">,</span> <span class="n">do_current_time</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">tag()</span></tt> method takes two arguments:</p>
<ol class="arabic simple">
<li>The name of the template tag – a string. If this is left out, the
name of the compilation function will be used.</li>
<li>The compilation function – a Python function (not the name of the
function as a string).</li>
</ol>
<p>As with filter registration, it is also possible to use this as a decorator:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.tag</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"current_time"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">do_current_time</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="o">...</span>
<span class="nd">@register.tag</span>
<span class="k">def</span> <span class="nf">shout</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>If you leave off the <tt class="docutils literal"><span class="pre">name</span></tt> argument, as in the second example above, Django
will use the function’s name as the tag name.</p>
</div>
<div class="section" id="s-passing-template-variables-to-the-tag">
<span id="passing-template-variables-to-the-tag"></span><h3>Passing template variables to the tag<a class="headerlink" href="#passing-template-variables-to-the-tag" title="Permalink to this headline">¶</a></h3>
<p>Although you can pass any number of arguments to a template tag using
<tt class="docutils literal"><span class="pre">token.split_contents()</span></tt>, the arguments are all unpacked as
string literals. A little more work is required in order to pass dynamic
content (a template variable) to a template tag as an argument.</p>
<p>While the previous examples have formatted the current time into a string and
returned the string, suppose you wanted to pass in a
<a class="reference internal" href="../ref/models/fields.html#django.db.models.DateTimeField" title="django.db.models.DateTimeField"><tt class="xref py py-class docutils literal"><span class="pre">DateTimeField</span></tt></a> from an object and have the template
tag format that date-time:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><p></span>This post was last updated at <span class="cp">{%</span> <span class="k">format_time</span> <span class="nv">blog_entry.date_updated</span> <span class="s2">"%Y-%m-%d %I:%M %p"</span> <span class="cp">%}</span>.<span class="nt"></p></span>
</pre></div>
</div>
<p>Initially, <tt class="docutils literal"><span class="pre">token.split_contents()</span></tt> will return three values:</p>
<ol class="arabic simple">
<li>The tag name <tt class="docutils literal"><span class="pre">format_time</span></tt>.</li>
<li>The string <tt class="docutils literal"><span class="pre">"blog_entry.date_updated"</span></tt> (without the surrounding
quotes).</li>
<li>The formatting string <tt class="docutils literal"><span class="pre">"%Y-%m-%d</span> <span class="pre">%I:%M</span> <span class="pre">%p"</span></tt>. The return value from
<tt class="docutils literal"><span class="pre">split_contents()</span></tt> will include the leading and trailing quotes for
string literals like this.</li>
</ol>
<p>Now your tag should begin to look like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">template</span>
<span class="k">def</span> <span class="nf">do_format_time</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="c"># split_contents() knows not to split quoted strings.</span>
<span class="n">tag_name</span><span class="p">,</span> <span class="n">date_to_be_formatted</span><span class="p">,</span> <span class="n">format_string</span> <span class="o">=</span> <span class="n">token</span><span class="o">.</span><span class="n">split_contents</span><span class="p">()</span>
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag requires exactly two arguments"</span> <span class="o">%</span> <span class="n">token</span><span class="o">.</span><span class="n">contents</span><span class="o">.</span><span class="n">split</span><span class="p">()[</span><span class="mi">0</span><span class="p">])</span>
<span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">format_string</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="n">format_string</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="ow">and</span> <span class="n">format_string</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="ow">in</span> <span class="p">(</span><span class="s">'"'</span><span class="p">,</span> <span class="s">"'"</span><span class="p">)):</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag's argument should be in quotes"</span> <span class="o">%</span> <span class="n">tag_name</span><span class="p">)</span>
<span class="k">return</span> <span class="n">FormatTimeNode</span><span class="p">(</span><span class="n">date_to_be_formatted</span><span class="p">,</span> <span class="n">format_string</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span>
</pre></div>
</div>
<p>You also have to change the renderer to retrieve the actual contents of the
<tt class="docutils literal"><span class="pre">date_updated</span></tt> property of the <tt class="docutils literal"><span class="pre">blog_entry</span></tt> object. This can be
accomplished by using the <tt class="docutils literal"><span class="pre">Variable()</span></tt> class in <tt class="docutils literal"><span class="pre">django.template</span></tt>.</p>
<p>To use the <tt class="docutils literal"><span class="pre">Variable</span></tt> class, simply instantiate it with the name of the
variable to be resolved, and then call <tt class="docutils literal"><span class="pre">variable.resolve(context)</span></tt>. So,
for example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">FormatTimeNode</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">date_to_be_formatted</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">date_to_be_formatted</span> <span class="o">=</span> <span class="n">template</span><span class="o">.</span><span class="n">Variable</span><span class="p">(</span><span class="n">date_to_be_formatted</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">format_string</span> <span class="o">=</span> <span class="n">format_string</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">actual_date</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">date_to_be_formatted</span><span class="o">.</span><span class="n">resolve</span><span class="p">(</span><span class="n">context</span><span class="p">)</span>
<span class="k">return</span> <span class="n">actual_date</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">format_string</span><span class="p">)</span>
<span class="k">except</span> <span class="n">template</span><span class="o">.</span><span class="n">VariableDoesNotExist</span><span class="p">:</span>
<span class="k">return</span> <span class="s">''</span>
</pre></div>
</div>
<p>Variable resolution will throw a <tt class="docutils literal"><span class="pre">VariableDoesNotExist</span></tt> exception if it
cannot resolve the string passed to it in the current context of the page.</p>
</div>
<div class="section" id="s-simple-tags">
<span id="s-howto-custom-template-tags-simple-tags"></span><span id="simple-tags"></span><span id="howto-custom-template-tags-simple-tags"></span><h3>Simple tags<a class="headerlink" href="#simple-tags" title="Permalink to this headline">¶</a></h3>
<p>Many template tags take a number of arguments – strings or template variables
– and return a string after doing some processing based solely on
the input arguments and some external information. For example, the
<tt class="docutils literal"><span class="pre">current_time</span></tt> tag we wrote above is of this variety: we give it a format
string, it returns the time as a string.</p>
<p>To ease the creation of these types of tags, Django provides a helper function,
<tt class="docutils literal"><span class="pre">simple_tag</span></tt>. This function, which is a method of
<tt class="docutils literal"><span class="pre">django.template.Library</span></tt>, takes a function that accepts any number of
arguments, wraps it in a <tt class="docutils literal"><span class="pre">render</span></tt> function and the other necessary bits
mentioned above and registers it with the template system.</p>
<p>Our earlier <tt class="docutils literal"><span class="pre">current_time</span></tt> function could thus be written like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">current_time</span><span class="p">(</span><span class="n">format_string</span><span class="p">):</span>
<span class="k">return</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="n">format_string</span><span class="p">)</span>
<span class="n">register</span><span class="o">.</span><span class="n">simple_tag</span><span class="p">(</span><span class="n">current_time</span><span class="p">)</span>
</pre></div>
</div>
<p>The decorator syntax also works:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.simple_tag</span>
<span class="k">def</span> <span class="nf">current_time</span><span class="p">(</span><span class="n">format_string</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>A few things to note about the <tt class="docutils literal"><span class="pre">simple_tag</span></tt> helper function:</p>
<ul class="simple">
<li>Checking for the required number of arguments, etc., has already been
done by the time our function is called, so we don’t need to do that.</li>
<li>The quotes around the argument (if any) have already been stripped away,
so we just receive a plain string.</li>
<li>If the argument was a template variable, our function is passed the
current value of the variable, not the variable itself.</li>
</ul>
<div class="versionadded">
<span class="title">New in Django 1.3:</span> <a class="reference internal" href="../releases/1.3.html"><em>Please see the release notes</em></a></div>
<p>If your template tag needs to access the current context, you can use the
<tt class="docutils literal"><span class="pre">takes_context</span></tt> argument when registering your tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># The first argument *must* be called "context" here.</span>
<span class="k">def</span> <span class="nf">current_time</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="n">timezone</span> <span class="o">=</span> <span class="n">context</span><span class="p">[</span><span class="s">'timezone'</span><span class="p">]</span>
<span class="k">return</span> <span class="n">your_get_current_time_method</span><span class="p">(</span><span class="n">timezone</span><span class="p">,</span> <span class="n">format_string</span><span class="p">)</span>
<span class="n">register</span><span class="o">.</span><span class="n">simple_tag</span><span class="p">(</span><span class="n">takes_context</span><span class="o">=</span><span class="bp">True</span><span class="p">)(</span><span class="n">current_time</span><span class="p">)</span>
</pre></div>
</div>
<p>Or, using decorator syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.simple_tag</span><span class="p">(</span><span class="n">takes_context</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">current_time</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="n">timezone</span> <span class="o">=</span> <span class="n">context</span><span class="p">[</span><span class="s">'timezone'</span><span class="p">]</span>
<span class="k">return</span> <span class="n">your_get_current_time_method</span><span class="p">(</span><span class="n">timezone</span><span class="p">,</span> <span class="n">format_string</span><span class="p">)</span>
</pre></div>
</div>
<p>For more information on how the <tt class="docutils literal"><span class="pre">takes_context</span></tt> option works, see the section
on <a class="reference internal" href="#howto-custom-template-tags-inclusion-tags"><em>inclusion tags</em></a>.</p>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>If you need to rename your tag, you can provide a custom name for it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">register</span><span class="o">.</span><span class="n">simple_tag</span><span class="p">(</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span> <span class="o">-</span> <span class="mi">1</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'minusone'</span><span class="p">)</span>
<span class="nd">@register.simple_tag</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'minustwo'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">some_function</span><span class="p">(</span><span class="n">value</span><span class="p">):</span>
<span class="k">return</span> <span class="n">value</span> <span class="o">-</span> <span class="mi">2</span>
</pre></div>
</div>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p><tt class="docutils literal"><span class="pre">simple_tag</span></tt> functions may accept any number of positional or keyword
arguments. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.simple_tag</span>
<span class="k">def</span> <span class="nf">my_tag</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">warning</span> <span class="o">=</span> <span class="n">kwargs</span><span class="p">[</span><span class="s">'warning'</span><span class="p">]</span>
<span class="n">profile</span> <span class="o">=</span> <span class="n">kwargs</span><span class="p">[</span><span class="s">'profile'</span><span class="p">]</span>
<span class="o">...</span>
<span class="k">return</span> <span class="o">...</span>
</pre></div>
</div>
<p>Then in the template any number of arguments, separated by spaces, may be
passed to the template tag. Like in Python, the values for keyword arguments
are set using the equal sign (“<tt class="docutils literal"><span class="pre">=</span></tt>”) and must be provided after the
positional arguments. For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">my_tag</span> <span class="m">123</span> <span class="s2">"abcd"</span> <span class="nv">book.title</span> <span class="nv">warning</span><span class="o">=</span><span class="nv">message</span><span class="o">|</span><span class="nf">lower</span> <span class="nv">profile</span><span class="o">=</span><span class="nv">user.profile</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="section" id="s-inclusion-tags">
<span id="s-howto-custom-template-tags-inclusion-tags"></span><span id="inclusion-tags"></span><span id="howto-custom-template-tags-inclusion-tags"></span><h3>Inclusion tags<a class="headerlink" href="#inclusion-tags" title="Permalink to this headline">¶</a></h3>
<p>Another common type of template tag is the type that displays some data by
rendering <em>another</em> template. For example, Django’s admin interface uses custom
template tags to display the buttons along the bottom of the “add/change” form
pages. Those buttons always look the same, but the link targets change
depending on the object being edited – so they’re a perfect case for using a
small template that is filled with details from the current object. (In the
admin’s case, this is the <tt class="docutils literal"><span class="pre">submit_row</span></tt> tag.)</p>
<p>These sorts of tags are called “inclusion tags”.</p>
<p>Writing inclusion tags is probably best demonstrated by example. Let’s write a
tag that outputs a list of choices for a given <tt class="docutils literal"><span class="pre">Poll</span></tt> object, such as was
created in the <a class="reference internal" href="../intro/tutorial01.html#creating-models"><em>tutorials</em></a>. We’ll use the tag like this:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">show_results</span> <span class="nv">poll</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>...and the output will be something like this:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><ul></span>
<span class="nt"><li></span>First choice<span class="nt"></li></span>
<span class="nt"><li></span>Second choice<span class="nt"></li></span>
<span class="nt"><li></span>Third choice<span class="nt"></li></span>
<span class="nt"></ul></span>
</pre></div>
</div>
<p>First, define the function that takes the argument and produces a dictionary of
data for the result. The important point here is we only need to return a
dictionary, not anything more complex. This will be used as a template context
for the template fragment. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">show_results</span><span class="p">(</span><span class="n">poll</span><span class="p">):</span>
<span class="n">choices</span> <span class="o">=</span> <span class="n">poll</span><span class="o">.</span><span class="n">choice_set</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<span class="k">return</span> <span class="p">{</span><span class="s">'choices'</span><span class="p">:</span> <span class="n">choices</span><span class="p">}</span>
</pre></div>
</div>
<p>Next, create the template used to render the tag’s output. This template is a
fixed feature of the tag: the tag writer specifies it, not the template
designer. Following our example, the template is very simple:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt"><ul></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">choice</span> <span class="k">in</span> <span class="nv">choices</span> <span class="cp">%}</span>
<span class="nt"><li></span> <span class="cp">{{</span> <span class="nv">choice</span> <span class="cp">}}</span> <span class="nt"></li></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="nt"></ul></span>
</pre></div>
</div>
<p>Now, create and register the inclusion tag by calling the <tt class="docutils literal"><span class="pre">inclusion_tag()</span></tt>
method on a <tt class="docutils literal"><span class="pre">Library</span></tt> object. Following our example, if the above template is
in a file called <tt class="docutils literal"><span class="pre">results.html</span></tt> in a directory that’s searched by the
template loader, we’d register the tag like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Here, register is a django.template.Library instance, as before</span>
<span class="n">register</span><span class="o">.</span><span class="n">inclusion_tag</span><span class="p">(</span><span class="s">'results.html'</span><span class="p">)(</span><span class="n">show_results</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>As always, decorator syntax works as well, so we could have written:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.inclusion_tag</span><span class="p">(</span><span class="s">'results.html'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">show_results</span><span class="p">(</span><span class="n">poll</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>...when first creating the function.</p>
<p>Sometimes, your inclusion tags might require a large number of arguments,
making it a pain for template authors to pass in all the arguments and remember
their order. To solve this, Django provides a <tt class="docutils literal"><span class="pre">takes_context</span></tt> option for
inclusion tags. If you specify <tt class="docutils literal"><span class="pre">takes_context</span></tt> in creating a template tag,
the tag will have no required arguments, and the underlying Python function
will have one argument – the template context as of when the tag was called.</p>
<p>For example, say you’re writing an inclusion tag that will always be used in a
context that contains <tt class="docutils literal"><span class="pre">home_link</span></tt> and <tt class="docutils literal"><span class="pre">home_title</span></tt> variables that point
back to the main page. Here’s what the Python function would look like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># The first argument *must* be called "context" here.</span>
<span class="k">def</span> <span class="nf">jump_link</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="k">return</span> <span class="p">{</span>
<span class="s">'link'</span><span class="p">:</span> <span class="n">context</span><span class="p">[</span><span class="s">'home_link'</span><span class="p">],</span>
<span class="s">'title'</span><span class="p">:</span> <span class="n">context</span><span class="p">[</span><span class="s">'home_title'</span><span class="p">],</span>
<span class="p">}</span>
<span class="c"># Register the custom tag as an inclusion tag with takes_context=True.</span>
<span class="n">register</span><span class="o">.</span><span class="n">inclusion_tag</span><span class="p">(</span><span class="s">'link.html'</span><span class="p">,</span> <span class="n">takes_context</span><span class="o">=</span><span class="bp">True</span><span class="p">)(</span><span class="n">jump_link</span><span class="p">)</span>
</pre></div>
</div>
<p>(Note that the first parameter to the function <em>must</em> be called <tt class="docutils literal"><span class="pre">context</span></tt>.)</p>
<p>In that <tt class="docutils literal"><span class="pre">register.inclusion_tag()</span></tt> line, we specified <tt class="docutils literal"><span class="pre">takes_context=True</span></tt>
and the name of the template. Here’s what the template <tt class="docutils literal"><span class="pre">link.html</span></tt> might look
like:</p>
<div class="highlight-html+django"><div class="highlight"><pre>Jump directly to <span class="nt"><a</span> <span class="na">href=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">link</span> <span class="cp">}}</span><span class="s">"</span><span class="nt">></span><span class="cp">{{</span> <span class="nv">title</span> <span class="cp">}}</span><span class="nt"></a></span>.
</pre></div>
</div>
<p>Then, any time you want to use that custom tag, load its library and call it
without any arguments, like so:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">jump_link</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Note that when you’re using <tt class="docutils literal"><span class="pre">takes_context=True</span></tt>, there’s no need to pass
arguments to the template tag. It automatically gets access to the context.</p>
<p>The <tt class="docutils literal"><span class="pre">takes_context</span></tt> parameter defaults to <tt class="docutils literal"><span class="pre">False</span></tt>. When it’s set to
<tt class="docutils literal"><span class="pre">True</span></tt>, the tag is passed the context object, as in this example. That’s the
only difference between this case and the previous <tt class="docutils literal"><span class="pre">inclusion_tag</span></tt> example.</p>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p><tt class="docutils literal"><span class="pre">inclusion_tag</span></tt> functions may accept any number of positional or keyword
arguments. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.inclusion_tag</span><span class="p">(</span><span class="s">'my_template.html'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">my_tag</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">warning</span> <span class="o">=</span> <span class="n">kwargs</span><span class="p">[</span><span class="s">'warning'</span><span class="p">]</span>
<span class="n">profile</span> <span class="o">=</span> <span class="n">kwargs</span><span class="p">[</span><span class="s">'profile'</span><span class="p">]</span>
<span class="o">...</span>
<span class="k">return</span> <span class="o">...</span>
</pre></div>
</div>
<p>Then in the template any number of arguments, separated by spaces, may be
passed to the template tag. Like in Python, the values for keyword arguments
are set using the equal sign (“<tt class="docutils literal"><span class="pre">=</span></tt>”) and must be provided after the
positional arguments. For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">my_tag</span> <span class="m">123</span> <span class="s2">"abcd"</span> <span class="nv">book.title</span> <span class="nv">warning</span><span class="o">=</span><span class="nv">message</span><span class="o">|</span><span class="nf">lower</span> <span class="nv">profile</span><span class="o">=</span><span class="nv">user.profile</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="section" id="s-setting-a-variable-in-the-context">
<span id="setting-a-variable-in-the-context"></span><h3>Setting a variable in the context<a class="headerlink" href="#setting-a-variable-in-the-context" title="Permalink to this headline">¶</a></h3>
<p>The above examples simply output a value. Generally, it’s more flexible if your
template tags set template variables instead of outputting values. That way,
template authors can reuse the values that your template tags create.</p>
<p>To set a variable in the context, just use dictionary assignment on the context
object in the <tt class="docutils literal"><span class="pre">render()</span></tt> method. Here’s an updated version of
<tt class="docutils literal"><span class="pre">CurrentTimeNode</span></tt> that sets a template variable <tt class="docutils literal"><span class="pre">current_time</span></tt> instead of
outputting it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CurrentTimeNode2</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">format_string</span> <span class="o">=</span> <span class="n">format_string</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="n">context</span><span class="p">[</span><span class="s">'current_time'</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">format_string</span><span class="p">)</span>
<span class="k">return</span> <span class="s">''</span>
</pre></div>
</div>
<p>Note that <tt class="docutils literal"><span class="pre">render()</span></tt> returns the empty string. <tt class="docutils literal"><span class="pre">render()</span></tt> should always
return string output. If all the template tag does is set a variable,
<tt class="docutils literal"><span class="pre">render()</span></tt> should return the empty string.</p>
<p>Here’s how you’d use this new version of the tag:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">current_time</span> <span class="s2">"%Y-%M-%d %I:%M %p"</span> <span class="cp">%}</span><span class="nt"><p></span>The time is <span class="cp">{{</span> <span class="nv">current_time</span> <span class="cp">}}</span>.<span class="nt"></p></span>
</pre></div>
</div>
<div class="admonition-variable-scope-in-context admonition">
<p class="first admonition-title">Variable scope in context</p>
<p class="last">Any variable set in the context will only be available in the same
<tt class="docutils literal"><span class="pre">block</span></tt> of the template in which it was assigned. This behavior is
intentional; it provides a scope for variables so that they don’t conflict
with context in other blocks.</p>
</div>
<p>But, there’s a problem with <tt class="docutils literal"><span class="pre">CurrentTimeNode2</span></tt>: The variable name
<tt class="docutils literal"><span class="pre">current_time</span></tt> is hard-coded. This means you’ll need to make sure your
template doesn’t use <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">current_time</span> <span class="pre">}}</span></tt> anywhere else, because the
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">current_time</span> <span class="pre">%}</span></tt> will blindly overwrite that variable’s value. A cleaner
solution is to make the template tag specify the name of the output variable,
like so:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">current_time</span> <span class="s2">"%Y-%M-%d %I:%M %p"</span> <span class="k">as</span> <span class="nv">my_current_time</span> <span class="cp">%}</span>
<span class="nt"><p></span>The current time is <span class="cp">{{</span> <span class="nv">my_current_time</span> <span class="cp">}}</span>.<span class="nt"></p></span>
</pre></div>
</div>
<p>To do that, you’ll need to refactor both the compilation function and <tt class="docutils literal"><span class="pre">Node</span></tt>
class, like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CurrentTimeNode3</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">format_string</span><span class="p">,</span> <span class="n">var_name</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">format_string</span> <span class="o">=</span> <span class="n">format_string</span>
<span class="bp">self</span><span class="o">.</span><span class="n">var_name</span> <span class="o">=</span> <span class="n">var_name</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="n">context</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">var_name</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">format_string</span><span class="p">)</span>
<span class="k">return</span> <span class="s">''</span>
<span class="kn">import</span> <span class="nn">re</span>
<span class="k">def</span> <span class="nf">do_current_time</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="c"># This version uses a regular expression to parse tag contents.</span>
<span class="k">try</span><span class="p">:</span>
<span class="c"># Splitting by None == splitting by spaces.</span>
<span class="n">tag_name</span><span class="p">,</span> <span class="n">arg</span> <span class="o">=</span> <span class="n">token</span><span class="o">.</span><span class="n">contents</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag requires arguments"</span> <span class="o">%</span> <span class="n">token</span><span class="o">.</span><span class="n">contents</span><span class="o">.</span><span class="n">split</span><span class="p">()[</span><span class="mi">0</span><span class="p">])</span>
<span class="n">m</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">r'(.*?) as (\w+)'</span><span class="p">,</span> <span class="n">arg</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">m</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag had invalid arguments"</span> <span class="o">%</span> <span class="n">tag_name</span><span class="p">)</span>
<span class="n">format_string</span><span class="p">,</span> <span class="n">var_name</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">groups</span><span class="p">()</span>
<span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">format_string</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="n">format_string</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="ow">and</span> <span class="n">format_string</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="ow">in</span> <span class="p">(</span><span class="s">'"'</span><span class="p">,</span> <span class="s">"'"</span><span class="p">)):</span>
<span class="k">raise</span> <span class="n">template</span><span class="o">.</span><span class="n">TemplateSyntaxError</span><span class="p">(</span><span class="s">"</span><span class="si">%r</span><span class="s"> tag's argument should be in quotes"</span> <span class="o">%</span> <span class="n">tag_name</span><span class="p">)</span>
<span class="k">return</span> <span class="n">CurrentTimeNode3</span><span class="p">(</span><span class="n">format_string</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="o">-</span><span class="mi">1</span><span class="p">],</span> <span class="n">var_name</span><span class="p">)</span>
</pre></div>
</div>
<p>The difference here is that <tt class="docutils literal"><span class="pre">do_current_time()</span></tt> grabs the format string and
the variable name, passing both to <tt class="docutils literal"><span class="pre">CurrentTimeNode3</span></tt>.</p>
<p>Finally, if you only need to have a simple syntax for your custom
context-updating template tag, you might want to consider using an
<a class="reference internal" href="#howto-custom-template-tags-assignment-tags"><em>assignment tag</em></a>.</p>
</div>
<div class="section" id="s-assignment-tags">
<span id="s-howto-custom-template-tags-assignment-tags"></span><span id="assignment-tags"></span><span id="howto-custom-template-tags-assignment-tags"></span><h3>Assignment tags<a class="headerlink" href="#assignment-tags" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<span class="title">New in Django 1.4:</span> <a class="reference internal" href="../releases/1.4.html"><em>Please see the release notes</em></a></div>
<p>To ease the creation of tags setting a variable in the context, Django provides
a helper function, <tt class="docutils literal"><span class="pre">assignment_tag</span></tt>. This function works the same way as
<a class="reference internal" href="#howto-custom-template-tags-simple-tags"><em>simple_tag</em></a>, except that it
stores the tag’s result in a specified context variable instead of directly
outputting it.</p>
<p>Our earlier <tt class="docutils literal"><span class="pre">current_time</span></tt> function could thus be written like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_current_time</span><span class="p">(</span><span class="n">format_string</span><span class="p">):</span>
<span class="k">return</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="n">format_string</span><span class="p">)</span>
<span class="n">register</span><span class="o">.</span><span class="n">assignment_tag</span><span class="p">(</span><span class="n">get_current_time</span><span class="p">)</span>
</pre></div>
</div>
<p>The decorator syntax also works:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.assignment_tag</span>
<span class="k">def</span> <span class="nf">get_current_time</span><span class="p">(</span><span class="n">format_string</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>You may then store the result in a template variable using the <tt class="docutils literal"><span class="pre">as</span></tt> argument
followed by the variable name, and output it yourself where you see fit:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">get_current_time</span> <span class="s2">"%Y-%m-%d %I:%M %p"</span> <span class="k">as</span> <span class="nv">the_time</span> <span class="cp">%}</span>
<span class="nt"><p></span>The time is <span class="cp">{{</span> <span class="nv">the_time</span> <span class="cp">}}</span>.<span class="nt"></p></span>
</pre></div>
</div>
<p>If your template tag needs to access the current context, you can use the
<tt class="docutils literal"><span class="pre">takes_context</span></tt> argument when registering your tag:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># The first argument *must* be called "context" here.</span>
<span class="k">def</span> <span class="nf">get_current_time</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="n">timezone</span> <span class="o">=</span> <span class="n">context</span><span class="p">[</span><span class="s">'timezone'</span><span class="p">]</span>
<span class="k">return</span> <span class="n">your_get_current_time_method</span><span class="p">(</span><span class="n">timezone</span><span class="p">,</span> <span class="n">format_string</span><span class="p">)</span>
<span class="n">register</span><span class="o">.</span><span class="n">assignment_tag</span><span class="p">(</span><span class="n">takes_context</span><span class="o">=</span><span class="bp">True</span><span class="p">)(</span><span class="n">get_current_time</span><span class="p">)</span>
</pre></div>
</div>
<p>Or, using decorator syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.assignment_tag</span><span class="p">(</span><span class="n">takes_context</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">get_current_time</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">format_string</span><span class="p">):</span>
<span class="n">timezone</span> <span class="o">=</span> <span class="n">context</span><span class="p">[</span><span class="s">'timezone'</span><span class="p">]</span>
<span class="k">return</span> <span class="n">your_get_current_time_method</span><span class="p">(</span><span class="n">timezone</span><span class="p">,</span> <span class="n">format_string</span><span class="p">)</span>
</pre></div>
</div>
<p>For more information on how the <tt class="docutils literal"><span class="pre">takes_context</span></tt> option works, see the section
on <a class="reference internal" href="#howto-custom-template-tags-inclusion-tags"><em>inclusion tags</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">assignment_tag</span></tt> functions may accept any number of positional or keyword
arguments. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@register.assignment_tag</span>
<span class="k">def</span> <span class="nf">my_tag</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">warning</span> <span class="o">=</span> <span class="n">kwargs</span><span class="p">[</span><span class="s">'warning'</span><span class="p">]</span>
<span class="n">profile</span> <span class="o">=</span> <span class="n">kwargs</span><span class="p">[</span><span class="s">'profile'</span><span class="p">]</span>
<span class="o">...</span>
<span class="k">return</span> <span class="o">...</span>
</pre></div>
</div>
<p>Then in the template any number of arguments, separated by spaces, may be
passed to the template tag. Like in Python, the values for keyword arguments
are set using the equal sign (“<tt class="docutils literal"><span class="pre">=</span></tt>”) and must be provided after the
positional arguments. For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">my_tag</span> <span class="m">123</span> <span class="s2">"abcd"</span> <span class="nv">book.title</span> <span class="nv">warning</span><span class="o">=</span><span class="nv">message</span><span class="o">|</span><span class="nf">lower</span> <span class="nv">profile</span><span class="o">=</span><span class="nv">user.profile</span> <span class="k">as</span> <span class="nv">the_result</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="section" id="s-parsing-until-another-block-tag">
<span id="parsing-until-another-block-tag"></span><h3>Parsing until another block tag<a class="headerlink" href="#parsing-until-another-block-tag" title="Permalink to this headline">¶</a></h3>
<p>Template tags can work in tandem. For instance, the standard
<a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-comment"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt></a> tag hides everything until <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt>.
To create a template tag such as this, use <tt class="docutils literal"><span class="pre">parser.parse()</span></tt> in your
compilation function.</p>
<p>Here’s how a simplified <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt> tag might be implemented:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">do_comment</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="n">nodelist</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">((</span><span class="s">'endcomment'</span><span class="p">,))</span>
<span class="n">parser</span><span class="o">.</span><span class="n">delete_first_token</span><span class="p">()</span>
<span class="k">return</span> <span class="n">CommentNode</span><span class="p">()</span>
<span class="k">class</span> <span class="nc">CommentNode</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="k">return</span> <span class="s">''</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The actual implementation of <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-comment"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt></a> is slightly
different in that it allows broken template tags to appear between
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt> and <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt>. It does so by calling
<tt class="docutils literal"><span class="pre">parser.skip_past('endcomment')</span></tt> instead of <tt class="docutils literal"><span class="pre">parser.parse(('endcomment',))</span></tt>
followed by <tt class="docutils literal"><span class="pre">parser.delete_first_token()</span></tt>, thus avoiding the generation of a
node list.</p>
</div>
<p><tt class="docutils literal"><span class="pre">parser.parse()</span></tt> takes a tuple of names of block tags ‘’to parse until’‘. It
returns an instance of <tt class="docutils literal"><span class="pre">django.template.NodeList</span></tt>, which is a list of
all <tt class="docutils literal"><span class="pre">Node</span></tt> objects that the parser encountered ‘’before’’ it encountered
any of the tags named in the tuple.</p>
<p>In <tt class="docutils literal"><span class="pre">"nodelist</span> <span class="pre">=</span> <span class="pre">parser.parse(('endcomment',))"</span></tt> in the above example,
<tt class="docutils literal"><span class="pre">nodelist</span></tt> is a list of all nodes between the <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt> and
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt>, not counting <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt> and <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt>
themselves.</p>
<p>After <tt class="docutils literal"><span class="pre">parser.parse()</span></tt> is called, the parser hasn’t yet “consumed” the
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt> tag, so the code needs to explicitly call
<tt class="docutils literal"><span class="pre">parser.delete_first_token()</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">CommentNode.render()</span></tt> simply returns an empty string. Anything between
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt> and <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt> is ignored.</p>
</div>
<div class="section" id="s-parsing-until-another-block-tag-and-saving-contents">
<span id="parsing-until-another-block-tag-and-saving-contents"></span><h3>Parsing until another block tag, and saving contents<a class="headerlink" href="#parsing-until-another-block-tag-and-saving-contents" title="Permalink to this headline">¶</a></h3>
<p>In the previous example, <tt class="docutils literal"><span class="pre">do_comment()</span></tt> discarded everything between
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">comment</span> <span class="pre">%}</span></tt> and <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endcomment</span> <span class="pre">%}</span></tt>. Instead of doing that, it’s
possible to do something with the code between block tags.</p>
<p>For example, here’s a custom template tag, <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">upper</span> <span class="pre">%}</span></tt>, that capitalizes
everything between itself and <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endupper</span> <span class="pre">%}</span></tt>.</p>
<p>Usage:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">upper</span> <span class="cp">%}</span>This will appear in uppercase, <span class="cp">{{</span> <span class="nv">your_name</span> <span class="cp">}}</span>.<span class="cp">{%</span> <span class="k">endupper</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>As in the previous example, we’ll use <tt class="docutils literal"><span class="pre">parser.parse()</span></tt>. But this time, we
pass the resulting <tt class="docutils literal"><span class="pre">nodelist</span></tt> to the <tt class="docutils literal"><span class="pre">Node</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">do_upper</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="n">token</span><span class="p">):</span>
<span class="n">nodelist</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">((</span><span class="s">'endupper'</span><span class="p">,))</span>
<span class="n">parser</span><span class="o">.</span><span class="n">delete_first_token</span><span class="p">()</span>
<span class="k">return</span> <span class="n">UpperNode</span><span class="p">(</span><span class="n">nodelist</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">UpperNode</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">Node</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">nodelist</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">nodelist</span> <span class="o">=</span> <span class="n">nodelist</span>
<span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">context</span><span class="p">):</span>
<span class="n">output</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">nodelist</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">context</span><span class="p">)</span>
<span class="k">return</span> <span class="n">output</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
</pre></div>
</div>
<p>The only new concept here is the <tt class="docutils literal"><span class="pre">self.nodelist.render(context)</span></tt> in
<tt class="docutils literal"><span class="pre">UpperNode.render()</span></tt>.</p>
<p>For more examples of complex rendering, see the source code for
<a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-if"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">if</span> <span class="pre">%}</span></tt></a>, <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-for"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">for</span> <span class="pre">%}</span></tt></a>, <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-ifequal"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">ifequal</span> <span class="pre">%}</span></tt></a>
or <a class="reference internal" href="../ref/templates/builtins.html#std:templatetag-ifchanged"><tt class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">ifchanged</span> <span class="pre">%}</span></tt></a>. They live in
<tt class="docutils literal"><span class="pre">django/template/defaulttags.py</span></tt>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Custom template tags and filters</a><ul>
<li><a class="reference internal" href="#code-layout">Code layout</a></li>
<li><a class="reference internal" href="#writing-custom-template-filters">Writing custom template filters</a><ul>
<li><a class="reference internal" href="#registering-custom-filters">Registering custom filters</a></li>
<li><a class="reference internal" href="#template-filters-that-expect-strings">Template filters that expect strings</a></li>
<li><a class="reference internal" href="#filters-and-auto-escaping">Filters and auto-escaping</a></li>
<li><a class="reference internal" href="#filters-and-time-zones">Filters and time zones</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-custom-template-tags">Writing custom template tags</a><ul>
<li><a class="reference internal" href="#a-quick-overview">A quick overview</a></li>
<li><a class="reference internal" href="#writing-the-compilation-function">Writing the compilation function</a></li>
<li><a class="reference internal" href="#writing-the-renderer">Writing the renderer</a></li>
<li><a class="reference internal" href="#auto-escaping-considerations">Auto-escaping considerations</a></li>
<li><a class="reference internal" href="#thread-safety-considerations">Thread-safety considerations</a></li>
<li><a class="reference internal" href="#registering-the-tag">Registering the tag</a></li>
<li><a class="reference internal" href="#passing-template-variables-to-the-tag">Passing template variables to the tag</a></li>
<li><a class="reference internal" href="#simple-tags">Simple tags</a></li>
<li><a class="reference internal" href="#inclusion-tags">Inclusion tags</a></li>
<li><a class="reference internal" href="#setting-a-variable-in-the-context">Setting a variable in the context</a></li>
<li><a class="reference internal" href="#assignment-tags">Assignment tags</a></li>
<li><a class="reference internal" href="#parsing-until-another-block-tag">Parsing until another block tag</a></li>
<li><a class="reference internal" href="#parsing-until-another-block-tag-and-saving-contents">Parsing until another block tag, and saving contents</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="custom-model-fields.html">Writing custom model fields</a></li>
<li>Next: <a href="custom-file-storage.html">Writing a custom storage system</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.4.5 documentation</a>
<ul><li><a href="index.html">“How-to” guides</a>
<ul><li>Custom template tags and filters</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/howto/custom-template-tags.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 21, 2013</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="custom-model-fields.html" title="Writing custom model fields">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="custom-file-storage.html" title="Writing a custom storage system">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
