Ticket #6351: filter_doc.diff

docs/templates.txt

@@ -1224 +1224 @@
 
 Adds the arg to the value.
 
+For example::
+
+    {{ value|add:2 }}
+
+If ``value`` is 4, then the output will be 6.
+
 addslashes
 ~~~~~~~~~~
 
@@ -1247 +1253 @@
 
 Removes all values of arg from the given string.
 
+For example::
+
+    {{ value|cut:" "}}
+
+If ``value`` is "String with spaces", the output will be ``Stringwithspaces``.
+
 date
 ~~~~
 
 Formats a date according to the given format (same as the `now`_ tag).
 
+For example::
+
+    {{ value|date:"D d M Y" }}
+
+If ``value`` is a datetime object (ie. datetime.datetime.now()), the output
+would be formatted like ``Wed 09 Jan 2008``.
+
 default
 ~~~~~~~
 
 If value is unavailable, use given default.
 
+For example::
+
+    {{ value|default:"nothing" }}
+
+If ``value`` is ``Undefined``, the output would be ``nothing``.
+
 default_if_none
 ~~~~~~~~~~~~~~~
 
 If value is ``None``, use given default.
 
+For example::
+
+    {{ value|default_if_none:"nothing" }}
+
+If ``value`` is ``None``, the output would be ``nothing``.
+
 dictsort
 ~~~~~~~~
 
 Takes a list of dictionaries, returns that list sorted by the key given in
 the argument.
 
+For example::
+
+    {{ value|dictsort:"n" }}
+
+If ``value`` is ``[{'n': 'g', 'm': 0}, {'n': 'a', 'm': 2}, {'n': 'z', 'm':
+    8}]``, the output would be ``[{'n': 'a', 'm': 2}, {'n': 'g', 'm': 0}, {'n': 'z', 'm':
+    8}]``.
+
 dictsortreversed
 ~~~~~~~~~~~~~~~~
 
 Takes a list of dictionaries, returns that list sorted in reverse order by the
 key given in the argument.
 
+For example::
+
+    {{ value|dictsortreversed:"n" }}
+
+If ``value`` is ``[{'n': 'g', 'm': 0}, {'n': 'a', 'm': 2}, {'n': 'z', 'm':
+    8}]``, the output would be ``[{'n': 'z', 'm': 8}, {'n': 'g', 'm': 0}, {'n': 'a', 'm':
+    2}]``.
+
 divisibleby
 ~~~~~~~~~~~
 
 Returns true if the value is divisible by the argument.
 
+For example::
+
+    {{ value|divisibleby:3 }}
+
+If ``value`` is 123456789, the output would be ``True``.
+
 escape
 ~~~~~~
 
@@ -1319 +1372 @@
 Format the value like a 'human-readable' file size (i.e. ``'13 KB'``,
 ``'4.1 MB'``, ``'102 bytes'``, etc).
 
+For example::
+
+    {{ value|filesizeformat }}
+
+If ``value`` is 123456789, the output would be ``117.7 MB``.
+
 first
 ~~~~~
 
 Returns the first item in a list.
 
+For example::
+
+    {{ value|first }}
+
+If ``value`` is ``['a', 'b', 'c']``, the output would be `a`.
+
 fix_ampersands
 ~~~~~~~~~~~~~~
 
 Replaces ampersands with ``&`` entities.
 
+For example::
+
+    {{ value|fix_ampersands }}
+
+If ``value`` is ``Tom & Jerry``, the output would be ``Tom & Jerry``.
+
 floatformat
 ~~~~~~~~~~~
 
@@ -1388 +1459 @@
 value for invalid input (if input or argument is not an integer, or if argument
 is less than 1). Otherwise, output is always an integer.
 
+For example::
+    
+    {{ value|get_digit:2 }}
+
+If ``value`` is 123456789, the output would be ``8``.
+
 iriencode
 ~~~~~~~~~
 
@@ -1403 +1480 @@
 
 Joins a list with a string, like Python's ``str.join(list)``.
 
