Ticket #15057: 15057-template-variable-lookups-r15173.diff

File 15057-template-variable-lookups-r15173.diff, 5.4 KB (added by Tai Lee, 14 years ago)
  • docs/intro/tutorial03.txt

     
    415415
    416416The template system uses dot-lookup syntax to access variable attributes. In
    417417the example of ``{{ poll.question }}``, first Django does a dictionary lookup
    418 on the object ``poll``. Failing that, it tries attribute lookup -- which works,
    419 in this case. If attribute lookup had failed, it would've tried calling the
    420 method ``question()`` on the poll object.
     418on the object ``poll``. Failing that, it tries an attribute lookup -- which
     419works, in this case. If attribute lookup had failed, it would've tried a
     420list-index lookup.
    421421
    422422Method-calling happens in the ``{% for %}`` loop: ``poll.choice_set.all`` is
    423423interpreted as the Python code ``poll.choice_set.all()``, which returns an
  • docs/ref/templates/api.txt

     
    115115or a dot.
    116116
    117117Dots have a special meaning in template rendering. A dot in a variable name
    118 signifies **lookup**. Specifically, when the template system encounters a dot
    119 in a variable name, it tries the following lookups, in this order:
     118signifies a **lookup**. Specifically, when the template system encounters a
     119dot in a variable name, it tries the following lookups, in this order:
    120120
    121121    * Dictionary lookup. Example: ``foo["bar"]``
    122122    * Attribute lookup. Example: ``foo.bar``
    123     * Method call. Example: ``foo.bar()``
    124123    * List-index lookup. Example: ``foo[bar]``
    125124
    126125The template system uses the first lookup type that works. It's short-circuit
    127 logic.
     126logic. Here are a few examples::
    128127
    129 Here are a few examples::
    130 
    131128    >>> from django.template import Context, Template
    132129    >>> t = Template("My name is {{ person.first_name }}.")
    133130    >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
     
    141138    >>> t.render(Context({"person": p}))
    142139    "My name is Ron."
    143140
    144     >>> class PersonClass2:
    145     ...     def first_name(self):
    146     ...         return "Samantha"
    147     >>> p = PersonClass2()
    148     >>> t.render(Context({"person": p}))
    149     "My name is Samantha."
    150 
    151141    >>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
    152142    >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
    153143    >>> t.render(c)
    154144    "The first stooge in the list is Larry."
    155145
    156 Method lookups are slightly more complex than the other lookup types. Here are
    157 some things to keep in mind:
     146If any part of the variable is callable, the template system will try calling
     147it. Example::
    158148
    159     * If, during the method lookup, a method raises an exception, the exception
    160       will be propagated, unless the exception has an attribute
     149    >>> class PersonClass2:
     150    ...     def name(self):
     151    ...         return "Samantha"
     152    >>> t = Template("My name is {{ person.name }}.")
     153    >>> t.render(Context({"person": PersonClass2}))
     154    "My name is Samantha."
     155
     156.. versionchanged:: 1.3
     157    Previously, only variables that originated with an attribute lookup would
     158    be called by the template system. This change was made for consistency
     159    across lookup types.
     160
     161Callable variables are slightly more complex than variables which only require
     162straight lookups. Here are some things to keep in mind:
     163
     164    * If the variable raises an exception when called, the exception will be
     165      propagated, unless the exception has an attribute
    161166      ``silent_variable_failure`` whose value is ``True``. If the exception
    162       *does* have a ``silent_variable_failure`` attribute, the variable will
    163       render as an empty string. Example::
     167      *does* have a ``silent_variable_failure`` attribute whose value is
     168      ``True``, the variable will render as an empty string. Example::
    164169
    165170        >>> t = Template("My name is {{ person.first_name }}.")
    166171        >>> class PersonClass3:
     
    187192      with Django model objects, any ``DoesNotExist`` exception will fail
    188193      silently.
    189194
    190     * A method call will only work if the method has no required arguments.
    191       Otherwise, the system will move to the next lookup type (list-index
    192       lookup).
     195    * A variable can only be called if it has no required arguments. Otherwise,
     196      the system will return an empty string.
    193197
    194     * Obviously, some methods have side effects, and it'd be either foolish or
    195       a security hole to allow the template system to access them.
     198    * Obviously, there can be side effects when calling some variables, and
     199      it'd be either foolish or a security hole to allow the template system
     200      to access them.
    196201
    197202      A good example is the :meth:`~django.db.models.Model.delete` method on
    198203      each Django model object. The template system shouldn't be allowed to do
     
    200205
    201206        I will now delete this valuable data. {{ data.delete }}
    202207
    203       To prevent this, set a function attribute ``alters_data`` on the method.
    204       The template system won't execute a method if the method has
     208      To prevent this, set an ``alters_data`` attribute on the callable
     209      variable. The template system won't call a variable if it has
    205210      ``alters_data=True`` set. The dynamically-generated
    206211      :meth:`~django.db.models.Model.delete` and
    207212      :meth:`~django.db.models.Model.save` methods on Django model objects get
Back to Top