From fefcbbfe3719eaf0b493eabaab591c0b7bc35d9e Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Sat, 10 Feb 2007 08:29:34 +0000 Subject: [PATCH] Fixed #2655 -- added documentation about resolve_variable() for custom template tags. Thanks dave@thebarproject.com. git-svn-id: http://code.djangoproject.com/svn/django/trunk@4477 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- AUTHORS | 1 + docs/templates_python.txt | 64 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/AUTHORS b/AUTHORS index 3024221103..4538512c06 100644 --- a/AUTHORS +++ b/AUTHORS @@ -66,6 +66,7 @@ answer newbie questions, and generally made Django that much better: Matt Croydon dackze+django@gmail.com Jonathan Daugherty (cygnus) + dave@thebarproject.com Jason Davies (Esaj) Alex Dedul deric@monowerks.com diff --git a/docs/templates_python.txt b/docs/templates_python.txt index 5f9c5bde43..3d6bfd7040 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -801,6 +801,70 @@ Python 2.4 and above:: If you leave off the ``name`` argument, as in the second example above, Django will use the function's name as the tag name. +Passing template variables to the tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although you can pass any number of arguments to a template tag using +``token.split_contents()``, the arguments are all unpacked as +string literals. A little more work is required in order to dynamic content (a +template variable) to a template tag as an argument. + +While the previous examples have formatted the current time into a string and +returned the string, suppose you wanted to pass in a ``DateTimeField`` from an +object and have the template tag format that date-time:: + +

This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.

+ +Initially, ``token.split_contents()`` will return three values: + + 1. The tag name ``format_time``. + 2. The string "blog_entry.date_updated" (without the surrounding quotes). + 3. The formatting string "%Y-%m-%d %I:%M %p". The return value from + ``split_contents()`` will include the leading and trailing quotes for + string literals like this. + +Now your tag should begin to look like this:: + + from django import template + def do_format_time(parser, token): + try: + # split_contents() knows not to split quoted strings. + tag_name, date_to_format, format_string = token.split_contents() + except ValueError: + raise template.TemplateSyntaxError, "%r tag requires exactly two arguments" % token.contents[0] + if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")): + raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name + return FormatTimeNode(date_to_format, format_string[1:-1]) + +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 ``resolve_variable()`` function in +``django.template``. You pass ``resolve_variable()`` the variable name and the +current context, available in the ``render`` method:: + + from django import template + from django.template import resolve_variable + import datetime + class FormatTimeNode(template.Node): + def __init__(self, date_to_format, format_string): + self.date_to_format = date_to_format + self.format_string = format_string + + def render(self, context): + try: + actual_date = resolve_variable(self.date_to_format, context) + return actual_date.strftime(self.format_string) + except VariableDoesNotExist: + return '' + +``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then +format it accordingly. + +.. note:: + The ``resolve_variable()`` function will throw a ``VariableDoesNotExist`` + exception if it cannot resolve the string passed to it in the current + context of the page. + Shortcut for simple tags ~~~~~~~~~~~~~~~~~~~~~~~~