innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Wrote main documentation for templates.

This commit is contained in:
Aymeric Augustin 2015-01-03 23:05:34 +01:00
parent 6c392bb2c0
commit ee8d5b91e9
7 changed files with 695 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/howto/custom-template-tags.txt
View File

@ -369,6 +369,8 @@ aware datetime, Django will convert it to the current time zone before passing
it to your filter when appropriate, according to :ref:`rules for time zones it to your filter when appropriate, according to :ref:`rules for time zones
conversions in templates <time-zones-in-templates>`. conversions in templates <time-zones-in-templates>`.
.. _howto-writing-custom-template-tags:
Writing custom template tags Writing custom template tags
---------------------------- ----------------------------

2
docs/intro/tutorial02.txt
View File

@ -578,7 +578,7 @@ more sensible to modify the *application's* templates, rather than those in the
*project*. That way, you could include the polls application in any new project *project*. That way, you could include the polls application in any new project
and be assured that it would find the custom templates it needed. and be assured that it would find the custom templates it needed.
See the :ref:`template loader documentation <template-loaders>` for more See the :ref:`template loading documentation <template-loading>` for more
information about how Django finds its templates. information about how Django finds its templates.
Customize the admin index page Customize the admin index page

263
docs/ref/templates/api.txt
View File

