Browse files

[1.7.x] Fixed #17719 -- Documented that template syntax sequences can…

…not be used as string literals.

Backport of e02f45d from master
  • Loading branch information...
1 parent 808722e commit 34116ad71c5f934fc2702c32a8cd743f36a85479 @timgraham timgraham committed Aug 26, 2014
Showing with 25 additions and 0 deletions.
  1. +25 −0 docs/ref/templates/api.txt
@@ -274,6 +274,31 @@ Builtin variables
Every context contains ``True``, ``False`` and ``None``. As you would expect,
these variables resolve to the corresponding Python objects.
+Limitations with string literals
+Django's template language has no way to escape the characters used for its own
+syntax. For example, the :ttag:`templatetag` tag is required if you need to
+output character sequences like ``{%`` and ``%}``.
+A similar issue exists if you want to include these sequences in template filter
+or tag arguments. For example, when parsing a block tag, Django's template
+parser looks for the first occurrence of ``%}`` after a ``{%``. This prevents
+the use of ``"%}"`` as a string literal. For example, a ``TemplateSyntaxError``
+will be raised for the following expressions::
+ {% include "template.html" tvar="Some string literal with %} in it." %}
+ {% with tvar="Some string literal with %} in it." %}{% endwith %}
+The same issue can be triggered by using a reserved sequence in filter
+ {{ some.variable|default:"}}" }}
+If you need to use strings with these sequences, store them in template
+variables or use a custom template tag or filter to workaround the limitation.
Playing with Context objects

0 comments on commit 34116ad

Please sign in to comment.