Permalink
Browse files

Edited templates.txt and templates_python.txt auto-escaping changes f…

…rom [6671]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6798 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent cf21274 commit 4a3084f3fca7732ab6ac9a5dea9006b413e7489a @adrianholovaty adrianholovaty committed Dec 1, 2007
Showing with 272 additions and 209 deletions.
  1. +133 −79 docs/templates.txt
  2. +139 −130 docs/templates_python.txt
View
@@ -310,58 +310,104 @@ Automatic HTML escaping
**New in Django development version**
-A very real problem when creating HTML (and other) output using templates and
-variable substitution is the possibility of accidently inserting some variable
-value that affects the resulting HTML. For example, a template fragment such as
-::
+When generating HTML from templates, there's always a risk that a variable will
+include characters that affect the resulting HTML. For example, consider this
+template fragment::
Hello, {{ name }}.
-seems like a harmless way to display the user's name. However, if you are
-displaying data that the user entered directly and they had entered their name as ::
+At first, this seems like a harmless way to display a user's name, but consider
+what would happen if the user entered his name as this::
<script>alert('hello')</script>
-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::
+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::
{% autoescape off %}
Hello {{ name }}
{% 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.
-
-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::
+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::
Auto-escaping is on by default. Hello {{ name }}
@@ -370,52 +416,60 @@ The ``autoescape`` tag takes either ``on`` or ``off`` as its argument. At times,
Nor this: {{ other_data }}
{% autoescape on %}
- Auto-escaping applies again, {{ name }}
+ 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::
+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 }}
+ # base.html
-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::
+ {% 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.
- This will be escaped: &lt;a&gt;
- This will not be escaped: <a>
-
-Generally, you won't need to worry about auto-escaping very much. View
-developers and custom filter authors need to think about when their data
-shouldn't be escaped and mark it appropriately. They are in a better position
-to know when that should happen than the template author, so it is their
-responsibility. By default, all output is escaped unless the template
-processor is explicitly told otherwise.
-
-You should also note that if you are trying to write a template that might be
-used in situations where automatic escaping is enabled or disabled and you
-don't know which (such as when your template is included in other templates),
-you can safely write as if you were in an ``{% autoescape off %}`` situation.
-Scatter ``escape`` filters around for any variables that need escaping. When
-auto-escaping is on, these extra filters won't change the output -- any
-variables that use the ``escape`` filter do not have further automatic
-escaping applied to them.
+If you're creating a template that might be used in situations where you're
+not sure whether auto-escaping is enabled, then add an ``escape`` filter to any
+variable that needs escaping. When auto-escaping is on, there's no danger of
+the ``escape`` filter *double-escaping* data -- the ``escape`` filter does not
+affect auto-escaped variables.
String literals and automatic escaping
--------------------------------------
-Sometimes you will pass a string literal as an argument to a filter. For
-example::
+As we mentioned earlier, filter arguments can be strings::
{{ data|default:"This is a string literal." }}
All string literals are inserted **without** any automatic escaping into the
-template, if they are used (it's as if they were all passed through the
-``safe`` filter). The reasoning behind this is that the template author is in
-control of what goes into the string literal, so they can make sure the text
-is correctly escaped when the template is written.
+template -- they act as if they were all passed through the ``safe`` filter.
+The reasoning behind this is that the template author is in control of what
+goes into the string literal, so they can make sure the text is correctly
+escaped when the template is written.
This means you would write ::
@@ -426,7 +480,7 @@ This means you would write ::
{{ data|default:"3 > 2" }} <-- Bad! Don't do this.
This doesn't affect what happens to data coming from the variable itself.
-The variable's contents are still automatically escaped, if necessary, since
+The variable's contents are still automatically escaped, if necessary, because
they're beyond the control of the template author.
Using the built-in reference
@@ -1230,11 +1284,11 @@ once, after all other filters).
Escapes a string's HTML. Specifically, it makes these replacements:
- * ``"&"`` to ``"&amp;"``
- * ``<`` to ``"&lt;"``
- * ``>`` to ``"&gt;"``
- * ``'"'`` (double quote) to ``'&quot;'``
- * ``"'"`` (single quote) to ``'&#39;'``
+ * ``<`` is converted to ``&lt;``
+ * ``>`` is converted to ``&gt;``
+ * ``'`` (single quote) is converted to ``&#39;``
+ * ``"`` (double quote) is converted to ``&quot;``
+ * ``&`` is converted to ``&amp;``
The escaping is only applied when the string is output, so it does not matter
where in a chained sequence of filters you put ``escape``: it will always be
Oops, something went wrong.

0 comments on commit 4a3084f

Please sign in to comment.