<!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: for Python programmers — 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="Upgrading templates to Django 1.8" href="upgrading.html" />
<link rel="prev" title="Built-in template tags and filters" href="builtins.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="builtins.html" title="Built-in template tags and filters">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="upgrading.html" title="Upgrading templates to Django 1.8">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-templates-api">
<div class="section" id="s-the-django-template-language-for-python-programmers">
<span id="the-django-template-language-for-python-programmers"></span><h1>The Django template language: for Python programmers<a class="headerlink" href="#the-django-template-language-for-python-programmers" title="Permalink to this headline">¶</a></h1>
<p>This document explains the Django template system from a technical
perspective – how it works and how to extend it. If you’re just looking for
reference on the language syntax, see <a class="reference internal" href="language.html"><span class="doc">The Django template language</span></a>.</p>
<p>It assumes an understanding of templates, contexts, variables, tags, and
rendering. Start with the <a class="reference internal" href="../../topics/templates.html#template-language-intro"><span class="std std-ref">introduction to the Django template language</span></a> if you aren’t familiar with these concepts.</p>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>Using the template system in Python is a three-step process:</p>
<ol class="arabic simple">
<li>You configure an <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a>.</li>
<li>You compile template code into a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>.</li>
<li>You render the template with a <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</li>
</ol>
<p>Django projects generally rely on the <a class="reference internal" href="../../topics/templates.html#template-engines"><span class="std std-ref">high level, backend agnostic APIs</span></a> for each of these steps instead of the template system’s
lower level APIs:</p>
<ol class="arabic simple">
<li>For each <a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal"><span class="pre">DjangoTemplates</span></code></a> backend
in the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal"><span class="pre">TEMPLATES</span></code></a> setting, Django instantiates an
<a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a>. <a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal"><span class="pre">DjangoTemplates</span></code></a>
wraps <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a> and adapts it to the common template backend API.</li>
<li>The <a class="reference internal" href="../../topics/templates.html#module-django.template.loader" title="django.template.loader"><code class="xref py py-mod docutils literal"><span class="pre">django.template.loader</span></code></a> module provides functions such as
<a class="reference internal" href="../../topics/templates.html#django.template.loader.get_template" title="django.template.loader.get_template"><code class="xref py py-func docutils literal"><span class="pre">get_template()</span></code></a> for loading templates. They
return a <code class="docutils literal"><span class="pre">django.template.backends.django.Template</span></code> which wraps the
actual <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">django.template.Template</span></code></a>.</li>
<li>The <code class="docutils literal"><span class="pre">Template</span></code> obtained in the previous step has a
<a class="reference internal" href="../../topics/templates.html#django.template.backends.base.Template.render" title="django.template.backends.base.Template.render"><code class="xref py py-meth docutils literal"><span class="pre">render()</span></code></a> method which
marshals a context and possibly a request into a <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> and
delegates the rendering to the underlying <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a>.</li>
</ol>
</div>
<div class="section" id="s-configuring-an-engine">
<span id="configuring-an-engine"></span><h2>Configuring an engine<a class="headerlink" href="#configuring-an-engine" title="Permalink to this headline">¶</a></h2>
<p>If you are simply using the
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal"><span class="pre">DjangoTemplates</span></code></a> backend, this
probably isn’t the documentation you’re looking for. An instance of the
<code class="docutils literal"><span class="pre">Engine</span></code> class described below is accessible using the <code class="docutils literal"><span class="pre">engine</span></code> attribute
of that backend and any attribute defaults mentioned below are overridden by
what’s passed by <a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal"><span class="pre">DjangoTemplates</span></code></a>.</p>
<dl class="class">
<dt id="django.template.Engine">
<em class="property">class </em><code class="descname">Engine</code>(<em>dirs=None</em>, <em>app_dirs=False</em>, <em>allowed_include_roots=None</em>, <em>context_processors=None</em>, <em>debug=False</em>, <em>loaders=None</em>, <em>string_if_invalid=''</em>, <em>file_charset='utf-8'</em>)<a class="reference internal" href="../../_modules/django/template/engine.html#Engine"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Engine" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.8.</span> </div>
<p>When instantiating an <code class="docutils literal"><span class="pre">Engine</span></code> all arguments must be passed as keyword
arguments:</p>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">dirs</span></code> is a list of directories where the engine should look for
template source files. It is used to configure
<a class="reference internal" href="#django.template.loaders.filesystem.Loader" title="django.template.loaders.filesystem.Loader"><code class="xref py py-class docutils literal"><span class="pre">filesystem.Loader</span></code></a>.</p>
<p>It defaults to an empty list.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">app_dirs</span></code> only affects the default value of <code class="docutils literal"><span class="pre">loaders</span></code>. See below.</p>
<p>It defaults to <code class="docutils literal"><span class="pre">False</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">allowed_include_roots</span></code> is a list of strings representing allowed
prefixes for the <code class="docutils literal"><span class="pre">{%</span> <span class="pre">ssi</span> <span class="pre">%}</span></code> template tag. This is a security measure,
so that template authors can’t access files that they shouldn’t be
accessing.</p>
<p>For example, if <code class="docutils literal"><span class="pre">'allowed_include_roots'</span></code> is <code class="docutils literal"><span class="pre">['/home/html',</span>
<span class="pre">'/var/www']</span></code>, then <code class="docutils literal"><span class="pre">{%</span> <span class="pre">ssi</span> <span class="pre">/home/html/foo.txt</span> <span class="pre">%}</span></code> would work, but <code class="docutils literal"><span class="pre">{%</span>
<span class="pre">ssi</span> <span class="pre">/etc/passwd</span> <span class="pre">%}</span></code> wouldn’t.</p>
<p>It defaults to an empty list.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.8: </span><code class="docutils literal"><span class="pre">allowed_include_roots</span></code> is deprecated.</p>
</div>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">context_processors</span></code> is a list of dotted Python paths to callables
that are used to populate the context when a template is rendered with a
request. These callables take a request object as their argument and
return a <code class="xref py py-class docutils literal"><span class="pre">dict</span></code> of items to be merged into the context.</p>
<p>It defaults to an empty list.</p>
<p>See <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal"><span class="pre">RequestContext</span></code></a> for more information.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">debug</span></code> is a boolean that turns on/off template debug mode. If it is
<code class="docutils literal"><span class="pre">True</span></code>, the template engine will store additional debug information
which can be used to display a detailed report for any exception raised
during template rendering.</p>
<p>It defaults to <code class="docutils literal"><span class="pre">False</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">loaders</span></code> is a list of template loader classes, specified as strings.
Each <code class="docutils literal"><span class="pre">Loader</span></code> class knows how to import templates from a particular
source. Optionally, a tuple can be used instead of a string. The first
item in the tuple should be the <code class="docutils literal"><span class="pre">Loader</span></code> class name, subsequent items
are passed to the <code class="docutils literal"><span class="pre">Loader</span></code> during initialization.</p>
<p>It defaults to a list containing:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'django.template.loaders.filesystem.Loader'</span></code></li>
<li><code class="docutils literal"><span class="pre">'django.template.loaders.app_directories.Loader'</span></code> if and only if
<code class="docutils literal"><span class="pre">app_dirs</span></code> is <code class="docutils literal"><span class="pre">True</span></code>.</li>
</ul>
<p>See <a class="reference internal" href="#template-loaders"><span class="std std-ref">Loader types</span></a> for details.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">string_if_invalid</span></code> is the output, as a string, that the template
system should use for invalid (e.g. misspelled) variables.</p>
<p>It defaults to the empty string.</p>
<p>See <a class="reference internal" href="#invalid-template-variables"><span class="std std-ref">How invalid variables are handled</span></a> for details.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">file_charset</span></code> is the charset used to read template files on disk.</p>
<p>It defaults to <code class="docutils literal"><span class="pre">'utf-8'</span></code>.</p>
</li>
</ul>
</dd></dl>
<dl class="staticmethod">
<dt id="django.template.Engine.get_default">
<em class="property">static </em><code class="descclassname">Engine.</code><code class="descname">get_default</code>()<a class="reference internal" href="../../_modules/django/template/engine.html#Engine.get_default"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Engine.get_default" title="Permalink to this definition">¶</a></dt>
<dd><p>When a Django project configures one and only one
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal"><span class="pre">DjangoTemplates</span></code></a> engine, this
method returns the underlying <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a>. In other circumstances it
will raise <a class="reference internal" href="../exceptions.html#django.core.exceptions.ImproperlyConfigured" title="django.core.exceptions.ImproperlyConfigured"><code class="xref py py-exc docutils literal"><span class="pre">ImproperlyConfigured</span></code></a>.</p>
<p>It’s required for preserving APIs that rely on a globally available,
implicitly configured engine. Any other use is strongly discouraged.</p>
</dd></dl>
<dl class="method">
<dt id="django.template.Engine.from_string">
<code class="descclassname">Engine.</code><code class="descname">from_string</code>(<em>template_code</em>)<a class="reference internal" href="../../_modules/django/template/engine.html#Engine.from_string"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Engine.from_string" title="Permalink to this definition">¶</a></dt>
<dd><p>Compiles the given template code and returns a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object.</p>
</dd></dl>
<dl class="method">
<dt id="django.template.Engine.get_template">
<code class="descclassname">Engine.</code><code class="descname">get_template</code>(<em>template_name</em>)<a class="reference internal" href="../../_modules/django/template/engine.html#Engine.get_template"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Engine.get_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads a template with the given name, compiles it and returns a
<a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object.</p>
</dd></dl>
<dl class="method">
<dt id="django.template.Engine.select_template">
<code class="descclassname">Engine.</code><code class="descname">select_template</code>(<em>self</em>, <em>template_name_list</em>)<a class="reference internal" href="../../_modules/django/template/engine.html#Engine.select_template"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Engine.select_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#django.template.Engine.get_template" title="django.template.Engine.get_template"><code class="xref py py-meth docutils literal"><span class="pre">get_template()</span></code></a>, except it takes a list of names
and returns the first template that was found.</p>
</dd></dl>
</div>
<div class="section" id="s-loading-a-template">
<span id="loading-a-template"></span><h2>Loading a template<a class="headerlink" href="#loading-a-template" title="Permalink to this headline">¶</a></h2>
<p>The recommended way to create a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> is by calling the factory
methods of the <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a>: <a class="reference internal" href="#django.template.Engine.get_template" title="django.template.Engine.get_template"><code class="xref py py-meth docutils literal"><span class="pre">get_template()</span></code></a>,
<a class="reference internal" href="#django.template.Engine.select_template" title="django.template.Engine.select_template"><code class="xref py py-meth docutils literal"><span class="pre">select_template()</span></code></a> and <a class="reference internal" href="#django.template.Engine.from_string" title="django.template.Engine.from_string"><code class="xref py py-meth docutils literal"><span class="pre">from_string()</span></code></a>.</p>
<p>In a Django project where the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal"><span class="pre">TEMPLATES</span></code></a> setting defines exactly one
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal"><span class="pre">DjangoTemplates</span></code></a> engine, it’s
possible to instantiate a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> directly.</p>
<dl class="class">
<dt id="django.template.Template">
<em class="property">class </em><code class="descname">Template</code><a class="reference internal" href="../../_modules/django/template/base.html#Template"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Template" title="Permalink to this definition">¶</a></dt>
<dd><p>This class lives at <code class="docutils literal"><span class="pre">django.template.Template</span></code>. The constructor takes
one argument — the raw template code:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">Template</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"My name is {{ my_name }}."</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<div class="admonition-behind-the-scenes admonition">
<p class="first admonition-title">Behind the scenes</p>
<p>The system only parses your raw template code once – when you create the
<code class="docutils literal"><span class="pre">Template</span></code> object. From then on, it’s stored internally as a tree
structure for performance.</p>
<p class="last">Even the parsing itself is quite fast. Most of the parsing happens via a
single call to a single, short, regular expression.</p>
</div>
</div>
<div class="section" id="s-rendering-a-context">
<span id="rendering-a-context"></span><h2>Rendering a context<a class="headerlink" href="#rendering-a-context" title="Permalink to this headline">¶</a></h2>
<p>Once you have a compiled <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object, you can render a context
with it. You can reuse the same template to render it several times with
different contexts.</p>
<dl class="class">
<dt id="django.template.Context">
<em class="property">class </em><code class="descname">Context</code>(<em>dict_=None</em>, <em>current_app=_current_app_undefined</em>)<a class="reference internal" href="../../_modules/django/template/context.html#Context"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Context" title="Permalink to this definition">¶</a></dt>
<dd><p>This class lives at <code class="docutils literal"><span class="pre">django.template.Context</span></code>. The constructor takes
two optional arguments:</p>
<ul>
<li><p class="first">A dictionary mapping variable names to variable values.</p>
</li>
<li><p class="first">The name of the current application. This application name is used
to help <a class="reference internal" href="../../topics/http/urls.html#topics-http-reversing-url-namespaces"><span class="std std-ref">resolve namespaced URLs</span></a>.
If you’re not using namespaced URLs, you can ignore this argument.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 1.8: </span>The <code class="docutils literal"><span class="pre">current_app</span></code> argument is deprecated. If you need it, you must
now use a <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal"><span class="pre">RequestContext</span></code></a> instead of a <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a>.</p>
</div>
</li>
</ul>
<p>For details, see <a class="reference internal" href="#playing-with-context"><span class="std std-ref">Playing with Context objects</span></a> below.</p>
</dd></dl>
<dl class="method">
<dt id="django.template.Template.render">
<code class="descclassname">Template.</code><code class="descname">render</code>(<em>context</em>)<a class="reference internal" href="../../_modules/django/template/base.html#Template.render"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Template.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Call the <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> object’s <code class="docutils literal"><span class="pre">render()</span></code> method with a
<a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> to “fill” the template:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">Context</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">>>> </span><span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"My name is {{ my_name }}."</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">"my_name"</span><span class="p">:</span> <span class="s2">"Adrian"</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">template</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="go">"My name is Adrian."</span>
<span class="gp">>>> </span><span class="n">context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">"my_name"</span><span class="p">:</span> <span class="s2">"Dolores"</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">template</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="go">"My name is Dolores."</span>
</pre></div>
</div>
</dd></dl>
<div class="section" id="s-variables-and-lookups">
<span id="variables-and-lookups"></span><h3>Variables and lookups<a class="headerlink" href="#variables-and-lookups" title="Permalink to this headline">¶</a></h3>
<p>Variable names must consist of any letter (A-Z), any digit (0-9), an underscore
(but they must not start with an underscore) or a dot.</p>
<p>Dots have a special meaning in template rendering. A dot in a variable name
signifies a <strong>lookup</strong>. Specifically, when the template system encounters a
dot in a variable name, it tries the following lookups, in this order:</p>
<ul class="simple">
<li>Dictionary lookup. Example: <code class="docutils literal"><span class="pre">foo["bar"]</span></code></li>
<li>Attribute lookup. Example: <code class="docutils literal"><span class="pre">foo.bar</span></code></li>
<li>List-index lookup. Example: <code class="docutils literal"><span class="pre">foo[bar]</span></code></li>
</ul>
<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>
<p>The template system uses the first lookup type that works. It’s short-circuit
logic. Here are a few examples:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">Context</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"My name is {{ person.first_name }}."</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"person"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"first_name"</span><span class="p">:</span> <span class="s2">"Joe"</span><span class="p">,</span> <span class="s2">"last_name"</span><span class="p">:</span> <span class="s2">"Johnson"</span><span class="p">}}</span>
<span class="gp">>>> </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="n">d</span><span class="p">))</span>
<span class="go">"My name is Joe."</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonClass</span><span class="p">:</span> <span class="k">pass</span>
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">PersonClass</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">first_name</span> <span class="o">=</span> <span class="s2">"Ron"</span>
<span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">last_name</span> <span class="o">=</span> <span class="s2">"Nasty"</span>
<span class="gp">>>> </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="s2">"person"</span><span class="p">:</span> <span class="n">p</span><span class="p">}))</span>
<span class="go">"My name is Ron."</span>
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"The first stooge in the list is {{ stooges.0 }}."</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">"stooges"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"Larry"</span><span class="p">,</span> <span class="s2">"Curly"</span><span class="p">,</span> <span class="s2">"Moe"</span><span class="p">]})</span>
<span class="gp">>>> </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>
<span class="go">"The first stooge in the list is Larry."</span>
</pre></div>
</div>
<p>If any part of the variable is callable, the template system will try calling
it. Example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonClass2</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="s2">"Samantha"</span>
<span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"My name is {{ person.name }}."</span><span class="p">)</span>
<span class="gp">>>> </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="s2">"person"</span><span class="p">:</span> <span class="n">PersonClass2</span><span class="p">}))</span>
<span class="go">"My name is Samantha."</span>
</pre></div>
</div>
<p>Callable variables are slightly more complex than variables which only require
straight lookups. Here are some things to keep in mind:</p>
<ul>
<li><p class="first">If the variable raises an exception when called, the exception will be
propagated, unless the exception has an attribute
<code class="docutils literal"><span class="pre">silent_variable_failure</span></code> whose value is <code class="docutils literal"><span class="pre">True</span></code>. If the exception
<em>does</em> have a <code class="docutils literal"><span class="pre">silent_variable_failure</span></code> attribute whose value is
<code class="docutils literal"><span class="pre">True</span></code>, the variable will render as the value of the engine’s
<code class="docutils literal"><span class="pre">string_if_invalid</span></code> configuration option (an empty string, by default).
Example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">"My name is {{ person.first_name }}."</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonClass3</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">first_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">PersonClass3</span><span class="p">()</span>
<span class="gp">>>> </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="s2">"person"</span><span class="p">:</span> <span class="n">p</span><span class="p">}))</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AssertionError</span>: <span class="n">foo</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">SilentAssertionError</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">silent_variable_failure</span> <span class="o">=</span> <span class="kc">True</span>
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">PersonClass4</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">first_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">raise</span> <span class="n">SilentAssertionError</span>
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">PersonClass4</span><span class="p">()</span>
<span class="gp">>>> </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="s2">"person"</span><span class="p">:</span> <span class="n">p</span><span class="p">}))</span>
<span class="go">"My name is ."</span>
</pre></div>
</div>
<p>Note that <a class="reference internal" href="../exceptions.html#django.core.exceptions.ObjectDoesNotExist" title="django.core.exceptions.ObjectDoesNotExist"><code class="xref py py-exc docutils literal"><span class="pre">django.core.exceptions.ObjectDoesNotExist</span></code></a>, which is the
base class for all Django database API <code class="docutils literal"><span class="pre">DoesNotExist</span></code> exceptions, has
<code class="docutils literal"><span class="pre">silent_variable_failure</span> <span class="pre">=</span> <span class="pre">True</span></code>. So if you’re using Django templates
with Django model objects, any <code class="docutils literal"><span class="pre">DoesNotExist</span></code> exception will fail
silently.</p>
</li>
<li><p class="first">A variable can only be called if it has no required arguments. Otherwise,
the system will return the value of the engine’s <code class="docutils literal"><span class="pre">string_if_invalid</span></code>
option.</p>
</li>
</ul>
<ul id="alters-data-description">
<li><p class="first">Obviously, there can be side effects when calling some variables, and
it’d be either foolish or a security hole to allow the template system
to access them.</p>
<p>A good example is the <a class="reference internal" href="../models/instances.html#django.db.models.Model.delete" title="django.db.models.Model.delete"><code class="xref py py-meth docutils literal"><span class="pre">delete()</span></code></a> method on
each Django model object. The template system shouldn’t be allowed to do
something like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">I</span> <span class="n">will</span> <span class="n">now</span> <span class="n">delete</span> <span class="n">this</span> <span class="n">valuable</span> <span class="n">data</span><span class="o">.</span> <span class="p">{{</span> <span class="n">data</span><span class="o">.</span><span class="n">delete</span> <span class="p">}}</span>
</pre></div>
</div>
<p>To prevent this, set an <code class="docutils literal"><span class="pre">alters_data</span></code> attribute on the callable
variable. The template system won’t call a variable if it has
<code class="docutils literal"><span class="pre">alters_data=True</span></code> set, and will instead replace the variable with
<code class="docutils literal"><span class="pre">string_if_invalid</span></code>, unconditionally. The
dynamically-generated <a class="reference internal" href="../models/instances.html#django.db.models.Model.delete" title="django.db.models.Model.delete"><code class="xref py py-meth docutils literal"><span class="pre">delete()</span></code></a> and
<a class="reference internal" href="../models/instances.html#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal"><span class="pre">save()</span></code></a> methods on Django model objects get
<code class="docutils literal"><span class="pre">alters_data=True</span></code> automatically. Example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">sensitive_function</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">database_record</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span>
<span class="n">sensitive_function</span><span class="o">.</span><span class="n">alters_data</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</div>
</li>
<li><p class="first">Occasionally you may want to turn off this feature for other reasons,
and tell the template system to leave a variable uncalled no matter
what. To do so, set a <code class="docutils literal"><span class="pre">do_not_call_in_templates</span></code> attribute on the
callable with the value <code class="docutils literal"><span class="pre">True</span></code>. The template system then will act as
if your variable is not callable (allowing you to access attributes of
the callable, for example).</p>
</li>
</ul>
</div>
<div class="section" id="s-how-invalid-variables-are-handled">
<span id="s-invalid-template-variables"></span><span id="how-invalid-variables-are-handled"></span><span id="invalid-template-variables"></span><h3>How invalid variables are handled<a class="headerlink" href="#how-invalid-variables-are-handled" title="Permalink to this headline">¶</a></h3>
<p>Generally, if a variable doesn’t exist, the template system inserts the value
of the engine’s <code class="docutils literal"><span class="pre">string_if_invalid</span></code> configuration option, which is set to
<code class="docutils literal"><span class="pre">''</span></code> (the empty string) by default.</p>
<p>Filters that are applied to an invalid variable will only be applied if
<code class="docutils literal"><span class="pre">string_if_invalid</span></code> is set to <code class="docutils literal"><span class="pre">''</span></code> (the empty string). If
<code class="docutils literal"><span class="pre">string_if_invalid</span></code> is set to any other value, variable filters will be
ignored.</p>
<p>This behavior is slightly different for the <code class="docutils literal"><span class="pre">if</span></code>, <code class="docutils literal"><span class="pre">for</span></code> and <code class="docutils literal"><span class="pre">regroup</span></code>
template tags. If an invalid variable is provided to one of these template
tags, the variable will be interpreted as <code class="docutils literal"><span class="pre">None</span></code>. Filters are always
applied to invalid variables within these template tags.</p>
<p>If <code class="docutils literal"><span class="pre">string_if_invalid</span></code> contains a <code class="docutils literal"><span class="pre">'%s'</span></code>, the format marker will be
replaced with the name of the invalid variable.</p>
<div class="admonition-for-debug-purposes-only admonition">
<p class="first admonition-title">For debug purposes only!</p>
<p>While <code class="docutils literal"><span class="pre">string_if_invalid</span></code> can be a useful debugging tool, it is a bad
idea to turn it on as a ‘development default’.</p>
<p>Many templates, including those in the Admin site, rely upon the silence
of the template system when a non-existent variable is encountered. If you
assign a value other than <code class="docutils literal"><span class="pre">''</span></code> to <code class="docutils literal"><span class="pre">string_if_invalid</span></code>, you will
experience rendering problems with these templates and sites.</p>
<p class="last">Generally, <code class="docutils literal"><span class="pre">string_if_invalid</span></code> should only be enabled in order to debug
a specific template problem, then cleared once debugging is complete.</p>
</div>
</div>
<div class="section" id="s-built-in-variables">
<span id="built-in-variables"></span><h3>Built-in variables<a class="headerlink" href="#built-in-variables" title="Permalink to this headline">¶</a></h3>
<p>Every context contains <code class="docutils literal"><span class="pre">True</span></code>, <code class="docutils literal"><span class="pre">False</span></code> and <code class="docutils literal"><span class="pre">None</span></code>. As you would expect,
these variables resolve to the corresponding Python objects.</p>
</div>
<div class="section" id="s-limitations-with-string-literals">
<span id="limitations-with-string-literals"></span><h3>Limitations with string literals<a class="headerlink" href="#limitations-with-string-literals" title="Permalink to this headline">¶</a></h3>
<p>Django’s template language has no way to escape the characters used for its own
syntax. For example, the <a class="reference internal" href="builtins.html#std:templatetag-templatetag"><code class="xref std std-ttag docutils literal"><span class="pre">templatetag</span></code></a> tag is required if you need to
output character sequences like <code class="docutils literal"><span class="pre">{%</span></code> and <code class="docutils literal"><span class="pre">%}</span></code>.</p>
<p>A similar issue exists if you want to include these sequences in template filter
or tag arguments. For example, when parsing a block tag, Django’s template
parser looks for the first occurrence of <code class="docutils literal"><span class="pre">%}</span></code> after a <code class="docutils literal"><span class="pre">{%</span></code>. This prevents
the use of <code class="docutils literal"><span class="pre">"%}"</span></code> as a string literal. For example, a <code class="docutils literal"><span class="pre">TemplateSyntaxError</span></code>
will be raised for the following expressions:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">include</span> <span class="s2">"template.html"</span> <span class="n">tvar</span><span class="o">=</span><span class="s2">"Some string literal with %} in it."</span> <span class="o">%</span><span class="p">}</span>
<span class="p">{</span><span class="o">%</span> <span class="k">with</span> <span class="n">tvar</span><span class="o">=</span><span class="s2">"Some string literal with %} in it."</span> <span class="o">%</span><span class="p">}{</span><span class="o">%</span> <span class="n">endwith</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>The same issue can be triggered by using a reserved sequence in filter
arguments:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{{</span> <span class="n">some</span><span class="o">.</span><span class="n">variable</span><span class="o">|</span><span class="n">default</span><span class="p">:</span><span class="s2">"}}"</span> <span class="p">}}</span>
</pre></div>
</div>
<p>If you need to use strings with these sequences, store them in template
variables or use a custom template tag or filter to workaround the limitation.</p>
</div>
</div>
<div class="section" id="s-playing-with-context-objects">
<span id="s-playing-with-context"></span><span id="playing-with-context-objects"></span><span id="playing-with-context"></span><h2>Playing with Context objects<a class="headerlink" href="#playing-with-context-objects" title="Permalink to this headline">¶</a></h2>
<p>Most of the time, you’ll instantiate <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> objects by passing in a
fully-populated dictionary to <code class="docutils literal"><span class="pre">Context()</span></code>. But you can add and delete items
from a <code class="docutils literal"><span class="pre">Context</span></code> object once it’s been instantiated, too, using standard
dictionary syntax:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">Context</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">"foo"</span><span class="p">:</span> <span class="s2">"bar"</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'bar'</span>
<span class="gp">>>> </span><span class="k">del</span> <span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">KeyError</span>: <span class="n">'foo'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'newvariable'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'hello'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'newvariable'</span><span class="p">]</span>
<span class="go">'hello'</span>
</pre></div>
</div>
<dl class="method">
<dt id="django.template.Context.get">
<code class="descclassname">Context.</code><code class="descname">get</code>(<em>key</em>, <em>otherwise=None</em>)<a class="headerlink" href="#django.template.Context.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the value for <code class="docutils literal"><span class="pre">key</span></code> if <code class="docutils literal"><span class="pre">key</span></code> is in the context, else returns
<code class="docutils literal"><span class="pre">otherwise</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="django.template.Context.pop">
<code class="descclassname">Context.</code><code class="descname">pop</code>()<a class="headerlink" href="#django.template.Context.pop" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="django.template.Context.push">
<code class="descclassname">Context.</code><code class="descname">push</code>()<a class="headerlink" href="#django.template.Context.push" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="exception">
<dt id="django.template.ContextPopException">
<em class="property">exception </em><code class="descname">ContextPopException</code><a class="reference internal" href="../../_modules/django/template/context.html#ContextPopException"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.ContextPopException" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>A <code class="docutils literal"><span class="pre">Context</span></code> object is a stack. That is, you can <code class="docutils literal"><span class="pre">push()</span></code> and <code class="docutils literal"><span class="pre">pop()</span></code> it.
If you <code class="docutils literal"><span class="pre">pop()</span></code> too much, it’ll raise
<code class="docutils literal"><span class="pre">django.template.ContextPopException</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'first level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">push</span><span class="p">()</span>
<span class="go">{}</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'second level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'second level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="go">{'foo': 'second level'}</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'first level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'overwritten'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'overwritten'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ContextPopException</span>
</pre></div>
</div>
<div class="versionadded">
<span class="title">New in Django 1.7.</span> </div>
<p>You can also use <code class="docutils literal"><span class="pre">push()</span></code> as a context manager to ensure a matching <code class="docutils literal"><span class="pre">pop()</span></code>
is called.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'first level'</span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">c</span><span class="o">.</span><span class="n">push</span><span class="p">():</span>
<span class="gp">... </span> <span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'second level'</span>
<span class="gp">... </span> <span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'second level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'first level'</span>
</pre></div>
</div>
<p>All arguments passed to <code class="docutils literal"><span class="pre">push()</span></code> will be passed to the <code class="docutils literal"><span class="pre">dict</span></code> constructor
used to build the new context level.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'first level'</span>
<span class="gp">>>> </span><span class="k">with</span> <span class="n">c</span><span class="o">.</span><span class="n">push</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="s1">'second level'</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'second level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'first level'</span>
</pre></div>
</div>
<dl class="method">
<dt id="django.template.Context.update">
<code class="descclassname">Context.</code><code class="descname">update</code>(<em>other_dict</em>)<a class="reference internal" href="../../_modules/django/template/context.html#Context.update"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.Context.update" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>In addition to <code class="docutils literal"><span class="pre">push()</span></code> and <code class="docutils literal"><span class="pre">pop()</span></code>, the <code class="docutils literal"><span class="pre">Context</span></code>
object also defines an <code class="docutils literal"><span class="pre">update()</span></code> method. This works like <code class="docutils literal"><span class="pre">push()</span></code>
but takes a dictionary as an argument and pushes that dictionary onto
the stack instead of an empty one.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'first level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'updated'</span><span class="p">})</span>
<span class="go">{'foo': 'updated'}</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'updated'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="go">{'foo': 'updated'}</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span>
<span class="go">'first level'</span>
</pre></div>
</div>
<p>Using a <code class="docutils literal"><span class="pre">Context</span></code> as a stack comes in handy in <a class="reference internal" href="../../howto/custom-template-tags.html#howto-writing-custom-template-tags"><span class="std std-ref">some custom template
tags</span></a>.</p>
<dl class="method">
<dt id="django.template.Context.flatten">
<code class="descclassname">Context.</code><code class="descname">flatten</code>()<a class="headerlink" href="#django.template.Context.flatten" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="versionadded">
<span class="title">New in Django 1.7.</span> </div>
<p>Using <code class="docutils literal"><span class="pre">flatten()</span></code> method you can get whole <code class="docutils literal"><span class="pre">Context</span></code> stack as one dictionary
including builtin variables.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'first level'</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'second level'</span><span class="p">})</span>
<span class="go">{'bar': 'second level'}</span>
<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">flatten</span><span class="p">()</span>
<span class="go">{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}</span>
</pre></div>
</div>
<p>A <code class="docutils literal"><span class="pre">flatten()</span></code> method is also internally used to make <code class="docutils literal"><span class="pre">Context</span></code> objects comparable.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">c1</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c1</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'first level'</span>
<span class="gp">>>> </span><span class="n">c1</span><span class="p">[</span><span class="s1">'bar'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'second level'</span>
<span class="gp">>>> </span><span class="n">c2</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">c2</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'second level'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'first level'</span><span class="p">})</span>
<span class="go">{'foo': 'first level', 'bar': 'second level'}</span>
<span class="gp">>>> </span><span class="n">c1</span> <span class="o">==</span> <span class="n">c2</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Result from <code class="docutils literal"><span class="pre">flatten()</span></code> can be useful in unit tests to compare <code class="docutils literal"><span class="pre">Context</span></code>
against <code class="docutils literal"><span class="pre">dict</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ContextTest</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">test_against_dictionary</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">c1</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="n">c1</span><span class="p">[</span><span class="s1">'update'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'value'</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">c1</span><span class="o">.</span><span class="n">flatten</span><span class="p">(),</span> <span class="p">{</span>
<span class="s1">'True'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
<span class="s1">'None'</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
<span class="s1">'False'</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>
<span class="s1">'update'</span><span class="p">:</span> <span class="s1">'value'</span><span class="p">,</span>
<span class="p">})</span>
</pre></div>
</div>
<div class="section" id="s-subclassing-context-requestcontext">
<span id="s-id1"></span><span id="subclassing-context-requestcontext"></span><span id="id1"></span><h3>Subclassing Context: RequestContext<a class="headerlink" href="#subclassing-context-requestcontext" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.template.RequestContext">
<em class="property">class </em><code class="descname">RequestContext</code>(<em>request</em>, <em>dict_=None</em>, <em>processors=None</em>)<a class="reference internal" href="../../_modules/django/template/context.html#RequestContext"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.RequestContext" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Django comes with a special <code class="docutils literal"><span class="pre">Context</span></code> class,
<code class="docutils literal"><span class="pre">django.template.RequestContext</span></code>, that acts slightly differently from the
normal <code class="docutils literal"><span class="pre">django.template.Context</span></code>. The first difference is that it takes an
<a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></code></a> as its first argument. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">c</span> <span class="o">=</span> <span class="n">RequestContext</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="p">{</span>
<span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'bar'</span><span class="p">,</span>
<span class="p">})</span>
</pre></div>
</div>
<p>The second difference is that it automatically populates the context with a
few variables, according to the engine’s <code class="docutils literal"><span class="pre">context_processors</span></code> configuration
option.</p>
<p>The <code class="docutils literal"><span class="pre">context_processors</span></code> option is a list of callables – called <strong>context
processors</strong> – that take a request object as their argument and return a
dictionary of items to be merged into the context. In the default generated
settings file, the default template engine contains the following context
processors:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="s1">'django.template.context_processors.debug'</span><span class="p">,</span>
<span class="s1">'django.template.context_processors.request'</span><span class="p">,</span>
<span class="s1">'django.contrib.auth.context_processors.auth'</span><span class="p">,</span>
<span class="s1">'django.contrib.messages.context_processors.messages'</span><span class="p">,</span>
<span class="p">]</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p>Built-in template context processors were moved from
<code class="docutils literal"><span class="pre">django.core.context_processors</span></code> to
<code class="docutils literal"><span class="pre">django.template.context_processors</span></code> in Django 1.8.</p>
</div>
<p>In addition to these, <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal"><span class="pre">RequestContext</span></code></a> always enables
<code class="docutils literal"><span class="pre">'django.template.context_processors.csrf'</span></code>. This is a security related
context processor required by the admin and other contrib apps, and, in case
of accidental misconfiguration, it is deliberately hardcoded in and cannot be
turned off in the <code class="docutils literal"><span class="pre">context_processors</span></code> option.</p>
<p>Each processor is applied in order. That means, if one processor adds a
variable to the context and a second processor adds a variable with the same
name, the second will override the first. The default processors are explained
below.</p>
<div class="admonition-when-context-processors-are-applied admonition">
<p class="first admonition-title">When context processors are applied</p>
<p>Context processors are applied on top of context data. This means that a
context processor may overwrite variables you’ve supplied to your
<a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal"><span class="pre">Context</span></code></a> or <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal"><span class="pre">RequestContext</span></code></a>, so take care to avoid
variable names that overlap with those supplied by your context
processors.</p>
<p>If you want context data to take priority over context processors, use the
following pattern:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">RequestContext</span>
<span class="n">request_context</span> <span class="o">=</span> <span class="n">RequestContext</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
<span class="n">request_context</span><span class="o">.</span><span class="n">push</span><span class="p">({</span><span class="s2">"my_name"</span><span class="p">:</span> <span class="s2">"Adrian"</span><span class="p">})</span>
</pre></div>
</div>
<p class="last">Django does this to allow context data to override context processors in
APIs such as <a class="reference internal" href="../../topics/http/shortcuts.html#django.shortcuts.render" title="django.shortcuts.render"><code class="xref py py-func docutils literal"><span class="pre">render()</span></code></a> and
<a class="reference internal" href="../template-response.html#django.template.response.TemplateResponse" title="django.template.response.TemplateResponse"><code class="xref py py-class docutils literal"><span class="pre">TemplateResponse</span></code></a>.</p>
</div>
<p>Also, you can give <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal"><span class="pre">RequestContext</span></code></a> a list of additional processors,
using the optional, third positional argument, <code class="docutils literal"><span class="pre">processors</span></code>. In this
example, the <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal"><span class="pre">RequestContext</span></code></a> instance gets a <code class="docutils literal"><span class="pre">ip_address</span></code> variable:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.http</span> <span class="k">import</span> <span class="n">HttpResponse</span>
<span class="kn">from</span> <span class="nn">django.template</span> <span class="k">import</span> <span class="n">RequestContext</span>
<span class="k">def</span> <span class="nf">ip_address_processor</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">'ip_address'</span><span class="p">:</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="p">[</span><span class="s1">'REMOTE_ADDR'</span><span class="p">]}</span>
<span class="k">def</span> <span class="nf">some_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
<span class="c1"># ...</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">RequestContext</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="p">{</span>
<span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'bar'</span><span class="p">,</span>
<span class="p">},</span> <span class="p">[</span><span class="n">ip_address_processor</span><span class="p">])</span>
<span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">c</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="s-built-in-template-context-processors">
<span id="s-context-processors"></span><span id="built-in-template-context-processors"></span><span id="context-processors"></span><h3>Built-in template context processors<a class="headerlink" href="#built-in-template-context-processors" title="Permalink to this headline">¶</a></h3>
<p>Here’s what each of the built-in processors does:</p>
<div class="section" id="s-django-contrib-auth-context-processors-auth">
<span id="django-contrib-auth-context-processors-auth"></span><h4>django.contrib.auth.context_processors.auth<a class="headerlink" href="#django-contrib-auth-context-processors-auth" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.contrib.auth.context_processors.auth">
<code class="descname">auth</code>()<a class="headerlink" href="#django.contrib.auth.context_processors.auth" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain these
variables:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">user</span></code> – An <code class="docutils literal"><span class="pre">auth.User</span></code> instance representing the currently
logged-in user (or an <code class="docutils literal"><span class="pre">AnonymousUser</span></code> instance, if the client isn’t
logged in).</li>
<li><code class="docutils literal"><span class="pre">perms</span></code> – An instance of
<code class="docutils literal"><span class="pre">django.contrib.auth.context_processors.PermWrapper</span></code>, representing the
permissions that the currently logged-in user has.</li>
</ul>
</div>
<div class="section" id="s-django-template-context-processors-debug">
<span id="django-template-context-processors-debug"></span><h4>django.template.context_processors.debug<a class="headerlink" href="#django-template-context-processors-debug" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.template.context_processors.debug">
<code class="descname">debug</code>()<a class="headerlink" href="#django.template.context_processors.debug" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain these two
variables – but only if your <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></code></a> setting is set to <code class="docutils literal"><span class="pre">True</span></code> and
the request’s IP address (<code class="docutils literal"><span class="pre">request.META['REMOTE_ADDR']</span></code>) is in the
<a class="reference internal" href="../settings.html#std:setting-INTERNAL_IPS"><code class="xref std std-setting docutils literal"><span class="pre">INTERNAL_IPS</span></code></a> setting:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">debug</span></code> – <code class="docutils literal"><span class="pre">True</span></code>. You can use this in templates to test whether
you’re in <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></code></a> mode.</li>
<li><code class="docutils literal"><span class="pre">sql_queries</span></code> – A list of <code class="docutils literal"><span class="pre">{'sql':</span> <span class="pre">...,</span> <span class="pre">'time':</span> <span class="pre">...}</span></code> dictionaries,
representing every SQL query that has happened so far during the request
and how long it took. The list is in order by query and lazily generated
on access.</li>
</ul>
</div>
<div class="section" id="s-django-template-context-processors-i18n">
<span id="django-template-context-processors-i18n"></span><h4>django.template.context_processors.i18n<a class="headerlink" href="#django-template-context-processors-i18n" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain these two
variables:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">LANGUAGES</span></code> – The value of the <a class="reference internal" href="../settings.html#std:setting-LANGUAGES"><code class="xref std std-setting docutils literal"><span class="pre">LANGUAGES</span></code></a> setting.</li>
<li><code class="docutils literal"><span class="pre">LANGUAGE_CODE</span></code> – <code class="docutils literal"><span class="pre">request.LANGUAGE_CODE</span></code>, if it exists. Otherwise,
the value of the <a class="reference internal" href="../settings.html#std:setting-LANGUAGE_CODE"><code class="xref std std-setting docutils literal"><span class="pre">LANGUAGE_CODE</span></code></a> setting.</li>
</ul>
<p>See <a class="reference internal" href="../../topics/i18n/index.html"><span class="doc">Internationalization and localization</span></a> for more.</p>
</div>
<div class="section" id="s-django-template-context-processors-media">
<span id="django-template-context-processors-media"></span><h4>django.template.context_processors.media<a class="headerlink" href="#django-template-context-processors-media" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal"><span class="pre">MEDIA_URL</span></code>, providing the value of the <a class="reference internal" href="../settings.html#std:setting-MEDIA_URL"><code class="xref std std-setting docutils literal"><span class="pre">MEDIA_URL</span></code></a> setting.</p>
</div>
<div class="section" id="s-django-template-context-processors-static">
<span id="django-template-context-processors-static"></span><h4>django.template.context_processors.static<a class="headerlink" href="#django-template-context-processors-static" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.template.context_processors.static">
<code class="descname">static</code>()<a class="headerlink" href="#django.template.context_processors.static" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal"><span class="pre">STATIC_URL</span></code>, providing the value of the <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><code class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></code></a> setting.</p>
</div>
<div class="section" id="s-django-template-context-processors-csrf">
<span id="django-template-context-processors-csrf"></span><h4>django.template.context_processors.csrf<a class="headerlink" href="#django-template-context-processors-csrf" title="Permalink to this headline">¶</a></h4>
<p>This processor adds a token that is needed by the <a class="reference internal" href="builtins.html#std:templatetag-csrf_token"><code class="xref std std-ttag docutils literal"><span class="pre">csrf_token</span></code></a> template
tag for protection against <a class="reference internal" href="../csrf.html"><span class="doc">Cross Site Request Forgeries</span></a>.</p>
</div>
<div class="section" id="s-django-template-context-processors-request">
<span id="django-template-context-processors-request"></span><h4>django.template.context_processors.request<a class="headerlink" href="#django-template-context-processors-request" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal"><span class="pre">request</span></code>, which is the current <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></code></a>.</p>
</div>
<div class="section" id="s-django-contrib-messages-context-processors-messages">
<span id="django-contrib-messages-context-processors-messages"></span><h4>django.contrib.messages.context_processors.messages<a class="headerlink" href="#django-contrib-messages-context-processors-messages" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal"><span class="pre">RequestContext</span></code> will contain these two
variables:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">messages</span></code> – A list of messages (as strings) that have been set
via the <a class="reference internal" href="../contrib/messages.html"><span class="doc">messages framework</span></a>.</li>
<li><code class="docutils literal"><span class="pre">DEFAULT_MESSAGE_LEVELS</span></code> – A mapping of the message level names to
<a class="reference internal" href="../contrib/messages.html#message-level-constants"><span class="std std-ref">their numeric value</span></a>.</li>
</ul>
<div class="versionchanged">
<span class="title">Changed in Django 1.7:</span> <p>The <code class="docutils literal"><span class="pre">DEFAULT_MESSAGE_LEVELS</span></code> variable was added.</p>
</div>
</div>
</div>
<div class="section" id="s-writing-your-own-context-processors">
<span id="writing-your-own-context-processors"></span><h3>Writing your own context processors<a class="headerlink" href="#writing-your-own-context-processors" title="Permalink to this headline">¶</a></h3>
<p>A context processor has a very simple interface: It’s just a Python function
that takes one argument, an <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></code></a> object, and
returns a dictionary that gets added to the template context. Each context
processor <em>must</em> return a dictionary.</p>
<p>Custom context processors can live anywhere in your code base. All Django
cares about is that your custom context processors are pointed to by the
<code class="docutils literal"><span class="pre">'context_processors'</span></code> option in your <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal"><span class="pre">TEMPLATES</span></code></a> setting — or the
<code class="docutils literal"><span class="pre">context_processors</span></code> argument of <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a> if you’re
using it directly.</p>
</div>
</div>
<div class="section" id="s-loading-templates">
<span id="loading-templates"></span><h2>Loading templates<a class="headerlink" href="#loading-templates" title="Permalink to this headline">¶</a></h2>
<p>Generally, you’ll store templates in files on your filesystem rather than
using the low-level <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal"><span class="pre">Template</span></code></a> API yourself. Save
templates in a directory specified as a <strong>template directory</strong>.</p>
<p>Django searches for template directories in a number of places, depending on
your template loading settings (see “Loader types” below), but the most basic
way of specifying template directories is by using the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal"><span class="pre">DIRS</span></code></a> option.</p>
<div class="section" id="s-the-dirs-option">
<span id="the-dirs-option"></span><h3>The <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal"><span class="pre">DIRS</span></code></a> option<a class="headerlink" href="#the-dirs-option" title="Permalink to this headline">¶</a></h3>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p>This value used to be defined by the <code class="docutils literal"><span class="pre">TEMPLATE_DIRS</span></code> setting.</p>
</div>
<p>Tell Django what your template directories are by using the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal"><span class="pre">DIRS</span></code></a> option in the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal"><span class="pre">TEMPLATES</span></code></a> setting in your settings
file — or the <code class="docutils literal"><span class="pre">dirs</span></code> argument of <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a>. This
should be set to a list of strings that contain full paths to your template
directories:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[</span>
<span class="p">{</span>
<span class="s1">'BACKEND'</span><span class="p">:</span> <span class="s1">'django.template.backends.django.DjangoTemplates'</span><span class="p">,</span>
<span class="s1">'DIRS'</span><span class="p">:</span> <span class="p">[</span>
<span class="s1">'/home/html/templates/lawrence.com'</span><span class="p">,</span>
<span class="s1">'/home/html/templates/default'</span><span class="p">,</span>
<span class="p">],</span>
<span class="p">},</span>
<span class="p">]</span>
</pre></div>
</div>
<p>Your templates can go anywhere you want, as long as the directories and
templates are readable by the Web server. They can have any extension you want,
such as <code class="docutils literal"><span class="pre">.html</span></code> or <code class="docutils literal"><span class="pre">.txt</span></code>, or they can have no extension at all.</p>
<p>Note that these paths should use Unix-style forward slashes, even on Windows.</p>
</div>
<div class="section" id="s-loader-types">
<span id="s-template-loaders"></span><span id="loader-types"></span><span id="template-loaders"></span><h3>Loader types<a class="headerlink" href="#loader-types" title="Permalink to this headline">¶</a></h3>
<p>By default, Django uses a filesystem-based template loader, but Django comes
with a few other template loaders, which know how to load templates from other
sources.</p>
<p>Some of these other loaders are disabled by default, but you can activate them
by adding a <code class="docutils literal"><span class="pre">'loaders'</span></code> option to your <code class="docutils literal"><span class="pre">DjangoTemplates</span></code> backend in the
<a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal"><span class="pre">TEMPLATES</span></code></a> setting or passing a <code class="docutils literal"><span class="pre">loaders</span></code> argument to
<a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a>. <code class="docutils literal"><span class="pre">loaders</span></code> should be a list of strings or
tuples, where each represents a template loader class. Here are the template
loaders that come with Django:</p>
<p><code class="docutils literal"><span class="pre">django.template.loaders.filesystem.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.filesystem.Loader">
<em class="property">class </em><code class="descclassname">filesystem.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.filesystem.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from the filesystem, according to
<a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal"><span class="pre">DIRS</span></code></a>.</p>
<p>This loader is enabled by default. However it won’t find any templates
until you set <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal"><span class="pre">DIRS</span></code></a> to a non-empty list:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
<span class="s1">'BACKEND'</span><span class="p">:</span> <span class="s1">'django.template.backends.django.DjangoTemplates'</span><span class="p">,</span>
<span class="s1">'DIRS'</span><span class="p">:</span> <span class="p">[</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">BASE_DIR</span><span class="p">,</span> <span class="s1">'templates'</span><span class="p">)],</span>
<span class="p">}]</span>
</pre></div>
</div>
</dd></dl>
<p><code class="docutils literal"><span class="pre">django.template.loaders.app_directories.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.app_directories.Loader">
<em class="property">class </em><code class="descclassname">app_directories.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.app_directories.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from Django apps on the filesystem. For each app 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>, the loader looks for a <code class="docutils literal"><span class="pre">templates</span></code>
subdirectory. If the directory exists, Django looks for templates in there.</p>
<p>This means you can store templates with your individual apps. This also
makes it easy to distribute Django apps with default templates.</p>
<p>For example, for this setting:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'myproject.polls'</span><span class="p">,</span> <span class="s1">'myproject.music'</span><span class="p">)</span>
</pre></div>
</div>
<p>...then <code class="docutils literal"><span class="pre">get_template('foo.html')</span></code> will look for <code class="docutils literal"><span class="pre">foo.html</span></code> in these
directories, in this order:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">/path/to/myproject/polls/templates/</span></code></li>
<li><code class="docutils literal"><span class="pre">/path/to/myproject/music/templates/</span></code></li>
</ul>
<p>... and will use the one it finds first.</p>
<p>The order of <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> is significant! For example, if you
want to customize the Django admin, you might choose to override the
standard <code class="docutils literal"><span class="pre">admin/base_site.html</span></code> template, from <code class="docutils literal"><span class="pre">django.contrib.admin</span></code>,
with your own <code class="docutils literal"><span class="pre">admin/base_site.html</span></code> in <code class="docutils literal"><span class="pre">myproject.polls</span></code>. You must
then make sure that your <code class="docutils literal"><span class="pre">myproject.polls</span></code> comes <em>before</em>
<code class="docutils literal"><span class="pre">django.contrib.admin</span></code> 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>, otherwise
<code class="docutils literal"><span class="pre">django.contrib.admin</span></code>’s will be loaded first and yours will be ignored.</p>
<p>Note that the loader performs an optimization when it first runs:
it caches a list of which <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> packages have a
<code class="docutils literal"><span class="pre">templates</span></code> subdirectory.</p>
<p>You can enable this loader simply by setting
<a class="reference internal" href="../settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal"><span class="pre">APP_DIRS</span></code></a> to <code class="docutils literal"><span class="pre">True</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
<span class="s1">'BACKEND'</span><span class="p">:</span> <span class="s1">'django.template.backends.django.DjangoTemplates'</span><span class="p">,</span>
<span class="s1">'APP_DIRS'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
<span class="p">}]</span>
</pre></div>
</div>
</dd></dl>
<p><code class="docutils literal"><span class="pre">django.template.loaders.eggs.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.eggs.Loader">
<em class="property">class </em><code class="descclassname">eggs.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.eggs.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Just like <code class="docutils literal"><span class="pre">app_directories</span></code> above, but it loads templates from Python
eggs rather than from the filesystem.</p>
<p>This loader is disabled by default.</p>
</dd></dl>
<p><code class="docutils literal"><span class="pre">django.template.loaders.cached.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.cached.Loader">
<em class="property">class </em><code class="descclassname">cached.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.cached.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>By default, the templating system will read and compile your templates every
time they need to be rendered. While the Django templating system is quite
fast, the overhead from reading and compiling templates can add up.</p>
<p>The cached template loader is a class-based loader that you configure with
a list of other loaders that it should wrap. The wrapped loaders are used to
locate unknown templates when they are first encountered. The cached loader
then stores the compiled <code class="docutils literal"><span class="pre">Template</span></code> in memory. The cached <code class="docutils literal"><span class="pre">Template</span></code>
instance is returned for subsequent requests to load the same template.</p>
<p>For example, to enable template caching with the <code class="docutils literal"><span class="pre">filesystem</span></code> and
<code class="docutils literal"><span class="pre">app_directories</span></code> template loaders you might use the following settings:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
<span class="s1">'BACKEND'</span><span class="p">:</span> <span class="s1">'django.template.backends.django.DjangoTemplates'</span><span class="p">,</span>
<span class="s1">'DIRS'</span><span class="p">:</span> <span class="p">[</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">BASE_DIR</span><span class="p">,</span> <span class="s1">'templates'</span><span class="p">)],</span>
<span class="s1">'OPTIONS'</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">'loaders'</span><span class="p">:</span> <span class="p">[</span>
<span class="p">(</span><span class="s1">'django.template.loaders.cached.Loader'</span><span class="p">,</span> <span class="p">[</span>
<span class="s1">'django.template.loaders.filesystem.Loader'</span><span class="p">,</span>
<span class="s1">'django.template.loaders.app_directories.Loader'</span><span class="p">,</span>
<span class="p">]),</span>
<span class="p">],</span>
<span class="p">},</span>
<span class="p">}]</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">All of the built-in Django template tags are safe to use with the
cached loader, but if you’re using custom template tags that come from
third party packages, or that you wrote yourself, you should ensure
that the <code class="docutils literal"><span class="pre">Node</span></code> implementation for each tag is thread-safe. For more
information, see <a class="reference internal" href="../../howto/custom-template-tags.html#template-tag-thread-safety"><span class="std std-ref">template tag thread safety considerations</span></a>.</p>
</div>
<p>This loader is disabled by default.</p>
</dd></dl>
<p><code class="docutils literal"><span class="pre">django.template.loaders.locmem.Loader</span></code></p>
<div class="versionadded">
<span class="title">New in Django 1.8.</span> </div>
<dl class="class">
<dt id="django.template.loaders.locmem.Loader">
<em class="property">class </em><code class="descclassname">locmem.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.locmem.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from a Python dictionary. This is useful for testing.</p>
<p>This loader takes a dictionary of templates as its first argument:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
<span class="s1">'BACKEND'</span><span class="p">:</span> <span class="s1">'django.template.backends.django.DjangoTemplates'</span><span class="p">,</span>
<span class="s1">'OPTIONS'</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">'loaders'</span><span class="p">:</span> <span class="p">[</span>
<span class="p">(</span><span class="s1">'django.template.loaders.locmem.Loader'</span><span class="p">,</span> <span class="p">{</span>
<span class="s1">'index.html'</span><span class="p">:</span> <span class="s1">'content here'</span><span class="p">,</span>
<span class="p">}),</span>
<span class="p">],</span>
<span class="p">},</span>
<span class="p">}]</span>
</pre></div>
</div>
<p>This loader is disabled by default.</p>
</dd></dl>
<p>Django uses the template loaders in order according to the <code class="docutils literal"><span class="pre">'loaders'</span></code>
option. It uses each loader until a loader finds a match.</p>
</div>
<div class="section" id="s-custom-loaders">
<span id="s-custom-template-loaders"></span><span id="custom-loaders"></span><span id="custom-template-loaders"></span><h3>Custom loaders<a class="headerlink" href="#custom-loaders" title="Permalink to this headline">¶</a></h3>
<p>Custom <code class="docutils literal"><span class="pre">Loader</span></code> classes should inherit from
<code class="docutils literal"><span class="pre">django.template.loaders.base.Loader</span></code> and override the
<code class="docutils literal"><span class="pre">load_template_source()</span></code> method, which takes a <code class="docutils literal"><span class="pre">template_name</span></code> argument,
loads the template from disk (or elsewhere), and returns a tuple:
<code class="docutils literal"><span class="pre">(template_string,</span> <span class="pre">template_origin)</span></code>.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p><code class="docutils literal"><span class="pre">django.template.loaders.base.Loader</span></code> used to be defined at
<code class="docutils literal"><span class="pre">django.template.loader.BaseLoader</span></code>.</p>
</div>
<p>The <code class="docutils literal"><span class="pre">load_template()</span></code> method of the <code class="docutils literal"><span class="pre">Loader</span></code> class retrieves the template
string by calling <code class="docutils literal"><span class="pre">load_template_source()</span></code>, instantiates a <code class="docutils literal"><span class="pre">Template</span></code> from
the template source, and returns a tuple: <code class="docutils literal"><span class="pre">(template,</span> <span class="pre">template_origin)</span></code>.</p>
</div>
</div>
<div class="section" id="s-template-origin">
<span id="template-origin"></span><h2>Template origin<a class="headerlink" href="#template-origin" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<span class="title">New in Django 1.7.</span> </div>
<p>When an <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal"><span class="pre">Engine</span></code></a> is initialized with <code class="docutils literal"><span class="pre">debug=True</span></code>,
its templates have an <code class="docutils literal"><span class="pre">origin</span></code> attribute depending on the source they are
loaded from. For engines initialized by Django, <code class="docutils literal"><span class="pre">debug</span></code> defaults to the
value of <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal"><span class="pre">DEBUG</span></code></a>.</p>
<dl class="class">
<dt id="django.template.loader.LoaderOrigin">
<em class="property">class </em><code class="descclassname">loader.</code><code class="descname">LoaderOrigin</code><a class="headerlink" href="#django.template.loader.LoaderOrigin" title="Permalink to this definition">¶</a></dt>
<dd><p>Templates created from a template loader will use the
<code class="docutils literal"><span class="pre">django.template.loader.LoaderOrigin</span></code> class.</p>
<dl class="attribute">
<dt id="django.template.loader.LoaderOrigin.name">
<code class="descname">name</code><a class="headerlink" href="#django.template.loader.LoaderOrigin.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The path to the template as returned by the template loader.
For loaders that read from the file system, this is the full
path to the template.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.template.loader.LoaderOrigin.loadname">
<code class="descname">loadname</code><a class="headerlink" href="#django.template.loader.LoaderOrigin.loadname" title="Permalink to this definition">¶</a></dt>
<dd><p>The relative path to the template as passed into the
template loader.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="django.template.StringOrigin">
<em class="property">class </em><code class="descname">StringOrigin</code><a class="reference internal" href="../../_modules/django/template/base.html#StringOrigin"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.template.StringOrigin" title="Permalink to this definition">¶</a></dt>
<dd><p>Templates created from a <code class="docutils literal"><span class="pre">Template</span></code> class will use the
<code class="docutils literal"><span class="pre">django.template.StringOrigin</span></code> class.</p>
<dl class="attribute">
<dt id="django.template.StringOrigin.source">
<code class="descname">source</code><a class="headerlink" href="#django.template.StringOrigin.source" title="Permalink to this definition">¶</a></dt>
<dd><p>The string used to create the template.</p>
</dd></dl>
</dd></dl>
</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: for Python programmers</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#configuring-an-engine">Configuring an engine</a></li>
<li><a class="reference internal" href="#loading-a-template">Loading a template</a></li>
<li><a class="reference internal" href="#rendering-a-context">Rendering a context</a><ul>
<li><a class="reference internal" href="#variables-and-lookups">Variables and lookups</a></li>
<li><a class="reference internal" href="#how-invalid-variables-are-handled">How invalid variables are handled</a></li>
<li><a class="reference internal" href="#built-in-variables">Built-in variables</a></li>
<li><a class="reference internal" href="#limitations-with-string-literals">Limitations with string literals</a></li>
</ul>
</li>
<li><a class="reference internal" href="#playing-with-context-objects">Playing with Context objects</a><ul>
<li><a class="reference internal" href="#subclassing-context-requestcontext">Subclassing Context: RequestContext</a></li>
<li><a class="reference internal" href="#built-in-template-context-processors">Built-in template context processors</a><ul>
<li><a class="reference internal" href="#django-contrib-auth-context-processors-auth">django.contrib.auth.context_processors.auth</a></li>
<li><a class="reference internal" href="#django-template-context-processors-debug">django.template.context_processors.debug</a></li>
<li><a class="reference internal" href="#django-template-context-processors-i18n">django.template.context_processors.i18n</a></li>
<li><a class="reference internal" href="#django-template-context-processors-media">django.template.context_processors.media</a></li>
<li><a class="reference internal" href="#django-template-context-processors-static">django.template.context_processors.static</a></li>
<li><a class="reference internal" href="#django-template-context-processors-csrf">django.template.context_processors.csrf</a></li>
<li><a class="reference internal" href="#django-template-context-processors-request">django.template.context_processors.request</a></li>
<li><a class="reference internal" href="#django-contrib-messages-context-processors-messages">django.contrib.messages.context_processors.messages</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-your-own-context-processors">Writing your own context processors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#loading-templates">Loading templates</a><ul>
<li><a class="reference internal" href="#the-dirs-option">The <code class="docutils literal"><span class="pre">DIRS</span></code> option</a></li>
<li><a class="reference internal" href="#loader-types">Loader types</a></li>
<li><a class="reference internal" href="#custom-loaders">Custom loaders</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-origin">Template origin</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="builtins.html">Built-in template tags and filters</a></li>
<li>Next: <a href="upgrading.html">Upgrading templates to Django 1.8</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: for Python programmers</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/api.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="builtins.html" title="Built-in template tags and filters">previous</a>
|
<a href="../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="upgrading.html" title="Upgrading templates to Django 1.8">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
65530c6176058f9b54858c3b4f6385e6
>
files
>
789
