Ticket #11152: template-docs.diff

File template-docs.diff, 9.2 KB (added by Adam Vandenberg, 14 years ago)

  • docs/ref/templates/api.txt 

    diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 44de4d9..db3f71a 100644
    a b from the context and executing all block tags.  
    5252Using the template system
    5353=========================
    5454
     55.. class:: django.template.Template
     56
    5557Using the template system in Python is a two-step process:
    5658
    5759    * First, you compile the raw template code into a ``Template`` object.
    … … Compiling a string  
    6264------------------
    6365
    6466The easiest way to create a ``Template`` object is by instantiating it
    65 directly. The class lives at ``django.template.Template``. The constructor
     67directly. The class lives at :class:`django.template.Template`. The constructor
    6668takes one argument -- the raw template code::
    6769
    6870    >>> from django.template import Template
    … … takes one argument -- the raw template code::  
    8284Rendering a context
    8385-------------------
    8486
     87.. method:: render(context)
     88
    8589Once you have a compiled ``Template`` object, you can render a context -- or
    8690multiple contexts -- with it. The ``Context`` class lives at
    87 ``django.template.Context``, and the constructor takes two (optional)
     91:class:`django.template.Context`, and the constructor takes two (optional)
    8892arguments:
    8993
    9094    * A dictionary mapping variable names to variable values.
    … … some things to keep in mind:  
    177181        >>> t.render(Context({"person": p}))
    178182        "My name is ."
    179183
    180       Note that ``django.core.exceptions.ObjectDoesNotExist``, which is the
     184      Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the
    181185      base class for all Django database API ``DoesNotExist`` exceptions, has
    182186      ``silent_variable_failure = True``. So if you're using Django templates
    183187      with Django model objects, any ``DoesNotExist`` exception will fail
    … … some things to keep in mind:  
    190194    * Obviously, some methods have side effects, and it'd be either foolish or
    191195      a security hole to allow the template system to access them.
    192196
    193       A good example is the ``delete()`` method on each Django model object.
    194       The template system shouldn't be allowed to do something like this::
     197      A good example is the :meth:`~django.models.Model.delete` method on
     198      each Django model object. The template system shouldn't be allowed to do
     199      something like this::
    195200
    196201        I will now delete this valuable data. {{ data.delete }}
    197202
    198203      To prevent this, set a function attribute ``alters_data`` on the method.
    199204      The template system won't execute a method if the method has
    200       ``alters_data=True`` set. The dynamically-generated ``delete()`` and
    201       ``save()`` methods on Django model objects get ``alters_data=True``
    202       automatically. Example::
     205      ``alters_data=True`` set. The dynamically-generated
     206      :meth:`~django.models.Model.delete` and
     207      :meth:`~django.models.Model.save` methods on Django model objects get
     208      ``alters_data=True`` automatically. Example::
    203209
    204210        def sensitive_function(self):
    205211            self.database_record.delete()
    … … be replaced with the name of the invalid variable.  
    245251Playing with Context objects
    246252----------------------------
    247253
     254.. class:: django.template.Context
     255
    248256Most of the time, you'll instantiate ``Context`` objects by passing in a
    249257fully-populated dictionary to ``Context()``. But you can add and delete items
    250258from a ``Context`` object once it's been instantiated, too, using standard
    … … dictionary syntax::  
    260268    >>> c['newvariable']
    261269    'hello'
    262270
     271.. method:: pop()
     272.. method:: push()
     273.. exception:: django.template.ContextPopException
     274
    263275A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it.
    264276If you ``pop()`` too much, it'll raise
    265277``django.template.ContextPopException``::
    … … If you ``pop()`` too much, it'll raise  
    281293    ...
    282294    django.template.ContextPopException
    283295
     296.. method:: update(other_dict)
     297
    284298In addition to ``push()`` and ``pop()``, the ``Context``
    285299object also defines an ``update()`` method. This works like ``push()``
    286300but takes a dictionary as an argument and pushes that dictionary onto
    … … and return a dictionary of items to be merged into the context. By default,  
    333347
    334348.. versionadded:: 1.2
    335349   In addition to these, ``RequestContext`` always uses
    336    ``'django.core.context_processors.csrf'``.  This is a security
     350   ``django.core.context_processors.csrf``.  This is a security
    337351   related context processor required by the admin and other contrib apps, and,
    338352   in case of accidental misconfiguration, it is deliberately hardcoded in and
    339353   cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
    … … Writing your own context processors  
    499513~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    500514
    501515A context processor has a very simple interface: It's just a Python function
    502 that takes one argument, an ``HttpRequest`` object, and returns a dictionary
    503 that gets added to the template context. Each context processor *must* return
    504 a dictionary.
     516that takes one argument, an :class:`~django.http.HttpRequest` object, and
     517returns a dictionary that gets added to the template context. Each context
     518processor *must* return a dictionary.
    505519
    506520Custom context processors can live anywhere in your code base. All Django cares
    507521about is that your custom context processors are pointed-to by your
    … … Django uses the template loaders in order according to the  
    685699:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
    686700match.
    687701
    688 The ``render_to_string()`` shortcut
     702The ``render_to_string`` shortcut
    689703===================================
    690704
     705.. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None)
     706
    691707To cut down on the repetitive nature of loading and rendering
    692708templates, Django provides a shortcut function which largely
    693709automates the process: ``render_to_string()`` in
    694 ``django.template.loader``, which loads a template, renders it and
     710:mod:`django.template.loader`, which loads a template, renders it and
    695711returns the resulting string::
    696712
    697713    from django.template.loader import render_to_string
    … … the first template in the list that exists) -- and two optional arguments:  
    713729        also be passed as the third positional argument.
    714730
    715731See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
    716 calls ``render_to_string`` and feeds the result into an ``HttpResponse``
     732calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
    717733suitable for returning directly from a view.
    718734
    719735Configuring the template system in standalone mode
    … … dealing with settings files and pointing to them via environment variables.  
    737753To solve this problem, you need to use the manual configuration option described
    738754in :ref:`settings-without-django-settings-module`. Simply import the appropriate
    739755pieces of the templating system and then, *before* you call any of the
    740 templating functions, call ``django.conf.settings.configure()`` with any
     756templating functions, call :func:`django.conf.settings.configure()` with any
    741757settings you wish to specify. You might want to consider setting at least
    742758:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
    743759:setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
    … … features like the Django ``Context`` object and handy shortcuts like  
    763779The core component of the Django templating system is the ``Template`` class.
    764780This class has a very simple interface: it has a constructor that takes a single
    765781positional argument specifying the template string, and a ``render()`` method
    766 that takes a ``django.template.context.Context`` object and returns a string
     782that takes a :class:`django.template.context.Context` object and returns a string
    767783containing the rendered response.
    768784
    769785Suppose we're using a template language that defines a ``Template`` object with
    … … That's all that's required to make our fictional ``Template`` class compatible  
    783799with the Django loading and rendering system!
    784800
    785801The next step is to write a ``Loader`` class that returns instances of our custom
    786 template class instead of the default ``django.template.Template``. Custom ``Loader``
     802template class instead of the default :class:`django.template.Template`. Custom ``Loader``
    787803classes should inherit from ``django.template.loader.BaseLoader`` and override
    788804the ``load_template_source()`` method, which takes a ``template_name`` argument,
    789805loads the template from disk (or elsewhere), and returns a tuple:
    … … string by calling ``load_template_source()``, instantiates a ``Template`` from  
    794810the template source, and returns a tuple: ``(template, template_origin)``. Since
    795811this is the method that actually instantiates the ``Template``, we'll need to
    796812override it to use our custom template class instead. We can inherit from the
    797 builtin ``django.template.loaders.app_directories.Loader`` to take advantage of
    798 the ``load_template_source()`` method implemented there::
     813builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
     814of the ``load_template_source()`` method implemented there::
    799815
    800816    from django.template.loaders import app_directories
    801817    class Loader(app_directories.Loader):
Back to Top