Fixed #2556 -- Documented that simple_tag functions can take any number of

arguments, not just one.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@3772 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Malcolm Tredinnick 2006-09-21 11:41:18 +00:00
parent d411a9a777
commit d85ee1c01e
1 changed files with 11 additions and 6 deletions

View File

@ -763,17 +763,17 @@ will use the function's name as the tag name.
Shortcut for simple tags Shortcut for simple tags
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
Many template tags take a single argument -- a string or a template variable Many template tags take a number of arguments -- strings or a template variables
reference -- and return a string after doing some processing based solely on -- and return a string after doing some processing based solely on
the input argument and some external information. For example, the the input argument and some external information. For example, the
``current_time`` tag we wrote above is of this variety: we give it a format ``current_time`` tag we wrote above is of this variety: we give it a format
string, it returns the time as a string. string, it returns the time as a string.
To ease the creation of the types of tags, Django provides a helper function, To ease the creation of the types of tags, Django provides a helper function,
``simple_tag``. This function, which is a method of ``simple_tag``. This function, which is a method of
``django.template.Library``, takes a function that accepts one argument, wraps ``django.template.Library``, takes a function that accepts any number of
it in a ``render`` function and the other necessary bits mentioned above and arguments, wraps it in a ``render`` function and the other necessary bits
registers it with the template system. mentioned above and registers it with the template system.
Our earlier ``current_time`` function could thus be written like this:: Our earlier ``current_time`` function could thus be written like this::
@ -789,11 +789,16 @@ In Python 2.4, the decorator syntax also works::
... ...
A couple of things to note about the ``simple_tag`` helper function: A couple of things to note about the ``simple_tag`` helper function:
* Only the (single) argument is passed into our function.
* Checking for the required number of arguments, etc, has already been * Checking for the required number of arguments, etc, has already been
done by the time our function is called, so we don't need to do that. done by the time our function is called, so we don't need to do that.
* The quotes around the argument (if any) have already been stripped away, * The quotes around the argument (if any) have already been stripped away,
so we just receive a plain string. so we just receive a plain string.
* If the argument was a template variable, our function is passed the
current value of the variable, not the variable itself.
When your template tag does not need access to the current context, writing a
function to work with the input values and using the ``simple_tag`` helper is
the easiest way to create a new tag.
Inclusion tags Inclusion tags
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~