Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[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
  • Loading branch information...
commit fe74b832b1fe0234cb71d057940157d27c89b2d1 1 parent 57c55c6
Tim Graham authored November 29, 2010

Showing 1 changed file with 52 additions and 20 deletions. Show diff stats Hide diff stats

  1. 72  docs/ref/templates/api.txt
72  docs/ref/templates/api.txt
@@ -52,6 +52,8 @@ from the context and executing all block tags.
52 52
 Using the template system
53 53
 =========================
54 54
 
  55
+.. class:: django.template.Template
  56
+
55 57
 Using the template system in Python is a two-step process:
56 58
 
57 59
     * First, you compile the raw template code into a ``Template`` object.
@@ -62,7 +64,7 @@ Compiling a string
62 64
 ------------------
63 65
 
64 66
 The easiest way to create a ``Template`` object is by instantiating it
65  
-directly. The class lives at ``django.template.Template``. The constructor
  67
+directly. The class lives at :class:`django.template.Template`. The constructor
66 68
 takes one argument -- the raw template code::
67 69
 
68 70
     >>> from django.template import Template
@@ -82,9 +84,11 @@ takes one argument -- the raw template code::
82 84
 Rendering a context
83 85
 -------------------
84 86
 
  87
+.. method:: render(context)
  88
+
85 89
 Once you have a compiled ``Template`` object, you can render a context -- or
86 90
 multiple 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)
88 92
 arguments:
89 93
 
90 94
     * A dictionary mapping variable names to variable values.
@@ -177,7 +181,7 @@ some things to keep in mind:
177 181
         >>> t.render(Context({"person": p}))
178 182
         "My name is ."
179 183
 
180  
-      Note that ``django.core.exceptions.ObjectDoesNotExist``, which is the
  184
+      Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the
181 185
       base class for all Django database API ``DoesNotExist`` exceptions, has
182 186
       ``silent_variable_failure = True``. So if you're using Django templates
183 187
       with Django model objects, any ``DoesNotExist`` exception will fail
@@ -190,16 +194,18 @@ some things to keep in mind:
190 194
     * Obviously, some methods have side effects, and it'd be either foolish or
191 195
       a security hole to allow the template system to access them.
192 196
 
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.db.models.Model.delete` method on
  198
+      each Django model object. The template system shouldn't be allowed to do
  199
+      something like this::
195 200
 
196 201
         I will now delete this valuable data. {{ data.delete }}
197 202
 
198 203
       To prevent this, set a function attribute ``alters_data`` on the method.
199 204
       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.db.models.Model.delete` and
  207
+      :meth:`~django.db.models.Model.save` methods on Django model objects get
  208
+      ``alters_data=True`` automatically. Example::
203 209
 
204 210
         def sensitive_function(self):
205 211
             self.database_record.delete()
@@ -245,6 +251,8 @@ be replaced with the name of the invalid variable.
245 251
 Playing with Context objects
246 252
 ----------------------------
247 253
 
  254
+.. class:: django.template.Context
  255
+
248 256
 Most of the time, you'll instantiate ``Context`` objects by passing in a
249 257
 fully-populated dictionary to ``Context()``. But you can add and delete items
250 258
 from a ``Context`` object once it's been instantiated, too, using standard
@@ -260,6 +268,10 @@ dictionary syntax::
260 268
     >>> c['newvariable']
261 269
     'hello'
262 270
 
  271
+.. method:: pop()
  272
+.. method:: push()
  273
+.. exception:: django.template.ContextPopException
  274
+
263 275
 A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it.
264 276
 If you ``pop()`` too much, it'll raise
265 277
 ``django.template.ContextPopException``::
@@ -281,6 +293,24 @@ If you ``pop()`` too much, it'll raise
281 293
     ...
282 294
     django.template.ContextPopException
283 295
 
  296
+.. method:: update(other_dict)
  297
+
  298
+In addition to ``push()`` and ``pop()``, the ``Context``
  299
+object also defines an ``update()`` method. This works like ``push()``
  300
+but takes a dictionary as an argument and pushes that dictionary onto
  301
+the stack instead of an empty one.
  302
+
  303
+    >>> c = Context()
  304
+    >>> c['foo'] = 'first level'
  305
+    >>> c.update({'foo': 'updated'})
  306
+    {'foo': 'updated'}
  307
+    >>> c['foo']
  308
+    'updated'
  309
+    >>> c.pop()
  310
+    {'foo': 'updated'}
  311
