test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[1.2.X] Fixed #11152 - Add some classes to the template docs. Thanks adamv for the patch. 

Backport of r14744 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14745 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Timo Graham 2010-11-29 01:00:09 +00:00
parent 57c55c69f8
commit fe74b832b1
1 changed files with 52 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -52,6 +52,8 @@ 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.
@ -62,7 +64,7 @@ Compiling a string
------------------
The easiest way to create a ``Template`` object is by instantiating it
directly. The class lives at ``django.template.Template``. The constructor
directly. The class lives at :class:`django.template.Template`. The constructor
takes one argument -- the raw template code::
>>> from django.template import Template
@ -82,9 +84,11 @@ takes one argument -- the raw template code::
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
``django.template.Context``, and the constructor takes two (optional)
:class:`django.template.Context`, and the constructor takes two (optional)
arguments:
* A dictionary mapping variable names to variable values.
@ -177,7 +181,7 @@ some things to keep in mind:
>>> t.render(Context({"person": p}))
"My name is ."
Note that ``django.core.exceptions.ObjectDoesNotExist``, which is the
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
@ -190,16 +194,18 @@ some things to keep in mind:
* 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 ``delete()`` method on each Django model object.
The template system shouldn't be allowed to do something like this::
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 ``delete()`` and
``save()`` methods on Django model objects get ``alters_data=True``
automatically. Example::
``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()
@ -245,6 +251,8 @@ be replaced with the name of the invalid variable.
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
@ -260,6 +268,10 @@ dictionary syntax::
>>> 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``::
@ -281,6 +293,24 @@ If you ``pop()`` too much, it'll raise
...
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.
@ -314,7 +344,7 @@ and return a dictionary of items to be merged into the context. By default,
.. versionadded:: 1.2
In addition to these, ``RequestContext`` always uses
``'django.core.context_processors.csrf'``. This is a security
``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.
@ -471,9 +501,9 @@ Writing your own context processors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A context processor has a very simple interface: It's just a Python function
that takes one argument, an ``HttpRequest`` object, and returns a dictionary
that gets added to the template context. Each context processor *must* return
a dictionary.
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
@ -657,13 +687,15 @@ 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
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
``django.template.loader``, which loads a template, renders it and
:mod:`django.template.loader`, which loads a template, renders it and
returns the resulting string::
from django.template.loader import render_to_string
@ -685,7 +717,7 @@ the first template in the list that exists) -- and two optional arguments:
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 ``HttpResponse``
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
@ -709,7 +741,7 @@ 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 ``django.conf.settings.configure()`` with any
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)
@ -735,7 +767,7 @@ features like the Django ``Context`` object and handy shortcuts like
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
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
@ -755,7 +787,7 @@ 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``
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:
@ -766,8 +798,8 @@ 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::
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):