diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/custom-template-tags.txt | 56 | ||||
| -rw-r--r-- | docs/internals/deprecation.txt | 2 | ||||
| -rw-r--r-- | docs/releases/1.9.txt | 13 |
3 files changed, 34 insertions, 37 deletions
diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index b13c8cb81a..e4fe6949ea 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -388,7 +388,7 @@ Simple tags .. method:: django.template.Library.simple_tag() Many template tags take a number of arguments -- strings or template variables --- and return a string after doing some processing based solely on +-- and return a result after doing some processing based solely on the input arguments and some external information. For example, a ``current_time`` tag might accept a format string and return the time as a string formatted accordingly. @@ -459,6 +459,18 @@ positional arguments. For example: {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %} +.. versionadded:: 1.9 + +It's possible to store the tag results in a template variable rather than +directly outputting it. This is done by using the ``as`` argument followed by +the variable name. Doing so enables you to output the content yourself where +you see fit: + +.. code-block:: html+django + + {% get_current_time "%Y-%m-%d %I:%M %p" as the_time %} + <p>The time is {{ the_time }}.</p> + .. _howto-custom-template-tags-inclusion-tags: Inclusion tags @@ -602,11 +614,15 @@ Assignment tags .. method:: django.template.Library.assignment_tag() +.. deprecated:: 1.9 + + ``simple_tag`` can now store results in a template variable and should + be used instead. + To ease the creation of tags setting a variable in the context, Django provides a helper function, ``assignment_tag``. This function works the same way as -:ref:`simple_tag<howto-custom-template-tags-simple-tags>`, except that it -stores the tag's result in a specified context variable instead of directly -outputting it. +:meth:`~django.template.Library.simple_tag` except that it stores the tag's +result in a specified context variable instead of directly outputting it. Our earlier ``current_time`` function could thus be written like this:: @@ -622,38 +638,6 @@ followed by the variable name, and output it yourself where you see fit: {% get_current_time "%Y-%m-%d %I:%M %p" as the_time %} <p>The time is {{ the_time }}.</p> -If your template tag needs to access the current context, you can use the -``takes_context`` argument when registering your tag:: - - @register.assignment_tag(takes_context=True) - def get_current_time(context, format_string): - timezone = context['timezone'] - return your_get_current_time_method(timezone, format_string) - -Note that the first parameter to the function *must* be called ``context``. - -For more information on how the ``takes_context`` option works, see the section -on :ref:`inclusion tags<howto-custom-template-tags-inclusion-tags>`. - -``assignment_tag`` functions may accept any number of positional or keyword -arguments. For example:: - - @register.assignment_tag - def my_tag(a, b, *args, **kwargs): - warning = kwargs['warning'] - profile = kwargs['profile'] - ... - return ... - -Then in the template any number of arguments, separated by spaces, may be -passed to the template tag. Like in Python, the values for keyword arguments -are set using the equal sign ("``=``") and must be provided after the -positional arguments. For example: - -.. code-block:: html+django - - {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile as the_result %} - Advanced custom template tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 50782b363c..66477109ec 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -20,6 +20,8 @@ details on these changes. * The ``django.forms.extras`` package will be removed. +* The ``assignment_tag`` helper will be removed. + .. _deprecation-removed-in-2.0: 2.0 diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt index 8c7aff8fe1..db9b6c324d 100644 --- a/docs/releases/1.9.txt +++ b/docs/releases/1.9.txt @@ -137,7 +137,9 @@ Signals Templates ^^^^^^^^^ -* ... +* Template tags created with the :meth:`~django.template.Library.simple_tag` + helper can now store results in a template variable by using the ``as`` + argument. Requests and Responses ^^^^^^^^^^^^^^^^^^^^^^ @@ -194,6 +196,15 @@ Miscellaneous Features deprecated in 1.9 ========================== +``assignment_tag()`` +~~~~~~~~~~~~~~~~~~~~ + +Django 1.4 added the ``assignment_tag`` helper to ease the creation of +template tags that store results in a template variable. The +:meth:`~django.template.Library.simple_tag` helper has gained this same +ability, making the ``assignment_tag`` obsolete. Tags that use +``assignment_tag`` should be updated to use ``simple_tag``. + Miscellaneous ~~~~~~~~~~~~~ |