yaffs.net Git - yaffs-website/blob - 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     {% autoescape %}
  10         Everything will be automatically escaped in this block
  11         using the HTML strategy
  12     {% endautoescape %}
  13
  14     {% autoescape 'html' %}
  15         Everything will be automatically escaped in this block
  16         using the HTML strategy
  17     {% endautoescape %}
  18
  19     {% autoescape 'js' %}
  20         Everything will be automatically escaped in this block
  21         using the js escaping strategy
  22     {% endautoescape %}
  23
  24     {% autoescape false %}
  25         Everything will be outputted as is in this block
  26     {% endautoescape %}
  27
  28 .. note::
  29
  30     Before Twig 1.8, the syntax was different:
  31
  32     .. code-block:: jinja
  33
  34         {% autoescape true %}
  35             Everything will be automatically escaped in this block
  36             using the HTML strategy
  37         {% endautoescape %}
  38
  39         {% autoescape false %}
  40             Everything will be outputted as is in this block
  41         {% endautoescape %}
  42
  43         {% autoescape true js %}
  44             Everything will be automatically escaped in this block
  45             using the js escaping strategy
  46         {% endautoescape %}
  47
  48 When automatic escaping is enabled everything is escaped by default except for
  49 values explicitly marked as safe. Those can be marked in the template by using
  50 the :doc:`raw<../filters/raw>` filter:
  51
  52 .. code-block:: jinja
  53
  54     {% autoescape %}
  55         {{ safe_value|raw }}
  56     {% endautoescape %}
  57
  58 Functions returning template data (like :doc:`macros<macro>` and
  59 :doc:`parent<../functions/parent>`) always return safe markup.
  60
  61 .. note::
  62
  63     Twig is smart enough to not escape an already escaped value by the
  64     :doc:`escape<../filters/escape>` filter.
  65
  66 .. note::
  67
  68     Twig does not escape static expressions:
  69
  70     .. code-block:: jinja
  71
  72         {% set hello = "<strong>Hello</strong>" %}
  73         {{ hello }}
  74         {{ "<strong>world</strong>" }}
  75
  76     Will be rendered "<strong>Hello</strong> **world**".
  77
  78 .. note::
  79
  80     The chapter :doc:`Twig for Developers<../api>` gives more information
  81     about when and how automatic escaping is applied.