diff --git a/docs/templates.txt b/docs/templates.txt index 471f44cfbf..3360b04178 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -1222,20 +1222,20 @@ Built-in filter reference add ~~~ -Adds the arg to the value. +Adds the argument to the value. For example:: - {{ value|add:2 }} + {{ value|add:"2" }} -If ``value`` is 4, then the output will be 6. +If ``value`` is ``4``, then the output will be ``6``. addslashes ~~~~~~~~~~ Adds slashes before quotes. Useful for escaping strings in CSV, for example. -**New in Django development version**: for escaping data in JavaScript strings, +**New in Django development version**: For escaping data in JavaScript strings, use the `escapejs`_ filter instead. capfirst @@ -1257,7 +1257,7 @@ For example:: {{ value|cut:" "}} -If ``value`` is "String with spaces", the output will be ``Stringwithspaces``. +If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``. date ~~~~ @@ -1268,35 +1268,40 @@ 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``. +If ``value`` is a ``datetime`` object (e.g., the result of +``datetime.datetime.now()``), the output will be the string +``'Wed 09 Jan 2008'``. default ~~~~~~~ -If value is unavailable, use given default. +If value evaluates to ``False``, use given default. Otherwise, use the value. For example:: {{ value|default:"nothing" }} -If ``value`` is ``Undefined``, the output would be ``nothing``. +If ``value`` is ``""`` (the empty string), the output will be ``nothing``. default_if_none ~~~~~~~~~~~~~~~ -If value is ``None``, use given default. +If (and only if) value is ``None``, use given default. Otherwise, use the +value. + +Note that if an empty string is given, the default value will *not* be used. +Use the ``default`` filter if you want to fallback for empty strings. For example:: {{ value|default_if_none:"nothing" }} -If ``value`` is ``None``, the output would be ``nothing``. +If ``value`` is ``None``, the output will be the string ``"nothing"``. dictsort ~~~~~~~~ -Takes a list of dictionaries, returns that list sorted by the key given in +Takes a list of dictionaries and returns that list sorted by the key given in the argument. For example:: @@ -1304,46 +1309,42 @@ For example:: {{ value|dictsort:"name" }} If ``value`` is:: - + [ - {'name': 'zed', 'age': 19} - {'name': 'amy', 'age': 22}, - {'name': 'joe', 'age': 31}, + {'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} + {'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. This works exactly the same as the above filter, but -the returned value will be in reverse order. +Takes a list of dictionaries and returns that list sorted in reverse order by +the 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. +Returns ``True`` if the value is divisible by the argument. For example:: - {{ value|divisibleby:3 }} + {{ value|divisibleby:"3" }} If ``value`` is ``21``, the output would be ``True``. escape ~~~~~~ -**New in Django development version:** The behaviour of this filter has -changed slightly in the development version (the affects are only applied -once, after all other filters). - Escapes a string's HTML. Specifically, it makes these replacements: * ``<`` is converted to ``<`` @@ -1362,6 +1363,10 @@ applied to the result will only result in one round of escaping being done. So it is safe to use this function even in auto-escaping environments. If you want multiple escaping passes to be applied, use the ``force_escape`` filter. +**New in Django development version:** Due to auto-escaping, the behavior of +this filter has changed slightly. The replacements are only made once, after +all other filters are applied -- including filters before and after it. + escapejs ~~~~~~~~ @@ -1392,7 +1397,7 @@ For example:: {{ value|first }} -If ``value`` is ``['a', 'b', 'c']``, the output would be `a`. +If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. fix_ampersands ~~~~~~~~~~~~~~ @@ -1403,11 +1408,11 @@ For example:: {{ value|fix_ampersands }} -If ``value`` is ``Tom & Jerry``, the output would be ``Tom & Jerry``. +If ``value`` is ``Tom & Jerry``, the output will 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. +**New in Django development version**: This filter generally is no longer +useful, because ampersands are automatically escaped in templates. See escape_ +for more on how auto-escaping works. floatformat ~~~~~~~~~~~ @@ -1463,16 +1468,16 @@ filter. get_digit ~~~~~~~~~ -Given a whole number, returns the requested digit of it, where 1 is the -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. +Given a whole number, returns the requested digit, where 1 is the 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``. + {{ value|get_digit:"2" }} + +If ``value`` is ``123456789``, the output will be ``8``. iriencode ~~~~~~~~~ @@ -1493,7 +1498,8 @@ For example:: {{ value|join:" // " }} -If ``value`` is ``['a', 'b', 'c']``, the output would be ``a // b // c``. +If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string +``"a // b // c"``. last ~~~~ @@ -1506,29 +1512,30 @@ For example:: {{ value|last }} -If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``d``. +If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string +``"d"``. length ~~~~~~ -Returns the length of the value. Useful for lists. +Returns the length of the value. This works for both strings and lists. For example:: {{ value|length }} -If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``4``. +If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``. length_is ~~~~~~~~~ -Returns a boolean of whether the value's length is the argument. +Returns ``True`` if the value's length is the argument, or ``False`` otherwise. For example:: - {{ value|length_is:4 }} + {{ value|length_is:"4" }} -If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``True``. +If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``. linebreaks ~~~~~~~~~~ @@ -1541,7 +1548,7 @@ For example:: {{ value|linebreaks }} -If ``value`` is ``Joel\nis a slug``, the output would be ``

Joe
is a +If ``value`` is ``Joel\nis a slug``, the output will be ``

Joe
is a slug

``. linebreaksbr @@ -1571,7 +1578,7 @@ For example:: {{ value|lower }} -If ``value`` is ``Joel Is a Slug``, the output would be ``joel is a slug``. +If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``. make_list ~~~~~~~~~ @@ -1583,8 +1590,9 @@ 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]``. +If ``value`` is the string ``"Joe"``, the output would be the list +``[u'J', u'o', u'e']``. If ``value`` is ``123``, the output will be the list +``[1, 2, 3]``. phone2numeric ~~~~~~~~~~~~~ @@ -1629,25 +1637,25 @@ __ http://www.python.org/doc/2.5/lib/module-pprint.html random ~~~~~~ -Returns a random item from the list. +Returns a random item from the given list. For example:: {{ value|random }} -If ``value`` is ``['a', 'b', 'c', 'd']``, the output could be ``b``. +If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``. removetags ~~~~~~~~~~ -Removes a space separated list of [X]HTML tags from the output. +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``. +If ``value`` is ``"Joel a slug"`` the +output will be ``"Joel a slug"``. rjust ~~~~~ @@ -1684,7 +1692,7 @@ For example:: {{ value|slugify }} -If ``value`` is ``Joel is a slug``, the output would be ``joel-is-a-slug``. +If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``. stringformat ~~~~~~~~~~~~ @@ -1700,7 +1708,7 @@ For example:: {{ value|stringformat:"s" }} -If ``value`` is ``Joel is a slug``, the output would be ``Joel is a slug``. +If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``. striptags ~~~~~~~~~ @@ -1711,8 +1719,8 @@ For example:: {{ value|striptags }} -If ``value`` is ``Joel a slug`` the -output would be ``Joel is a slug``. +If ``value`` is ``"Joel a slug"``, the +output will be ``"Joel is a slug"``. time ~~~~ @@ -1726,13 +1734,13 @@ For example:: {{ value|time:"H:i" }} -If ``value`` is ``datetime.datetime.now()``, the output would be formatted -like ``01:23``. +If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be +the string ``"01:23"``. timesince ~~~~~~~~~ -Formats a date as the time since that date (i.e. "4 days, 6 hours"). +Formats a date as the time since that date (e.g., "4 days, 6 hours"). Takes an optional argument that is a variable containing the date to use as the comparison point (without the argument, the comparison point is *now*). @@ -1774,7 +1782,7 @@ For example:: {{ value|truncatewords:2 }} -If ``value`` is ``Joel is a slug``, the output would be ``Joel is ...``. +If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``. truncatewords_html ~~~~~~~~~~~~~~~~~~ @@ -1792,10 +1800,8 @@ unordered_list Recursively takes a self-nested list and returns an HTML unordered list -- WITHOUT opening and closing