<!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" lang="">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The Django template language — Django 1.8.19 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.8.19',
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="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="top" title="Django 1.8.19 documentation" href="../../contents.html" />
<link rel="up" title="Templates" href="index.html" />
<link rel="next" title="Built-in template tags and filters" href="builtins.html" />
<link rel="prev" title="Templates" href="index.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 = "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 role="document">
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.8.19 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="index.html" title="Templates">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="builtins.html" title="Built-in template tags and filters">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-templates-language">
<div class="section" id="s-the-django-template-language">
<span id="the-django-template-language"></span><h1>The Django template language<a class="headerlink" href="#the-django-template-language" title="Permalink to this headline">¶</a></h1>
<p>This document explains the language syntax of the Django template system. If
you’re looking for a more technical perspective on how it works and how to
extend it, see <a class="reference internal" href="api.html"><span class="doc">The Django template language: for Python programmers</span></a>.</p>
<p>Django’s template language is designed to strike a balance between power and
ease. It’s designed to feel comfortable to those used to working with HTML. If
you have any exposure to other text-based template languages, such as <a class="reference external" href="http://www.smarty.net/">Smarty</a>
or <a class="reference external" href="http://jinja.pocoo.org/">Jinja2</a>, you should feel right at home with Django’s templates.</p>
<div class="admonition-philosophy admonition">
<p class="first admonition-title">Philosophy</p>
<p>If you have a background in programming, or if you’re used to languages
which mix programming code directly into HTML, you’ll want to bear in
mind that the Django template system is not simply Python embedded into
HTML. This is by design: the template system is meant to express
presentation, not program logic.</p>
<p class="last">The Django template system provides tags which function similarly to some
programming constructs – an <a class="reference internal" href="builtins.html#std:templatetag-if"><code class="xref std std-ttag docutils literal"><span class="pre">if</span></code></a> tag for boolean tests, a <a class="reference internal" href="builtins.html#std:templatetag-for"><code class="xref std std-ttag docutils literal"><span class="pre">for</span></code></a>
tag for looping, etc. – but these are not simply executed as the
corresponding Python code, and the template system will not execute
arbitrary Python expressions. Only the tags, filters and syntax listed below
are supported by default (although you can add <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">your own extensions</span></a> to the template language as needed).</p>
</div>
<div class="section" id="s-templates">
<span id="templates"></span><h2>Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h2>
<p>A template is simply a text file. It can generate any text-based format (HTML,
XML, CSV, etc.).</p>
<p>A template contains <strong>variables</strong>, which get replaced with values when the
template is evaluated, and <strong>tags</strong>, which control the logic of the template.</p>
<p>Below is a minimal template that illustrates a few basics. Each element will be
explained later in this document.</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">"base_generic.html"</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{{</span> <span class="nv">section.title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">h1</span><span class="p">></span><span class="cp">{{</span> <span class="nv">section.title</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">h1</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">story</span> <span class="k">in</span> <span class="nv">story_list</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">h2</span><span class="p">></span>
<span class="p"><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">story.get_absolute_url</span> <span class="cp">}}</span><span class="s">"</span><span class="p">></span>
<span class="cp">{{</span> <span class="nv">story.headline</span><span class="o">|</span><span class="nf">upper</span> <span class="cp">}}</span>
<span class="p"></</span><span class="nt">a</span><span class="p">></span>
<span class="p"></</span><span class="nt">h2</span><span class="p">></span>
<span class="p"><</span><span class="nt">p</span><span class="p">></span><span class="cp">{{</span> <span class="nv">story.tease</span><span class="o">|</span><span class="nf">truncatewords</span><span class="s2">:"100"</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">p</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<div class="admonition-philosophy admonition">
<p class="first admonition-title">Philosophy</p>
<p>Why use a text-based template instead of an XML-based one (like Zope’s
TAL)? We wanted Django’s template language to be usable for more than
just XML/HTML templates. At World Online, we use it for emails,
JavaScript and CSV. You can use the template language for any text-based
format.</p>
<p class="last">Oh, and one more thing: making humans edit XML is sadistic!</p>
</div>
</div>
<div class="section" id="s-variables">
<span id="s-template-variables"></span><span id="variables"></span><span id="template-variables"></span><h2>Variables<a class="headerlink" href="#variables" title="Permalink to this headline">¶</a></h2>
<p>Variables look like this: <code class="docutils literal"><span class="pre">{{</span> <span class="pre">variable</span> <span class="pre">}}</span></code>. When the template engine
encounters a variable, it evaluates that variable and replaces it with the
result. Variable names consist of any combination of alphanumeric characters
and the underscore (<code class="docutils literal"><span class="pre">"_"</span></code>). The dot (<code class="docutils literal"><span class="pre">"."</span></code>) also appears in variable
sections, although that has a special meaning, as indicated below.
Importantly, <em>you cannot have spaces or punctuation characters in variable
names.</em></p>
<p>Use a dot (<code class="docutils literal"><span class="pre">.</span></code>) to access attributes of a variable.</p>
<div class="admonition-behind-the-scenes admonition">
<p class="first admonition-title">Behind the scenes</p>
<p>Technically, when the template system encounters a dot, it tries the
following lookups, in this order:</p>
<ul class="simple">
<li>Dictionary lookup</li>
<li>Attribute or method lookup</li>
<li>Numeric index lookup</li>
</ul>
<p>If the resulting value is callable, it is called with no arguments. The
result of the call becomes the template value.</p>
<p>This lookup order can cause some unexpected behavior with objects that
override dictionary lookup. For example, consider the following code snippet
that attempts to loop over a <code class="docutils literal"><span class="pre">collections.defaultdict</span></code>:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">k</span><span class="o">,</span> <span class="nv">v</span> <span class="k">in</span> <span class="nv">defaultdict.iteritems</span> <span class="cp">%}</span>
Do something with k and v here...
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p class="last">Because dictionary lookup happens first, that behavior kicks in and provides
a default value instead of using the intended <code class="docutils literal"><span class="pre">.iteritems()</span></code>
method. In this case, consider converting to a dictionary first.</p>
</div>
<p>In the above example, <code class="docutils literal"><span class="pre">{{</span> <span class="pre">section.title</span> <span class="pre">}}</span></code> will be replaced with the
<code class="docutils literal"><span class="pre">title</span></code> attribute of the <code class="docutils literal"><span class="pre">section</span></code> object.</p>
<p>If you use a variable that doesn’t exist, the template system will insert the
value of the <code class="docutils literal"><span class="pre">string_if_invalid</span></code> option, which is set to <code class="docutils literal"><span class="pre">''</span></code> (the empty
string) by default.</p>
<p>Note that “bar” in a template expression like <code class="docutils literal"><span class="pre">{{</span> <span class="pre">foo.bar</span> <span class="pre">}}</span></code> will be
interpreted as a literal string and not using the value of the variable “bar”,
if one exists in the template context.</p>
</div>
<div class="section" id="s-filters">
<span id="filters"></span><h2>Filters<a class="headerlink" href="#filters" title="Permalink to this headline">¶</a></h2>
<p>You can modify variables for display by using <strong>filters</strong>.</p>
<p>Filters look like this: <code class="docutils literal"><span class="pre">{{</span> <span class="pre">name|lower</span> <span class="pre">}}</span></code>. This displays the value of the
<code class="docutils literal"><span class="pre">{{</span> <span class="pre">name</span> <span class="pre">}}</span></code> variable after being filtered through the <a class="reference internal" href="builtins.html#std:templatefilter-lower"><code class="xref std std-tfilter docutils literal"><span class="pre">lower</span></code></a>
filter, which converts text to lowercase. Use a pipe (<code class="docutils literal"><span class="pre">|</span></code>) to apply a filter.</p>
<p>Filters can be “chained.” The output of one filter is applied to the next.
<code class="docutils literal"><span class="pre">{{</span> <span class="pre">text|escape|linebreaks</span> <span class="pre">}}</span></code> is a common idiom for escaping text contents,
then converting line breaks to <code class="docutils literal"><span class="pre"><p></span></code> tags.</p>
<p>Some filters take arguments. A filter argument looks like this: <code class="docutils literal"><span class="pre">{{</span>
<span class="pre">bio|truncatewords:30</span> <span class="pre">}}</span></code>. This will display the first 30 words of the <code class="docutils literal"><span class="pre">bio</span></code>
variable.</p>
<p>Filter arguments that contain spaces must be quoted; for example, to join a
list with commas and spaces you’d use <code class="docutils literal"><span class="pre">{{</span> <span class="pre">list|join:",</span> <span class="pre">"</span> <span class="pre">}}</span></code>.</p>
<p>Django provides about sixty built-in template filters. You can read all about
them in the <a class="reference internal" href="builtins.html#ref-templates-builtins-filters"><span class="std std-ref">built-in filter reference</span></a>.
To give you a taste of what’s available, here are some of the more commonly
used template filters:</p>
<dl class="docutils">
<dt><a class="reference internal" href="builtins.html#std:templatefilter-default"><code class="xref std std-tfilter docutils literal"><span class="pre">default</span></code></a></dt>
<dd><p class="first">If a variable is false or empty, use given default. Otherwise, use the
value of the variable. For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">default</span><span class="s2">:"nothing"</span> <span class="cp">}}</span>
</pre></div>
</div>
<p class="last">If <code class="docutils literal"><span class="pre">value</span></code> isn’t provided or is empty, the above will display
“<code class="docutils literal"><span class="pre">nothing</span></code>”.</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std:templatefilter-length"><code class="xref std std-tfilter docutils literal"><span class="pre">length</span></code></a></dt>
<dd><p class="first">Returns the length of the value. This works for both strings and lists.
For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">length</span> <span class="cp">}}</span>
</pre></div>
</div>
<p class="last">If <code class="docutils literal"><span class="pre">value</span></code> is <code class="docutils literal"><span class="pre">['a',</span> <span class="pre">'b',</span> <span class="pre">'c',</span> <span class="pre">'d']</span></code>, the output will be <code class="docutils literal"><span class="pre">4</span></code>.</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std:templatefilter-filesizeformat"><code class="xref std std-tfilter docutils literal"><span class="pre">filesizeformat</span></code></a></dt>
<dd><p class="first">Formats the value like a “human-readable” file size (i.e. <code class="docutils literal"><span class="pre">'13</span> <span class="pre">KB'</span></code>,
<code class="docutils literal"><span class="pre">'4.1</span> <span class="pre">MB'</span></code>, <code class="docutils literal"><span class="pre">'102</span> <span class="pre">bytes'</span></code>, etc). For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">filesizeformat</span> <span class="cp">}}</span>
</pre></div>
</div>
<p class="last">If <code class="docutils literal"><span class="pre">value</span></code> is 123456789, the output would be <code class="docutils literal"><span class="pre">117.7</span> <span class="pre">MB</span></code>.</p>
</dd>
</dl>
<p>Again, these are just a few examples; see the <a class="reference internal" href="builtins.html#ref-templates-builtins-filters"><span class="std std-ref">built-in filter reference</span></a> for the complete list.</p>
<p>You can also create your own custom template filters; see
<a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">Custom template tags and filters</span></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">Django’s admin interface can include a complete reference of all template
tags and filters available for a given site. See
<a class="reference internal" href="../contrib/admin/admindocs.html"><span class="doc">The Django admin documentation generator</span></a>.</p>
</div>
</div>
<div class="section" id="s-tags">
<span id="tags"></span><h2>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h2>
<p>Tags look like this: <code class="docutils literal"><span class="pre">{%</span> <span class="pre">tag</span> <span class="pre">%}</span></code>. Tags are more complex than variables: Some
create text in the output, some control flow by performing loops or logic, and
some load external information into the template to be used by later variables.</p>
<p>Some tags require beginning and ending tags (i.e. <code class="docutils literal"><span class="pre">{%</span> <span class="pre">tag</span> <span class="pre">%}</span> <span class="pre">...</span> <span class="pre">tag</span> <span class="pre">contents</span>
<span class="pre">...</span> <span class="pre">{%</span> <span class="pre">endtag</span> <span class="pre">%}</span></code>).</p>
<p>Django ships with about two dozen built-in template tags. You can read all about
them in the <a class="reference internal" href="builtins.html#ref-templates-builtins-tags"><span class="std std-ref">built-in tag reference</span></a>. To give
you a taste of what’s available, here are some of the more commonly used
tags:</p>
<dl class="docutils">
<dt><a class="reference internal" href="builtins.html#std:templatetag-for"><code class="xref std std-ttag docutils literal"><span class="pre">for</span></code></a></dt>
<dd><p class="first">Loop over each item in an array. For example, to display a list of athletes
provided in <code class="docutils literal"><span class="pre">athlete_list</span></code>:</p>
<div class="last highlight-html+django"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">ul</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">athlete</span> <span class="k">in</span> <span class="nv">athlete_list</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">li</span><span class="p">></span><span class="cp">{{</span> <span class="nv">athlete.name</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">li</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="p"></</span><span class="nt">ul</span><span class="p">></span>
</pre></div>
</div>
</dd>
<dt><a class="reference internal" href="builtins.html#std:templatetag-if"><code class="xref std std-ttag docutils literal"><span class="pre">if</span></code></a>, <code class="docutils literal"><span class="pre">elif</span></code>, and <code class="docutils literal"><span class="pre">else</span></code></dt>
<dd><p class="first">Evaluates a variable, and if that variable is “true” the contents of the
block are displayed:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">athlete_list</span> <span class="cp">%}</span>
Number of athletes: <span class="cp">{{</span> <span class="nv">athlete_list</span><span class="o">|</span><span class="nf">length</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">elif</span> <span class="nv">athlete_in_locker_room_list</span> <span class="cp">%}</span>
Athletes should be out of the locker room soon!
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
No athletes.
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>In the above, if <code class="docutils literal"><span class="pre">athlete_list</span></code> is not empty, the number of athletes
will be displayed by the <code class="docutils literal"><span class="pre">{{</span> <span class="pre">athlete_list|length</span> <span class="pre">}}</span></code> variable. Otherwise,
if <code class="docutils literal"><span class="pre">athlete_in_locker_room_list</span></code> is not empty, the message “Athletes
should be out...” will be displayed. If both lists are empty,
“No athletes.” will be displayed.</p>
<p>You can also use filters and various operators in the <a class="reference internal" href="builtins.html#std:templatetag-if"><code class="xref std std-ttag docutils literal"><span class="pre">if</span></code></a> tag:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">athlete_list</span><span class="o">|</span><span class="nf">length</span> <span class="o">></span> <span class="m">1</span> <span class="cp">%}</span>
Team: <span class="cp">{%</span> <span class="k">for</span> <span class="nv">athlete</span> <span class="k">in</span> <span class="nv">athlete_list</span> <span class="cp">%}</span> ... <span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
Athlete: <span class="cp">{{</span> <span class="nv">athlete_list.0.name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p class="last">While the above example works, be aware that most template filters return
strings, so mathematical comparisons using filters will generally not work
as you expect. <a class="reference internal" href="builtins.html#std:templatefilter-length"><code class="xref std std-tfilter docutils literal"><span class="pre">length</span></code></a> is an exception.</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">block</span></code></a> and <a class="reference internal" href="builtins.html#std:templatetag-extends"><code class="xref std std-ttag docutils literal"><span class="pre">extends</span></code></a></dt>
<dd>Set up <a class="reference internal" href="#id1">template inheritance</a> (see below), a powerful way
of cutting down on “boilerplate” in templates.</dd>
</dl>
<p>Again, the above is only a selection of the whole list; see the <a class="reference internal" href="builtins.html#ref-templates-builtins-tags"><span class="std std-ref">built-in
tag reference</span></a> for the complete list.</p>
<p>You can also create your own custom template tags; see
<a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">Custom template tags and filters</span></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">Django’s admin interface can include a complete reference of all template
tags and filters available for a given site. See
<a class="reference internal" href="../contrib/admin/admindocs.html"><span class="doc">The Django admin documentation generator</span></a>.</p>
</div>
</div>
<div class="section" id="s-comments">
<span id="s-template-comments"></span><span id="comments"></span><span id="template-comments"></span><h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2>
<p>To comment-out part of a line in a template, use the comment syntax: <code class="docutils literal"><span class="pre">{#</span> <span class="pre">#}</span></code>.</p>
<p>For example, this template would render as <code class="docutils literal"><span class="pre">'hello'</span></code>:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="c">{# greeting #}</span>hello
</pre></div>
</div>
<p>A comment can contain any template code, invalid or not. For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="c">{# {% if foo %}bar{% else %} #}</span>
</pre></div>
</div>
<p>This syntax can only be used for single-line comments (no newlines are permitted
between the <code class="docutils literal"><span class="pre">{#</span></code> and <code class="docutils literal"><span class="pre">#}</span></code> delimiters). If you need to comment out a
multiline portion of the template, see the <a class="reference internal" href="builtins.html#std:templatetag-comment"><code class="xref std std-ttag docutils literal"><span class="pre">comment</span></code></a> tag.</p>
</div>
<div class="section" id="s-template-inheritance">
<span id="s-id1"></span><span id="template-inheritance"></span><span id="id1"></span><h2>Template inheritance<a class="headerlink" href="#template-inheritance" title="Permalink to this headline">¶</a></h2>
<p>The most powerful – and thus the most complex – part of Django’s template
engine is template inheritance. Template inheritance allows you to build a base
“skeleton” template that contains all the common elements of your site and
defines <strong>blocks</strong> that child templates can override.</p>
<p>It’s easiest to understand template inheritance by starting with an example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp"><!DOCTYPE html></span>
<span class="p"><</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">"en"</span><span class="p">></span>
<span class="p"><</span><span class="nt">head</span><span class="p">></span>
<span class="p"><</span><span class="nt">link</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span> <span class="na">href</span><span class="o">=</span><span class="s">"style.css"</span> <span class="p">/></span>
<span class="p"><</span><span class="nt">title</span><span class="p">></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>My amazing site<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="p"></</span><span class="nt">title</span><span class="p">></span>
<span class="p"></</span><span class="nt">head</span><span class="p">></span>
<span class="p"><</span><span class="nt">body</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">"sidebar"</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">sidebar</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">ul</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/"</span><span class="p">></span>Home<span class="p"></</span><span class="nt">a</span><span class="p">></</span><span class="nt">li</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/blog/"</span><span class="p">></span>Blog<span class="p"></</span><span class="nt">a</span><span class="p">></</span><span class="nt">li</span><span class="p">></span>
<span class="p"></</span><span class="nt">ul</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">"content"</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"></</span><span class="nt">body</span><span class="p">></span>
<span class="p"></</span><span class="nt">html</span><span class="p">></span>
</pre></div>
</div>
<p>This template, which we’ll call <code class="docutils literal"><span class="pre">base.html</span></code>, defines a simple HTML skeleton
document that you might use for a simple two-column page. It’s the job of
“child” templates to fill the empty blocks with content.</p>
<p>In this example, the <a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">block</span></code></a> tag defines three blocks that child
templates can fill in. All the <a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">block</span></code></a> tag does is to tell the template
engine that a child template may override those portions of the template.</p>
<p>A child template might look like this:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">"base.html"</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>My amazing blog<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">entry</span> <span class="k">in</span> <span class="nv">blog_entries</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">h2</span><span class="p">></span><span class="cp">{{</span> <span class="nv">entry.title</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">h2</span><span class="p">></span>
<span class="p"><</span><span class="nt">p</span><span class="p">></span><span class="cp">{{</span> <span class="nv">entry.body</span> <span class="cp">}}</span><span class="p"></</span><span class="nt">p</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="builtins.html#std:templatetag-extends"><code class="xref std std-ttag docutils literal"><span class="pre">extends</span></code></a> tag is the key here. It tells the template engine that
this template “extends” another template. When the template system evaluates
this template, first it locates the parent – in this case, “base.html”.</p>
<p>At that point, the template engine will notice the three <a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">block</span></code></a> tags
in <code class="docutils literal"><span class="pre">base.html</span></code> and replace those blocks with the contents of the child
template. Depending on the value of <code class="docutils literal"><span class="pre">blog_entries</span></code>, the output might look
like:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp"><!DOCTYPE html></span>
<span class="p"><</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">"en"</span><span class="p">></span>
<span class="p"><</span><span class="nt">head</span><span class="p">></span>
<span class="p"><</span><span class="nt">link</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span> <span class="na">href</span><span class="o">=</span><span class="s">"style.css"</span> <span class="p">/></span>
<span class="p"><</span><span class="nt">title</span><span class="p">></span>My amazing blog<span class="p"></</span><span class="nt">title</span><span class="p">></span>
<span class="p"></</span><span class="nt">head</span><span class="p">></span>
<span class="p"><</span><span class="nt">body</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">"sidebar"</span><span class="p">></span>
<span class="p"><</span><span class="nt">ul</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/"</span><span class="p">></span>Home<span class="p"></</span><span class="nt">a</span><span class="p">></</span><span class="nt">li</span><span class="p">></span>
<span class="p"><</span><span class="nt">li</span><span class="p">><</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">"/blog/"</span><span class="p">></span>Blog<span class="p"></</span><span class="nt">a</span><span class="p">></</span><span class="nt">li</span><span class="p">></span>
<span class="p"></</span><span class="nt">ul</span><span class="p">></span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"><</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">"content"</span><span class="p">></span>
<span class="p"><</span><span class="nt">h2</span><span class="p">></span>Entry one<span class="p"></</span><span class="nt">h2</span><span class="p">></span>
<span class="p"><</span><span class="nt">p</span><span class="p">></span>This is my first entry.<span class="p"></</span><span class="nt">p</span><span class="p">></span>
<span class="p"><</span><span class="nt">h2</span><span class="p">></span>Entry two<span class="p"></</span><span class="nt">h2</span><span class="p">></span>
<span class="p"><</span><span class="nt">p</span><span class="p">></span>This is my second entry.<span class="p"></</span><span class="nt">p</span><span class="p">></span>
<span class="p"></</span><span class="nt">div</span><span class="p">></span>
<span class="p"></</span><span class="nt">body</span><span class="p">></span>
<span class="p"></</span><span class="nt">html</span><span class="p">></span>
</pre></div>
</div>
<p>Note that since the child template didn’t define the <code class="docutils literal"><span class="pre">sidebar</span></code> block, the
value from the parent template is used instead. Content within a <code class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code>
tag in a parent template is always used as a fallback.</p>
<p>You can use as many levels of inheritance as needed. One common way of using
inheritance is the following three-level approach:</p>
<ul class="simple">
<li>Create a <code class="docutils literal"><span class="pre">base.html</span></code> template that holds the main look-and-feel of your
site.</li>
<li>Create a <code class="docutils literal"><span class="pre">base_SECTIONNAME.html</span></code> template for each “section” of your
site. For example, <code class="docutils literal"><span class="pre">base_news.html</span></code>, <code class="docutils literal"><span class="pre">base_sports.html</span></code>. These
templates all extend <code class="docutils literal"><span class="pre">base.html</span></code> and include section-specific
styles/design.</li>
<li>Create individual templates for each type of page, such as a news
article or blog entry. These templates extend the appropriate section
template.</li>
</ul>
<p>This approach maximizes code reuse and makes it easy to add items to shared
content areas, such as section-wide navigation.</p>
<p>Here are some tips for working with inheritance:</p>
<ul>
<li><p class="first">If you use <a class="reference internal" href="builtins.html#std:templatetag-extends"><code class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></code></a> in a template, it must be the first template
tag in that template. Template inheritance won’t work, otherwise.</p>
</li>
<li><p class="first">More <a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> tags in your base templates are better. Remember,
child templates don’t have to define all parent blocks, so you can fill
in reasonable defaults in a number of blocks, then only define the ones
you need later. It’s better to have more hooks than fewer hooks.</p>
</li>
<li><p class="first">If you find yourself duplicating content in a number of templates, it
probably means you should move that content to a <code class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> in a
parent template.</p>
</li>
<li><p class="first">If you need to get the content of the block from the parent template,
the <code class="docutils literal"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> variable will do the trick. This is useful
if you want to add to the contents of a parent block instead of
completely overriding it. Data inserted using <code class="docutils literal"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> will
not be automatically escaped (see the <a class="reference external" href="#automatic-html-escaping">next section</a>), since it was
already escaped, if necessary, in the parent template.</p>
</li>
<li><p class="first">For extra readability, you can optionally give a <em>name</em> to your
<code class="docutils literal"><span class="pre">{%</span> <span class="pre">endblock</span> <span class="pre">%}</span></code> tag. For example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
...
<span class="cp">{%</span> <span class="k">endblock</span> <span class="nv">content</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>In larger templates, this technique helps you see which <code class="docutils literal"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code>
tags are being closed.</p>
</li>
</ul>
<p>Finally, note that you can’t define multiple <a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">block</span></code></a> tags with the same
name in the same template. This limitation exists because a block tag works in
“both” directions. That is, a block tag doesn’t just provide a hole to fill –
it also defines the content that fills the hole in the <em>parent</em>. If there were
two similarly-named <a class="reference internal" href="builtins.html#std:templatetag-block"><code class="xref std std-ttag docutils literal"><span class="pre">block</span></code></a> tags in a template, that template’s parent
wouldn’t know which one of the blocks’ content to use.</p>
</div>
<div class="section" id="s-automatic-html-escaping">
<span id="s-id2"></span><span id="automatic-html-escaping"></span><span id="id2"></span><h2>Automatic HTML escaping<a class="headerlink" href="#automatic-html-escaping" title="Permalink to this headline">¶</a></h2>
<p>When generating HTML from templates, there’s always a risk that a variable will
include characters that affect the resulting HTML. For example, consider this
template fragment:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span>Hello, <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>At first, this seems like a harmless way to display a user’s name, but consider
what would happen if the user entered their name as this:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">script</span><span class="p">></span><span class="nx">alert</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</</span><span class="nt">script</span><span class="p">></span>
</pre></div>
</div>
<p>With this name value, the template would be rendered as:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span>Hello, <span class="p"><</span><span class="nt">script</span><span class="p">></span><span class="nx">alert</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</</span><span class="nt">script</span><span class="p">></span>
</pre></div>
</div>
<p>...which means the browser would pop-up a JavaScript alert box!</p>
<p>Similarly, what if the name contained a <code class="docutils literal"><span class="pre">'<'</span></code> symbol, like this?</p>
<div class="highlight-html"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">b</span><span class="p">></span>username
</pre></div>
</div>
<p>That would result in a rendered template like this:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span>Hello, <span class="p"><</span><span class="nt">b</span><span class="p">></span>username
</pre></div>
</div>
<p>...which, in turn, would result in the remainder of the Web page being bolded!</p>
<p>Clearly, user-submitted data shouldn’t be trusted blindly and inserted directly
into your Web pages, because a malicious user could use this kind of hole to
do potentially bad things. This type of security exploit is called a
<a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_scripting">Cross Site Scripting</a> (XSS) attack.</p>
<p>To avoid this problem, you have two options:</p>
<ul class="simple">
<li>One, you can make sure to run each untrusted variable through the
<a class="reference internal" href="builtins.html#std:templatefilter-escape"><code class="xref std std-tfilter docutils literal"><span class="pre">escape</span></code></a> filter (documented below), which converts potentially
harmful HTML characters to unharmful ones. This was the default solution
in Django for its first few years, but the problem is that it puts the
onus on <em>you</em>, the developer / template author, to ensure you’re escaping
everything. It’s easy to forget to escape data.</li>
<li>Two, you can take advantage of Django’s automatic HTML escaping. The
remainder of this section describes how auto-escaping works.</li>
</ul>
<p>By default in Django, every template automatically escapes the output
of every variable tag. Specifically, these five characters are
escaped:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre"><</span></code> is converted to <code class="docutils literal"><span class="pre">&lt;</span></code></li>
<li><code class="docutils literal"><span class="pre">></span></code> is converted to <code class="docutils literal"><span class="pre">&gt;</span></code></li>
<li><code class="docutils literal"><span class="pre">'</span></code> (single quote) is converted to <code class="docutils literal"><span class="pre">&#39;</span></code></li>
<li><code class="docutils literal"><span class="pre">"</span></code> (double quote) is converted to <code class="docutils literal"><span class="pre">&quot;</span></code></li>
<li><code class="docutils literal"><span class="pre">&</span></code> is converted to <code class="docutils literal"><span class="pre">&amp;</span></code></li>
</ul>
<p>Again, we stress that this behavior is on by default. If you’re using Django’s
template system, you’re protected.</p>
<div class="section" id="s-how-to-turn-it-off">
<span id="how-to-turn-it-off"></span><h3>How to turn it off<a class="headerlink" href="#how-to-turn-it-off" title="Permalink to this headline">¶</a></h3>
<p>If you don’t want data to be auto-escaped, on a per-site, per-template level or
per-variable level, you can turn it off in several ways.</p>
<p>Why would you want to turn it off? Because sometimes, template variables
contain data that you <em>intend</em> to be rendered as raw HTML, in which case you
don’t want their contents to be escaped. For example, you might store a blob of
HTML in your database and want to embed that directly into your template. Or,
you might be using Django’s template system to produce text that is <em>not</em> HTML
– like an email message, for instance.</p>
<div class="section" id="s-for-individual-variables">
<span id="for-individual-variables"></span><h4>For individual variables<a class="headerlink" href="#for-individual-variables" title="Permalink to this headline">¶</a></h4>
<p>To disable auto-escaping for an individual variable, use the <a class="reference internal" href="builtins.html#std:templatefilter-safe"><code class="xref std std-tfilter docutils literal"><span class="pre">safe</span></code></a>
filter:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span>This will be escaped: <span class="cp">{{</span> <span class="nv">data</span> <span class="cp">}}</span>
This will not be escaped: <span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">safe</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Think of <em>safe</em> as shorthand for <em>safe from further escaping</em> or <em>can be
safely interpreted as HTML</em>. In this example, if <code class="docutils literal"><span class="pre">data</span></code> contains <code class="docutils literal"><span class="pre">'<b>'</span></code>,
the output will be:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span>This will be escaped: <span class="ni">&lt;</span>b<span class="ni">&gt;</span>
This will not be escaped: <span class="p"><</span><span class="nt">b</span><span class="p">></span>
</pre></div>
</div>
</div>
<div class="section" id="s-for-template-blocks">
<span id="for-template-blocks"></span><h4>For template blocks<a class="headerlink" href="#for-template-blocks" title="Permalink to this headline">¶</a></h4>
<p>To control auto-escaping for a template, wrap the template (or just a
particular section of the template) in the <a class="reference internal" href="builtins.html#std:templatetag-autoescape"><code class="xref std std-ttag docutils literal"><span class="pre">autoescape</span></code></a> tag, like so:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="builtins.html#std:templatetag-autoescape"><code class="xref std std-ttag docutils literal"><span class="pre">autoescape</span></code></a> tag takes either <code class="docutils literal"><span class="pre">on</span></code> or <code class="docutils literal"><span class="pre">off</span></code> as its argument. At
times, you might want to force auto-escaping when it would otherwise be
disabled. Here is an example template:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span>Auto-escaping is on by default. Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
This will not be auto-escaped: <span class="cp">{{</span> <span class="nv">data</span> <span class="cp">}}</span>.
Nor this: <span class="cp">{{</span> <span class="nv">other_data</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">on</span> <span class="cp">%}</span>
Auto-escaping applies again: <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>The auto-escaping tag passes its effect onto templates that extend the
current one as well as templates included via the <a class="reference internal" href="builtins.html#std:templatetag-include"><code class="xref std std-ttag docutils literal"><span class="pre">include</span></code></a> tag,
just like all block tags. For example:</p>
<div class="highlight-html+django"><div class="snippet-filename">base.html</div>
<div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
<span class="p"><</span><span class="nt">h1</span><span class="p">></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="p"></</span><span class="nt">h1</span><span class="p">></span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<div class="highlight-html+django"><div class="snippet-filename">child.html</div>
<div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">"base.html"</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>This <span class="ni">&amp;</span> that<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{{</span> <span class="nv">greeting</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Because auto-escaping is turned off in the base template, it will also be
turned off in the child template, resulting in the following rendered
HTML when the <code class="docutils literal"><span class="pre">greeting</span></code> variable contains the string <code class="docutils literal"><span class="pre"><b>Hello!</b></span></code>:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">h1</span><span class="p">></span>This <span class="ni">&amp;</span> that<span class="p"></</span><span class="nt">h1</span><span class="p">></span>
<span class="p"><</span><span class="nt">b</span><span class="p">></span>Hello!<span class="p"></</span><span class="nt">b</span><span class="p">></span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-notes">
<span id="notes"></span><h3>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h3>
<p>Generally, template authors don’t need to worry about auto-escaping very much.
Developers on the Python side (people writing views and custom filters) need to
think about the cases in which data shouldn’t be escaped, and mark data
appropriately, so things Just Work in the template.</p>
<p>If you’re creating a template that might be used in situations where you’re
not sure whether auto-escaping is enabled, then add an <a class="reference internal" href="builtins.html#std:templatefilter-escape"><code class="xref std std-tfilter docutils literal"><span class="pre">escape</span></code></a> filter
to any variable that needs escaping. When auto-escaping is on, there’s no
danger of the <a class="reference internal" href="builtins.html#std:templatefilter-escape"><code class="xref std std-tfilter docutils literal"><span class="pre">escape</span></code></a> filter <em>double-escaping</em> data – the
<a class="reference internal" href="builtins.html#std:templatefilter-escape"><code class="xref std std-tfilter docutils literal"><span class="pre">escape</span></code></a> filter does not affect auto-escaped variables.</p>
</div>
<div class="section" id="s-string-literals-and-automatic-escaping">
<span id="s-id3"></span><span id="string-literals-and-automatic-escaping"></span><span id="id3"></span><h3>String literals and automatic escaping<a class="headerlink" href="#string-literals-and-automatic-escaping" title="Permalink to this headline">¶</a></h3>
<p>As we mentioned earlier, filter arguments can be strings:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:"This is a string literal."</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>All string literals are inserted <strong>without</strong> any automatic escaping into the
template – they act as if they were all passed through the <a class="reference internal" href="builtins.html#std:templatefilter-safe"><code class="xref std std-tfilter docutils literal"><span class="pre">safe</span></code></a>
filter. The reasoning behind this is that the template author is in control of
what goes into the string literal, so they can make sure the text is correctly
escaped when the template is written.</p>
<p>This means you would write</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:"3 &lt; 2"</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>...rather than:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:"3 < 2"</span> <span class="cp">}}</span> <span class="c">{# Bad! Don't do this. #}</span>
</pre></div>
</div>
<p>This doesn’t affect what happens to data coming from the variable itself.
The variable’s contents are still automatically escaped, if necessary, because
they’re beyond the control of the template author.</p>
</div>
</div>
<div class="section" id="s-accessing-method-calls">
<span id="s-template-accessing-methods"></span><span id="accessing-method-calls"></span><span id="template-accessing-methods"></span><h2>Accessing method calls<a class="headerlink" href="#accessing-method-calls" title="Permalink to this headline">¶</a></h2>
<p>Most method calls attached to objects are also available from within templates.
This means that templates have access to much more than just class attributes
(like field names) and variables passed in from views. For example, the Django
ORM provides the <a class="reference internal" href="../../topics/db/queries.html#topics-db-queries-related"><span class="std std-ref">“entry_set”</span></a> syntax for
finding a collection of objects related on a foreign key. Therefore, given
a model called “comment” with a foreign key relationship to a model called
“task” you can loop through all comments attached to a given task like this:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">comment</span> <span class="k">in</span> <span class="nv">task.comment_set.all</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="nv">comment</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Similarly, <a class="reference internal" href="../models/querysets.html"><span class="doc">QuerySets</span></a> provide a <code class="docutils literal"><span class="pre">count()</span></code> method
to count the number of objects they contain. Therefore, you can obtain a count
of all comments related to the current task with:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">task.comment_set.all.count</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>And of course you can easily access methods you’ve explicitly defined on your
own models:</p>
<div class="highlight-html+django"><div class="snippet-filename">models.py</div>
<div class="highlight"><pre><span></span>class Task(models.Model):
def foo(self):
return "bar"
</pre></div>
</div>
<div class="highlight-html+django"><div class="snippet-filename">template.html</div>
<div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">task.foo</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Because Django intentionally limits the amount of logic processing available
in the template language, it is not possible to pass arguments to method calls
accessed from within templates. Data should be calculated in views, then passed
to templates for display.</p>
</div>
<div class="section" id="s-custom-tag-and-filter-libraries">
<span id="s-loading-custom-template-libraries"></span><span id="custom-tag-and-filter-libraries"></span><span id="loading-custom-template-libraries"></span><h2>Custom tag and filter libraries<a class="headerlink" href="#custom-tag-and-filter-libraries" title="Permalink to this headline">¶</a></h2>
<p>Certain applications provide custom tag and filter libraries. To access them in
a template, ensure the application is in <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> (we’d add
<code class="docutils literal"><span class="pre">'django.contrib.humanize'</span></code> for this example), and then use the <a class="reference internal" href="builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal"><span class="pre">load</span></code></a>
tag in a template:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">load</span> <span class="nv">humanize</span> <span class="cp">%}</span>
<span class="cp">{{</span> <span class="m">45000</span><span class="o">|</span><span class="nf">intcomma</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>In the above, the <a class="reference internal" href="builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal"><span class="pre">load</span></code></a> tag loads the <code class="docutils literal"><span class="pre">humanize</span></code> tag library, which then
makes the <code class="docutils literal"><span class="pre">intcomma</span></code> filter available for use. If you’ve enabled
<a class="reference internal" href="../contrib/admin/admindocs.html#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal"><span class="pre">django.contrib.admindocs</span></code></a>, you can consult the documentation area in your
admin to find the list of custom libraries in your installation.</p>
<p>The <a class="reference internal" href="builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal"><span class="pre">load</span></code></a> tag can take multiple library names, separated by spaces.
Example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">load</span> <span class="nv">humanize</span> <span class="nv">i18n</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">Custom template tags and filters</span></a> for information on writing your own custom
template libraries.</p>
<div class="section" id="s-custom-libraries-and-template-inheritance">
<span id="custom-libraries-and-template-inheritance"></span><h3>Custom libraries and template inheritance<a class="headerlink" href="#custom-libraries-and-template-inheritance" title="Permalink to this headline">¶</a></h3>
<p>When you load a custom tag or filter library, the tags/filters are only made
available to the current template – not any parent or child templates along
the template-inheritance path.</p>
<p>For example, if a template <code class="docutils literal"><span class="pre">foo.html</span></code> has <code class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">humanize</span> <span class="pre">%}</span></code>, a child
template (e.g., one that has <code class="docutils literal"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">"foo.html"</span> <span class="pre">%}</span></code>) will <em>not</em> have
access to the humanize template tags and filters. The child template is
responsible for its own <code class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">humanize</span> <span class="pre">%}</span></code>.</p>
<p>This is a feature for the sake of maintainability and sanity.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="index.html"><span class="doc">The Templates Reference</span></a></dt>
<dd>Covers built-in tags, built-in filters, using an alternative template,
language, and more.</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The Django template language</a><ul>
<li><a class="reference internal" href="#templates">Templates</a></li>
<li><a class="reference internal" href="#variables">Variables</a></li>
<li><a class="reference internal" href="#filters">Filters</a></li>
<li><a class="reference internal" href="#tags">Tags</a></li>
<li><a class="reference internal" href="#comments">Comments</a></li>
<li><a class="reference internal" href="#template-inheritance">Template inheritance</a></li>
<li><a class="reference internal" href="#automatic-html-escaping">Automatic HTML escaping</a><ul>
<li><a class="reference internal" href="#how-to-turn-it-off">How to turn it off</a><ul>
<li><a class="reference internal" href="#for-individual-variables">For individual variables</a></li>
<li><a class="reference internal" href="#for-template-blocks">For template blocks</a></li>
</ul>
</li>
<li><a class="reference internal" href="#notes">Notes</a></li>
<li><a class="reference internal" href="#string-literals-and-automatic-escaping">String literals and automatic escaping</a></li>
</ul>
</li>
<li><a class="reference internal" href="#accessing-method-calls">Accessing method calls</a></li>
<li><a class="reference internal" href="#custom-tag-and-filter-libraries">Custom tag and filter libraries</a><ul>
<li><a class="reference internal" href="#custom-libraries-and-template-inheritance">Custom libraries and template inheritance</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="index.html">Templates</a></li>
<li>Next: <a href="builtins.html">Built-in template tags and filters</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../index.html">Django 1.8.19 documentation</a>
<ul><li><a href="../index.html">API Reference</a>
<ul><li><a href="index.html">Templates</a>
<ul><li>The Django template language</li></ul>
</li></ul></li></ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/ref/templates/language.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 10, 2018</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="index.html" title="Templates">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="builtins.html" title="Built-in template tags and filters">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
65530c6176058f9b54858c3b4f6385e6
>
files
>
792
