--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/ref/templates/api.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,815 @@
+====================================================
+The Django template language: For Python programmers
+====================================================
+
+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 :doc:`/topics/templates`.
+
+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
+the `configuration`_ section later in this document.
+
+.. _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
+=========================
+
+.. class:: django.template.Template
+
+Using the template system in Python is a two-step process:
+
+ * First, you compile the raw template code into a ``Template`` object.
+ * Then, you call the ``render()`` method of the ``Template`` object with a
+ given context.
+
+Compiling a string
+------------------
+
+The easiest way to create a ``Template`` object is by instantiating it
+directly. The class lives at :class:`django.template.Template`. The constructor
+takes one argument -- the raw template code::
+
+ >>> from django.template import Template
+ >>> t = Template("My name is {{ my_name }}.")
+ >>> print t
+ <django.template.Template instance>
+
+.. admonition:: Behind the scenes
+
+ The system only parses your raw template code once -- when you create the
+ ``Template`` object. From then on, it's stored internally as a "node"
+ structure for performance.
+
+ Even the parsing itself is quite fast. Most of the parsing happens via a
+ single call to a single, short, regular expression.
+
+Rendering a context
+-------------------
+
+.. method:: render(context)
+
+Once you have a compiled ``Template`` object, you can render a context -- or
+multiple contexts -- with it. The ``Context`` class lives at
+:class:`django.template.Context`, and the constructor takes two (optional)
+arguments:
+
+ * A dictionary mapping variable names to variable values.
+
+ * The name of the current application. This application name is used
+ to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`.
+ If you're not using namespaced URLs, you can ignore this argument.
+
+Call the ``Template`` object's ``render()`` method with the context to "fill" the
+template::
+
+ >>> from django.template import Context, Template
+ >>> t = Template("My name is {{ my_name }}.")
+
+ >>> c = Context({"my_name": "Adrian"})
+ >>> t.render(c)
+ "My name is Adrian."
+
+ >>> c = Context({"my_name": "Dolores"})
+ >>> t.render(c)
+ "My name is Dolores."
+
+Variable names must consist of any letter (A-Z), any digit (0-9), an underscore
+or a dot.
+
+Dots have a special meaning in template rendering. A dot in a variable name
+signifies **lookup**. Specifically, when the template system encounters a dot
+in a variable name, it tries the following lookups, in this order:
+
+ * Dictionary lookup. Example: ``foo["bar"]``
+ * Attribute lookup. Example: ``foo.bar``
+ * Method call. Example: ``foo.bar()``
+ * List-index lookup. Example: ``foo[bar]``
+
+The template system uses the first lookup type that works. It's short-circuit
+logic.
+
+Here are a few examples::
+
+ >>> from django.template import Context, Template
+ >>> t = Template("My name is {{ person.first_name }}.")
+ >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
+ >>> t.render(Context(d))
+ "My name is Joe."
+
+ >>> class PersonClass: pass
+ >>> p = PersonClass()
+ >>> p.first_name = "Ron"
+ >>> p.last_name = "Nasty"
+ >>> t.render(Context({"person": p}))
+ "My name is Ron."
+
+ >>> class PersonClass2:
+ ... def first_name(self):
+ ... return "Samantha"
+ >>> p = PersonClass2()
+ >>> t.render(Context({"person": p}))
+ "My name is Samantha."
+
+ >>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
+ >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
+ >>> t.render(c)
+ "The first stooge in the list is Larry."
+
+Method lookups are slightly more complex than the other lookup types. Here are
+some things to keep in mind:
+
+ * If, during the method lookup, a method raises an exception, the exception
+ will be propagated, unless the exception has an attribute
+ ``silent_variable_failure`` whose value is ``True``. If the exception
+ *does* have a ``silent_variable_failure`` attribute, the variable will
+ render as an empty string. Example::
+
+ >>> t = Template("My name is {{ person.first_name }}.")
+ >>> class PersonClass3:
+ ... def first_name(self):
+ ... raise AssertionError, "foo"
+ >>> p = PersonClass3()
+ >>> t.render(Context({"person": p}))
+ Traceback (most recent call last):
+ ...
+ AssertionError: foo
+
+ >>> class SilentAssertionError(Exception):
+ ... silent_variable_failure = True
+ >>> class PersonClass4:
+ ... def first_name(self):
+ ... raise SilentAssertionError
+ >>> p = PersonClass4()
+ >>> t.render(Context({"person": p}))
+ "My name is ."
+
+ Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the
+ base class for all Django database API ``DoesNotExist`` exceptions, has
+ ``silent_variable_failure = True``. So if you're using Django templates
+ with Django model objects, any ``DoesNotExist`` exception will fail
+ silently.
+
+ * A method call will only work if the method has no required arguments.
+ Otherwise, the system will move to the next lookup type (list-index
+ lookup).
+
+ * Obviously, some methods have side effects, and it'd be either foolish or
+ a security hole to allow the template system to access them.
+
+ A good example is the :meth:`~django.db.models.Model.delete` method on
+ each Django model object. The template system shouldn't be allowed to do
+ something like this::
+
+ I will now delete this valuable data. {{ data.delete }}
+
+ To prevent this, set a function attribute ``alters_data`` on the method.
+ The template system won't execute a method if the method has
+ ``alters_data=True`` set. The dynamically-generated
+ :meth:`~django.db.models.Model.delete` and
+ :meth:`~django.db.models.Model.save` methods on Django model objects get
+ ``alters_data=True`` automatically. Example::
+
+ def sensitive_function(self):
+ self.database_record.delete()
+ sensitive_function.alters_data = True
+
+.. _invalid-template-variables:
+
+How invalid variables are handled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally, if a variable doesn't exist, the template system inserts the
+value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
+``''`` (the empty string) by default.
+
+Filters that are applied to an invalid variable will only be applied if
+:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If
+:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable
+filters will be ignored.
+
+This behavior is slightly different for the ``if``, ``for`` and ``regroup``
+template tags. If an invalid variable is provided to one of these template
+tags, the variable will be interpreted as ``None``. Filters are always
+applied to invalid variables within these template tags.
+
+If :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will
+be replaced with the name of the invalid variable.
+
+.. admonition:: For debug purposes only!
+
+ While :setting:`TEMPLATE_STRING_IF_INVALID` can be a useful debugging tool,
+ it is a bad idea to turn it on as a 'development default'.
+
+ 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 ``''`` to
+ :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering
+ problems with these templates and sites.
+
+ Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled
+ in order to debug a specific template problem, then cleared
+ once debugging is complete.
+
+Playing with Context objects
+----------------------------
+
+.. class:: django.template.Context
+
+Most of the time, you'll instantiate ``Context`` objects by passing in a
+fully-populated dictionary to ``Context()``. But you can add and delete items
+from a ``Context`` object once it's been instantiated, too, using standard
+dictionary syntax::
+
+ >>> c = Context({"foo": "bar"})
+ >>> c['foo']
+ 'bar'
+ >>> del c['foo']
+ >>> c['foo']
+ ''
+ >>> c['newvariable'] = 'hello'
+ >>> c['newvariable']
+ 'hello'
+
+.. method:: pop()
+.. method:: push()
+.. exception:: django.template.ContextPopException
+
+A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it.
+If you ``pop()`` too much, it'll raise
+``django.template.ContextPopException``::
+
+ >>> c = Context()
+ >>> c['foo'] = 'first level'
+ >>> c.push()
+ >>> c['foo'] = 'second level'
+ >>> c['foo']
+ 'second level'
+ >>> c.pop()
+ >>> c['foo']
+ 'first level'
+ >>> c['foo'] = 'overwritten'
+ >>> c['foo']
+ 'overwritten'
+ >>> c.pop()
+ Traceback (most recent call last):
+ ...
+ django.template.ContextPopException
+
+.. method:: update(other_dict)
+
+In addition to ``push()`` and ``pop()``, the ``Context``
+object also defines an ``update()`` method. This works like ``push()``
+but takes a dictionary as an argument and pushes that dictionary onto
+the stack instead of an empty one.
+
+ >>> c = Context()
+ >>> c['foo'] = 'first level'
+ >>> c.update({'foo': 'updated'})
+ {'foo': 'updated'}
+ >>> c['foo']
+ 'updated'
+ >>> c.pop()
+ {'foo': 'updated'}
+ >>> c['foo']
+ 'first level'
+
+Using a ``Context`` as a stack comes in handy in some custom template tags, as
+you'll see below.
+
+.. _subclassing-context-requestcontext:
+
+Subclassing Context: RequestContext
+-----------------------------------
+
+Django comes with a special ``Context`` class,
+``django.template.RequestContext``, that acts slightly differently than the
+normal ``django.template.Context``. The first difference is that it takes an
+:class:`~django.http.HttpRequest` as its first argument. For example::
+
+ c = RequestContext(request, {
+ 'foo': 'bar',
+ })
+
+The second difference is that it automatically populates the context with a few
+variables, according to your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+The :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting is a tuple of callables --
+called **context processors** -- that take a request object as their argument
+and return a dictionary of items to be merged into the context. By default,
+:setting:`TEMPLATE_CONTEXT_PROCESSORS` is set to::
+
+ ("django.contrib.auth.context_processors.auth",
+ "django.core.context_processors.debug",
+ "django.core.context_processors.i18n",
+ "django.core.context_processors.media",
+ "django.contrib.messages.context_processors.messages")
+
+.. versionadded:: 1.2
+ In addition to these, ``RequestContext`` always uses
+ ``django.core.context_processors.csrf``. 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 by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+.. versionadded:: 1.2
+ The ``'messages'`` context processor was added. For more information, see
+ the :doc:`messages documentation </ref/contrib/messages>`.
+
+.. versionchanged:: 1.2
+ The auth context processor was moved in this release from its old location
+ ``django.core.context_processors.auth`` to
+ ``django.contrib.auth.context_processors.auth``.
+
+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.
+
+.. admonition:: When context processors are applied
+
+ When you use ``RequestContext``, the variables you supply directly
+ are added first, followed any variables supplied by context
+ processors. This means that a context processor may overwrite a
+ variable you've supplied, so take care to avoid variable names
+ which overlap with those supplied by your context processors.
+
+Also, you can give ``RequestContext`` a list of additional processors, using the
+optional, third positional argument, ``processors``. In this example, the
+``RequestContext`` instance gets a ``ip_address`` variable::
+
+ def ip_address_processor(request):
+ return {'ip_address': request.META['REMOTE_ADDR']}
+
+ def some_view(request):
+ # ...
+ c = RequestContext(request, {
+ 'foo': 'bar',
+ }, [ip_address_processor])
+ return HttpResponse(t.render(c))
+
+.. note::
+ If you're using Django's ``render_to_response()`` shortcut to populate a
+ template with the contents of a dictionary, your template will be passed a
+ ``Context`` instance by default (not a ``RequestContext``). To use a
+ ``RequestContext`` in your template rendering, pass an optional third
+ argument to ``render_to_response()``: a ``RequestContext``
+ instance. Your code might look like this::
+
+ def some_view(request):
+ # ...
+ return render_to_response('my_template.html',
+ my_data_dictionary,
+ context_instance=RequestContext(request))
+
+Here's what each of the default processors does:
+
+django.contrib.auth.context_processors.auth
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain these three variables:
+
+ * ``user`` -- An ``auth.User`` instance representing the currently
+ logged-in user (or an ``AnonymousUser`` instance, if the client isn't
+ logged in).
+
+ * ``messages`` -- A list of messages (as strings) that have been set
+ via the :doc:`messages framework </ref/contrib/messages>`.
+
+ * ``perms`` -- An instance of
+ ``django.core.context_processors.PermWrapper``, representing the
+ permissions that the currently logged-in user has.
+
+.. versionchanged:: 1.2
+ This context processor was moved in this release from
+ ``django.core.context_processors.auth`` to its current location.
+
+.. versionchanged:: 1.2
+ Prior to version 1.2, the ``messages`` variable was a lazy accessor for
+ ``user.get_and_delete_messages()``. It has been changed to include any
+ messages added via the :doc:`messages framework </ref/contrib/messages>`.
+
+django.core.context_processors.debug
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain these two variables -- but only if your
+:setting:`DEBUG` setting is set to ``True`` and the request's IP address
+(``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting:
+
+ * ``debug`` -- ``True``. You can use this in templates to test whether
+ you're in :setting:`DEBUG` mode.
+ * ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` 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.
+
+django.core.context_processors.i18n
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain these two variables:
+
+ * ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting.
+ * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise,
+ the value of the :setting:`LANGUAGE_CODE` setting.
+
+See :doc:`/topics/i18n/index` for more.
+
+django.core.context_processors.media
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
+value of the :setting:`MEDIA_URL` setting.
+
+django.core.context_processors.csrf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+This processor adds a token that is needed by the ``csrf_token`` template tag
+for protection against :doc:`Cross Site Request Forgeries </ref/contrib/csrf>`.
+
+django.core.context_processors.request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a variable ``request``, which is the current
+:class:`~django.http.HttpRequest`. Note that this processor is not enabled by default;
+you'll have to activate it.
+
+django.contrib.messages.context_processors.messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a single additional variable:
+
+ * ``messages`` -- A list of messages (as strings) that have been set
+ via the user model (using ``user.message_set.create``) or through
+ the :doc:`messages framework </ref/contrib/messages>`.
+
+.. versionadded:: 1.2
+ This template context variable was previously supplied by the ``'auth'``
+ context processor. For backwards compatibility the ``'auth'`` context
+ processor will continue to supply the ``messages`` variable until Django
+ 1.4. If you use the ``messages`` variable, your project will work with
+ either (or both) context processors, but it is recommended to add
+ ``django.contrib.messages.context_processors.messages`` so your project
+ will be prepared for the future upgrade.
+
+Writing your own context processors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A context processor has a very simple interface: It's just a Python function
+that takes one argument, an :class:`~django.http.HttpRequest` object, and
+returns a dictionary that gets added to the template context. Each context
+processor *must* return a dictionary.
+
+Custom context processors can live anywhere in your code base. All Django cares
+about is that your custom context processors are pointed-to by your
+:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+Loading templates
+-----------------
+
+Generally, you'll store templates in files on your filesystem rather than using
+the low-level ``Template`` API yourself. Save templates in a directory
+specified as a **template directory**.
+
+Django searches for template directories in a number of places, depending on
+your template-loader settings (see "Loader types" below), but the most basic
+way of specifying template directories is by using the :setting:`TEMPLATE_DIRS`
+setting.
+
+The TEMPLATE_DIRS setting
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tell Django what your template directories are by using the
+:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a
+list or tuple of strings that contain full paths to your template
+directory(ies). Example::
+
+ TEMPLATE_DIRS = (
+ "/home/html/templates/lawrence.com",
+ "/home/html/templates/default",
+ )
+
+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 ``.html`` or ``.txt``, or they can have no extension at all.
+
+Note that these paths should use Unix-style forward slashes, even on Windows.
+
+.. _ref-templates-api-the-python-api:
+
+The Python API
+~~~~~~~~~~~~~~
+
+Django has two ways to load templates from files:
+
+.. function:: django.template.loader.get_template(template_name)
+
+ ``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``.
+
+.. function:: django.template.loader.select_template(template_name_list)
+
+ ``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.
+
+For example, if you call ``get_template('story_detail.html')`` and have the
+above :setting:`TEMPLATE_DIRS` setting, 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:`TEMPLATE_DIRS` setting 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:
+
+Loader types
+~~~~~~~~~~~~
+
+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.
+
+Some of these other loaders are disabled by default, but you can activate them
+by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS`
+should be a tuple of strings, where each string represents a template loader.
+Here are the template loaders that come with Django:
+
+``django.template.loaders.filesystem.Loader``
+ Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
+ This loader is enabled by default.
+
+``django.template.loaders.app_directories.Loader``
+ Loads templates from Django apps on the filesystem. For each app in
+ :setting:`INSTALLED_APPS`, the loader looks for a ``templates``
+ subdirectory. If the directory exists, Django looks for templates in there.
+
+ This means you can store templates with your individual apps. This also
+ makes it easy to distribute Django apps with default templates.
+
+ For example, for this setting::
+
+ INSTALLED_APPS = ('myproject.polls', 'myproject.music')
+
+ ...then ``get_template('foo.html')`` will look for templates in these
+ directories, in this order:
+
+ * ``/path/to/myproject/polls/templates/foo.html``
+ * ``/path/to/myproject/music/templates/foo.html``
+
+ Note that the loader performs an optimization when it is first imported: It
+ caches a list of which :setting:`INSTALLED_APPS` packages have a
+ ``templates`` subdirectory.
+
+ This loader is enabled by default.
+
+``django.template.loaders.eggs.Loader``
+ Just like ``app_directories`` above, but it loads templates from Python
+ eggs rather than from the filesystem.
+
+ This loader is disabled by default.
+
+``django.template.loaders.cached.Loader``
+ 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.
+
+ 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 ``Template`` in memory. The cached ``Template``
+ instance is returned for subsequent requests to load the same template.
+
+ For example, to enable template caching with the ``filesystem`` and
+ ``app_directories`` template loaders you might use the following settings::
+
+ TEMPLATE_LOADERS = (
+ ('django.template.loaders.cached.Loader', (
+ 'django.template.loaders.filesystem.Loader',
+ 'django.template.loaders.app_directories.Loader',
+ )),
+ )
+
+ .. note::
+ 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
+ ``Node`` implementation for each tag is thread-safe. For more
+ information, see
+ :ref:`template tag thread safety considerations<template_tag_thread_safety>`.
+
+ This loader is disabled by default.
+
+Django uses the template loaders in order according to the
+:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
+match.
+
+The ``render_to_string`` shortcut
+===================================
+
+.. function:: django.template.loader.render_to_string(template_name, dictionary=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:
+
+ dictionary
+ A dictionary to be used as variables and values for the
+ template's context. This can also be passed as the second
+ positional argument.
+
+ context_instance
+ An instance of ``Context`` or a subclass (e.g., an instance of
+ ``RequestContext``) to use as the template's context. This can
+ also be passed as the third positional argument.
+
+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
+==================================================
+
+.. note::
+
+ This section is only of interest to people trying to use the template
+ system as an output component in another application. If you're using the
+ template system as part of a Django application, nothing here applies to
+ you.
+
+Normally, Django will load all the configuration information it needs from its
+own default configuration file, combined with the settings in the module given
+in the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. But if you're
+using the template system independently of the rest of Django, the environment
+variable approach isn't very convenient, because you probably want to configure
+the template system in line with the rest of your application rather than
+dealing with settings files and pointing to them via environment variables.
+
+To solve this problem, you need to use the manual configuration option described
+in :ref:`settings-without-django-settings-module`. Simply import the appropriate
+pieces of the templating system and then, *before* you call any of the
+templating functions, call :func:`django.conf.settings.configure()` with any
+settings you wish to specify. You might want to consider setting at least
+:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
+:setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
+and :setting:`TEMPLATE_DEBUG`. All available settings are described in the
+:doc:`settings documentation </ref/settings>`, and any setting starting with
+``TEMPLATE_`` is of obvious interest.
+
+.. _topic-template-alternate-language:
+
+Using an alternative template language
+======================================
+
+.. versionadded:: 1.2
+
+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/2/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
+allows us to use third-party template libraries without giving up useful Django
+features like the Django ``Context`` object and handy shortcuts like
+``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.loader.BaseLoader`` 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)``.
+
+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.