From 44b9076bbed3e629230d9b77a8765e4c906036d1 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Mon, 14 Dec 2009 12:08:23 +0000 Subject: Fixed #6262 -- Added a cached template loader, and modified existing template loaders and tag to be cacheable. Thanks to Mike Malone for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11862 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/sitemaps.txt | 4 +- docs/ref/settings.txt | 13 +++-- docs/ref/templates/api.txt | 108 +++++++++++++++++++++++++++++++++++++++--- 3 files changed, 112 insertions(+), 13 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index e7cd224e3e..82a4d15cf4 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -36,7 +36,7 @@ To install the sitemap app, follow these steps: 1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` setting. - 2. Make sure ``'django.template.loaders.app_directories.load_template_source'`` + 2. Make sure ``'django.template.loaders.app_directories.Loader'`` is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default, so you'll only need to change this if you've changed that setting. @@ -45,7 +45,7 @@ To install the sitemap app, follow these steps: (Note: The sitemap application doesn't install any database tables. The only reason it needs to go into :setting:`INSTALLED_APPS` is so that the -:func:`~django.template.loaders.app_directories.load_template_source` template +:func:`~django.template.loaders.app_directories.Loader` template loader can find the default templates.) Initialization diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 9730c1ddf4..8ff15097ac 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -819,7 +819,7 @@ MESSAGE_LEVEL Default: `messages.INFO` -Sets the minimum message level that will be recorded by the messages +Sets the minimum message level that will be recorded by the messages framework. See the :ref:`messages documentation ` for more details. @@ -1150,11 +1150,14 @@ TEMPLATE_LOADERS Default:: - ('django.template.loaders.filesystem.load_template_source', - 'django.template.loaders.app_directories.load_template_source') + ('django.template.loaders.filesystem.Loader', + 'django.template.loaders.app_directories.Loader') -A tuple of callables (as strings) that know how to import templates from -various sources. See :ref:`ref-templates-api`. +A tuple of template loader classes, specified as strings. Each ``Loader`` class +knows how to import templates from a particular sources. Optionally, a tuple can be +used instead of a string. The first item in the tuple should be the ``Loader``'s +module, subsequent items are passed to the ``Loader`` during initialization. See +:ref:`ref-templates-api`. .. setting:: TEMPLATE_STRING_IF_INVALID diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 077325b48e..fa42949eea 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -322,7 +322,7 @@ and return a dictionary of items to be merged into the context. By default, 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 ``'messages'`` context processor was added. For more information, see the :ref:`messages documentation `. Each processor is applied in order. That means, if one processor adds a @@ -379,7 +379,7 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every .. 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 + ``user.get_and_delete_messages()``. It has been changed to include any messages added via the :ref:`messages framework `. + + 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. @@ -667,3 +698,68 @@ settings you wish to specify. You might want to consider setting at least and :setting:`TEMPLATE_DEBUG`. All available settings are described in the :ref:`settings documentation `, 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 +`_ or `Cheetah `_. 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 ``django.template.context.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 ``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 ``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. -- cgit v1.3