+For example::
+
+    {{ value|join:" or " }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``a or be or c
+or d``.
+
 last
 ~~~~
 
 Returns the last item in a list.
 
+For example::
+
+    {{ value|last }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``d``.
+
 length
 ~~~~~~
 
 Returns the length of the value. Useful for lists.
 
+For example::
+
+    {{ value|length }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``4``.
+
 length_is
 ~~~~~~~~~
 
 Returns a boolean of whether the value's length is the argument.
 
+For example::
+
+    {{ value|length_is:4 }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``4``.
+
 linebreaks
 ~~~~~~~~~~
 
@@ -1425 +1527 @@
 newline becomes an HTML line break (``<br />``) and a new line
 followed by a blank line becomes a paragraph break (``</p>``).
 
+For example::
+
+    {{ value|linebreaks }}
+
+If ``value`` is ``Joel\nis a slug``, the output would be ``<p>Joe<br>is a
+slug</p>``.
+
 linebreaksbr
 ~~~~~~~~~~~~
 
@@ -1448 +1557 @@
 
 Converts a string into all lowercase.
 
+For example::
+
+    {{ value|lower }}
+
+If ``value`` is ``Joel Is a Slug``, the output would be ``joel is a slug``.
+
 make_list
 ~~~~~~~~~
 
 Returns the value turned into a list. For an integer, it's a list of
 digits. For a string, it's a list of characters.
 
+For example::
+
+    {{ value|make_list }}
+
+If ``value`` is 123456789, the output would be ``[u'1', u'2', u'3', u'4',
+   u'5', u'6', u'7', u'8', u'9']``
+If ``value`` is 123456789, the output would be ``[u'J', u'o', u'e', u'l',
+   u'i', u's', u'a', u's', u'l', u'u', u'g']``
+
 phone2numeric
 ~~~~~~~~~~~~~
 
@@ -1497 +1621 @@
 
 Returns a random item from the list.
 
+For example::
+
+    {{ value|random }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output could be ``b``.
+
 removetags
 ~~~~~~~~~~
 
 Removes a space separated list of [X]HTML tags from the output.
 
+For example::
+
+    {{ value|removetags:"b span"|safe }}
+
+If ``value`` is ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the
+output would be ``Joel <button>is</button> a slug``.
+
 rjust
 ~~~~~
 
@@ -1533 +1670 @@
 underscores) and converts spaces to hyphens. Also strips leading and trailing
 whitespace.
 
+For example::
+
+    {{ value|slugify }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``joel-is-a-slug``.
+
 stringformat
 ~~~~~~~~~~~~
 
@@ -1543 +1686 @@
 See http://docs.python.org/lib/typesseq-strings.html for documentation of
 Python string formatting
 
+For example::
+
+    {{ value|stringformat:"s" }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``Joel is a slug``.
+
 striptags
 ~~~~~~~~~
 
 Strips all [X]HTML tags.
 
+For example::
+
+    {{ value|striptags }}
+
+If ``value`` is ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the
+output would be ``Joel is a slug``.
+
 time
 ~~~~
 
@@ -1556 +1712 @@
 to the time of day, not the date (for obvious reasons). If you need to
 format a date, use the `date`_ filter.
 
+For example::
+
+    {{ value|time:"H:i" }}
+
+If ``value`` is ``datetime.datetime.now()``, the output would be formatted
+like ``01:23``.
+
 timesince
 ~~~~~~~~~
 
@@ -1597 +1760 @@
 
 **Argument:** Number of words to truncate after
 
+For example::
+
+    {{ value|truncatewords:2 }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``Joel is ...``.
+
 truncatewords_html
 ~~~~~~~~~~~~~~~~~~
 
@@ -1642 +1811 @@
 
 Converts a string into all uppercase.
 
+For example::
+
+    {{ value|upper }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``JOEL IS A SLUG``.
+
 urlencode
 ~~~~~~~~~
 
@@ -1655 +1830 @@
 Note that if ``urlize`` is applied to text that already contains HTML markup,
 things won't work as expected. Apply this filter only to *plain* text.
 
+For example::
+
+    {{ value|urlize }}
+
+If ``value`` is ``Check out www.djangoproject.com``, the output would be
+``Check out <a
+href="http://www.djangoproject.com">www.djangoproject.com</a>``.
+
 urlizetrunc
 ~~~~~~~~~~~
 
@@ -1665 +1848 @@
 
 **Argument:** Length to truncate URLs to
 
+For example::
+
+    {{ value|urlizetrunc:15 }}
+
+If ``value`` is ``Check out www.djangoproject.com``, the output would be
+``Check out <a
+href="http://www.djangoproject.com">www.djangopr...</a>``.
+
 wordcount
 ~~~~~~~~~
 
@@ -1677 +1868 @@
 
 **Argument:** number of characters at which to wrap the text
 
+For example::
+
+    {{ value|wordwrap:5 }}
+
+If ``value`` is ``Joel is a slug``, the output would be::
+
+    Joel
+    is a
+    slug
+
 yesno
 ~~~~~