Browse files

Fixed #17719 -- Documented that template syntax sequences cannot be u…

…sed as string literals.
  • Loading branch information...
1 parent 035f2e6 commit e02f45d5ea767b0028ecf24bb5874992eb3ca7dd @timgraham timgraham committed Aug 26, 2014
Showing with 25 additions and 0 deletions.
  1. +25 −0 docs/ref/templates/api.txt
View
25 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
+arguments::
+
+ {{ 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 e02f45d

Please sign in to comment.