Permalink
Browse files

Fixed #6351: added more examples to template filters. Thanks, David T…

…ulig and atlithorn.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7276 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 4f5f873 commit 8e14a4e6d7718cb1c1866453bc6b404df0c938b4 @jacobian jacobian committed Mar 18, 2008
Showing with 214 additions and 3 deletions.
  1. +2 −0 AUTHORS
  2. +212 −3 docs/templates.txt
View
2 AUTHORS
@@ -43,6 +43,7 @@ answer newbie questions, and generally made Django that much better:
alang@bright-green.com
Marty Alchin <gulopine@gamemusic.org>
+ atlithorn <atlithorn@gmail.com>
Daniel Alves Barbosa de Oliveira Vaz <danielvaz@gmail.com>
AgarFu <heaven@croasanaso.sytes.net>
Dagur Páll Ammendrup <dagurp@gmail.com>
@@ -347,6 +348,7 @@ answer newbie questions, and generally made Django that much better:
tstromberg@google.com
Makoto Tsuyuki <mtsuyuki@gmail.com>
tt@gurgle.no
+ David Tulig <david.tulig@gmail.com>
Amit Upadhyay
Geert Vanderkelen
I.S. van Oostveen <v.oostveen@idca.nl>
View
215 docs/templates.txt
@@ -1224,6 +1224,12 @@ add
Adds the arg to the value.
+For example::
+
+ {{ value|add:2 }}
+
+If ``value`` is 4, then the output will be 6.
+
addslashes
~~~~~~~~~~
@@ -1247,38 +1253,90 @@ cut
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:"name" }}
+
+If ``value`` is::
+
+ [
+ {'name': 'zed', 'age': 19}
+ {'name': 'amy', 'age': 22},
+ {'name': 'joe', 'age': 31},
+ ]
+
+then the output would be::
+
+ [
+ {'name': 'amy', 'age': 22},
+ {'name': 'joe', 'age': 31},
+ {'name': 'zed', 'age': 19}
+ ]
+
dictsortreversed
~~~~~~~~~~~~~~~~
Takes a list of dictionaries, returns that list sorted in reverse order by the
-key given in the argument.
+key given in the argument. This works exactly the same as the above filter, but
+the returned value will be in reverse order.
divisibleby
~~~~~~~~~~~
Returns true if the value is divisible by the argument.
+For example::
+
+ {{ value|divisibleby:3 }}
+
+If ``value`` is ``21``, the output would be ``True``.
+
escape
~~~~~~
@@ -1319,16 +1377,38 @@ filesizeformat
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 ``&amp;`` entities.
+For example::
+
+ {{ value|fix_ampersands }}
+
+If ``value`` is ``Tom & Jerry``, the output would be ``Tom &amp; Jerry``.
+
+**New in Django development version**: you probably don't need to use this
+filter since ampersands will be automatically escaped. See escape_ for more on
+how auto-escaping works.
+
floatformat
~~~~~~~~~~~
@@ -1388,6 +1468,12 @@ right-most digit, 2 is the second-right-most digit, etc. Returns the original
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
~~~~~~~~~
@@ -1401,7 +1487,13 @@ It's safe to use this filter on a string that has already gone through the
join
~~~~
-Joins a list with a string, like Python's ``str.join(list)``.
+Joins a list with a string, like Python's ``str.join(list)``
+
+For example::
+
+ {{ value|join:" // " }}
+
+If ``value`` is ``['a', 'b', 'c']``, the output would be ``a // b // c``.
last
~~~~
@@ -1410,23 +1502,48 @@ 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 ``True``.
+
linebreaks
~~~~~~~~~~
Replaces line breaks in plain text with appropriate HTML; a single
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
~~~~~~~~~~~~
@@ -1450,12 +1567,25 @@ lower
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 "Joe", the output would be ``[u'J', u'o', u'e']. If ``value`` is
+123, the output would be ``[1, 2, 3]``.
+
phone2numeric
~~~~~~~~~~~~~
@@ -1492,18 +1622,33 @@ Example::
pprint
~~~~~~
-A wrapper around pprint.pprint -- for debugging, really.
+A wrapper around `pprint.pprint`__ -- for debugging, really.
+
+__ http://www.python.org/doc/2.5/lib/module-pprint.html
random
~~~~~~
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
~~~~~
@@ -1535,6 +1680,12 @@ Converts to lowercase, removes non-word characters (alphanumerics and
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
~~~~~~~~~~~~
@@ -1545,11 +1696,24 @@ the leading "%" is dropped.
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
~~~~
@@ -1558,6 +1722,13 @@ The time filter will only accept parameters in the format string that relate
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
~~~~~~~~~
@@ -1599,6 +1770,12 @@ Truncates a string after a certain number of words.
**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
~~~~~~~~~~~~~~~~~~
@@ -1644,6 +1821,12 @@ upper
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
~~~~~~~~~
@@ -1657,6 +1840,14 @@ Converts URLs in plain text into clickable links.
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
~~~~~~~~~~~
@@ -1667,6 +1858,14 @@ As with urlize_, this filter should only be applied to *plain* text.
**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
~~~~~~~~~
@@ -1679,6 +1878,16 @@ Wraps words at specified line length.
**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
~~~~~

0 comments on commit 8e14a4e

Please sign in to comment.