Fixes #15732 -- better introduction of template filter decorator concepts (first register, then stringfilter). Thanks for the patch, hahasee.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16251 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 21 insertions, 19 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index c9dacb590f..1b56cf85c3 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -105,23 +105,6 @@ your function. Example::
         "Converts a string into all lowercase"
         return value.lower()
 
-Template filters that expect strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you're writing a template filter that only expects a string as the first
-argument, you should use the decorator ``stringfilter``. This will
-convert an object to its string value before being passed to your function::
-
-    from django.template.defaultfilters import stringfilter
-
-    @stringfilter
-    def lower(value):
-        return value.lower()
-
-This way, you'll be able to pass, say, an integer to this filter, and it
-won't cause an ``AttributeError`` (because integers don't have ``lower()``
-methods).
-
 Registering custom filters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -140,18 +123,37 @@ The ``Library.filter()`` method takes two arguments:
 You can use ``register.filter()`` as a decorator instead::
 
     @register.filter(name='cut')
-    @stringfilter
     def cut(value, arg):
         return value.replace(arg, '')
 
     @register.filter
-    @stringfilter
     def lower(value):
         return value.lower()
 
 If you leave off the ``name`` argument, as in the second example above, Django
 will use the function's name as the filter name.
 
+Template filters that expect strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're writing a template filter that only expects a string as the first
+argument, you should use the decorator ``stringfilter``. This will
+convert an object to its string value before being passed to your function::
+
+    from django import template
+    from django.template.defaultfilters import stringfilter
+
+    register = template.Library()
+
+    @register.filter
+    @stringfilter
+    def lower(value):
+        return value.lower()
+
+This way, you'll be able to pass, say, an integer to this filter, and it
+won't cause an ``AttributeError`` (because integers don't have ``lower()``
+methods).
+
 Filters and auto-escaping
 ~~~~~~~~~~~~~~~~~~~~~~~~~