@ -2,56 +2,22 @@
The Django template language: For Python programmers The Django template language: For Python programmers
==================================================== ====================================================
.. module:: django.template .. currentmodule:: django.template
:synopsis: Django's template system
This document explains the Django template system from a technical 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 perspective -- how it works and how to extend it. If you're just looking for
reference on the language syntax, see :doc:`/ref/templates/language`. reference on the language syntax, see :doc:`/ref/templates/language`.
It assumes an understanding of templates, contexts, variables, tags, and
rendering. Start with the :ref:`introduction to the Django template language
<template-language-intro>` if you aren't familiar with these concepts.
If you're looking to use the Django template system as part of another If you're looking to use the Django template system as part of another
application -- i.e., without the rest of the framework -- make sure to read application -- i.e., without the rest of the framework -- make sure to read
the `configuration`_ section later in this document. the `configuration`_ section later in this document.
.. _configuration: `configuring the template system in standalone mode`_ .. _configuration: `configuring the template system in standalone mode`_
Basics
======
A **template** is a text document, or a normal Python string, that is marked-up
using the Django template language. A template can contain **block tags** or
**variables**.
A **block tag** is a symbol within a template that does something.
This definition is deliberately vague. For example, a block tag can output
content, serve as a control structure (an "if" statement or "for" loop), grab
content from a database or enable access to other template tags.
Block tags are surrounded by ``"{%"`` and ``"%}"``.
Example template with block tags:
.. code-block:: html+django
{% if is_logged_in %}Thanks for logging in!{% else %}Please log in.{% endif %}
A **variable** is a symbol within a template that outputs a value.
Variable tags are surrounded by ``"{{"`` and ``"}}"``.
Example template with variables:
.. code-block:: html+django
My first name is {{ first_name }}. My last name is {{ last_name }}.
A **context** is a "variable name" -> "variable value" mapping that is passed
to a template.
A template **renders** a context by replacing the variable "holes" with values
from the context and executing all block tags.
Using the template system Using the template system
========================= =========================
@ -87,7 +53,7 @@ takes one argument -- the raw template code::
Rendering a context Rendering a context
------------------- -------------------
.. method:: render(context) .. method:: Template.render(context)
Once you have a compiled ``Template`` object, you can render a context -- or Once you have a compiled ``Template`` object, you can render a context -- or
multiple contexts -- with it. The ``Context`` class lives at multiple contexts -- with it. The ``Context`` class lives at
@ -518,6 +484,11 @@ optional, third positional argument, ``processors``. In this example, the
the same as a call to :func:`~django.shortcuts.render_to_response()` with a the same as a call to :func:`~django.shortcuts.render_to_response()` with a
``context_instance`` argument that forces the use of a ``RequestContext``. ``context_instance`` argument that forces the use of a ``RequestContext``.
.. _context-processors:
Context processors
------------------
Here's what each of the default processors does: Here's what each of the default processors does:
django.contrib.auth.context_processors.auth django.contrib.auth.context_processors.auth
@ -658,88 +629,6 @@ such as ``.html`` or ``.txt``, or they can have no extension at all.
Note that these paths should use Unix-style forward slashes, even on Windows. Note that these paths should use Unix-style forward slashes, even on Windows.
.. _ref-templates-api-the-python-api:
The Python API
~~~~~~~~~~~~~~
.. module:: django.template.loader
``django.template.loader`` has two functions to load templates from files:
.. function:: get_template(template_name[, dirs])
``get_template`` returns the compiled template (a ``Template`` object) for
the template with the given name. If the template doesn't exist, it raises
``django.template.TemplateDoesNotExist``.
.. versionchanged:: 1.7
The ``dirs`` parameter was added.
.. versionchanged:: 1.8
The ``dirs`` parameter was deprecated.
.. function:: select_template(template_name_list[, dirs])
``select_template`` is just like ``get_template``, except it takes a list
of template names. Of the list, it returns the first template that exists.
.. versionchanged:: 1.7
The ``dirs`` parameter was added.
.. versionchanged:: 1.8
The ``dirs`` parameter was deprecated.
For example, if you call ``get_template('story_detail.html')`` and have the
above :setting:`DIRS <TEMPLATES-DIRS>` option, here are the files Django will
look for, in order:
* ``/home/html/templates/lawrence.com/story_detail.html``
* ``/home/html/templates/default/story_detail.html``
If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``,
here's what Django will look for:
* ``/home/html/templates/lawrence.com/story_253_detail.html``
* ``/home/html/templates/default/story_253_detail.html``
* ``/home/html/templates/lawrence.com/story_detail.html``
* ``/home/html/templates/default/story_detail.html``
When Django finds a template that exists, it stops looking.
.. admonition:: Tip
You can use ``select_template()`` for super-flexible "templatability." For
example, if you've written a news story and want some stories to have
custom templates, use something like
``select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])``.
That'll allow you to use a custom template for an individual story, with a
fallback template for stories that don't have custom templates.
Using subdirectories
~~~~~~~~~~~~~~~~~~~~
It's possible -- and preferable -- to organize templates in subdirectories of
the template directory. The convention is to make a subdirectory for each
Django app, with subdirectories within those subdirectories as needed.
Do this for your own sanity. Storing all templates in the root level of a
single directory gets messy.
To load a template that's within a subdirectory, just use a slash, like so::
get_template('news/story_detail.html')
Using the same :setting:`DIRS <TEMPLATES-DIRS>` option from above, this
example ``get_template()`` call will attempt to load the following templates:
* ``/home/html/templates/lawrence.com/news/story_detail.html``
* ``/home/html/templates/default/news/story_detail.html``
.. _template-loaders: .. _template-loaders:
Loader types Loader types
@ -892,6 +781,26 @@ loaders that come with Django:
Django uses the template loaders in order according to the ``'loaders'`` Django uses the template loaders in order according to the ``'loaders'``
option. It uses each loader until a loader finds a match. option. It uses each loader until a loader finds a match.
.. _custom-template-loaders:
Custom loaders
~~~~~~~~~~~~~~
Custom ``Loader`` classes should inherit from
``django.template.loaders.base.Loader`` and override the
``load_template_source()`` method, which takes a ``template_name`` argument,
loads the template from disk (or elsewhere), and returns a tuple:
``(template_string, template_origin)``.
.. versionchanged:: 1.8
``django.template.loaders.base.Loader`` used to be defined at
``django.template.loader.BaseLoader``.
The ``load_template()`` method of the ``Loader`` class retrieves the template
string by calling ``load_template_source()``, instantiates a ``Template`` from
the template source, and returns a tuple: ``(template, template_origin)``.
.. currentmodule:: django.template .. currentmodule:: django.template
Template origin Template origin
@ -927,48 +836,6 @@ When :setting:`TEMPLATE_DEBUG` is ``True`` template objects will have an
The string used to create the template. The string used to create the template.
The ``render_to_string`` shortcut
===================================
.. function:: loader.render_to_string(template_name, context=None, context_instance=None)
To cut down on the repetitive nature of loading and rendering
templates, Django provides a shortcut function which largely
automates the process: ``render_to_string()`` in
:mod:`django.template.loader`, which loads a template, renders it and
returns the resulting string::
from django.template.loader import render_to_string
rendered = render_to_string('my_template.html', {'foo': 'bar'})
The ``render_to_string`` shortcut takes one required argument --
``template_name``, which should be the name of the template to load
and render (or a list of template names, in which case Django will use
the first template in the list that exists) -- and two optional arguments:
``context``
A dictionary to be used as variables and values for the
template's context. This should be passed as the second
positional argument.
.. versionchanged:: 1.8
The ``context`` argument used to be called ``dictionary``. That name
is deprecated in Django 1.8 and will be removed in Django 2.0.
``context_instance``
An instance of :class:`~django.template.Context` or a subclass (e.g., an
instance of :class:`~django.template.RequestContext`) to use as the
template's context. This can also be passed as the third positional argument.
.. deprecated:: 1.8
The ``context_instance`` argument is deprecated. Simply use ``context``.
See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
suitable for returning directly from a view.
Configuring the template system in standalone mode Configuring the template system in standalone mode
================================================== ==================================================
@ -998,71 +865,3 @@ and :setting:`TEMPLATE_DEBUG`. If you plan to use the :ttag:`url` template tag,
you will also need to set the :setting:`ROOT_URLCONF` setting. All available you will also need to set the :setting:`ROOT_URLCONF` setting. All available
settings are described in the :doc:`settings documentation </ref/settings>`, settings are described in the :doc:`settings documentation </ref/settings>`,
and any setting starting with ``TEMPLATE_`` is of obvious interest. and any setting starting with ``TEMPLATE_`` is of obvious interest.
.. _topic-template-alternate-language:
Using an alternative template language
======================================
The Django ``Template`` and ``Loader`` classes implement a simple API for
loading and rendering templates. By providing some simple wrapper classes that
implement this API we can use third party template systems like `Jinja2
<http://jinja.pocoo.org/docs/>`_. This
allows us to use third-party template libraries without giving up useful Django
features like the Django ``Context`` object and handy shortcuts like
:func:`~django.shortcuts.render_to_response()`.
The core component of the Django templating system is the ``Template`` class.
This class has a very simple interface: it has a constructor that takes a single
positional argument specifying the template string, and a ``render()`` method
that takes a :class:`~django.template.Context` object and returns a string
containing the rendered response.
Suppose we're using a template language that defines a ``Template`` object with
a ``render()`` method that takes a dictionary rather than a ``Context`` object.
We can write a simple wrapper that implements the Django ``Template`` interface::
import some_template_language
class Template(some_template_language.Template):
def render(self, context):
# flatten the Django Context into a single dictionary.
context_dict = {}
for d in context.dicts:
context_dict.update(d)
return super(Template, self).render(context_dict)
That's all that's required to make our fictional ``Template`` class compatible
with the Django loading and rendering system!
The next step is to write a ``Loader`` class that returns instances of our custom
template class instead of the default :class:`~django.template.Template`. Custom ``Loader``
classes should inherit from ``django.template.loaders.base.Loader`` and override
the ``load_template_source()`` method, which takes a ``template_name`` argument,
loads the template from disk (or elsewhere), and returns a tuple:
``(template_string, template_origin)``.
.. versionchanged:: 1.8
``django.template.loaders.base.Loader`` used to be defined at
``django.template.loader.BaseLoader``.
The ``load_template()`` method of the ``Loader`` class retrieves the template
string by calling ``load_template_source()``, instantiates a ``Template`` from
the template source, and returns a tuple: ``(template, template_origin)``. Since
this is the method that actually instantiates the ``Template``, we'll need to
override it to use our custom template class instead. We can inherit from the
builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
of the ``load_template_source()`` method implemented there::
from django.template.loaders import app_directories
class Loader(app_directories.Loader):
is_usable = True
def load_template(self, template_name, template_dirs=None):
source, origin = self.load_template_source(template_name, template_dirs)
template = Template(source)
return template, origin
Finally, we need to modify our project settings, telling Django to use our custom
loader. Now we can write all of our templates in our alternative template
language while continuing to use the rest of the Django templating system.

