1 ============================

     2 The Django template language

     3 ============================

     4 

     5 .. admonition:: About this document

     6 

     7     This document explains the language syntax of the Django template system. If

     8     you're looking for a more technical perspective on how it works and how to

     9     extend it, see :doc:`/ref/templates/api`.

    10 

    11 Django's template language is designed to strike a balance between power and

    12 ease. It's designed to feel comfortable to those used to working with HTML. If

    13 you have any exposure to other text-based template languages, such as Smarty_

    14 or CheetahTemplate_, you should feel right at home with Django's templates.

    15 

    16 .. admonition:: Philosophy

    17 

    18     If you have a background in programming, or if you're used to languages

    19     like PHP which mix programming code directly into HTML, you'll want to

    20     bear in mind that the Django template system is not simply Python embedded

    21     into HTML. This is by design: the template system is meant to express

    22     presentation, not program logic.

    23 

    24     The Django template system provides tags which function similarly to some

    25     programming constructs -- an :ttag:`if` tag for boolean tests, a :ttag:`for`

    26     tag for looping, etc. -- but these are not simply executed as the

    27     corresponding Python code, and the template system will not execute

    28     arbitrary Python expressions. Only the tags, filters and syntax listed below

    29     are supported by default (although you can add :doc:`your own extensions

    30     </howto/custom-template-tags>` to the template language as needed).

    31 

    32 .. _`The Django template language: For Python programmers`: ../templates_python/

    33 .. _Smarty: http://smarty.php.net/

    34 .. _CheetahTemplate: http://www.cheetahtemplate.org/

    35 

    36 Templates

    37 =========

    38 

    39 .. highlightlang:: html+django

    40 

    41 A template is simply a text file. It can generate any text-based format (HTML,

    42 XML, CSV, etc.).

    43 

    44 A template contains **variables**, which get replaced with values when the

    45 template is evaluated, and **tags**, which control the logic of the template.

    46 

    47 Below is a minimal template that illustrates a few basics. Each element will be

    48 explained later in this document.::

    49 

    50     {% extends "base_generic.html" %}

    51 

    52     {% block title %}{{ section.title }}{% endblock %}

    53 

    54     {% block content %}

    55     <h1>{{ section.title }}</h1>

    56 

    57     {% for story in story_list %}

    58     <h2>

    59       <a href="{{ story.get_absolute_url }}">

    60         {{ story.headline|upper }}

    61       </a>

    62     </h2>

    63     <p>{{ story.tease|truncatewords:"100" }}</p>

    64     {% endfor %}

    65     {% endblock %}

    66 

    67 .. admonition:: Philosophy

    68 

    69     Why use a text-based template instead of an XML-based one (like Zope's

    70     TAL)? We wanted Django's template language to be usable for more than

    71     just XML/HTML templates. At World Online, we use it for e-mails,

    72     JavaScript and CSV. You can use the template language for any text-based

    73     format.

    74 

    75     Oh, and one more thing: Making humans edit XML is sadistic!

    76 

    77 Variables

    78 =========

    79 

    80 Variables look like this: ``{{ variable }}``. When the template engine

    81 encounters a variable, it evaluates that variable and replaces it with the

    82 result.

    83 

    84 Use a dot (``.``) to access attributes of a variable.

    85 

    86 .. admonition:: Behind the scenes

    87 

    88     Technically, when the template system encounters a dot, it tries the

    89     following lookups, in this order:

    90 

    91         * Dictionary lookup

    92         * Attribute lookup

    93         * Method call

    94         * List-index lookup

    95 

    96 In the above example, ``{{ section.title }}`` will be replaced with the

    97 ``title`` attribute of the ``section`` object.

    98 

    99 If you use a variable that doesn't exist, the template system will insert

   100 the value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''``

   101 (the empty string) by default.

   102 

   103 Filters

   104 =======

   105 

   106 You can modify variables for display by using **filters**.

   107 

   108 Filters look like this: ``{{ name|lower }}``. This displays the value of the

   109 ``{{ name }}`` variable after being filtered through the ``lower`` filter,

   110 which converts text to lowercase. Use a pipe (``|``) to apply a filter.

   111 

   112 Filters can be "chained." The output of one filter is applied to the next.

   113 ``{{ text|escape|linebreaks }}`` is a common idiom for escaping text contents,

   114 then converting line breaks to ``<p>`` tags.

   115 

   116 Some filters take arguments. A filter argument looks like this: ``{{

   117 bio|truncatewords:30 }}``. This will display the first 30 words of the ``bio``

   118 variable.

   119 

   120 Filter arguments that contain spaces must be quoted; for example, to join a list

   121 with commas and spaced you'd use ``{{ list|join:", " }}``.

   122 

   123 Django provides about thirty built-in template filters. You can read all about

   124 them in the :ref:`built-in filter reference <ref-templates-builtins-filters>`.

   125 To give you a taste of what's available, here are some of the more commonly used

   126 template filters:

   127 

   128     :tfilter:`default`

   129         If a variable is false or empty, use given default. Otherwise, use the

   130         value of the variable

   131 

   132         For example::

   133 

   134             {{ value|default:"nothing" }}

   135 

   136         If ``value`` isn't provided or is empty, the above will display

   137         "``nothing``".

   138 

   139     :tfilter:`length`

   140         Returns the length of the value. This works for both strings and lists;

   141         for example::

   142 

   143             {{ value|length }}

   144 

   145         If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.

   146 

   147     :tfilter:`striptags`

   148         Strips all [X]HTML tags. For example::

   149 

   150             {{ value|striptags }}

   151 

   152         If ``value`` is ``"<b>Joel</b> <button>is</button> a

   153         <span>slug</span>"``, the output will be ``"Joel is a slug"``.

   154 

   155 Again, these are just a few examples; see the :ref:`built-in filter reference

   156 <ref-templates-builtins-filters>` for the complete list.

   157 

   158 You can also create your own custom template filters; see

   159 :doc:`/howto/custom-template-tags`.

   160 

   161 .. seealso::

   162 

   163     Django's admin interface can include a complete reference of all template

   164     tags and filters available for a given site. See

   165     :doc:`/ref/contrib/admin/admindocs`.

   166 

   167 Tags

   168 ====

   169 

   170 Tags look like this: ``{% tag %}``. Tags are more complex than variables: Some

   171 create text in the output, some control flow by performing loops or logic, and

   172 some load external information into the template to be used by later variables.

   173 

   174 Some tags require beginning and ending tags (i.e. ``{% tag %} ... tag contents

   175 ... {% endtag %}``).

   176 

   177 Django ships with about two dozen built-in template tags. You can read all about

   178 them in the :ref:`built-in tag reference <ref-templates-builtins-tags>`. To give

   179 you a taste of what's available, here are some of the more commonly used

   180 tags:

   181 

   182     :ttag:`for`

   183         Loop over each item in an array.  For example, to display a list of athletes

   184         provided in ``athlete_list``::

   185 

   186             <ul>

   187             {% for athlete in athlete_list %}

   188                 <li>{{ athlete.name }}</li>

   189             {% endfor %}

   190             </ul>

   191 

   192     :ttag:`if` and ``else``

   193         Evaluates a variable, and if that variable is "true" the contents of the

   194         block are displayed::

   195 

   196             {% if athlete_list %}

   197                 Number of athletes: {{ athlete_list|length }}

   198             {% else %}

   199                 No athletes.

   200             {% endif %}

   201 

   202         In the above, if ``athlete_list`` is not empty, the number of athletes

   203         will be displayed by the ``{{ athlete_list|length }}`` variable.

   204 

   205         You can also use filters and various operators in the ``if`` tag::

   206 

   207             {% if athlete_list|length > 1 %}

   208                Team: {% for athlete in athlete_list %} ... {% endfor %}

   209             {% else %}

   210                Athlete: {{ athlete_list.0.name }}

   211             {% endif %}

   212 

   213     :ttag:`block` and :ttag:`extends`

   214         Set up `template inheritance`_ (see below), a powerful way

   215         of cutting down on "boilerplate" in templates.

   216 

   217 Again, the above is only a selection of the whole list; see the :ref:`built-in

   218 tag reference <ref-templates-builtins-tags>` for the complete list.

   219 

   220 You can also create your own custom template tags; see

   221 :doc:`/howto/custom-template-tags`.

   222 

   223 .. seealso::

   224 

   225     Django's admin interface can include a complete reference of all template

   226     tags and filters available for a given site. See

   227     :doc:`/ref/contrib/admin/admindocs`.

   228 

   229 Comments

   230 ========

   231 

   232 To comment-out part of a line in a template, use the comment syntax: ``{# #}``.

   233 

   234 For example, this template would render as ``'hello'``::

   235 

   236     {# greeting #}hello

   237 

   238 A comment can contain any template code, invalid or not. For example::

   239 

   240     {# {% if foo %}bar{% else %} #}

   241 

   242 This syntax can only be used for single-line comments (no newlines are permitted

   243 between the ``{#`` and ``#}`` delimiters). If you need to comment out a

   244 multiline portion of the template, see the :ttag:`comment` tag.

   245 

   246 .. _template-inheritance:

   247 

   248 Template inheritance

   249 ====================

   250 

   251 The most powerful -- and thus the most complex -- part of Django's template

   252 engine is template inheritance. Template inheritance allows you to build a base

   253 "skeleton" template that contains all the common elements of your site and

   254 defines **blocks** that child templates can override.

   255 

   256 It's easiest to understand template inheritance by starting with an example::

   257 

   258     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

   259         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

   260     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

   261     <head>

   262         <link rel="stylesheet" href="style.css" />

   263         <title>{% block title %}My amazing site{% endblock %}</title>

   264     </head>

   265 

   266     <body>

   267         <div id="sidebar">

   268             {% block sidebar %}

   269             <ul>

   270                 <li><a href="/">Home</a></li>

   271                 <li><a href="/blog/">Blog</a></li>

   272             </ul>

   273             {% endblock %}

   274         </div>

   275 

   276         <div id="content">

   277             {% block content %}{% endblock %}

   278         </div>

   279     </body>

   280     </html>

   281 

   282 This template, which we'll call ``base.html``, defines a simple HTML skeleton

   283 document that you might use for a simple two-column page. It's the job of

   284 "child" templates to fill the empty blocks with content.

   285 

   286 In this example, the ``{% block %}`` tag defines three blocks that child

   287 templates can fill in. All the ``block`` tag does is to tell the template

   288 engine that a child template may override those portions of the template.

   289 

   290 A child template might look like this::

   291 

   292     {% extends "base.html" %}

   293 

   294     {% block title %}My amazing blog{% endblock %}

   295 

   296     {% block content %}

   297     {% for entry in blog_entries %}

   298         <h2>{{ entry.title }}</h2>

   299         <p>{{ entry.body }}</p>

   300     {% endfor %}

   301     {% endblock %}

   302 

   303 The ``{% extends %}`` tag is the key here. It tells the template engine that

   304 this template "extends" another template. When the template system evaluates

   305 this template, first it locates the parent -- in this case, "base.html".

   306 

   307 At that point, the template engine will notice the three ``{% block %}`` tags

   308 in ``base.html`` and replace those blocks with the contents of the child

   309 template. Depending on the value of ``blog_entries``, the output might look

   310 like::

   311 

   312     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

   313         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

   314     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

   315     <head>

   316         <link rel="stylesheet" href="style.css" />

   317         <title>My amazing blog</title>

   318     </head>

   319 

   320     <body>

   321         <div id="sidebar">

   322             <ul>

   323                 <li><a href="/">Home</a></li>

   324                 <li><a href="/blog/">Blog</a></li>

   325             </ul>

   326         </div>

   327 

   328         <div id="content">

   329             <h2>Entry one</h2>

   330             <p>This is my first entry.</p>

   331 

   332             <h2>Entry two</h2>

   333             <p>This is my second entry.</p>

   334         </div>

   335     </body>

   336     </html>

   337 

   338 Note that since the child template didn't define the ``sidebar`` block, the

   339 value from the parent template is used instead. Content within a ``{% block %}``

   340 tag in a parent template is always used as a fallback.

   341 

   342 You can use as many levels of inheritance as needed. One common way of using

   343 inheritance is the following three-level approach:

   344 

   345     * Create a ``base.html`` template that holds the main look-and-feel of your

   346       site.

   347     * Create a ``base_SECTIONNAME.html`` template for each "section" of your

   348       site. For example, ``base_news.html``, ``base_sports.html``. These

   349       templates all extend ``base.html`` and include section-specific

   350       styles/design.

   351     * Create individual templates for each type of page, such as a news

   352       article or blog entry. These templates extend the appropriate section

   353       template.

   354 

   355 This approach maximizes code reuse and makes it easy to add items to shared

   356 content areas, such as section-wide navigation.

   357 

   358 Here are some tips for working with inheritance:

   359 

   360     * If you use ``{% extends %}`` in a template, it must be the first template

   361       tag in that template. Template inheritance won't work, otherwise.

   362 

   363     * More ``{% block %}`` tags in your base templates are better. Remember,

   364       child templates don't have to define all parent blocks, so you can fill

   365       in reasonable defaults in a number of blocks, then only define the ones

   366       you need later. It's better to have more hooks than fewer hooks.

   367 

   368     * If you find yourself duplicating content in a number of templates, it

   369       probably means you should move that content to a ``{% block %}`` in a

   370       parent template.

   371 

   372     * If you need to get the content of the block from the parent template,

   373       the ``{{ block.super }}`` variable will do the trick. This is useful

   374       if you want to add to the contents of a parent block instead of

   375       completely overriding it. Data inserted using ``{{ block.super }}`` will

   376       not be automatically escaped (see the `next section`_), since it was

   377       already escaped, if necessary, in the parent template.

   378 

   379     * For extra readability, you can optionally give a *name* to your

   380       ``{% endblock %}`` tag. For example::

   381 

   382           {% block content %}

   383           ...

   384           {% endblock content %}

   385 

   386       In larger templates, this technique helps you see which ``{% block %}``

   387       tags are being closed.

   388 

   389 Finally, note that you can't define multiple ``{% block %}`` tags with the same

   390 name in the same template. This limitation exists because a block tag works in

   391 "both" directions. That is, a block tag doesn't just provide a hole to fill --

   392 it also defines the content that fills the hole in the *parent*. If there were

   393 two similarly-named ``{% block %}`` tags in a template, that template's parent

   394 wouldn't know which one of the blocks' content to use.

   395 

   396 .. _next section: #automatic-html-escaping

   397 .. _automatic-html-escaping:

   398 

   399 Automatic HTML escaping

   400 =======================

   401 

   402 .. versionadded:: 1.0

   403 

   404 When generating HTML from templates, there's always a risk that a variable will

   405 include characters that affect the resulting HTML. For example, consider this

   406 template fragment::

   407 

   408     Hello, {{ name }}.

   409 

   410 At first, this seems like a harmless way to display a user's name, but consider

   411 what would happen if the user entered his name as this::

   412 

   413     <script>alert('hello')</script>

   414 

   415 With this name value, the template would be rendered as::

   416 

   417     Hello, <script>alert('hello')</script>

   418 

   419 ...which means the browser would pop-up a JavaScript alert box!

   420 

   421 Similarly, what if the name contained a ``'<'`` symbol, like this?

   422 

   423     <b>username

   424 

   425 That would result in a rendered template like this::

   426 

   427     Hello, <b>username

   428 

   429 ...which, in turn, would result in the remainder of the Web page being bolded!

   430 

   431 Clearly, user-submitted data shouldn't be trusted blindly and inserted directly

   432 into your Web pages, because a malicious user could use this kind of hole to

   433 do potentially bad things. This type of security exploit is called a

   434 `Cross Site Scripting`_ (XSS) attack.

   435 

   436 To avoid this problem, you have two options:

   437 

   438     * One, you can make sure to run each untrusted variable through the

   439       ``escape`` filter (documented below), which converts potentially harmful

   440       HTML characters to unharmful ones. This was the default solution

   441       in Django for its first few years, but the problem is that it puts the

   442       onus on *you*, the developer / template author, to ensure you're escaping

   443       everything. It's easy to forget to escape data.

   444 

   445     * Two, you can take advantage of Django's automatic HTML escaping. The

   446       remainder of this section describes how auto-escaping works.

   447 

   448 By default in Django, every template automatically escapes the output

   449 of every variable tag. Specifically, these five characters are

   450 escaped:

   451 

   452     * ``<`` is converted to ``&lt;``

   453     * ``>`` is converted to ``>``

   454     * ``'`` (single quote) is converted to ``'``

   455     * ``"`` (double quote) is converted to ``"``

   456     * ``&`` is converted to ``&``

   457 

   458 Again, we stress that this behavior is on by default. If you're using Django's

   459 template system, you're protected.

   460 

   461 .. _Cross Site Scripting: http://en.wikipedia.org/wiki/Cross-site_scripting

   462 

   463 How to turn it off

   464 ------------------

   465 

   466 If you don't want data to be auto-escaped, on a per-site, per-template level or

   467 per-variable level, you can turn it off in several ways.

   468 

   469 Why would you want to turn it off? Because sometimes, template variables

   470 contain data that you *intend* to be rendered as raw HTML, in which case you

   471 don't want their contents to be escaped. For example, you might store a blob of

   472 HTML in your database and want to embed that directly into your template. Or,

   473 you might be using Django's template system to produce text that is *not* HTML

   474 -- like an e-mail message, for instance.

   475 

   476 For individual variables

   477 ~~~~~~~~~~~~~~~~~~~~~~~~

   478 

   479 To disable auto-escaping for an individual variable, use the ``safe`` filter::

   480 

   481     This will be escaped: {{ data }}

   482     This will not be escaped: {{ data|safe }}

   483 

   484 Think of *safe* as shorthand for *safe from further escaping* or *can be

   485 safely interpreted as HTML*. In this example, if ``data`` contains ``'<b>'``,

   486 the output will be::

   487 

   488     This will be escaped: <b>

   489     This will not be escaped: <b>

   490 

   491 For template blocks

   492 ~~~~~~~~~~~~~~~~~~~

   493 

   494 To control auto-escaping for a template, wrap the template (or just a

   495 particular section of the template) in the ``autoescape`` tag, like so::

   496 

   497     {% autoescape off %}

   498         Hello {{ name }}

   499     {% endautoescape %}

   500 

   501 The ``autoescape`` tag takes either ``on`` or ``off`` as its argument. At

   502 times, you might want to force auto-escaping when it would otherwise be

   503 disabled. Here is an example template::

   504 

   505     Auto-escaping is on by default. Hello {{ name }}

   506 

   507     {% autoescape off %}

   508         This will not be auto-escaped: {{ data }}.

   509 

   510         Nor this: {{ other_data }}

   511         {% autoescape on %}

   512             Auto-escaping applies again: {{ name }}

   513         {% endautoescape %}

   514     {% endautoescape %}

   515 

   516 The auto-escaping tag passes its effect onto templates that extend the

   517 current one as well as templates included via the ``include`` tag, just like

   518 all block tags. For example::

   519 

   520     # base.html

   521 

   522     {% autoescape off %}

   523     <h1>{% block title %}{% endblock %}</h1>

   524     {% block content %}

   525     {% endblock %}

   526     {% endautoescape %}

   527 

   528 

   529     # child.html

   530 

   531     {% extends "base.html" %}

   532     {% block title %}This & that{% endblock %}

   533     {% block content %}{{ greeting }}{% endblock %}

   534 

   535 Because auto-escaping is turned off in the base template, it will also be

   536 turned off in the child template, resulting in the following rendered

   537 HTML when the ``greeting`` variable contains the string ``<b>Hello!</b>``::

   538 

   539     <h1>This & that</h1>

   540     <b>Hello!</b>

   541 

   542 Notes

   543 -----

   544 

   545 Generally, template authors don't need to worry about auto-escaping very much.

   546 Developers on the Python side (people writing views and custom filters) need to

   547 think about the cases in which data shouldn't be escaped, and mark data

   548 appropriately, so things Just Work in the template.

   549 

   550 If you're creating a template that might be used in situations where you're

   551 not sure whether auto-escaping is enabled, then add an ``escape`` filter to any

   552 variable that needs escaping. When auto-escaping is on, there's no danger of

   553 the ``escape`` filter *double-escaping* data -- the ``escape`` filter does not

   554 affect auto-escaped variables.

   555 

   556 String literals and automatic escaping

   557 --------------------------------------

   558 

   559 As we mentioned earlier, filter arguments can be strings::

   560 

   561     {{ data|default:"This is a string literal." }}

   562 

   563 All string literals are inserted **without** any automatic escaping into the

   564 template -- they act as if they were all passed through the ``safe`` filter.

   565 The reasoning behind this is that the template author is in control of what

   566 goes into the string literal, so they can make sure the text is correctly

   567 escaped when the template is written.

   568 

   569 This means you would write ::

   570 

   571     {{ data|default:"3 < 2" }}

   572 

   573 ...rather than ::

   574 

   575     {{ data|default:"3 < 2" }}  <-- Bad! Don't do this.

   576 

   577 This doesn't affect what happens to data coming from the variable itself.

   578 The variable's contents are still automatically escaped, if necessary, because

   579 they're beyond the control of the template author.

   580 

   581 .. _loading-custom-template-libraries:

   582 

   583 Custom tag and filter libraries

   584 ===============================

   585 

   586 Certain applications provide custom tag and filter libraries. To access them in

   587 a template, use the ``{% load %}`` tag::

   588 

   589     {% load comments %}

   590 

   591     {% comment_form for blogs.entries entry.id with is_public yes %}

   592 

   593 In the above, the ``load`` tag loads the ``comments`` tag library, which then

   594 makes the ``comment_form`` tag available for use. Consult the documentation

   595 area in your admin to find the list of custom libraries in your installation.

   596 

   597 The ``{% load %}`` tag can take multiple library names, separated by spaces.

   598 Example::

   599 

   600     {% load comments i18n %}

   601 

   602 See :doc:`/howto/custom-template-tags` for information on writing your own custom

   603 template libraries.

   604 

   605 Custom libraries and template inheritance

   606 -----------------------------------------

   607 

   608 When you load a custom tag or filter library, the tags/filters are only made

   609 available to the current template -- not any parent or child templates along

   610 the template-inheritance path.

   611 

   612 For example, if a template ``foo.html`` has ``{% load comments %}``, a child

   613 template (e.g., one that has ``{% extends "foo.html" %}``) will *not* have

   614 access to the comments template tags and filters. The child template is

   615 responsible for its own ``{% load comments %}``.

   616 

   617 This is a feature for the sake of maintainability and sanity.