Edited docs/templates.txt changes from [7276]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7280 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2008-03-18 04:21:08 +00:00
parent 17155d3845
commit e5342282cc
1 changed files with 81 additions and 75 deletions

View File

@ -1222,20 +1222,20 @@ Built-in filter reference
add add
~~~ ~~~
Adds the arg to the value. Adds the argument to the value.
For example:: 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 addslashes
~~~~~~~~~~ ~~~~~~~~~~
Adds slashes before quotes. Useful for escaping strings in CSV, for example. 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. use the `escapejs`_ filter instead.
capfirst capfirst
@ -1257,7 +1257,7 @@ For example::
{{ value|cut:" "}} {{ 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 date
~~~~ ~~~~
@ -1268,35 +1268,40 @@ For example::
{{ value|date:"D d M Y" }} {{ value|date:"D d M Y" }}
If ``value`` is a datetime object (ie. datetime.datetime.now()), the output If ``value`` is a ``datetime`` object (e.g., the result of
would be formatted like ``Wed 09 Jan 2008``. ``datetime.datetime.now()``), the output will be the string
``'Wed 09 Jan 2008'``.
default default
~~~~~~~ ~~~~~~~
If value is unavailable, use given default. If value evaluates to ``False``, use given default. Otherwise, use the value.
For example:: For example::
{{ value|default:"nothing" }} {{ 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 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:: For example::
{{ value|default_if_none:"nothing" }} {{ 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 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. the argument.
For example:: For example::
@ -1306,7 +1311,7 @@ For example::
If ``value`` is:: If ``value`` is::
[ [
{'name': 'zed', 'age': 19} {'name': 'zed', 'age': 19},
{'name': 'amy', 'age': 22}, {'name': 'amy', 'age': 22},
{'name': 'joe', 'age': 31}, {'name': 'joe', 'age': 31},
] ]
@ -1316,34 +1321,30 @@ then the output would be::
[ [
{'name': 'amy', 'age': 22}, {'name': 'amy', 'age': 22},
{'name': 'joe', 'age': 31}, {'name': 'joe', 'age': 31},
{'name': 'zed', 'age': 19} {'name': 'zed', 'age': 19},
] ]
dictsortreversed dictsortreversed
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
Takes a list of dictionaries, returns that list sorted in reverse order by the Takes a list of dictionaries and returns that list sorted in reverse order by
key given in the argument. This works exactly the same as the above filter, but the key given in the argument. This works exactly the same as the above filter,
the returned value will be in reverse order. but the returned value will be in reverse order.
divisibleby divisibleby
~~~~~~~~~~~ ~~~~~~~~~~~
Returns true if the value is divisible by the argument. Returns ``True`` if the value is divisible by the argument.
For example:: For example::
{{ value|divisibleby:3 }} {{ value|divisibleby:"3" }}
If ``value`` is ``21``, the output would be ``True``. If ``value`` is ``21``, the output would be ``True``.
escape 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: Escapes a string's HTML. Specifically, it makes these replacements:
* ``<`` is converted to ``&lt;`` * ``<`` is converted to ``&lt;``
@ -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 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. 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 escapejs
~~~~~~~~ ~~~~~~~~
@ -1392,7 +1397,7 @@ For example::
{{ value|first }} {{ 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 fix_ampersands
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
@ -1403,11 +1408,11 @@ For example::
{{ value|fix_ampersands }} {{ value|fix_ampersands }}
If ``value`` is ``Tom & Jerry``, the output would be ``Tom &amp; Jerry``. If ``value`` is ``Tom & Jerry``, the output will be ``Tom &amp; Jerry``.
**New in Django development version**: you probably don't need to use this **New in Django development version**: This filter generally is no longer
filter since ampersands will be automatically escaped. See escape_ for more on useful, because ampersands are automatically escaped in templates. See escape_
how auto-escaping works. for more on how auto-escaping works.
floatformat floatformat
~~~~~~~~~~~ ~~~~~~~~~~~
@ -1463,16 +1468,16 @@ filter.
get_digit get_digit
~~~~~~~~~ ~~~~~~~~~
Given a whole number, returns the requested digit of it, where 1 is the Given a whole number, returns the requested digit, where 1 is the right-most
right-most digit, 2 is the second-right-most digit, etc. Returns the original digit, 2 is the second-right-most digit, etc. Returns the original value for
value for invalid input (if input or argument is not an integer, or if argument invalid input (if input or argument is not an integer, or if argument is less
is less than 1). Otherwise, output is always an integer. than 1). Otherwise, output is always an integer.
For example:: For example::
{{ value|get_digit:2 }} {{ value|get_digit:"2" }}
If ``value`` is 123456789, the output would be ``8``. If ``value`` is ``123456789``, the output will be ``8``.
iriencode iriencode
~~~~~~~~~ ~~~~~~~~~
@ -1493,7 +1498,8 @@ For example::
{{ value|join:" // " }} {{ 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 last
~~~~ ~~~~
@ -1506,29 +1512,30 @@ For example::
{{ value|last }} {{ 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 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:: For example::
{{ value|length }} {{ 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 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:: 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 linebreaks
~~~~~~~~~~ ~~~~~~~~~~
@ -1541,7 +1548,7 @@ For example::
{{ value|linebreaks }} {{ value|linebreaks }}
If ``value`` is ``Joel\nis a slug``, the output would be ``<p>Joe<br>is a If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joe<br>is a
slug</p>``. slug</p>``.
linebreaksbr linebreaksbr
@ -1571,7 +1578,7 @@ For example::
{{ value|lower }} {{ 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 make_list
~~~~~~~~~ ~~~~~~~~~
@ -1583,8 +1590,9 @@ For example::
{{ value|make_list }} {{ value|make_list }}
If ``value`` is "Joe", the output would be ``[u'J', u'o', u'e']. If ``value`` is If ``value`` is the string ``"Joe"``, the output would be the list
123, the output would be ``[1, 2, 3]``. ``[u'J', u'o', u'e']``. If ``value`` is ``123``, the output will be the list
``[1, 2, 3]``.
phone2numeric phone2numeric
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -1629,25 +1637,25 @@ __ http://www.python.org/doc/2.5/lib/module-pprint.html
random random
~~~~~~ ~~~~~~
Returns a random item from the list. Returns a random item from the given list.
For example:: For example::
{{ value|random }} {{ 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 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:: For example::
{{ value|removetags:"b span"|safe }} {{ value|removetags:"b span"|safe }}
If ``value`` is ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
output would be ``Joel <button>is</button> a slug``. output will be ``"Joel <button>is</button> a slug"``.
rjust rjust
~~~~~ ~~~~~
@ -1684,7 +1692,7 @@ For example::
{{ value|slugify }} {{ 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 stringformat
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -1700,7 +1708,7 @@ For example::
{{ value|stringformat:"s" }} {{ 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 striptags
~~~~~~~~~ ~~~~~~~~~
@ -1711,8 +1719,8 @@ For example::
{{ value|striptags }} {{ value|striptags }}
If ``value`` is ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the
output would be ``Joel is a slug``. output will be ``"Joel is a slug"``.
time time
~~~~ ~~~~
@ -1726,13 +1734,13 @@ For example::
{{ value|time:"H:i" }} {{ value|time:"H:i" }}
If ``value`` is ``datetime.datetime.now()``, the output would be formatted If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be
like ``01:23``. the string ``"01:23"``.
timesince 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 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*). the comparison point (without the argument, the comparison point is *now*).
@ -1774,7 +1782,7 @@ For example::
{{ value|truncatewords:2 }} {{ 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 truncatewords_html
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
@ -1792,10 +1800,8 @@ unordered_list
Recursively takes a self-nested list and returns an HTML unordered list -- Recursively takes a self-nested list and returns an HTML unordered list --
WITHOUT opening and closing <ul> tags. WITHOUT opening and closing <ul> tags.
**Changed in Django development version** **New in Django development version:** The format accepted by
``unordered_list`` has changed to be easier to understand.
The format accepted by ``unordered_list`` has changed to an easier to
understand format.
The list is assumed to be in the proper format. For example, if ``var`` contains The list is assumed to be in the proper format. For example, if ``var`` contains
``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
@ -1825,7 +1831,7 @@ For example::
{{ value|upper }} {{ value|upper }}
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"``.
urlencode urlencode
~~~~~~~~~ ~~~~~~~~~
@ -1844,9 +1850,9 @@ For example::
{{ value|urlize }} {{ value|urlize }}
If ``value`` is ``Check out www.djangoproject.com``, the output would be If ``value`` is ``"Check out www.djangoproject.com"``, the output will be
``Check out <a ``"Check out <a
href="http://www.djangoproject.com">www.djangoproject.com</a>``. href="http://www.djangoproject.com">www.djangoproject.com</a>"``.
urlizetrunc urlizetrunc
~~~~~~~~~~~ ~~~~~~~~~~~
@ -1862,9 +1868,9 @@ For example::
{{ value|urlizetrunc:15 }} {{ value|urlizetrunc:15 }}
If ``value`` is ``Check out www.djangoproject.com``, the output would be If ``value`` is ``"Check out www.djangoproject.com"``, the output would be
``Check out <a ``'Check out <a
href="http://www.djangoproject.com">www.djangopr...</a>``. href="http://www.djangoproject.com">www.djangopr...</a>'``.
wordcount wordcount
~~~~~~~~~ ~~~~~~~~~