From 8e14a4e6d7718cb1c1866453bc6b404df0c938b4 Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Tue, 18 Mar 2008 00:14:41 +0000 Subject: [PATCH] Fixed #6351: added more examples to template filters. Thanks, David Tulig and atlithorn. git-svn-id: http://code.djangoproject.com/svn/django/trunk@7276 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- AUTHORS | 2 + docs/templates.txt | 215 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 214 insertions(+), 3 deletions(-) diff --git a/AUTHORS b/AUTHORS index 8f9147be57..6c9a7d40db 100644 --- a/AUTHORS +++ b/AUTHORS @@ -43,6 +43,7 @@ answer newbie questions, and generally made Django that much better: alang@bright-green.com Marty Alchin + atlithorn Daniel Alves Barbosa de Oliveira Vaz AgarFu Dagur Páll Ammendrup @@ -347,6 +348,7 @@ answer newbie questions, and generally made Django that much better: tstromberg@google.com Makoto Tsuyuki tt@gurgle.no + David Tulig Amit Upadhyay Geert Vanderkelen I.S. van Oostveen diff --git a/docs/templates.txt b/docs/templates.txt index d473a6f06f..471f44cfbf 100644 --- a/docs/templates.txt +++ b/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 ``&`` entities. +For example:: + + {{ value|fix_ampersands }} + +If ``value`` is ``Tom & Jerry``, the output would be ``Tom & 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,16 +1502,34 @@ 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 ~~~~~~~~~~ @@ -1427,6 +1537,13 @@ Replaces line breaks in plain text with appropriate HTML; a single newline becomes an HTML line break (``
``) and a new line followed by a blank line becomes a paragraph break (``

``). +For example:: + + {{ value|linebreaks }} + +If ``value`` is ``Joel\nis a slug``, the output would be ``

Joe
is a +slug

``. + 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 ``Joel a slug`` the +output would be ``Joel 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 ``Joel a slug`` 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 www.djangoproject.com``. + 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 www.djangopr...``. + 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 ~~~~~