From 07711e999779eff4296d1a363c1131dbb14acae2 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Thu, 2 Jan 2014 16:28:56 -0500
Subject: [PATCH] Fixed #21722 -- Added a warning for avoiding XSS
 vulnerabilities when reusing built-in filters.

Thanks Stephen McDonald for the suggestion.
---
 docs/howto/custom-template-tags.txt | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index 1f6d2d5c750..b5cbf571b76 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -339,6 +339,34 @@ Template filter code falls into one of two situations:
    handle the auto-escaping issues and return a safe string, the
    ``is_safe`` flag won't change anything either way.
 
+.. 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.
+
+    For example, if you wanted to write a custom filter called
+    ``urlize_and_linebreaks`` that combined the :tfilter:`urlize` and
+    :tfilter:`linebreaksbr` filters, the filter would look like::
+
+        from django.template.defaultfilters import linebreaksbr, urlize
+
+        @register.filter
+        def urlize_and_linebreaks(text):
+            return linebreaksbr(urlize(text, autoescape=True), autoescape=True)
+
+    Then:
+
+    .. code-block:: html+django
+
+        {{ comment|urlize_and_linebreaks }}
+
+    would be equivalent to:
+
+    .. code-block:: html+django
+
+        {{ comment|urlize|linebreaksbr }}
+
 .. _filters-timezones:
 
 Filters and time zones