diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/custom-template-tags.txt | 27 | ||||
| -rw-r--r-- | docs/releases/1.8.txt | 20 |
2 files changed, 39 insertions, 8 deletions
diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index 7bf698ae23..a340ac7b83 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -281,7 +281,9 @@ Template filter code falls into one of two situations: (If you don't specify this flag, it defaults to ``False``). This flag tells Django that your filter function wants to be passed an extra keyword argument, called ``autoescape``, that is ``True`` if auto-escaping is in - effect and ``False`` otherwise. + effect and ``False`` otherwise. It is recommended to set the default of the + ``autoescape`` parameter to ``True``, so that if you call the function + from Python code it will have escaping enabled by default. For example, let's write a filter that emphasizes the first character of a string:: @@ -293,7 +295,7 @@ Template filter code falls into one of two situations: register = template.Library() @register.filter(needs_autoescape=True) - def initial_letter_filter(text, autoescape=None): + def initial_letter_filter(text, autoescape=True): first, other = text[0], text[1:] if autoescape: esc = conditional_escape @@ -323,9 +325,15 @@ Template filter code falls into one of two situations: .. warning:: Avoiding XSS vulnerabilities when reusing built-in filters - Be careful when reusing Django's built-in filters. You'll need to pass - ``autoescape=True`` to the filter in order to get the proper autoescaping - behavior and avoid a cross-site script vulnerability. + .. versionchanged:: 1.8 + + Django's built-in filters have ``autoescape=True`` by default in order to + get the proper autoescaping behavior and avoid a cross-site script + vulnerability. + + In older versions of Django, be careful when reusing Django's built-in + filters as ``autoescape`` defaults to ``None``. You'll need to pass + ``autoescape=True`` to get autoescaping. For example, if you wanted to write a custom filter called ``urlize_and_linebreaks`` that combined the :tfilter:`urlize` and @@ -333,9 +341,12 @@ Template filter code falls into one of two situations: from django.template.defaultfilters import linebreaksbr, urlize - @register.filter - def urlize_and_linebreaks(text): - return linebreaksbr(urlize(text, autoescape=True), autoescape=True) + @register.filter(needs_autoescape=True) + def urlize_and_linebreaks(text, autoescape=True): + return linebreaksbr( + urlize(text, autoescape=autoescape), + autoescape=autoescape + ) Then: diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index a6fa0cb33e..bbbe97a881 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -1012,6 +1012,26 @@ those writing third-party backends in updating their code: now takes a second argument named ``obj_id`` which is the serialized identifier used to retrieve the object before deletion. +Default autoescaping of functions in ``django.template.defaultfilters`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to make built-in template filters that output HTML "safe by default" +when calling them in Python code, the following functions in +``django.template.defaultfilters`` have been changed to automatically escape +their input value: + +* ``join`` +* ``linebreaksbr`` +* ``linebreaks_filter`` +* ``linenumbers`` +* ``unordered_list`` +* ``urlize`` +* ``urlizetrunc`` + +You can revert to the old behavior by specifying ``autoescape=False`` if you +are passing trusted content. This change doesn't have any effect when using +the corresponding filters in templates. + Miscellaneous ~~~~~~~~~~~~~ |