+    >>> c['foo']
  312
+    'first level'
  313
+
284 314
 Using a ``Context`` as a stack comes in handy in some custom template tags, as
285 315
 you'll see below.
286 316
 
@@ -314,7 +344,7 @@ and return a dictionary of items to be merged into the context. By default,
314 344
 
315 345
 .. versionadded:: 1.2
316 346
    In addition to these, ``RequestContext`` always uses
317  
-   ``'django.core.context_processors.csrf'``.  This is a security
  347
+   ``django.core.context_processors.csrf``.  This is a security
318 348
    related context processor required by the admin and other contrib apps, and,
319 349
    in case of accidental misconfiguration, it is deliberately hardcoded in and
320 350
    cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
@@ -471,9 +501,9 @@ Writing your own context processors
471 501
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472 502
 
473 503
 A context processor has a very simple interface: It's just a Python function
474  
-that takes one argument, an ``HttpRequest`` object, and returns a dictionary
475  
-that gets added to the template context. Each context processor *must* return
476  
-a dictionary.
  504
+that takes one argument, an :class:`~django.http.HttpRequest` object, and
  505
+returns a dictionary that gets added to the template context. Each context
  506
+processor *must* return a dictionary.
477 507
 
478 508
 Custom context processors can live anywhere in your code base. All Django cares
479 509
 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
657 687
 :setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
658 688
 match.
659 689
 
660  
-The ``render_to_string()`` shortcut
  690
+The ``render_to_string`` shortcut
661 691
 ===================================
662 692
 
  693
+.. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None)
  694
+
663 695
 To cut down on the repetitive nature of loading and rendering
664 696
 templates, Django provides a shortcut function which largely
665 697
 automates the process: ``render_to_string()`` in
666  
-``django.template.loader``, which loads a template, renders it and
  698
+:mod:`django.template.loader`, which loads a template, renders it and
667 699
 returns the resulting string::
668 700
 
669 701
     from django.template.loader import render_to_string
@@ -685,7 +717,7 @@ the first template in the list that exists) -- and two optional arguments:
685 717
         also be passed as the third positional argument.
686 718
 
687 719
 See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
688  
-calls ``render_to_string`` and feeds the result into an ``HttpResponse``
  720
+calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
689 721
 suitable for returning directly from a view.
690 722
 
691 723
 Configuring the template system in standalone mode
@@ -709,7 +741,7 @@ dealing with settings files and pointing to them via environment variables.
709 741
 To solve this problem, you need to use the manual configuration option described
710 742
 in :ref:`settings-without-django-settings-module`. Simply import the appropriate
711 743
 pieces of the templating system and then, *before* you call any of the
712  
-templating functions, call ``django.conf.settings.configure()`` with any
  744
+templating functions, call :func:`django.conf.settings.configure()` with any
713 745
 settings you wish to specify. You might want to consider setting at least
714 746
 :setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
715 747
 :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
735 767
 The core component of the Django templating system is the ``Template`` class.
736 768
 This class has a very simple interface: it has a constructor that takes a single
737 769
 positional argument specifying the template string, and a ``render()`` method
738  
-that takes a ``django.template.context.Context`` object and returns a string
  770
+that takes a :class:`~django.template.Context` object and returns a string
739 771
 containing the rendered response.
740 772
 
741 773
 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
755 787
 with the Django loading and rendering system!
756 788
 
757 789
 The next step is to write a ``Loader`` class that returns instances of our custom
758  
-template class instead of the default ``django.template.Template``. Custom ``Loader``
  790
+template class instead of the default :class:`~django.template.Template`. Custom ``Loader``
759 791
 classes should inherit from ``django.template.loader.BaseLoader`` and override
760 792
 the ``load_template_source()`` method, which takes a ``template_name`` argument,
761 793
 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
766 798
 the template source, and returns a tuple: ``(template, template_origin)``. Since
767 799
 this is the method that actually instantiates the ``Template``, we'll need to
768 800
 override it to use our custom template class instead. We can inherit from the
769  
-builtin ``django.template.loaders.app_directories.Loader`` to take advantage of
770  
-the ``load_template_source()`` method implemented there::
  801
+builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
  802
+of the ``load_template_source()`` method implemented there::
771 803
 
772 804
     from django.template.loaders import app_directories
773 805
     class Loader(app_directories.Loader):

0 notes on commit fe74b83

Please sign in to comment.
Something went wrong with that request. Please try again.