p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Reformatted docs/templates.txt to put headings in filter and tag references, so each tag/filter gets a permalink 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1110 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2005-11-06 23:30:06 +00:00
parent 5defabca11
commit 92241e21b8
1 changed files with 586 additions and 453 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
docs/templates.txt
View File

@ -289,18 +289,23 @@ available, and what they do.
Built-in tag reference Built-in tag reference
---------------------- ----------------------
``block`` block
Define a block that can be overridden by child templates. See `Template ~~~~~
inheritance`_ for more information.
Define a block that can be overridden by child templates. See
`Template inheritance`_ for more information.
comment
~~~~~~~
``comment``
Ignore everything between ``{% comment %}`` and ``{% endcomment %}`` Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
``cycle`` cycle
~~~~~
Cycle among the given strings each time this tag is encountered. Cycle among the given strings each time this tag is encountered.
Within a loop, cycles among the given strings each time through Within a loop, cycles among the given strings each time through the loop::
the loop::
{% for o in some_list %} {% for o in some_list %}
<tr class="{% cycle row1,row2 %}"> <tr class="{% cycle row1,row2 %}">
@ -318,11 +323,15 @@ Built-in tag reference
You can use any number of values, separated by commas. Make sure not to put You can use any number of values, separated by commas. Make sure not to put
spaces between the values -- only commas. spaces between the values -- only commas.
``debug`` debug
~~~~~
Output a whole load of debugging information, including the current context and Output a whole load of debugging information, including the current context and
imported modules. imported modules.
``extends`` extends
~~~~~~~
Signal that this template extends a parent template. Signal that this template extends a parent template.
This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
@ -332,7 +341,9 @@ Built-in tag reference
See `Template inheritance`_ for more information. See `Template inheritance`_ for more information.
``filter`` filter
~~~~~~
Filter the contents of the variable through variable filters. Filter the contents of the variable through variable filters.
Filters can also be piped through each other, and they can have arguments -- Filters can also be piped through each other, and they can have arguments --
@ -344,7 +355,9 @@ Built-in tag reference
This text will be HTML-escaped, and will appear in all lowercase. This text will be HTML-escaped, and will appear in all lowercase.
{% endfilter %} {% endfilter %}
``firstof`` firstof
~~~~~~~
Outputs the first variable passed that is not False. Outputs nothing if all the Outputs the first variable passed that is not False. Outputs nothing if all the
passed variables are False. passed variables are False.
@ -362,9 +375,9 @@ Built-in tag reference
{{ var3 }} {{ var3 }}
{% endif %}{% endif %}{% endif %} {% endif %}{% endif %}{% endif %}
but obviously much cleaner! for
~~~
``for``
Loop over each item in an array. For example, to display a list of athletes Loop over each item in an array. For example, to display a list of athletes
given ``athlete_list``:: given ``athlete_list``::
@ -393,7 +406,9 @@ Built-in tag reference
current one current one
========================== ================================================ ========================== ================================================
``if`` if
~~
The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
exists, is not empty, and is not a false boolean value) the contents of the exists, is not empty, and is not a false boolean value) the contents of the
block are output:: block are output::
@ -437,7 +452,9 @@ Built-in tag reference
{% endif %} {% endif %}
{% endif %} {% endif %}
``ifchanged`` ifchanged
~~~~~~~~~
Check if a value has changed from the last iteration of a loop. Check if a value has changed from the last iteration of a loop.
The 'ifchanged' block tag is used within a loop. It checks its own rendered The 'ifchanged' block tag is used within a loop. It checks its own rendered
@ -451,7 +468,9 @@ Built-in tag reference
<a href="{{ day|date:"M/d"|lower }}/">{{ day|date:"j" }}</a> <a href="{{ day|date:"M/d"|lower }}/">{{ day|date:"j" }}</a>
{% endfor %} {% endfor %}
``ifequal`` ifequal
~~~~~~~
Output the contents of the block if the two arguments equal each other. Output the contents of the block if the two arguments equal each other.
Example:: Example::
@ -468,15 +487,21 @@ Built-in tag reference
... ...
{% endifequal %} {% endifequal %}
``ifnotequal`` ifnotequal
~~~~~~~~~~
Just like ``ifequal``, except it tests that the two arguments are not equal. Just like ``ifequal``, except it tests that the two arguments are not equal.
``load`` load
~~~~
Load a custom template tag set. Load a custom template tag set.
See `Custom tag and filter libraries`_ for more information. See `Custom tag and filter libraries`_ for more information.
``now`` now
~~~
Display the date, formatted according to the given string. Display the date, formatted according to the given string.
Uses the same format as PHP's ``date()`` function (http://php.net/date) Uses the same format as PHP's ``date()`` function (http://php.net/date)
@ -556,7 +581,9 @@ Built-in tag reference
(Displays "It is the 4th of September" %} (Displays "It is the 4th of September" %}
``regroup`` regroup
~~~~~~~
Regroup a list of alike objects by a common attribute. Regroup a list of alike objects by a common attribute.
This complex tag is best illustrated by use of an example: say that ``people`` This complex tag is best illustrated by use of an example: say that ``people``
@ -599,7 +626,9 @@ Built-in tag reference
{% regroup people|dictsort:"gender" by gender as grouped %} {% regroup people|dictsort:"gender" by gender as grouped %}
``ssi`` ssi
~~~
Output the contents of a given file into the page. Output the contents of a given file into the page.
Like a simple "include" tag, ``{% ssi %}`` includes the contents of another Like a simple "include" tag, ``{% ssi %}`` includes the contents of another
@ -618,8 +647,10 @@ Built-in tag reference
.. _ALLOWED_INCLUDE_ROOTS: http://www.djangoproject.com/documentation/settings/#allowed-include-roots .. _ALLOWED_INCLUDE_ROOTS: http://www.djangoproject.com/documentation/settings/#allowed-include-roots
``templatetag`` templatetag
Output one of the bits used to compose template tags. ~~~~~~~~~~~
Output one of the syntax characters used to compose template tags.
Since the template system has no concept of "escaping", to display one of the Since the template system has no concept of "escaping", to display one of the
bits used in template tags, you must use the ``{% templatetag %}`` tag. bits used in template tags, you must use the ``{% templatetag %}`` tag.
@ -635,7 +666,9 @@ Built-in tag reference
``closevariable`` ``}}`` ``closevariable`` ``}}``
================== ======= ================== =======
``widthratio`` widthratio
~~~~~~~~~~
For creating bar charts and such, this tag calculates the ratio of a given value For creating bar charts and such, this tag calculates the ratio of a given value
to a maximum value, and then applies that ratio to a constant. to a maximum value, and then applies that ratio to a constant.
@ -650,154 +683,241 @@ Built-in tag reference
Built-in filter reference Built-in filter reference
------------------------- -------------------------
``add`` add
~~~
Adds the arg to the value. Adds the arg to the value.
``addslashes`` addslashes
~~~~~~~~~~
Adds slashes. Useful for passing strings to JavaScript, for example. Adds slashes. Useful for passing strings to JavaScript, for example.
``capfirst``
capfirst
~~~~~~~~
Capitalizes the first character of the value. Capitalizes the first character of the value.
``center`` center
~~~~~~
Centers the value in a field of a given width. Centers the value in a field of a given width.
``cut`` cut
~~~
Removes all values of arg from the given string. Removes all values of arg from the given string.
``date`` date
~~~~
Formats a date according to the given format (same as the ``now`` tag). Formats a date according to the given format (same as the ``now`` tag).
``default`` default
~~~~~~~
If value is unavailable, use given default. If value is unavailable, use given default.
``default_if_none`` default_if_none
~~~~~~~~~~~~~~~
If value is ``None``, use given default. If value is ``None``, use given default.
``dictsort`` dictsort
~~~~~~~~
Takes a list of dicts, returns that list sorted by the property given in the Takes a list of dicts, returns that list sorted by the property given in the
argument. argument.
``dictsortreversed`` dictsortreversed
Takes a list of dicts, returns that list sorted in reverse order by the property ~~~~~~~~~~~~~~~~
given in the argument.
Takes a list of dicts, returns that list sorted in reverse order by the
property given in the argument.
divisibleby
~~~~~~~~~~~
``divisibleby``
Returns true if the value is divisible by the argument. Returns true if the value is divisible by the argument.
``escape`` escape
Escapes a string's HTML. ~~~~~~
Escapes a string's HTML. Specifically, it makes these replacements:
* ``"&"`` to ``"&amp;"``
* ``<`` to ``"&lt;"``
* ``>`` to ``"&gt;"``
* ``'"'`` (double quote) to ``"&quot;"``
filesizeformat
~~~~~~~~~~~~~~
``filesizeformat``
Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102 Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
bytes, etc). bytes, etc).
``first`` first
~~~~~
Returns the first item in a list. Returns the first item in a list.
``fix_ampersands`` fix_ampersands
~~~~~~~~~~~~~~
Replaces ampersands with ``&amp;`` entities. Replaces ampersands with ``&amp;`` entities.
``floatformat`` floatformat
Displays a floating point number as 34.2 (with one decimal places) - but
only if there's a point to be displayed. Displays a floating point number as 34.2 (with one decimal places) -- but only
if there's a point to be displayed.
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 of it, where 1 is the
right-most digit, 2 is the second-right-most digit, etc. Returns the right-most digit, 2 is the second-right-most digit, etc. Returns the original
original value for invalid input (if input or argument is not an integer, value for invalid input (if input or argument is not an integer, or if argument
or if argument is less than 1). Otherwise, output is always an integer. is less than 1). Otherwise, output is always an integer.
join
~~~~
``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)``.
``length`` length
~~~~~~
Returns the length of the value. Useful for lists. Returns the length of the value. Useful for lists.
``length_is`` length_is
~~~~~~~~~
Returns a boolean of whether the value's length is the argument. Returns a boolean of whether the value's length is the argument.
``linebreaks`` linebreaks
~~~~~~~~~~
Converts newlines into <p> and <br />s. Converts newlines into <p> and <br />s.
``linebreaksbr`` linebreaksbr
~~~~~~~~~~~~
Converts newlines into <br />s. Converts newlines into <br />s.
``linenumbers`` linenumbers
~~~~~~~~~~~
Displays text with line numbers. Displays text with line numbers.
``ljust`` ljust
~~~~~
Left-aligns the value in a field of a given width. Left-aligns the value in a field of a given width.
**Argument:** field size **Argument:** field size
``lower`` lower
~~~~~
Converts a string into all lowercase. Converts a string into all lowercase.
``make_list`` make_list
~~~~~~~~~
Returns the value turned into a list. For an integer, it's a list of 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. digits. For a string, it's a list of characters.
``phone2numeric`` phone2numeric
Takes a phone number and converts it in to its numerical equivalent. ~~~~~~~~~~~~~
Converts a phone number to its numerical equivalent.
pluralize
~~~~~~~~~
``pluralize``
Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'. Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'.
``pprint`` pprint
~~~~~~
A wrapper around pprint.pprint -- for debugging, really. A wrapper around pprint.pprint -- for debugging, really.
``random`` random
~~~~~~
Returns a random item from the list. Returns a random item from the list.
``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.
``rjust`` rjust
~~~~~
Right-aligns the value in a field of a given width. Right-aligns the value in a field of a given width.
**Argument:** field size **Argument:** field size
``slice`` slice
~~~~~
Returns a slice of the list. Returns a slice of the list.
Uses the same syntax as Python's list slicing; see Uses the same syntax as Python's list slicing. See
http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
for an introduction. for an introduction.
Example: ``{{ some_list|slice:":2" }}`` Example: ``{{ some_list|slice:":2" }}``
``slugify`` slugify
Converts to lowercase, removes non-word characters (alphanumerics and ~~~~~~~
underscores) and converts spaces to hyphens. Also strips leading and
trailing whitespace. Converts to lowercase, removes non-word characters (alphanumerics and
underscores) and converts spaces to hyphens. Also strips leading and trailing
whitespace.
stringformat
~~~~~~~~~~~~
``stringformat``
Formats the variable according to the argument, a string formatting specifier. Formats the variable according to the argument, a string formatting specifier.
This specifier uses Python string formating syntax, with the exception that This specifier uses Python string formating syntax, with the exception that
the leading "%" is dropped. the leading "%" is dropped.
See http://docs.python.org/lib/typesseq-strings.html for documentation See http://docs.python.org/lib/typesseq-strings.html for documentation of
of Python string formatting Python string formatting
striptags
~~~~~~~~~
``striptags``
Strips all [X]HTML tags. Strips all [X]HTML tags.
``time`` time
~~~~
Formats a time according to the given format (same as the ``now`` tag). Formats a time according to the given format (same as the ``now`` tag).
``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 (i.e. "4 days, 6 hours").
``title`` title
~~~~~
Converts a string into titlecase. Converts a string into titlecase.
``truncatewords`` truncatewords
~~~~~~~~~~~~~
Truncates a string after a certain number of words. Truncates a string after a certain number of words.
**Argument:** Number of words to truncate after **Argument:** Number of words to truncate after
``unordered_list`` 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.
@ -817,30 +937,43 @@ Built-in filter reference
</ul> </ul>
</li> </li>
``upper`` upper
~~~~~
Converts a string into all uppercase. Converts a string into all uppercase.
``urlencode`` urlencode
~~~~~~~~~
Escapes a value for use in a URL. Escapes a value for use in a URL.
``urlize`` urlize
~~~~~~
Converts URLs in plain text into clickable links. Converts URLs in plain text into clickable links.
``urlizetrunc`` urlizetrunc
Converts URLs into clickable links, truncating URLs to the given character ~~~~~~~~~~~
limit.
Converts URLs into clickable links, truncating URLs to the given character limit.
**Argument:** Length to truncate URLs to **Argument:** Length to truncate URLs to
``wordcount`` wordcount
~~~~~~~~~
Returns the number of words. Returns the number of words.
``wordwrap`` wordwrap
~~~~~~~~
Wraps words at specified line length. Wraps words at specified line length.
**Argument:** number of words at which to wrap the text **Argument:** number of words at which to wrap the text
``yesno`` yesno
~~~~~
Given a string mapping values for true, false and (optionally) None, Given a string mapping values for true, false and (optionally) None,
returns one of those strings according to the value: returns one of those strings according to the value: