Django

Code

Show
Ignore:
Timestamp:
06/22/07 11:56:04 (1 year ago)
Author:
bouldersprinters
Message:

boulder-oracle-sprint: Merged to [5511]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/boulder-oracle-sprint/docs/templates_python.txt

    r5491 r5512  
    220220    While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool, 
    221221    it is a bad idea to turn it on as a 'development default'. 
    222  
     222     
    223223    Many templates, including those in the Admin site, rely upon the 
    224224    silence of the template system when a non-existent variable is 
    …… 
    226226    ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering 
    227227    problems with these templates and sites. 
    228  
     228     
    229229    Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled 
    230230    in order to debug a specific template problem, then cleared 
    …… 
    694694When Django compiles a template, it splits the raw template text into 
    695695''nodes''. Each node is an instance of ``django.template.Node`` and has 
    696 either a ``render()`` or ``iter_render()`` method. A compiled template is, 
    697 simply, a list of ``Node`` objects. When you call ``render()`` on a compiled 
    698 template object, the template calls ``render()`` on each ``Node`` in its node 
    699 list, with the given context. The results are all concatenated together to 
    700 form the output of the template. 
     696a ``render()`` method. A compiled template is, simply, a list of ``Node`` 
     697objects. When you call ``render()`` on a compiled template object, the template 
     698calls ``render()`` on each ``Node`` in its node list, with the given context. 
     699The results are all concatenated together to form the output of the template. 
    701700 
    702701Thus, to define a custom template tag, you specify how the raw template tag is 
    703702converted into a ``Node`` (the compilation function), and what the node's 
    704 ``render()`` or ``iter_render()`` method does. 
     703``render()`` method does. 
    705704 
    706705Writing the compilation function 
    …… 
    772771 
    773772The second step in writing custom tags is to define a ``Node`` subclass that 
    774 has a ``render()`` method (we will discuss the ``iter_render()`` alternative 
    775 in `Improving rendering speed`_, below). 
     773has a ``render()`` method. 
    776774 
    777775Continuing the above example, we need to define ``CurrentTimeNode``:: 
    …… 
    877875            self.date_to_be_formatted = date_to_be_formatted 
    878876            self.format_string = format_string 
    879  
     877         
    880878        def render(self, context): 
    881879            try: 
    …… 
    11781176.. _configuration: 
    11791177 
    1180 Improving rendering speed 
    1181 ~~~~~~~~~~~~~~~~~~~~~~~~~ 
    1182  
    1183 For most practical purposes, the ``render()`` method on a ``Node`` will be 
    1184 sufficient and the simplest way to implement a new tag. However, if your 
    1185 template tag is expected to produce large strings via ``render()``, you can 
    1186 speed up the rendering process (and reduce memory usage) using iterative 
    1187 rendering via the ``iter_render()`` method. 
    1188  
    1189 The ``iter_render()`` method should either be an iterator that yields string 
    1190 chunks, one at a time, or a method that returns a sequence of string chunks. 
    1191 The template renderer will join the successive chunks together when creating 
    1192 the final output. The improvement over the ``render()`` method here is that 
    1193 you do not need to create one large string containing all the output of the 
    1194 ``Node``, instead you can produce the output in smaller chunks. 
    1195  
    1196 By way of example, here's a trivial ``Node`` subclass that simply returns the 
    1197 contents of a file it is given:: 
    1198  
    1199     class FileNode(Node): 
    1200         def __init__(self, filename): 
    1201             self.filename = filename 
    1202  
    1203         def iter_render(self): 
    1204             for line in file(self.filename): 
    1205                 yield line 
    1206  
    1207 For very large files, the full file contents will never be read entirely into 
    1208 memory when this tag is used, which is a useful optimisation. 
    1209  
    1210 If you define an ``iter_render()`` method on your ``Node`` subclass, you do 
    1211 not need to define a ``render()`` method. The reverse is true as well: the 
    1212 default ``Node.iter_render()`` method will call your ``render()`` method if 
    1213 necessary. A useful side-effect of this is that you can develop a new tag 
    1214 using ``render()`` and producing all the output at once, which is easy to 
    1215 debug. Then you can rewrite the method as an iterator, rename it to 
    1216 ``iter_render()`` and everything will still work. 
    1217  
    1218 It is compulsory, however, to define *either* ``render()`` or ``iter_render()`` 
    1219 in your subclass. If you omit them both, a ``TypeError`` will be raised when 
    1220 the code is imported. 
    1221  
    12221178Configuring the template system in standalone mode 
    12231179================================================== 
    …… 
    12511207.. _settings file: ../settings/#using-settings-without-the-django-settings-module-environment-variable 
    12521208.. _settings documentation: ../settings/ 
    1253