vendor/twig/twig/doc/tags/autoescape.rst

   1 ``autoescape``
   2 ==============
   3
   4 Whether automatic escaping is enabled or not, you can mark a section of a
   5 template to be escaped or not by using the ``autoescape`` tag:
   6
   7 .. code-block:: jinja
   8
   9     {# The following syntax works as of Twig 1.8 -- see the note below for previous versions #}
  10
  11     {% autoescape %}
  12         Everything will be automatically escaped in this block
  13         using the HTML strategy
  14     {% endautoescape %}
  15
  16     {% autoescape 'html' %}
  17         Everything will be automatically escaped in this block
  18         using the HTML strategy
  19     {% endautoescape %}
  20
  21     {% autoescape 'js' %}
  22         Everything will be automatically escaped in this block
  23         using the js escaping strategy
  24     {% endautoescape %}
  25
  26     {% autoescape false %}
  27         Everything will be outputted as is in this block
  28     {% endautoescape %}
  29
  30 .. note::
  31
  32     Before Twig 1.8, the syntax was different:
  33
  34     .. code-block:: jinja
  35
  36         {% autoescape true %}
  37             Everything will be automatically escaped in this block
  38             using the HTML strategy
  39         {% endautoescape %}
  40
  41         {% autoescape false %}
  42             Everything will be outputted as is in this block
  43         {% endautoescape %}
  44
  45         {% autoescape true js %}
  46             Everything will be automatically escaped in this block
  47             using the js escaping strategy
  48         {% endautoescape %}
  49
  50 When automatic escaping is enabled everything is escaped by default except for
  51 values explicitly marked as safe. Those can be marked in the template by using
  52 the :doc:`raw<../filters/raw>` filter:
  53
  54 .. code-block:: jinja
  55
  56     {% autoescape %}
  57         {{ safe_value|raw }}
  58     {% endautoescape %}
  59
  60 Functions returning template data (like :doc:`macros<macro>` and
  61 :doc:`parent<../functions/parent>`) always return safe markup.
  62
  63 .. note::
  64
  65     Twig is smart enough to not escape an already escaped value by the
  66     :doc:`escape<../filters/escape>` filter.
  67
  68 .. note::
  69
  70     The chapter :doc:`Twig for Developers<../api>` gives more information
  71     about when and how automatic escaping is applied.