              Auto-escaping applies again, {{ name }}
          {% endautoescape %}
      {% endautoescape %}
  
  For individual variables, the ``safe`` filter can also be used to indicate
  that the contents should not be automatically escaped::
  
      This will be escaped: {{ data }}
      This will not be escaped: {{ data|safe }}
  
  Think of *safe* as shorthand for *safe from further escaping* or *can be
 
</s> remove             Auto-escaping applies again, {{ name }}
 </s> add             Auto-escaping applies again: {{ name }} </s> remove     This will be escaped: {{ data }}
    This will not be escaped: {{ data|safe }}
 </s> add     # base.html </s> remove Think of *safe* as shorthand for *safe from further escaping* or *can be
safely interpreted as HTML*. In this example, if ``data`` contains ``'<a>'``,
the output will be::
 </s> add     {% autoescape off %}
    <h1>{% block title %}</h1>
    {% block content %}
    {% endautoescape %}


    # child.html

    {% extends "base.html" %}
    {% block title %}This & that{% endblock %}
    {% block content %}<b>Hello!</b>{% endblock %}

Because auto-escaping is turned off in the base template, it will also be
turned off in the child template, resulting in the following rendered HTML::

    <h1>This & that</h1>
    <b>Hello!</b>

Notes
-----

Generally, template authors don't need to worry about auto-escaping very much.
Developers on the Python side (people writing views and custom filters) need to
think about the cases in which data shouldn't be escaped, and mark data
appropriately, so things Just Work in the template. </s> remove this would always display a Javascript alert box when the page was loaded.
Similarly, if you were displaying some data generated by another process and it
contained a '<' symbol, you couldn't just dump this straight into your HTML,
because it would be treated as the start of an element. The effects of these
sorts of problems can vary from merely annoying to allowing exploits via `Cross
Site Scripting`_ (XSS) attacks.

.. _Cross Site Scripting: http://en.wikipedia.org/wiki/Cross-site_scripting

In order to provide some protection against these problems, Django
provides automatic (but controllable) HTML escaping for data coming from
tempate variables. Inside this tag, any data that comes from template
variables is examined to see if it contains one of the five HTML characters
(<, >, ', " and &) that often need escaping and those characters are converted
to their respective HTML entities. It causes no harm if a character is
converted to an entity when it doesn't need to be, so all five characters are
always converted.

Since some variables will contain data that is *intended* to be rendered
as HTML, template tag and filter writers can mark their output strings as
requiring no further escaping. For example, the ``unordered_list`` filter is
designed to return raw HTML and we want the template processor to simply
display the results as returned, without applying any escaping. That is taken
care of by the filter. The template author need do nothing special in that
case.

By default, automatic HTML escaping is always applied. However, sometimes you
will not want this to occur (for example, if you're using the templating
system to create an email). To control automatic escaping inside your template,
wrap the affected content in the ``autoescape`` tag, like so::
 </s> add With this name value, the template would be rendered as::

    Hello, <script>alert('hello')</script>

...which means the browser would pop-up a JavaScript alert box!

Similarly, what if the name contained a ``'<'`` symbol, like this?

    <b>username

That would result in a rendered template like this::

    Hello, <b>username

...which, in turn, would result in the remainder of the Web page being bolded!

Clearly, user-submitted data shouldn't be trusted blindly and inserted directly
into your Web pages, because a malicious user could use this kind of hole to
do potentially bad things. This type of security exploit is called a
Cross Site Scripting`_ (XSS) attack.

To avoid this problem, you have two options:

    * One, you can make sure to run each untrusted variable through the
      ``escape`` filter (documented below), which converts potentially harmful
      HTML characters to unharmful ones. This was default the default solution
      in Django for its first few years, but the problem is that it puts the
      onus on *you*, the developer / template author, to ensure you're escaping
      everything. It's easy to forget to escape data.

    * Two, you can take advantage of Django's automatic HTML escaping. The
      remainder of this section describes how auto-escaping works.

By default in the Django development version, every template automatically
escapes the output of every variable tag. Specifically, these five characters
are escaped:

    * ``<`` is converted to ``&lt;``
    * ``>`` is converted to ``&gt;``
    * ``'`` (single quote) is converted to ``&#39;``
    * ``"`` (double quote) is converted to ``&quot;``
    * ``&`` is converted to ``&amp;``

Again, we stress that this behavior is on by default. If you're using Django's
template system, you're protected.

How to turn it off
------------------

If you don't want data to be auto-escaped, on a per-site, per-template level or
per-variable level, you can turn it off in several ways.

Why would you want to turn it off? Because sometimes, template variables
contain data that you *intend* to be rendered as raw HTML, in which case you
don't want their contents to be escaped. For example, you might store a blob of
HTML in your database and want to embed that directly into your template. Or,
you might be using Django's template system to produce text that is *not* HTML
-- like an e-mail message, for instance.

For individual variables
~~~~~~~~~~~~~~~~~~~~~~~~

To disable auto-escaping for an individual variable, use the ``safe`` filter::

    This will be escaped: {{ data }}
    This will not be escaped: {{ data|safe }}

Think of *safe* as shorthand for *safe from further escaping* or *can be
safely interpreted as HTML*. In this example, if ``data`` contains ``'<b>'``,
the output will be::

    This will be escaped: &lt;b&gt;
    This will not be escaped: <b>

For template blocks
~~~~~~~~~~~~~~~~~~~

To control auto-escaping for a template, wrap the template (or just a
particular section of the template) in the ``autoescape`` tag, like so:: </s> remove The auto-escaping tag passes its effect onto templates that extend the
current one as well as templates included via the ``include`` tag, just like
all block tags.

The ``autoescape`` tag takes either ``on`` or ``off`` as its argument. At times, you might want to force auto-escaping when it would otherwise be disabled. For example::
 </s> add The ``autoescape`` tag takes either ``on`` or ``off`` as its argument. At
times, you might want to force auto-escaping when it would otherwise be
disabled. Here is an example template::
The auto-escaping tag passes its effect onto templates that extend the
current one as well as templates included via the ``include`` tag, just like
all block tags. For example::
              Auto-escaping applies again, {{ name }}
          {% endautoescape %}
      {% endautoescape %}
  
The auto-escaping tag passes its effect onto templates that extend the
current one as well as templates included via the ``include`` tag, just like
all block tags. For example::
The auto-escaping tag passes its effect onto templates that extend the
current one as well as templates included via the ``include`` tag, just like
all block tags. For example::
  
      This will be escaped: {{ data }}
      This will not be escaped: {{ data|safe }}
  
  Think of *safe* as shorthand for *safe from further escaping* or *can be
keep keep keep keep replace replace keep keep keep keep keep
 Edited templates.txt and templates_python.txt auto-escaping changes from [6671]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6798 bcc190cf-cafb-0310-a4f2-bffc1f526a37 
docs/templates.txt