2
docs/ref/templates/language.txt
View File

@ -2,8 +2,6 @@
The Django template language The Django template language
============================ ============================
.. admonition:: About this document
This document explains the language syntax of the Django template system. If This document explains the language syntax of the Django template system. If
you're looking for a more technical perspective on how it works and how to you're looking for a more technical perspective on how it works and how to
extend it, see :doc:`/ref/templates/api`. extend it, see :doc:`/ref/templates/api`.

11
docs/releases/1.2.txt
View File

@ -253,8 +253,7 @@ lots of smaller subtemplates (using the ``{% extends %}`` or ``{%
include %}`` tags). include %}`` tags).
As a side effect, it is now much easier to support non-Django template As a side effect, it is now much easier to support non-Django template
languages. For more details, see the :ref:`notes on supporting languages.
non-Django template languages<topic-template-alternate-language>`.
Class-based template loaders Class-based template loaders
---------------------------- ----------------------------
@ -275,9 +274,8 @@ If you have developed your own custom template loaders we suggest to consider
porting them to a class-based implementation because the code for backwards porting them to a class-based implementation because the code for backwards
compatibility with function-based loaders starts its deprecation process in compatibility with function-based loaders starts its deprecation process in
Django 1.2 and will be removed in Django 1.4. There is a description of the Django 1.2 and will be removed in Django 1.4. There is a description of the
API these loader classes must implement :ref:`here API these loader classes must implement in the template API reference and you
<topic-template-alternate-language>` and you can also examine the source code can also examine the source code of the loaders shipped with Django.
of the loaders shipped with Django.
Natural keys in fixtures Natural keys in fixtures
------------------------ ------------------------
@ -1172,5 +1170,4 @@ Function-based template loaders
Django 1.2 changes the template loading mechanism to use a class-based Django 1.2 changes the template loading mechanism to use a class-based
approach. Old style function-based template loaders will still work, but should approach. Old style function-based template loaders will still work, but should
be updated to use the new :ref:`class-based template loaders be updated to use the new class-based template loaders.
<topic-template-alternate-language>`.

