Changes between Version 132 and Version 133 of BackwardsIncompatibleChanges

Timestamp:

Nov 14, 2007, 7:05:08 AM (16 years ago)

Author:

Malcolm Tredinnick

Comment:

Required auto-escaping changes noted.

BackwardsIncompatibleChanges

@@ -43 +43 @@
  * [6582] Oct. 21, 2007: [http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges#_nolongerinbuiltins  _() no longer in builtins]
  * [6668] Nov. 10, 2007: [#django.newforms.forms.SortedDictFromListclassremoved django.newforms.forms.SortedDictFromList class removed]
+ * [6671] Nov. 15, 2007: [#auto-escapingintemplates Auto-escaping in templates]
 
 
@@ -426 +427 @@
  1. Use `django.utils.datastructures.SortedDict` wherever you were using `django.newforms.forms.SortedDictFromList`.
  1. Since `SortedDict`'s copy method doesn't return a deepcopy as `SortedDictFromList`'s `copy` method did, you will need to update your code if you were relying on `SortedDictFromList.copy` to return a deepcopy.  Do this by using `copy.deepcopy` instead of `SortedDict`'s `copy` method.
+
+== Auto-escaping in templates ==
+
+In [XXXX] a long-awaited feature was committed to make default HTML template usage a bit safe from some forms of cross-site scripting attacks. For full details, read the [http://www.djangoproject.com/documentation/templates/#automatic-html-escaping template author documentation] and the [http://www.djangoproject.com/documentation/templates_python/#filters-and-auto-escaping template filter documentation].
+
+Automatic HTML escaping (henceforth ''auto-escaping'') affects any variables in templates. It is only applied to variables and not to template tags.
+
+{{{
+{{ a_variable }}   -- This will be auto-escaped.
+{{ variable|filter1|filter1 }} -- so will this
+{% a_template_tag %} -- This will not be; it's a tag
+}}}
+
+Also note that the {{{escape}}} filter's behaviour has changed slightly (it is only applied once and only as the last thing done to the output) and new filters {{{force_escape}}} and {{{safe}}} have been introduced if you need them.
+
+If you never intentionally insert raw HTML into your context variables, no changes will be needed.
+
+If you have any variables in your templates that do insert raw HTML output and you do ''not'' want this output automatically escaped, you will need to make some changes. There are two approaches here, the first one being the easiest (but not the safest) and can act as a temporary step whilst you do the more detailed second step.
+
+ 1. '''Simple backwards compatibility:''' In every root template (such as your `base.html` template), wrap the entire contents in tags to disable auto-escaping:
+
+    {{{
+    {% autoescape off %}
+       ... normal template content here ...
+    {% endautoescape %}
+    }}}
+
+    If one template extends from another template, the auto-escaping behaviour from the root template (the one in the {{{ {% extends ... %} }}} tag) will be inherited. So you only need to add these tags to your root templates.
+
+    This is also the recommended approach for templates that produce, say, email  messages or other non-HTML output. The `autoescape` template tag exists for this reason.
+
+    The drawback of this method in templates that are destined for HTML output is that you receive none of the benefits of auto-escaping.
+
+ 2. '''More detailed porting to take advantage of auto-escaping:''' There are two approaches to inserting raw HTML via variables into templates. One option is to pass the variable content through the {{{safe}}} filter. This tells the renderer not to auto-escape the contents:
+       
+      {{{
+      {{ variable_with_html|safe }} -- will not be auto-escaped.
+      }}}
+      
+      The second and probably more robust way is to use {{{mark_safe()}}} where appropriate (see [http://www.djangoproject.com/documentation/templates_python/#filters-and-auto-escaping the documentation] for details) and go through each of your custom filters attaching {{{is_safe}}} and {{{needs_autoescape}}} attributes where necessary (again, the details are in the above documentation).
+      
+      Have a look at Django's default filters (in {{{django/template/defaultfilters.py}}}) for examples of how mixed filters (those which behave differently depending upon whether auto-escaping is in effect or not) can be written.
+
+The attributes on filter functions and the new {{{escape}}} behaviour mean that you can write templates and filters that will operate correctly in both auto-escaping and non-auto-escaping environments, so you're not forcing your decision onto users of your filters, if you distribute the code.
+