Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Edited docs/templates.txt changes from [7276]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7280 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit e5342282cc93f6178ed23eff19f5eda76dcd07c8 1 parent 17155d3
@adrianholovaty adrianholovaty authored
Showing with 81 additions and 75 deletions.
  1. +81 −75 docs/templates.txt
View
156 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 ``&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
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 &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
-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 ``<p>Joe<br>is a
+If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joe<br>is a
slug</p>``.
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 ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the
-output would be ``Joel <button>is</button> a slug``.
+If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
+output will be ``"Joel <button>is</button> 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 ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the
-output would be ``Joel is a slug``.
+If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, 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 <ul> tags.
-**Changed in Django development version**
-
-The format accepted by ``unordered_list`` has changed to an easier to
-understand format.
+**New in Django development version:** The format accepted by
+``unordered_list`` has changed to be easier to understand.
The list is assumed to be in the proper format. For example, if ``var`` contains
``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
@@ -1825,7 +1831,7 @@ For example::
{{ 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
~~~~~~~~~
@@ -1844,9 +1850,9 @@ 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>``.
+If ``value`` is ``"Check out www.djangoproject.com"``, the output will be
+``"Check out <a
+href="http://www.djangoproject.com">www.djangoproject.com</a>"``.
urlizetrunc
~~~~~~~~~~~
@@ -1862,9 +1868,9 @@ 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>``.
+If ``value`` is ``"Check out www.djangoproject.com"``, the output would be
+``'Check out <a
+href="http://www.djangoproject.com">www.djangopr...</a>'``.
wordcount
~~~~~~~~~

0 comments on commit e534228

Please sign in to comment.
Something went wrong with that request. Please try again.