Ticket #2655: resolve_variable_docspatch.diff

File resolve_variable_docspatch.diff, 3.3 KB (added by dave@…, 18 years ago)

Documentation patch to docs/template_python.txt

  • docs/templates_python.txt

     
    750750If you leave off the ``name`` argument, as in the second example above, Django
    751751will use the function's name as the tag name.
    752752
     753Passing object values to the tag using 'resolve_variable'
     754~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     755
     756Although you can pass any number of arguments to a template tag using ``token.split_contents()``
     757to unpack the arguments as illustrated above, ``token.split_contents()`` only unpacks the arguments
     758sent to the tag as string literals.  This makes it difficult to pass dynamic content to a template tag
     759as an argument.  While the previous examples have formatted the current time into a string and returned
     760the string, suppose you wanted to pass in a ``DateTimeField`` from an object and have the template tag
     761format that date-time::
     762
     763    <p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>
     764
     765Initially, ``token.split_contents()`` will return three values:
     766
     767    1. The tag name ``format_time``
     768    2. The string "blog_entry.date_updated", NOT the contents of the ``date_updated`` property
     769       of the ``blog_entry`` object
     770    3. The formatting string "%Y-%m-%d %I:%M %p"
     771
     772Now our tag should begin to look like this::
     773
     774    from django import template
     775    def do_format_time(parser, token):
     776        try:
     777            # split_contents() knows not to split quoted strings.
     778            tag_name, date_to_format, format_string = token.split_contents()
     779        except ValueError:
     780            raise template.TemplateSyntaxError, "%r tag requires exactly two arguments" % token.contents[0]
     781        if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
     782            raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name
     783        return FormatTimeNode(date_to_format, format_string[1:-1])
     784
     785Next we have to change the renderer to format the actual contents of the ``date_updated`` property
     786of the ``blog_entry`` object, not the string literal "blog_entry.date_updated" which will throw an
     787exception.  This can be accomplished by using the ``resolve_variable`` function in
     788``django.template``.  We have to pass ``resolve_variable`` both the variable name as well as the
     789current context, available in the ``render`` method::
     790
     791    from django import template
     792    from django.template import resolve_variable
     793    import datetime
     794    class FormatTimeNode(template.Node):
     795        def __init__(self, date_to_format, format_string):
     796            self.date_to_format = date_to_format
     797            self.format_string = format_string
     798        def render(self, context):
     799            try:
     800                actual_date = resolve_variable(date_to_format, context)
     801                return actual_date.strftime(self.format_string)
     802            except VariableDoesNotExist:
     803                return ''
     804
     805``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then format it
     806accordingly.
     807
     808Notes:
     809
     810    * ``resolve_variable`` will throw a ``VariableDoesNotExist`` exception if it cannot
     811      resolve the string passed to it in the current context of the page.
     812
    753813Shortcut for simple tags
    754814~~~~~~~~~~~~~~~~~~~~~~~~
    755815
Back to Top