Ticket #12199: firstof_as.diff

django/template/defaulttags.py

@@ -86 +86 @@
         return filtered
 
 class FirstOfNode(Node):
-    def __init__(self, vars):
+    def __init__(self, vars, variable_name=None):
         self.vars = vars
+        self.variable_name = variable_name
 
     def render(self, context):
         for var in self.vars:
             value = var.resolve(context, True)
             if value:
-                return smart_unicode(value)
+                if self.variable_name:
+                    context[self.variable_name] = value
+                    break
+                else:
+                    return smart_unicode(value)
         return u''
 
 class ForNode(Node):
@@ -614 +619 @@
 
         {% filter force_escape %}
             {% firstof var1 var2 var3 "fallback value" %}
-        {% endfilter %}
+        {% endfilter %}
 
+    If you need to preserve the result instead of printing it to the output,
+    you may leverage the familiar Python keyword ``as``::
+
+        {% firstof substitute teacher as teacher_for_today %}
+
+    Consider the following template code, which would prove unreliable if not
+    using the ``as`` syntax::
+
+        Today the teacher is {% firstof substitute.name teacher.name %},
+        and drives a {% firstof substitute.car teacher.car %}
+
+    If ``substitute`` doesn't have a car, the second tag would give incorrect
+    information about what ``substitute`` drives.  Use the ``as`` syntax when
+    multiple fields should be tested on the single dominant object of a
+    ``{% firstof %}`` usage.
+
     """
     bits = token.split_contents()[1:]
+    variable_name = None
+    expecting_save_as = bits[-2] == 'as'
+    if expecting_save_as:
+        variable_name = bits.pop(-1)
+        bits = bits[:-1]
     if len(bits) < 1:
         raise TemplateSyntaxError("'firstof' statement requires at least one"
                                   " argument")
-    return FirstOfNode([parser.compile_filter(bit) for bit in bits])
+    return FirstOfNode([parser.compile_filter(bit) for bit in bits], variable_name)
 firstof = register.tag(firstof)
 
 #@register.tag(name="for")

docs/ref/templates/builtins.txt

@@ -209 +209 @@
         {% firstof var1 var2 var3 "fallback value" %}
     {% endfilter %}
 
+.. versionchanged:: 1.2
+
+If you need to preserve the result instead of printing it to the output,
+you may leverage the familiar Python keyword ``as``::
+
+    {% firstof substitute teacher as teacher_for_today %}
+
+Consider the following template code, which would prove unreliable if not
+using the ``as`` syntax::
+
+    Today the teacher is {% firstof substitute.name teacher.name %},
+    and drives a {% firstof substitute.car teacher.car %}
+
+If ``substitute`` doesn't have a car, the second tag would give incorrect
+information about what ``substitute`` drives.  Use the ``as`` syntax when
+multiple fields should be tested on the single dominant object of a
+``{% firstof %}`` usage.
+
 .. templatetag:: for
 
 for