4
docs/topics/http/shortcuts.txt
View File

@ -124,8 +124,8 @@ Required arguments
``template_name`` ``template_name``
The full name of a template to use or sequence of template names. If a The full name of a template to use or sequence of template names. If a
sequence is given, the first template that exists will be used. See the sequence is given, the first template that exists will be used. See the
:ref:`template loader documentation <ref-templates-api-the-python-api>` :ref:`template loading documentation <template-loading>` for more
for more information on how templates are found. information on how templates are found.
Optional arguments Optional arguments
------------------ ------------------

653
docs/topics/templates.txt
View File

@ -1 +1,652 @@
TODO - explain multiple template engines and the django template language =========
Templates
=========
.. module:: django.template
:synopsis: Django's template system
Being a web framework, Django needs a convenient way to generate HTML
dynamically. The most common approach relies on templates. A template contains
the static parts of the desired HTML output as well as some special syntax
describing how dynamic content will be inserted. For a hands-on example of
creating HTML pages with templates, see :doc:`Tutorial 3 </intro/tutorial03>`.
A Django project can be configured with one or several template engines (or
even zero if you don't use templates). Django ships built-in backends for its
own template system, creatively called the Django template language (DTL), and
for the popular alternative Jinja2_. Backends for other template languages may
be available from third-parties.
Django defines a standard API for loading and rendering templates regardless
of the backend. Loading consists of finding the template for a given identifier
and preprocessing it, usually compiling it to an in-memory representation.
Rendering means interpolating the template with context data and returning the
resulting string.
The :doc:`Django template language </ref/templates/language>` is Django's own
template system. Until Django 1.8 it was the only built-in option available.
It's a good template library even though it's fairly opinionated and sports a
few idiosyncrasies. If you don't have a pressing reason to choose another
backend, you should use the DTL, especially if you're writing a pluggable
application and you intend to distribute templates. Django's contrib apps that
include templates, like :doc:`django.contrib.admin </ref/contrib/admin/index>`,
use the DTL.
For historical reasons, both the generic support for template engines and the
implementation of the Django template language live in the ``django.template``
namespace.
.. _template-engines:
Support for template engines
============================
.. versionadded:: 1.8
Support for multiple template engines and the :setting:`TEMPLATES` setting
were added in Django 1.8.
Configuration
-------------
Templates engines are configured with the :setting:`TEMPLATES` setting. It's a
list of configurations, one for each engine. The default value is empty. The
``settings.py`` generated by the :djadmin:`startproject` command defines a
more useful value::
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'APP_DIRS': True,
'OPTIONS': {
# ... some options here ...
},
},
]
:setting:`BACKEND <TEMPLATES-BACKEND>` is a dotted Python path to a template
engine class implementing Django's template backend API. The built-in backends
are :class:`django.template.backends.django.DjangoTemplates` and
:class:`django.template.backends.jinja2.Jinja2`.
Since most engines load templates from files, the top-level configuration for
each engine contains two common settings:
* :setting:`DIRS <TEMPLATES-DIRS>` defines a list of directories where the
engine should look for template source files, in search order.
* :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` tells whether the engine should
look for templates inside installed applications. Each backend defines a
conventional name for the subdirectory inside applications where its
templates should be stored.
While uncommon, it's possible to configure several instances of the same
backend with different options. In that case you should define a unique
:setting:`NAME <TEMPLATES-NAME>` for each engine.
:setting:`OPTIONS <TEMPLATES-OPTIONS>` contains backend-specific settings.
Usage
-----
.. _template-loading:
.. module:: django.template.loader
The ``django.template.loader`` module defines two functions to load templates.
.. function:: get_template(template_name[, dirs][, using])
This function loads the template with the given name and returns a
``Template`` object.
The exact type of the return value depends on the backend that loaded the
template. Each backend has its own ``Template`` class.
``get_template()`` tries each template engine in order until one succeeds.
If the template cannot be found, it raises
:exc:`~django.template.TemplateDoesNotExist`. If the template is found but
contains invalid syntax, it raises
:exc:`~django.template.TemplateSyntaxError`.
How templates are searched and loaded depends on each engine's backend and
configuration.
If you want to restrict the search to a particular template engine, pass
the engine's :setting:`NAME <TEMPLATES-NAME>` in the ``using`` argument.
.. versionchanged:: 1.7
The ``dirs`` parameter was added.
.. deprecated:: 1.8
The ``dirs`` parameter was deprecated.
.. versionchanged:: 1.8
The ``using`` parameter was added.
.. versionchanged:: 1.8
``get_template()`` returns a backend-dependent ``Template`` instead
of a :class:`django.template.Template`.
.. function:: select_template(template_name_list[, dirs][, using])
``select_template()`` is just like ``get_template()``, except it takes a
list of template names. It tries each name in order and returns the first
template that exists.
.. versionchanged:: 1.7
The ``dirs`` parameter was added.
.. deprecated:: 1.8
The ``dirs`` parameter was deprecated.
.. versionchanged:: 1.8
The ``using`` parameter was added.
.. versionchanged:: 1.8
``select_template()`` returns a backend-dependent ``Template`` instead
of a :class:`django.template.Template`.
.. currentmodule:: django.template
If loading a template fails, the following two exceptions, defined in
``django.template``, may be raised:
.. exception:: TemplateDoesNotExist
This exception is raised when a template cannot be found.
.. exception:: TemplateSyntaxError
This exception is raised when a template was found but contains errors.
``Template`` objects returned by ``get_template()`` and ``select_template()``
must provide a ``render()`` method with the following signature:
.. currentmodule:: django.template.backends.base
.. method:: Template.render(context=None, request=None)
Renders this template with a given context.
If ``context`` is provided, it must be a :class:`dict`. If it isn't
provided, the engine will render the template with an empty context.
If ``request`` is provided, it must be an :class:`~django.http.HttpRequest`.
Then the engine must make it, as well as the CSRF token, available in the
template. How this is achieved is up to each backend.
Here's an example of the search algorithm. For this example the
:setting:`TEMPLATES` setting is::
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [
'/home/html/example.com',
'/home/html/default',
],
},
{
'BACKEND': 'django.template.backends.jinja2.Jinja2',
'DIRS': [
'/home/html/jinja2',
],
},
]
If you call ``get_template('story_detail.html')``, here are the files Django
will look for, in order:
* ``/home/html/example.com/story_detail.html`` (``'django'`` engine)
* ``/home/html/default/story_detail.html`` (``'django'`` engine)
* ``/home/html/jinja2/story_detail.html`` (``'jinja2'`` engine)
If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``,
here's what Django will look for:
* ``/home/html/example.com/story_253_detail.html`` (``'django'`` engine)
* ``/home/html/default/story_253_detail.html`` (``'django'`` engine)
* ``/home/html/jinja2/story_253_detail.html`` (``'jinja2'`` engine)
* ``/home/html/example.com/story_detail.html`` (``'django'`` engine)
* ``/home/html/default/story_detail.html`` (``'django'`` engine)
* ``/home/html/jinja2/story_detail.html`` (``'jinja2'`` engine)
When Django finds a template that exists, it stops looking.
.. admonition:: Tip
You can use :func:`~django.template.loader.select_template()` for flexible
template loading. For example, if you've written a news story and want
some stories to have custom templates, use something like
``select_template(['story_%s_detail.html' % story.id,
'story_detail.html'])``. That'll allow you to use a custom template for an
individual story, with a fallback template for stories that don't have
custom templates.
It's possible -- and preferable -- to organize templates in subdirectories
inside each directory containing templates. The convention is to make a
subdirectory for each Django app, with subdirectories within those
subdirectories as needed.
Do this for your own sanity. Storing all templates in the root level of a
single directory gets messy.
To load a template that's within a subdirectory, just use a slash, like so::
get_template('news/story_detail.html')
Using the same :setting:`TEMPLATES` option as above, this will attempt to load
the following templates:
* ``/home/html/example.com/news/story_detail.html`` (``'django'`` engine)
* ``/home/html/default/news/story_detail.html`` (``'django'`` engine)
* ``/home/html/jinja2/news/story_detail.html`` (``'jinja2'`` engine)
.. currentmodule:: django.template.loader
In addition, to cut down on the repetitive nature of loading and rendering
templates, Django provides a shortcut function which automates the process.
.. function:: render_to_string(template_name[, context][, context_instance][, request][, using])
``render_to_string()`` loads a template like :func:`get_template` and
calls its ``render()`` method immediately. It takes the following
arguments.
``template_name``
The name of the template to load and render. If it's a list of template
names, Django uses :func:`select_template` instead of
:func:`get_template` to find the template.
``context``
A :class:`dict` to be used as the template's context for rendering.
.. versionchanged:: 1.8
The ``context`` argument used to be called ``dictionary``. That name
is deprecated in Django 1.8 and will be removed in Django 2.0.
``context`` is now optional. An empty context will be used if it
isn't provided.
``context_instance``
An instance of :class:`~django.template.Context` or a subclass (e.g., an
instance of :class:`~django.template.RequestContext`) to use as the
template's context.
.. deprecated:: 1.8
The ``context_instance`` argument is deprecated. Use ``context`` and
if needed ``request``.
``request``
An optional :class:`~django.http.HttpRequest` that will be available
during the template's rendering process.
.. versionadded:: 1.8
The ``request`` argument was added.
See also the :func:`~django.shortcuts.render()` and
:func:`~django.shortcuts.render_to_response()` shortcuts, which call
:func:`render_to_string()` and feed the result into an
:class:`~django.http.HttpResponse` suitable for returning from a view.
Finally, you can use configured engines directly:
.. data:: engines
Template engines are available in ``django.template.engines``::
from django.template import engines
django_engine = engines['django']
template = django_engine.from_string("Hello {{ name }}!")
The lookup key — ``'django'`` in this example — is the engine's
:setting:`NAME <TEMPLATES-NAME>`.
.. module:: django.template.backends
Built-in backends
-----------------
.. module:: django.template.backends.django
.. class:: DjangoTemplates
Set :setting:`BACKEND <TEMPLATES-BACKEND>` to
``'django.template.backends.django.DjangoTemplates'`` to configure a Django
template engine.
When :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` is ``True``, ``DjangoTemplates``
engines look for templates in the ``templates`` subdirectory of installed
applications. This generic name was kept for backwards-compatibility.
``DjangoTemplates`` engines accept the following :setting:`OPTIONS
<TEMPLATES-OPTIONS>`:
* ``'allowed_include_roots'``: a list of strings representing allowed prefixes
for the ``{% ssi %}`` template tag. This is a security measure, so that
template authors can't access files that they shouldn't be accessing.
For example, if ``'allowed_include_roots'`` is ``['/home/html',
'/var/www']``, then ``{% ssi /home/html/foo.txt %}`` would work, but ``{%
ssi /etc/passwd %}`` wouldn't.
It defaults to an empty list.
.. deprecated:: 1.8
``allowed_include_roots`` is deprecated because the {% ssi %} tag is
deprecated.
* ``'context_processors'``: 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
:class:`dict` of items to be merged into the context.
It defaults to an empty list.
See :class:`~django.template.RequestContext` for more information.
* ``'debug'``: a boolean that turns on/off template debug mode. If it is
``True``, the fancy error page will display a detailed report for any
exception raised during template rendering. This report contains the
relevant snippet of the template with the appropriate line highlighted.
It defaults to the value of the :setting:`TEMPLATE_DEBUG` setting. The
setting is convenient for toggling template debug mode globally rather than
on a per-engine basis.
* ``'loaders'``: a list of dotted Python paths to template loader classes.
Each ``Loader`` 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 ``Loader`` class name, and subsequent items are
passed to the ``Loader`` during initialization.
The default depends on the values of :setting:`DIRS <TEMPLATES-DIRS>` and
:setting:`APP_DIRS <TEMPLATES-APP_DIRS>`.
See :ref:`template-loaders` for details.
* ``'string_if_invalid'``: the output, as a string, that the template system
should use for invalid (e.g. misspelled) variables.
It defaults to an empty string.
See :ref:`invalid-template-variables` for details.
* ``'file_charset'``: the charset used to read template files on disk.
It defaults to the value of :setting:`FILE_CHARSET`.
.. module:: django.template.backends.jinja2
.. class:: Jinja2
Set :setting:`BACKEND <TEMPLATES-BACKEND>` to
``'django.template.backends.jinja2.Jinja2'`` to configure a Jinja2_ engine.
When :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` is ``True``, ``Jinja2`` engines
look for templates in the ``jinja2`` subdirectory of installed applications.
The most important entry in :setting:`OPTIONS <TEMPLATES-OPTIONS>` is
``'environment'``. It's a dotted Python path to a callable returning a Jinja2
environment. It defaults to ``'jinja2.Environment'``. Django invokes that
callable and passes other options as keyword arguments. Furthermore, Django
adds defaults that differ from Jinja2's for a few options:
* ``'autoescape'``: ``True``
* ``'loader'``: a loader configured for :setting:`DIRS <TEMPLATES-DIRS>` and
:setting:`APP_DIRS <TEMPLATES-APP_DIRS>`
* ``'auto_reload'``: ``settings.DEBUG``
* ``'undefined'``: ``DebugUndefined if settings.DEBUG else Undefined``
Custom backends
---------------
Here's how to implement a custom template backend in order to use another
template system. A template backend is a class that inherits
``django.template.backends.base.BaseEngine``. It must implement
``get_template()`` and optionally ``from_string()``. Here's an example for a
fictional ``foobar`` template library::
from django.template import TemplateDoesNotExist, TemplateSyntaxError
from django.template.backends.base import BaseEngine
from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy
import foobar
class FooBar(BaseEngine):
# Name of the subdirectory containing the templates for this engine
# inside an installed application.
app_dirname = 'foobar'
def __init__(self, params):
params = params.copy()
options = params.pop('OPTIONS').copy()
super(FooBar, self).__init__(params)
self.engine = foobar.Engine(**options)
def from_string(self, template_code):
try:
return Template(self.engine.from_string(template_code))
except foobar.TemplateCompilationFailed as exc:
raise TemplateSyntaxError(exc.args)
def get_template(self, template_name):
try:
return Template(self.engine.get_template(template_name))
except foobar.TemplateNotFound as exc:
raise TemplateDoesNotExist(exc.args)
except foobar.TemplateCompilationFailed as exc:
raise TemplateSyntaxError(exc.args)
class Template(object):
def __init__(self, template):
self.template = template
def render(self, context=None, request=None):
if context is None:
context = {}
if request is not None:
context['request'] = request
context['csrf_input'] = csrf_input_lazy(request)
context['csrf_token'] = csrf_token_lazy(request)
return self.template.render(context)
See `DEP 182`_ for more information.
.. currentmodule:: django.template
.. _template-language-intro:
The Django template language
============================
.. highlightlang:: html+django
Syntax
------
.. admonition:: About this section
This is an overview of the Django template language's syntax. For details
see the :doc:`language syntax reference </ref/templates/language>`.
A Django template is simply a text document or a Python string marked-up using
the Django template language. Some constructs are recognized and interpreted
by the template engine. The main ones are variables and tags.
A template is rendered with a context. Rendering replaces variables with their
values, which are looked up in the context, and executes tags. Everything else
is output as is.
The syntax of the Django template language involves four constructs.
Variables
~~~~~~~~~
A variable outputs a value from the context, which is a dict-like object
mapping keys to values.
Variables are surrounded by ``{{`` and ``}}`` like this::
My first name is {{ first_name }}. My last name is {{ last_name }}.
With a context of ``{'first_name': 'John', 'last_name': 'Doe'}``, this
template renders to::
My first name is John. My last name is Doe.
Dictionary lookup, attribute lookup and list-index lookups are implemented
with a dot notation::
{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}
If a variable resolves to a callable, the template system will call it with no
arguments and use its result instead of the callable.
Tags
~~~~
Tags provide arbitrary logic in the rendering process.
This definition is deliberately vague. For example, a tag can output content,
serve as a control structure e.g. an "if" statement or a "for" loop, grab
content from a database, or even enable access to other template tags.
Tags are surrounded by ``{%`` and ``%}`` like this::
{% csrf_token %}
Most tags accept arguments::
{% cycle 'odd' 'even' %}
Some tags require beginning and ending tags::
{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}
A :ref:`reference of built-in tags <ref-templates-builtins-tags>` is
available as well as :ref:`instructions for writing custom tags
<howto-writing-custom-template-tags>`.
Filters
~~~~~~~
Filters transform the values of variables and tag arguments.
They look like this::
{{ django|title }}
With a context of ``{'django': 'the web framework for perfectionists with
deadlines'}``, this template renders to::
The Web Framework For Perfectionists With Deadlines
Some filters take an argument::
{{ my_date|date:"Y-m-d" }}
A :ref:`reference of built-in filters <ref-templates-builtins-filters>` is
available as well as :ref:`instructions for writing custom filters
<howto-writing-custom-template-filters>`.
Comments
~~~~~~~~
Comments look like this::
{# this won't be rendered #}
A :ttag:`{% comment %} <comment>` tag provides multi-line comments.
Components
----------
.. admonition:: About this section
This is an overview of the Django template language's APIs. For details
see the :doc:`API reference </ref/templates/api>`.
Engine
~~~~~~
:class:`django.template.Engine` encapsulates an instance of the Django
template system. The main reason for instantiating an
:class:`~django.template.Engine` directly is to use the Django template
language outside of a Django project.
:class:`django.template.backends.django.DjangoTemplates` is a thin wrapper
adapting :class:`django.template.Engine` to Django's template backend API.
Template
~~~~~~~~
:class:`django.template.Template` represents a compiled template.
Templates are obtained with :meth:`Engine.get_template()
<django.template.Engine.get_template>` or :meth:`Engine.from_string()
<django.template.Engine.from_string>`
Likewise ``django.template.backends.django.Template`` is a thin wrapper
adapting :class:`django.template.Template` to the common template API.
Context
~~~~~~~
:class:`django.template.Context` holds some metadata in addition to the
context data. It is passed to :meth:`Template.render()
<django.template.Template.render>` for rendering a template.
:class:`django.template.RequestContext` is a subclass of
:class:`~django.template.Context` that stores the current
:class:`~django.http.HttpRequest` and runs template context processors.
The common API doesn't have an equivalent concept. Context data is passed in a
plain :class:`dict` and the current :class:`~django.http.HttpRequest` is passed
separately if needed.
Loaders
~~~~~~~
Template loaders are responsible for locating templates, loading them, and
returning :class:`~django.template.Template` objects.
Django provides several :ref:`built-in template loaders <template-loaders>`
and supports :ref:`custom template loaders <custom-template-loaders>`.
Context processors
~~~~~~~~~~~~~~~~~~
Context processors are functions that receive the current
:class:`~django.http.HttpRequest` as an argument and return a :class:`dict` of
data to be added to the rendering context.
Their main use is to add common data shared by all templates to the context
without repeating code in every view.
Django provides many :ref:`built-in context processors <context-processors>`.
Implementing a custom context processor is as simple as defining a function.
.. _Jinja2: http://jinja.pocoo.org/
.. _DEP 182: https://github.com/django/deps/blob/master/accepted/0182-multiple-template-engines.rst