diff options
Diffstat (limited to 'docs/howto/custom-template-tags.txt')
| -rw-r--r-- | docs/howto/custom-template-tags.txt | 45 |
1 files changed, 22 insertions, 23 deletions
diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 2ff0cc56f9..977e00b4a3 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -89,7 +89,7 @@ an application. Writing custom template filters =============================== -Custom filters are just Python functions that take one or two arguments: +Custom filters are Python functions that take one or two arguments: * The value of the variable (input) -- not necessarily a string. * The value of the argument -- this can have a default value, or be left @@ -117,8 +117,8 @@ And here's an example of how that filter would be used: {{ somevariable|cut:"0" }} -Most filters don't take arguments. In this case, just leave the argument out of -your function. Example:: +Most filters don't take arguments. In this case, leave the argument out of your +function:: def lower(value): # Only one argument. """Converts a string into all lowercase""" @@ -312,11 +312,11 @@ Template filter code falls into one of two situations: that our function will know whether automatic escaping is in effect when the filter is called. We use ``autoescape`` to decide whether the input data needs to be passed through ``django.utils.html.conditional_escape`` or not. - (In the latter case, we just use the identity function as the "escape" - function.) The ``conditional_escape()`` function is like ``escape()`` except - it only escapes input that is **not** a ``SafeData`` instance. If a - ``SafeData`` instance is passed to ``conditional_escape()``, the data is - returned unchanged. + (In the latter case, we use the identity function as the "escape" function.) + The ``conditional_escape()`` function is like ``escape()`` except it only + escapes input that is **not** a ``SafeData`` instance. If a ``SafeData`` + instance is passed to ``conditional_escape()``, the data is returned + unchanged. Finally, in the above example, we remember to mark the result as safe so that our HTML is inserted directly into the template without further @@ -428,7 +428,7 @@ A few things to note about the ``simple_tag`` helper function: * 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. * The quotes around the argument (if any) have already been stripped away, - so we just receive a plain string. + so we 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. @@ -539,7 +539,7 @@ for the template fragment. Example:: Next, create the template used to render the tag's output. This template is a fixed feature of the tag: the tag writer specifies it, not the template -designer. Following our example, the template is very simple: +designer. Following our example, the template is very short: .. code-block:: html+django @@ -645,10 +645,10 @@ the rendering works. When Django compiles a template, it splits the raw template text into ''nodes''. Each node is an instance of ``django.template.Node`` and has -a ``render()`` method. A compiled template is, simply, a list of ``Node`` -objects. When you call ``render()`` on a compiled template object, the template -calls ``render()`` on each ``Node`` in its node list, with the given context. -The results are all concatenated together to form the output of the template. +a ``render()`` method. A compiled template is a list of ``Node`` objects. When +you call ``render()`` on a compiled template object, the template calls +``render()`` on each ``Node`` in its node list, with the given context. The +results are all concatenated together to form the output of the template. Thus, to define a custom template tag, you specify how the raw template tag is converted into a ``Node`` (the compilation function), and what the node's @@ -661,7 +661,7 @@ For each template tag the template parser encounters, it calls a Python function with the tag contents and the parser object itself. This function is responsible for returning a ``Node`` instance based on the contents of the tag. -For example, let's write a full implementation of our simple template tag, +For example, let's write a full implementation of our template tag, ``{% current_time %}``, that displays the current date/time, formatted according to a parameter given in the tag, in :func:`~time.strftime` syntax. It's a good idea to decide the tag syntax before anything else. In our case, let's say the @@ -715,7 +715,7 @@ Notes: arguments. * The function returns a ``CurrentTimeNode`` with everything the node needs - to know about this tag. In this case, it just passes the argument -- + to know about this tag. In this case, it passes the argument -- ``"%Y-%m-%d %I:%M %p"``. The leading and trailing quotes from the template tag are removed in ``format_string[1:-1]``. @@ -853,7 +853,7 @@ the same time: The CycleNode is iterating, but it's iterating globally. As far as Thread 1 and Thread 2 are concerned, it's always returning the same value. This is -obviously not what we want! +not what we want! To address this problem, Django provides a ``render_context`` that's associated with the ``context`` of the template that is currently being rendered. The @@ -965,9 +965,8 @@ You also have to change the renderer to retrieve the actual contents of the ``date_updated`` property of the ``blog_entry`` object. This can be accomplished by using the ``Variable()`` class in ``django.template``. -To use the ``Variable`` class, simply instantiate it with the name of the -variable to be resolved, and then call ``variable.resolve(context)``. So, -for example:: +To use the ``Variable`` class, instantiate it with the name of the variable to +be resolved, and then call ``variable.resolve(context)``. So, for example:: class FormatTimeNode(template.Node): def __init__(self, date_to_be_formatted, format_string): @@ -987,11 +986,11 @@ cannot resolve the string passed to it in the current context of the page. Setting a variable in the context --------------------------------- -The above examples simply output a value. Generally, it's more flexible if your +The above examples output a value. Generally, it's more flexible if your template tags set template variables instead of outputting values. That way, template authors can reuse the values that your template tags create. -To set a variable in the context, just use dictionary assignment on the context +To set a variable in the context, use dictionary assignment on the context object in the ``render()`` method. Here's an updated version of ``CurrentTimeNode`` that sets a template variable ``current_time`` instead of outputting it:: @@ -1116,7 +1115,7 @@ After ``parser.parse()`` is called, the parser hasn't yet "consumed" the ``{% endcomment %}`` tag, so the code needs to explicitly call ``parser.delete_first_token()``. -``CommentNode.render()`` simply returns an empty string. Anything between +``CommentNode.render()`` returns an empty string. Anything between ``{% comment %}`` and ``{% endcomment %}`` is ignored. Parsing until another block tag, and saving contents |