diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 51ef03c886..b9fa99bf6f 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -1017,6 +1017,12 @@ addslashes Adds slashes before quotes. Useful for escaping strings in CSV, for example. +For example:: + + {{ value|addslashes }} + +If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``. + .. templatefilter:: capfirst capfirst @@ -1024,6 +1030,12 @@ capfirst Capitalizes the first character of the value. +For example:: + + {{ value|capfirst }} + +If ``value`` is ``"django"``, the output will be ``"Django"``. + .. templatefilter:: center center @@ -1031,6 +1043,12 @@ center Centers the value in a field of a given width. +For example:: + + "{{ value|center:"15" }}" + +If ``value`` is ``"Django"``, the output will be ``" Django "``. + .. templatefilter:: cut cut @@ -1194,6 +1212,13 @@ Escapes characters for use in JavaScript strings. This does *not* make the string safe for use in HTML, but does protect you from syntax errors when using templates to generate JavaScript/JSON. +For example:: + + {{ value|escapejs }} + +If ``value`` is ``"testing\r\njavascript \'string" escaping"``, +the output will be ``"testing\\x0D\\x0Ajavascript \\x27string\\x22 \\x3Cb\\x3Eescaping\\x3C/b\\x3E"``. + .. templatefilter:: filesizeformat filesizeformat @@ -1320,6 +1345,12 @@ strings containing non-ASCII characters in a URL. It's safe to use this filter on a string that has already gone through the ``urlencode`` filter. +For example:: + + {{ value|iriencode }} + +If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&me=2"``. + .. templatefilter:: join join @@ -1400,6 +1431,13 @@ linebreaksbr Converts all newlines in a piece of plain text to HTML line breaks (``
``). +For example:: + + {{ value|linebreaksbr }} + +If ``value`` is ``Joel\nis a slug``, the output will be ``Joel
is a +slug``. + .. templatefilter:: linenumbers linenumbers @@ -1407,6 +1445,22 @@ linenumbers Displays text with line numbers. +For example:: + + {{ value|linenumbers }} + +If ``value`` is:: + + one + two + three + +the output will be:: + + 1. one + 2. two + 3. three + .. templatefilter:: ljust ljust @@ -1416,6 +1470,12 @@ Left-aligns the value in a field of a given width. **Argument:** field size +For example:: + + "{{ value|ljust:"10" }}" + +If ``value`` is ``Django``, the output will be ``"Django "``. + .. templatefilter:: lower lower @@ -1451,12 +1511,17 @@ phone2numeric ~~~~~~~~~~~~~ Converts a phone number (possibly containing letters) to its numerical -equivalent. For example, ``'800-COLLECT'`` will be converted to -``'800-2655328'``. +equivalent. The input doesn't have to be a valid phone number. This will happily convert any string. +For example:: + + {{ value|phone2numeric }} + +If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``. + .. templatefilter:: pluralize pluralize @@ -1468,6 +1533,9 @@ Example:: You have {{ num_messages }} message{{ num_messages|pluralize }}. +If ``num_messages`` is ``1``, the output will be ``You have 1 message.`` +If ``num_messages`` is ``2`` the output will be ``You have 2 messages.`` + For words that require a suffix other than ``'s'``, you can provide an alternate suffix as a parameter to the filter. @@ -1527,6 +1595,12 @@ Right-aligns the value in a field of a given width. **Argument:** field size +For example:: + + "{{ value|rjust:"10" }}" + +If ``value`` is ``Django``, the output will be ``" Django"``. + .. templatefilter:: safe safe @@ -1565,6 +1639,8 @@ Example:: {{ some_list|slice:":2" }} +If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``. + .. templatefilter:: slugify slugify @@ -1684,6 +1760,12 @@ title Converts a string into titlecase. +For example:: + + {{ value|title }} + +If ``value`` is ``"my first post"``, the output will be ``"My First Post"``. + .. templatefilter:: truncatewords truncatewords @@ -1711,6 +1793,13 @@ closed immediately after the truncation. This is less efficient than ``truncatewords``, so should only be used when it is being passed HTML text. +For example:: + + {{ value|truncatewords_html:2 }} + +If ``value`` is ``"

Joel is a slug

"``, the output will be +``"

Joel is ...

"``. + .. templatefilter:: unordered_list unordered_list @@ -1761,6 +1850,13 @@ urlencode Escapes a value for use in a URL. +For example:: + + {{ value|urlencode }} + +If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be +``"http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``. + .. templatefilter:: urlize urlize @@ -1806,6 +1902,12 @@ wordcount Returns the number of words. +For example:: + + {{ value|wordcount }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``4``. + .. templatefilter:: wordwrap wordwrap