Document that template syntax sequences cannot be used as string literals

[development@…]

Django template parsing (Lexer) looks for the first occurrence of %} after a {% when determining what a block tag is. This prevents the use of "%}" as a string literal. So a template syntax error will be raised for the following valid expressions:

  {% include "template.html" tvar="Some string literal with %} in it." %}
  {% with tvar="Some string literal with %} in it." %}{% endwith %}

This is also true for variable tag parsing. Example:

  {{ some.variable|default:"}}" }}

If this is expected/intended behavior, it doesn't appear to be documented anywhere.

The actual fix doesn't look trivial, but shouldn't be too bad. I could help with a fix if there's interest in that.

[Łukasz Rekucki]

I don't think it's possible to fix this without either an API change or adding some escape sequence (which could also be backwards incompatible). There is one place this is documented: ​https://docs.djangoproject.com/en/dev/ref/templates/builtins/#templatetag. It doesn't explicitly mention string literals, but OTOH there is no strict concept of string literals in the docs. Maybe add a section about them ​here, between Variables and Filters. This could also include this edge case.

[Glenn Washburn <development@…>]

Replying to lrekucki:

I don't think it's possible to fix this without either an API change or adding some escape sequence (which could also be backwards incompatible). There is one place this is documented: ​https://docs.djangoproject.com/en/dev/ref/templates/builtins/#templatetag. It doesn't explicitly mention string literals, but OTOH there is no strict concept of string literals in the docs. Maybe add a section about them ​here, between Variables and Filters. This could also include this edge case.

The documentation for templatetag states: "to display one of the bits used in template tags". This is definitely misleading if its supposed to cover this issue because the string literal need not be displayed anywhere. It could for instance just be a string literal passed to a custom template tag for other purposes.

Thinking about it more, its worse than I thought. You're right, the fix would need to be pretty drastic. The crux of the issue is that Lexer (and Parser) doesn't know about string literals. But because tag contents can be anything, the Lexer wouldn't know how to parse them. I think the best solution is a documentation update for now.

[Tim Graham <timograham@…>]

In e02f45d5ea767b0028ecf24bb5874992eb3ca7dd:

Fixed #17719 -- Documented that template syntax sequences cannot be used as string literals.

[Tim Graham <timograham@…>]

In 34116ad71c5f934fc2702c32a8cd743f36a85479:

[1.7.x] Fixed #17719 -- Documented that template syntax sequences cannot be used as string literals.

Backport of e02f45d5ea from master