[1.4.x] Fixed #13608 - Noted that template lookups use literal values.

Backport of 74c025d0285450bf277afbee095172af54562ab6 from master.

2 files changed, 20 insertions, 0 deletions

diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 1955bd4ead..aa386254aa 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -122,6 +122,10 @@ dot in a variable name, it tries the following lookups, in this order:
 * Attribute lookup. Example: ``foo.bar``
 * List-index lookup. Example: ``foo[bar]``
 
+Note that "bar" in a template expression like ``{{ foo.bar }}`` will be
+interpreted as a literal string and not using the value of the variable "bar",
+if one exists in the template context.
+
 The template system uses the first lookup type that works. It's short-circuit
 logic. Here are a few examples::
 
diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 17e5d6944e..5f6c563312 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -97,6 +97,18 @@ Use a dot (``.``) to access attributes of a variable.
     * Method call
     * List-index lookup
 
+    This can cause some unexpected behavior with objects that override
+    dictionary lookup. For example, consider the following code snippet that
+    attempts to loop over a ``collections.defaultdict``::
+
+        {% for k, v in defaultdict.iteritems %}
+            Do something with k and v here...
+        {% endfor %}
+
+    Because dictionary lookup happens first, that behavior kicks in and provides
+    a default value instead of using the intended ``.iteritems()``
+    method. In this case, consider converting to a dictionary first.
+
 In the above example, ``{{ section.title }}`` will be replaced with the
 ``title`` attribute of the ``section`` object.
 
@@ -104,6 +116,10 @@ If you use a variable that doesn't exist, the template system will insert
 the value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set
 to ``''`` (the empty string) by default.
 
+Note that "bar" in a template expression like ``{{ foo.bar }}`` will be
+interpreted as a literal string and not using the value of the variable "bar",
+if one exists in the template context.
+
 Filters
 =======