Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #11152 - Add some classes to the template docs. Thanks adamv fo…

…r the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14744 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 08daa3df4781a886f6555f7fc5aafe2e54671e31 1 parent 2fa0fd2
Tim Graham authored November 29, 2010

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

  1. 56  docs/ref/templates/api.txt
56  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,8 @@ If you ``pop()`` too much, it'll raise
281 293
     ...
282 294
     django.template.ContextPopException
283 295
 
  296
+.. method:: update(other_dict)
  297
+
284 298
 In addition to ``push()`` and ``pop()``, the ``Context``
285 299
 object also defines an ``update()`` method. This works like ``push()``
286 300
 but takes a dictionary as an argument and pushes that dictionary onto
@@ -333,7 +347,7 @@ and return a dictionary of items to be merged into the context. By default,
333 347
 
334 348
 .. versionadded:: 1.2
335 349
    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
337 351
    related context processor required by the admin and other contrib apps, and,
338 352
    in case of accidental misconfiguration, it is deliberately hardcoded in and
339 353
    cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
@@ -499,9 +513,9 @@ Writing your own context processors
499 513
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500 514
 
501 515
 A 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.
  516
+that takes one argument, an :class:`~django.http.HttpRequest` object, and
  517
+returns a dictionary that gets added to the template context. Each context
  518
+processor *must* return a dictionary.
505 519
 
506 520
 Custom context processors can live anywhere in your code base. All Django cares
507 521
 about is that your custom context processors are pointed-to by your
@@ -685,13 +699,15 @@ Django uses the template loaders in order according to the
685 699
 :setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
686 700
 match.
687 701
 
688  
-The ``render_to_string()`` shortcut
  702
+The ``render_to_string`` shortcut
689 703
 ===================================
690 704
 
  705
+.. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None)
  706
+
691 707
 To cut down on the repetitive nature of loading and rendering
692 708
 templates, Django provides a shortcut function which largely
693 709
 automates 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
695 711
 returns the resulting string::
696 712
 
697 713
     from django.template.loader import render_to_string
@@ -713,7 +729,7 @@ the first template in the list that exists) -- and two optional arguments:
713 729
         also be passed as the third positional argument.
714 730
 
715 731
 See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
716  
-calls ``render_to_string`` and feeds the result into an ``HttpResponse``
  732
+calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
717 733
 suitable for returning directly from a view.
718 734
 
719 735
 Configuring the template system in standalone mode
@@ -737,7 +753,7 @@ dealing with settings files and pointing to them via environment variables.
737 753
 To solve this problem, you need to use the manual configuration option described
738 754
 in :ref:`settings-without-django-settings-module`. Simply import the appropriate
739 755
 pieces of the templating system and then, *before* you call any of the
740  
-templating functions, call ``django.conf.settings.configure()`` with any
  756
+templating functions, call :func:`django.conf.settings.configure()` with any
741 757
 settings you wish to specify. You might want to consider setting at least
742 758
 :setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
743 759
 :setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
@@ -763,7 +779,7 @@ features like the Django ``Context`` object and handy shortcuts like
763 779
 The core component of the Django templating system is the ``Template`` class.
764 780
 This class has a very simple interface: it has a constructor that takes a single
765 781
 positional argument specifying the template string, and a ``render()`` method
766  
-that takes a ``django.template.context.Context`` object and returns a string
  782
+that takes a :class:`~django.template.Context` object and returns a string
767 783
 containing the rendered response.
768 784
 
769 785
 Suppose we're using a template language that defines a ``Template`` object with
@@ -783,7 +799,7 @@ That's all that's required to make our fictional ``Template`` class compatible
783 799
 with the Django loading and rendering system!
784 800
 
785 801
 The 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``
  802
+template class instead of the default :class:`~django.template.Template`. Custom ``Loader``
787 803
 classes should inherit from ``django.template.loader.BaseLoader`` and override
788 804
 the ``load_template_source()`` method, which takes a ``template_name`` argument,
789 805
 loads the template from disk (or elsewhere), and returns a tuple:
@@ -794,8 +810,8 @@ string by calling ``load_template_source()``, instantiates a ``Template`` from
794 810
 the template source, and returns a tuple: ``(template, template_origin)``. Since
795 811
 this is the method that actually instantiates the ``Template``, we'll need to
796 812
 override 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::
  813
+builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
  814
+of the ``load_template_source()`` method implemented there::
799 815
 
800 816
     from django.template.loaders import app_directories
801 817
     class Loader(app_directories.Loader):

0 notes on commit 08daa3d

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