diff options
Diffstat (limited to 'docs/howto')
| -rw-r--r-- | docs/howto/custom-template-tags.txt | 27 |
1 files changed, 19 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: |