Changes between Version 132 and Version 133 of BackwardsIncompatibleChanges


Ignore:
Timestamp:
11/14/2007 07:05:08 AM (8 years ago)
Author:
mtredinnick
Comment:

Required auto-escaping changes noted.

Legend:

Unmodified
Added
Removed
Modified
  • BackwardsIncompatibleChanges

    v132 v133  
    4343 * [6582] Oct. 21, 2007: [http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges#_nolongerinbuiltins  _() no longer in builtins]
    4444 * [6668] Nov. 10, 2007: [#django.newforms.forms.SortedDictFromListclassremoved django.newforms.forms.SortedDictFromList class removed]
     45 * [6671] Nov. 15, 2007: [#auto-escapingintemplates Auto-escaping in templates]
    4546
    4647
     
    426427 1. Use `django.utils.datastructures.SortedDict` wherever you were using `django.newforms.forms.SortedDictFromList`.
    427428 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.
     429
     430== Auto-escaping in templates ==
     431
     432In [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].
     433
     434Automatic HTML escaping (henceforth ''auto-escaping'') affects any variables in templates. It is only applied to variables and not to template tags.
     435
     436{{{
     437{{ a_variable }}   -- This will be auto-escaped.
     438{{ variable|filter1|filter1 }} -- so will this
     439{% a_template_tag %} -- This will not be; it's a tag
     440}}}
     441
     442Also 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.
     443
     444If you never intentionally insert raw HTML into your context variables, no changes will be needed.
     445
     446If 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.
     447
     448 1. '''Simple backwards compatibility:''' In every root template (such as your `base.html` template), wrap the entire contents in tags to disable auto-escaping:
     449
     450    {{{
     451    {% autoescape off %}
     452       ... normal template content here ...
     453    {% endautoescape %}
     454    }}}
     455
     456    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.
     457
     458    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.
     459
     460    The drawback of this method in templates that are destined for HTML output is that you receive none of the benefits of auto-escaping.
     461
     462 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:
     463       
     464      {{{
     465      {{ variable_with_html|safe }} -- will not be auto-escaped.
     466      }}}
     467     
     468      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).
     469     
     470      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.
     471
     472The 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.
     473
Back to Top