Django

Code

Changeset 2979

Show
Ignore:
Timestamp:
05/25/06 00:29:27 (2 years ago)
Author:
adrian
Message:

Made some edits to docs/templates_python.txt 'inclusion_tag' section

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/templates_python.txt

    r2978 r2979  
    785785~~~~~~~~~~~~~~ 
    786786 
    787 Another type of template tag that is sometimes useful is when you want to 
    788 display some data that is computed at render time in a template fragment. For 
    789 example, in Django's admin interface, there is a line of buttons along the 
    790 bottom of the `create/edit record` screen. These buttons always look the same, 
    791 but the link targets change depending upon the object being edited. So they 
    792 are a perfect example for using a small template that is filled in with 
    793 details from the current object. To save typing, it would also be nice if we 
    794 could wrap this whole display up in a single tag (in the admin templates this 
    795 is the ``submit_row`` tag). 
    796  
    797 We call these sorts of tags `inclusion tags`. In your template, you pass in 
    798 any appropriate arguments and the tag uses those arguments, together with the 
    799 current context to render a template and include the result in the output. 
    800  
    801 Writing inclusion tags is probably best demonstrated by example. We will write 
    802 a tag that outputs a list of choices for a Poll object, such as was created in 
    803 the tutorials_. We will use this tag like this:: 
     787Another common type of template tag is the type that displays some data by 
     788rendering *another* template. For example, Django's admin interface uses custom 
     789template tags to display the buttons along the botton of the "add/change" form 
     790pages. Those buttons always look the same, but the link targets change depending 
     791on the object being edited -- so they're a perfect case for using a small 
     792template that is filled with details from the current object. (In the admin's 
     793case, this is the ``submit_row`` tag.) 
     794 
     795These sorts of tags are called `inclusion tags`. 
     796 
     797Writing inclusion tags is probably best demonstrated by example. Let's write a 
     798tag that outputs a list of choices for a given ``Poll`` object, such as was 
     799created in the tutorials_. We'll use the tag like this:: 
    804800 
    805801    {% show_results poll %} 
    806802 
    807 and the output will be something like this:: 
     803...and the output will be something like this:: 
    808804 
    809805    <ul> 
    …… 
    813809    </ul> 
    814810 
    815 First, we define the function which takes the argument and produces a 
    816 dictionary of data for the result. The important point here is we only need to 
    817 return a dictionary, not anything more complex. This will be used to substitue 
    818 for values in the template fragment, just as when templates are used 
    819 elsewhere. 
    820  
    821 :: 
     811First, define the function that takes the argument and produces a dictionary of 
     812data for the result. The important point here is we only need to return a 
     813dictionary, not anything more complex. This will be used as a template context 
     814for the template fragment. Example:: 
    822815 
    823816    def show_results(poll): 
    …… 
    825818        return {'choices': choices} 
    826819 
    827 We also need to create the template that is used to render the output. This 
    828 template is a fixed feature of the tag: the tag writer specifies it, not the 
    829 template designer. In our case, the template is very simple:: 
     820Next, create the template used to render the tag's output. This template is a 
     821fixed feature of the tag: the tag writer specifies it, not the template 
     822designer. Following our example, the template is very simple:: 
    830823 
    831824    <ul> 
    …… 
    835828    </ul> 
    836829 
    837 Now we can create the inclusion tag. Suppose the above template is in a file 
    838 called ``results.html`` in a directory that is searched by the template 
    839 loader. We register our new tag similarly to a normal tag. 
    840  
    841 :: 
     830Now, create and register the inclusion tag by calling the ``inclusion_tag()`` 
     831method on a ``Library`` object. Following our example, if the above template is 
     832in a file called ``results.html`` in a directory that's searched by the template 
     833loader, we'd register the tag like this:: 
    842834 
    843835    # Here, register is a django.template.Library instance, as before 
    …… 
    845837 
    846838As always, Python 2.4 decorator syntax works as well, so we could have 
    847 written 
    848  
    849 :: 
     839written:: 
    850840 
    851841    @inclusion_tag('results.html') 
    …… 
    853843        ... 
    854844 
    855 when first creating the function. 
    856  
    857 In some cases, an inclusion tag might require a large number of arguments to 
    858 display itself properly. In essence, it would depend largely on the current 
    859 context it was being rendered with. We can make these sorts of tags easier to 
    860 write by telling the ``inclusion_tag`` function that the whole context 
    861 should be passed in as an argument to the function. This will be done 
    862 invisibly as far as the template tag user is concerned: they will not need to 
    863 do anything to pass in the context. 
    864  
    865 For example, suppose we are writing an inclusion tag that will always be used 
    866 in a context that contains ``home_link`` and ``home_title`` variables that 
    867 point back to the main page. We can write a tag that is used like this:: 
    868  
    869     {% jump_link %} 
    870  
    871 and renders this:: 
    872  
    873     Jump directly to <a href="http://example.com/home">Home</a> 
    874  
    875 The tag function is almost as simple as before. This time it takes no 
    876 arguments except the ``context`` (and the parameter `must` be called 
    877 ``context`` in this case; the special parameter named is used internally by 
    878 Django to fill in the values correctly). 
    879  
    880 :: 
     845...when first creating the function. 
     846 
     847Sometimes, your inclusion tags might require a large number of arguments, 
     848making it a pain for template authors to pass in all the arguments and remember 
     849their order. To solve this, Django provides a ``takes_context`` option for 
     850inclusion tags. If you specify ``takes_context`` in creating a template tag, 
     851the tag will have no required arguments, and the underlying Python function 
     852will have one argument -- the template context as of when the tag was called. 
     853 
     854For example, say you're writing an inclusion tag that will always be used in a 
     855context that contains ``home_link`` and ``home_title`` variables that point 
     856back to the main page. Here's what the Python function would look like:: 
    881857 
    882858    # The first argument *must* be called "context" here. 
    …… 
    886862            'title': context['home_title'], 
    887863        } 
    888  
    889 Our template is very simple again:: 
     864    # Register the custom tag as an inclusion tag with takes_context=True. 
     865    register.inclusion_tag('link.html', takes_context=True)(jump_link) 
     866 
     867(Note that the first parameter to the function *must* be called ``context``.) 
     868 
     869In that ``register.inclusion_tag()`` line, we specified ``takes_context=True`` 
     870and the name of the template. Here's what the template ``link.html`` might look 
     871like:: 
    890872 
    891873    Jump directly to <a href="{{ link }}">{{ title }}</a>. 
    892874 
    893 Assuming the template is in a file called ``link.html``, we register this new 
    894 tag as follows:: 
    895  
    896     register.inclusion_tag('link.html', takes_context = True)(jump_link) 
    897  
    898 The ``takes_context`` parameter here defaults to *False*. When it is set to 
    899 *True*, our tag is passed the implicit context as in this example. That is the 
    900 only difference between this case and our previous use of ``inclusion_tag``. 
     875Then, any time you want to use that custom tag, load its library and call it 
     876without any arguments, like so:: 
     877 
     878    {% jump_link %} 
     879 
     880Note that when you're using ``takes_context=True``, there's no need to pass 
     881arguments to the template tag. It automatically gets access to the context. 
     882 
     883The ``takes_context`` parameter defaults to ``False``. When it's set to *True*, 
     884the tag is passed the context object, as in this example. That's the only 
     885difference between this case and the previous ``inclusion_tag`` example. 
    901886 
    902887.. _tutorials: http://www.djangoproject.com/documentation/tutorial1/#creating-models