diff options
Diffstat (limited to 'parts/django/docs/ref/templates/builtins.txt')
| -rw-r--r-- | parts/django/docs/ref/templates/builtins.txt | 2107 |
1 files changed, 2107 insertions, 0 deletions
diff --git a/parts/django/docs/ref/templates/builtins.txt b/parts/django/docs/ref/templates/builtins.txt new file mode 100644 index 0000000..44bbc37 --- /dev/null +++ b/parts/django/docs/ref/templates/builtins.txt @@ -0,0 +1,2107 @@ +================================== +Built-in template tags and filters +================================== + +This document describes Django's built-in template tags and filters. It is +recommended that you use the :doc:`automatic documentation +</ref/contrib/admin/admindocs>`, if available, as this will also include +documentation for any custom tags or filters installed. + +.. _ref-templates-builtins-tags: + +Built-in tag reference +---------------------- + +.. highlightlang:: html+django + +.. templatetag:: autoescape + +autoescape +~~~~~~~~~~ + +.. versionadded:: 1.0 + +Control the current auto-escaping behavior. This tag takes either ``on`` or +``off`` as an argument and that determines whether auto-escaping is in effect +inside the block. The block is closed with an ``endautoescape`` ending tag. + +When auto-escaping is in effect, all variable content has HTML escaping applied +to it before placing the result into the output (but after any filters have +been applied). This is equivalent to manually applying the ``escape`` filter +to each variable. + +The only exceptions are variables that are already marked as "safe" from +escaping, either by the code that populated the variable, or because it has had +the ``safe`` or ``escape`` filters applied. + +Sample usage:: + + {% autoescape on %} + {{ body }} + {% endautoescape %} + +.. templatetag:: block + +block +~~~~~ + +Define a block that can be overridden by child templates. See +:ref:`Template inheritance <template-inheritance>` for more information. + +.. templatetag:: comment + +comment +~~~~~~~ + +Ignore everything between ``{% comment %}`` and ``{% endcomment %}`` + +.. templatetag:: csrf_token + +csrf_token +~~~~~~~~~~ + +.. versionadded:: 1.1.2 + +In the Django 1.1.X series, this is a no-op tag that returns an empty string for +future compatibility purposes. In Django 1.2 and later, it is used for CSRF +protection, as described in the documentation for :doc:`Cross Site Request +Forgeries </ref/contrib/csrf>`. + +.. templatetag:: cycle + +cycle +~~~~~ + +.. versionchanged:: 1.0 + Cycle among the given strings or variables each time this tag is encountered. + +Within a loop, cycles among the given strings each time through the +loop:: + + {% for o in some_list %} + <tr class="{% cycle 'row1' 'row2' %}"> + ... + </tr> + {% endfor %} + +You can use variables, too. For example, if you have two template variables, +``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this:: + + {% for o in some_list %} + <tr class="{% cycle rowvalue1 rowvalue2 %}"> + ... + </tr> + {% endfor %} + +Yes, you can mix variables and strings:: + + {% for o in some_list %} + <tr class="{% cycle 'row1' rowvalue2 'row3' %}"> + ... + </tr> + {% endfor %} + +In some cases you might want to refer to the next value of a cycle from +outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using +"as", like this:: + + {% cycle 'row1' 'row2' as rowcolors %} + +From then on, you can insert the current value of the cycle wherever you'd like +in your template:: + + <tr class="{% cycle rowcolors %}">...</tr> + <tr class="{% cycle rowcolors %}">...</tr> + +You can use any number of values in a ``{% cycle %}`` tag, separated by spaces. +Values enclosed in single (``'``) or double quotes (``"``) are treated as +string literals, while values without quotes are treated as template variables. + +Note that the variables included in the cycle will not be escaped. +This is because template tags do not escape their content. Any HTML or +Javascript code contained in the printed variable will be rendered +as-is, which could potentially lead to security issues. + +If you need to escape the variables in the cycle, you must do so +explicitly:: + + {% filter force_escape %} + {% cycle var1 var2 var3 %} + {% endfilter %} + +For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior +old syntax from previous Django versions. You shouldn't use this in any new +projects, but for the sake of the people who are still using it, here's what it +looks like:: + + {% cycle row1,row2,row3 %} + +In this syntax, each value gets interpreted as a literal string, and there's no +way to specify variable values. Or literal commas. Or spaces. Did we mention +you shouldn't use this syntax in any new projects? + +.. templatetag:: debug + +debug +~~~~~ + +Output a whole load of debugging information, including the current context and +imported modules. + +.. templatetag:: extends + +extends +~~~~~~~ + +Signal that this template extends a parent template. + +This tag can be used in two ways: + + * ``{% extends "base.html" %}`` (with quotes) uses the literal value + ``"base.html"`` as the name of the parent template to extend. + + * ``{% extends variable %}`` uses the value of ``variable``. If the variable + evaluates to a string, Django will use that string as the name of the + parent template. If the variable evaluates to a ``Template`` object, + Django will use that object as the parent template. + +See :ref:`template-inheritance` for more information. + +.. templatetag:: filter + +filter +~~~~~~ + +Filter the contents of the variable through variable filters. + +Filters can also be piped through each other, and they can have arguments -- +just like in variable syntax. + +Sample usage:: + + {% filter force_escape|lower %} + This text will be HTML-escaped, and will appear in all lowercase. + {% endfilter %} + +.. templatetag:: firstof + +firstof +~~~~~~~ + +Outputs the first variable passed that is not False, without escaping. + +Outputs nothing if all the passed variables are False. + +Sample usage:: + + {% firstof var1 var2 var3 %} + +This is equivalent to:: + + {% if var1 %} + {{ var1|safe }} + {% else %}{% if var2 %} + {{ var2|safe }} + {% else %}{% if var3 %} + {{ var3|safe }} + {% endif %}{% endif %}{% endif %} + +You can also use a literal string as a fallback value in case all +passed variables are False:: + + {% firstof var1 var2 var3 "fallback value" %} + +Note that the variables included in the firstof tag will not be +escaped. This is because template tags do not escape their content. +Any HTML or Javascript code contained in the printed variable will be +rendered as-is, which could potentially lead to security issues. + +If you need to escape the variables in the firstof tag, you must do so +explicitly:: + + {% filter force_escape %} + {% firstof var1 var2 var3 "fallback value" %} + {% endfilter %} + +.. templatetag:: for + +for +~~~ + +Loop over each item in an array. For example, to display a list of athletes +provided in ``athlete_list``:: + + <ul> + {% for athlete in athlete_list %} + <li>{{ athlete.name }}</li> + {% endfor %} + </ul> + +You can loop over a list in reverse by using ``{% for obj in list reversed %}``. + +.. versionadded:: 1.0 + +If you need to loop over a list of lists, you can unpack the values +in each sub-list into individual variables. For example, if your context +contains a list of (x,y) coordinates called ``points``, you could use the +following to output the list of points:: + + {% for x, y in points %} + There is a point at {{ x }},{{ y }} + {% endfor %} + +This can also be useful if you need to access the items in a dictionary. +For example, if your context contained a dictionary ``data``, the following +would display the keys and values of the dictionary:: + + {% for key, value in data.items %} + {{ key }}: {{ value }} + {% endfor %} + +The for loop sets a number of variables available within the loop: + + ========================== ================================================ + Variable Description + ========================== ================================================ + ``forloop.counter`` The current iteration of the loop (1-indexed) + ``forloop.counter0`` The current iteration of the loop (0-indexed) + ``forloop.revcounter`` The number of iterations from the end of the + loop (1-indexed) + ``forloop.revcounter0`` The number of iterations from the end of the + loop (0-indexed) + ``forloop.first`` True if this is the first time through the loop + ``forloop.last`` True if this is the last time through the loop + ``forloop.parentloop`` For nested loops, this is the loop "above" the + current one + ========================== ================================================ + +for ... empty +^^^^^^^^^^^^^ + +.. versionadded:: 1.1 + +The ``for`` tag can take an optional ``{% empty %}`` clause that will be +displayed if the given array is empty or could not be found:: + + <ul> + {% for athlete in athlete_list %} + <li>{{ athlete.name }}</li> + {% empty %} + <li>Sorry, no athlete in this list!</li> + {% endfor %} + <ul> + +The above is equivalent to -- but shorter, cleaner, and possibly faster +than -- the following:: + + <ul> + {% if athlete_list %} + {% for athlete in athlete_list %} + <li>{{ athlete.name }}</li> + {% endfor %} + {% else %} + <li>Sorry, no athletes in this list.</li> + {% endif %} + </ul> + +.. templatetag:: if + +if +~~ + +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 +block are output:: + + {% if athlete_list %} + Number of athletes: {{ athlete_list|length }} + {% else %} + No athletes. + {% endif %} + +In the above, if ``athlete_list`` is not empty, the number of athletes will be +displayed by the ``{{ athlete_list|length }}`` variable. + +As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that +will be displayed if the test fails. + +Boolean operators +^^^^^^^^^^^^^^^^^ + +``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or +to negate a given variable:: + + {% if athlete_list and coach_list %} + Both athletes and coaches are available. + {% endif %} + + {% if not athlete_list %} + There are no athletes. + {% endif %} + + {% if athlete_list or coach_list %} + There are some athletes or some coaches. + {% endif %} + + {% if not athlete_list or coach_list %} + There are no athletes or there are some coaches (OK, so + writing English translations of boolean logic sounds + stupid; it's not our fault). + {% endif %} + + {% if athlete_list and not coach_list %} + There are some athletes and absolutely no coaches. + {% endif %} + +.. versionchanged:: 1.2 + +Use of both ``and`` and ``or`` clauses within the same tag is allowed, with +``and`` having higher precedence than ``or`` e.g.:: + + {% if athlete_list and coach_list or cheerleader_list %} + +will be interpreted like: + +.. code-block:: python + + if (athlete_list and coach_list) or cheerleader_list + +Use of actual brackets in the ``if`` tag is invalid syntax. If you need them to +indicate precedence, you should use nested ``if`` tags. + +.. versionadded:: 1.2 + + +``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``, +``<=``, ``>=`` and ``in`` which work as follows: + + +``==`` operator +^^^^^^^^^^^^^^^ + +Equality. Example:: + + {% if somevar == "x" %} + This appears if variable somevar equals the string "x" + {% endif %} + +``!=`` operator +^^^^^^^^^^^^^^^ + +Inequality. Example:: + + {% if somevar != "x" %} + This appears if variable somevar does not equal the string "x", + or if somevar is not found in the context + {% endif %} + +``<`` operator +^^^^^^^^^^^^^^ + +Less than. Example:: + + {% if somevar < 100 %} + This appears if variable somevar is less than 100. + {% endif %} + +``>`` operator +^^^^^^^^^^^^^^ + +Greater than. Example:: + + {% if somevar > 0 %} + This appears if variable somevar is greater than 0. + {% endif %} + +``<=`` operator +^^^^^^^^^^^^^^^ + +Less than or equal to. Example:: + + {% if somevar <= 100 %} + This appears if variable somevar is less than 100 or equal to 100. + {% endif %} + +``>=`` operator +^^^^^^^^^^^^^^^ + +Greater than or equal to. Example:: + + {% if somevar >= 1 %} + This appears if variable somevar is greater than 1 or equal to 1. + {% endif %} + +``in`` operator +^^^^^^^^^^^^^^^ + +Contained within. This operator is supported by many Python containers to test +whether the given value is in the container. The following are some examples of +how ``x in y`` will be interpreted:: + + {% if "bc" in "abcdef" %} + This appears since "bc" is a substring of "abcdef" + {% endif %} + + {% if "hello" in greetings %} + If greetings is a list or set, one element of which is the string + "hello", this will appear. + {% endif %} + + {% if user in users %} + If users is a QuerySet, this will appear if user is an + instance that belongs to the QuerySet. + {% endif %} + +``not in`` operator +~~~~~~~~~~~~~~~~~~~~ + +Not contained within. This is the negation of the ``in`` operator. + + +The comparison operators cannot be 'chained' like in Python or in mathematical +notation. For example, instead of using:: + + {% if a > b > c %} (WRONG) + +you should use:: + + {% if a > b and b > c %} + + +Filters +^^^^^^^ + +You can also use filters in the ``if`` expression. For example:: + + {% if messages|length >= 100 %} + You have lots of messages today! + {% endif %} + +Complex expressions +^^^^^^^^^^^^^^^^^^^ + +All of the above can be combined to form complex expressions. For such +expressions, it can be important to know how the operators are grouped when the +expression is evaluated - that is, the precedence rules. The precedence of the +operators, from lowest to highest, is as follows: + + * ``or`` + * ``and`` + * ``not`` + * ``in`` + * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=`` + +(This follows Python exactly). So, for example, the following complex if tag: + + {% if a == b or c == d and e %} + +...will be interpreted as: + +.. code-block:: python + + (a == b) or ((c == d) and e) + +If you need different precedence, you will need to use nested if tags. Sometimes +that is better for clarity anyway, for the sake of those who do not know the +precedence rules. + + +.. templatetag:: ifchanged + +ifchanged +~~~~~~~~~ + +Check if a value has changed from the last iteration of a loop. + +The 'ifchanged' block tag is used within a loop. It has two possible uses. + +1. Checks its own rendered contents against its previous state and only + displays the content if it has changed. For example, this displays a list of + days, only displaying the month if it changes:: + + <h1>Archive for {{ year }}</h1> + + {% for date in days %} + {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %} + <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a> + {% endfor %} + +2. If given a variable, check whether that variable has changed. For + example, the following shows the date every time it changes, but + only shows the hour if both the hour and the date has changed:: + + {% for date in days %} + {% ifchanged date.date %} {{ date.date }} {% endifchanged %} + {% ifchanged date.hour date.date %} + {{ date.hour }} + {% endifchanged %} + {% endfor %} + +The ``ifchanged`` tag can also take an optional ``{% else %}`` clause that +will be displayed if the value has not changed:: + + {% for match in matches %} + <div style="background-color: + {% ifchanged match.ballot_id %} + {% cycle "red" "blue" %} + {% else %} + grey + {% endifchanged %} + ">{{ match }}</div> + {% endfor %} + +.. templatetag:: ifequal + +ifequal +~~~~~~~ + +Output the contents of the block if the two arguments equal each other. + +Example:: + + {% ifequal user.id comment.user_id %} + ... + {% endifequal %} + +As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional. + +The arguments can be hard-coded strings, so the following is valid:: + + {% ifequal user.username "adrian" %} + ... + {% endifequal %} + +It is only possible to compare an argument to template variables or strings. +You cannot check for equality with Python objects such as ``True`` or +``False``. If you need to test if something is true or false, use the ``if`` +tag instead. + +.. versionadded:: 1.2 + An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator. + +.. templatetag:: ifnotequal + +ifnotequal +~~~~~~~~~~ + +Just like ``ifequal``, except it tests that the two arguments are not equal. + +.. versionadded:: 1.2 + An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and the ``!=`` operator. + +.. templatetag:: include + +include +~~~~~~~ + +Loads a template and renders it with the current context. This is a way of +"including" other templates within a template. + +The template name can either be a variable or a hard-coded (quoted) string, +in either single or double quotes. + +This example includes the contents of the template ``"foo/bar.html"``:: + + {% include "foo/bar.html" %} + +This example includes the contents of the template whose name is contained in +the variable ``template_name``:: + + {% include template_name %} + +An included template is rendered with the context of the template that's +including it. This example produces the output ``"Hello, John"``: + + * Context: variable ``person`` is set to ``"john"``. + * Template:: + + {% include "name_snippet.html" %} + + * The ``name_snippet.html`` template:: + + Hello, {{ person }} + +See also: ``{% ssi %}``. + +.. note:: + The :ttag:`include` tag should be considered as an implementation of + "render this subtemplate and include the HTML", not as "parse this + subtemplate and include its contents as if it were part of the parent". + This means that there is no shared state between included templates -- + each include is a completely independent rendering process. + +.. templatetag:: load + +load +~~~~ + +Load a custom template tag set. + +See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information. + +.. templatetag:: now + +now +~~~ + +Display the current date and/or time, according to the given string. + +Given format can be one of the predefined ones ``DATE_FORMAT``, +``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, +or a custom format, same as the :tfilter:`date` filter. Note that predefined +formats may vary depending on the current locale. + +Example:: + + It is {% now "jS F Y H:i" %} + +Note that you can backslash-escape a format string if you want to use the +"raw" value. In this example, "f" is backslash-escaped, because otherwise +"f" is a format string that displays the time. The "o" doesn't need to be +escaped, because it's not a format character:: + + It is the {% now "jS o\f F" %} + +This would display as "It is the 4th of September". + +.. templatetag:: regroup + +regroup +~~~~~~~ + +Regroup a list of alike objects by a common attribute. + +This complex tag is best illustrated by use of an example: say that ``people`` +is a list of people represented by dictionaries with ``first_name``, +``last_name``, and ``gender`` keys: + +.. code-block:: python + + people = [ + {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'}, + {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, + {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, + {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, + {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, + ] + +...and you'd like to display a hierarchical list that is ordered by gender, +like this: + + * Male: + * George Bush + * Bill Clinton + * Female: + * Margaret Thatcher + * Condoleezza Rice + * Unknown: + * Pat Smith + +You can use the ``{% regroup %}`` tag to group the list of people by gender. +The following snippet of template code would accomplish this:: + + {% regroup people by gender as gender_list %} + + <ul> + {% for gender in gender_list %} + <li>{{ gender.grouper }} + <ul> + {% for item in gender.list %} + <li>{{ item.first_name }} {{ item.last_name }}</li> + {% endfor %} + </ul> + </li> + {% endfor %} + </ul> + +Let's walk through this example. ``{% regroup %}`` takes three arguments: the +list you want to regroup, the attribute to group by, and the name of the +resulting list. Here, we're regrouping the ``people`` list by the ``gender`` +attribute and calling the result ``gender_list``. + +``{% regroup %}`` produces a list (in this case, ``gender_list``) of +**group objects**. Each group object has two attributes: + + * ``grouper`` -- the item that was grouped by (e.g., the string "Male" or + "Female"). + * ``list`` -- a list of all items in this group (e.g., a list of all people + with gender='Male'). + +Note that ``{% regroup %}`` does not order its input! Our example relies on +the fact that the ``people`` list was ordered by ``gender`` in the first place. +If the ``people`` list did *not* order its members by ``gender``, the regrouping +would naively display more than one group for a single gender. For example, +say the ``people`` list was set to this (note that the males are not grouped +together): + +.. code-block:: python + + people = [ + {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, + {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, + {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, + {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'}, + {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, + ] + +With this input for ``people``, the example ``{% regroup %}`` template code +above would result in the following output: + + * Male: + * Bill Clinton + * Unknown: + * Pat Smith + * Female: + * Margaret Thatcher + * Male: + * George Bush + * Female: + * Condoleezza Rice + +The easiest solution to this gotcha is to make sure in your view code that the +data is ordered according to how you want to display it. + +Another solution is to sort the data in the template using the ``dictsort`` +filter, if your data is in a list of dictionaries:: + + {% regroup people|dictsort:"gender" by gender as gender_list %} + +.. templatetag:: spaceless + +spaceless +~~~~~~~~~ + +Removes whitespace between HTML tags. This includes tab +characters and newlines. + +Example usage:: + + {% spaceless %} + <p> + <a href="foo/">Foo</a> + </p> + {% endspaceless %} + +This example would return this HTML:: + + <p><a href="foo/">Foo</a></p> + +Only space between *tags* is removed -- not space between tags and text. In +this example, the space around ``Hello`` won't be stripped:: + + {% spaceless %} + <strong> + Hello + </strong> + {% endspaceless %} + +.. templatetag:: ssi + +ssi +~~~ + +Output the contents of a given file into the page. + +Like a simple "include" tag, ``{% ssi %}`` includes the contents of another +file -- which must be specified using an absolute path -- in the current +page:: + + {% ssi /home/html/ljworld.com/includes/right_generic.html %} + +If the optional "parsed" parameter is given, the contents of the included +file are evaluated as template code, within the current context:: + + {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %} + +Note that if you use ``{% ssi %}``, you'll need to define +:setting:`ALLOWED_INCLUDE_ROOTS` in your Django settings, as a security measure. + +See also: ``{% include %}``. + +.. templatetag:: templatetag + +templatetag +~~~~~~~~~~~ + +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 +bits used in template tags, you must use the ``{% templatetag %}`` tag. + +The argument tells which template bit to output: + + ================== ======= + Argument Outputs + ================== ======= + ``openblock`` ``{%`` + ``closeblock`` ``%}`` + ``openvariable`` ``{{`` + ``closevariable`` ``}}`` + ``openbrace`` ``{`` + ``closebrace`` ``}`` + ``opencomment`` ``{#`` + ``closecomment`` ``#}`` + ================== ======= + +.. templatetag:: url + +url +~~~ + +Returns an absolute path reference (a URL without the domain name) matching a +given view function and optional parameters. This is a way to output links +without violating the DRY principle by having to hard-code URLs in your +templates:: + + {% url path.to.some_view v1 v2 %} + +The first argument is a path to a view function in the format +``package.package.module.function``. Additional arguments are optional and +should be space-separated values that will be used as arguments in the URL. +The example above shows passing positional arguments. Alternatively you may +use keyword syntax:: + + {% url path.to.some_view arg1=v1 arg2=v2 %} + +Do not mix both positional and keyword syntax in a single call. All arguments +required by the URLconf should be present. + +For example, suppose you have a view, ``app_views.client``, whose URLconf +takes a client ID (here, ``client()`` is a method inside the views file +``app_views.py``). The URLconf line might look like this: + +.. code-block:: python + + ('^client/(\d+)/$', 'app_views.client') + +If this app's URLconf is included into the project's URLconf under a path +such as this: + +.. code-block:: python + + ('^clients/', include('project_name.app_name.urls')) + +...then, in a template, you can create a link to this view like this:: + + {% url app_views.client client.id %} + +The template tag will output the string ``/clients/client/123/``. + +.. versionadded:: 1.0 + +If you're using :ref:`named URL patterns <naming-url-patterns>`, you can +refer to the name of the pattern in the ``url`` tag instead of using the +path to the view. + +Note that if the URL you're reversing doesn't exist, you'll get an +:exc:`NoReverseMatch` exception raised, which will cause your site to display an +error page. + +.. versionadded:: 1.0 + +If you'd like to retrieve a URL without displaying it, you can use a slightly +different call:: + + + {% url path.to.view arg arg2 as the_url %} + + <a href="{{ the_url }}">I'm linking to {{ the_url }}</a> + +This ``{% url ... as var %}`` syntax will *not* cause an error if the view is +missing. In practice you'll use this to link to views that are optional:: + + {% url path.to.view as the_url %} + {% if the_url %} + <a href="{{ the_url }}">Link to optional stuff</a> + {% endif %} + +.. versionadded:: 1.1 + +If you'd like to retrieve a namespaced URL, specify the fully qualified name:: + + {% url myapp:view-name %} + +This will follow the normal :ref:`namespaced URL resolution strategy +<topics-http-reversing-url-namespaces>`, including using any hints provided +by the context as to the current application. + +.. versionchanged:: 1.2 + +For backwards compatibility, the ``{% url %}`` tag also supports the +use of commas to separate arguments. You shouldn't use this in any new +projects, but for the sake of the people who are still using it, +here's what it looks like:: + + {% url path.to.view arg,arg2 %} + {% url path.to.view arg, arg2 %} + +This syntax doesn't support the use of literal commas, or or equals +signs. Did we mention you shouldn't use this syntax in any new +projects? + +.. templatetag:: widthratio + +widthratio +~~~~~~~~~~ + +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. + +For example:: + + <img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" /> + +Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the +above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 +which is rounded up to 88). + +.. templatetag:: with + +with +~~~~ + +.. versionadded:: 1.0 + +Caches a complex variable under a simpler name. This is useful when accessing +an "expensive" method (e.g., one that hits the database) multiple times. + +For example:: + + {% with business.employees.count as total %} + {{ total }} employee{{ total|pluralize }} + {% endwith %} + +The populated variable (in the example above, ``total``) is only available +between the ``{% with %}`` and ``{% endwith %}`` tags. + +.. _ref-templates-builtins-filters: + +Built-in filter reference +------------------------- + +.. templatefilter:: add + +add +~~~ + +Adds the argument to the value. + +For example:: + + {{ value|add:"2" }} + +If ``value`` is ``4``, then the output will be ``6``. + +.. versionchanged:: 1.2 + The following behavior didn't exist in previous Django versions. + +This filter will first try to coerce both values to integers. If this fails, +it'll attempt to add the values together anyway. This will work on some data +types (strings, list, etc.) and fail on others. If it fails, the result will +be an empty string. + +For example, if we have:: + + {{ first|add:second }} + +and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the +output will be ``[1, 2, 3, 4, 5, 6]``. + +.. warning:: + + Strings that can be coerced to integers will be **summed**, not + concatenated, as in the first example above. + +.. templatefilter:: addslashes + +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 +~~~~~~~~ + +Capitalizes the first character of the value. + +For example:: + + {{ value|capfirst }} + +If ``value`` is ``"django"``, the output will be ``"Django"``. + +.. templatefilter:: center + +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 +~~~ + +Removes all values of arg from the given string. + +For example:: + + {{ value|cut:" "}} + +If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``. + +.. templatefilter:: date + +date +~~~~ + +Formats a date according to the given format. + +Uses the same format as PHP's ``date()`` function (http://php.net/date) +with some custom extensions. + +Available format strings: + + ================ ======================================== ===================== + Format character Description Example output + ================ ======================================== ===================== + a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` + this is slightly different than PHP's + output, because this includes periods + to match Associated Press style.) + A ``'AM'`` or ``'PM'``. ``'AM'`` + b Month, textual, 3 letters, lowercase. ``'jan'`` + B Not implemented. + c ISO 8601 Format. ``2008-01-02T10:30:00.000123`` + d Day of the month, 2 digits with ``'01'`` to ``'31'`` + leading zeros. + D Day of the week, textual, 3 letters. ``'Fri'`` + f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` + with minutes left off if they're zero. + Proprietary extension. + F Month, textual, long. ``'January'`` + g Hour, 12-hour format without leading ``'1'`` to ``'12'`` + zeros. + G Hour, 24-hour format without leading ``'0'`` to ``'23'`` + zeros. + h Hour, 12-hour format. ``'01'`` to ``'12'`` + H Hour, 24-hour format. ``'00'`` to ``'23'`` + i Minutes. ``'00'`` to ``'59'`` + I Not implemented. + j Day of the month without leading ``'1'`` to ``'31'`` + zeros. + l Day of the week, textual, long. ``'Friday'`` + L Boolean for whether it's a leap year. ``True`` or ``False`` + m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` + M Month, textual, 3 letters. ``'Jan'`` + n Month without leading zeros. ``'1'`` to ``'12'`` + N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` + style. Proprietary extension. + O Difference to Greenwich time in hours. ``'+0200'`` + P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` + 'a.m.'/'p.m.', with minutes left off + if they're zero and the special-case + strings 'midnight' and 'noon' if + appropriate. Proprietary extension. + r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` + s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` + S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` + month, 2 characters. + t Number of days in the given month. ``28`` to ``31`` + T Time zone of this machine. ``'EST'``, ``'MDT'`` + u Microseconds. ``0`` to ``999999`` + U Seconds since the Unix Epoch + (January 1 1970 00:00:00 UTC). + w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) + leading zeros. + W ISO-8601 week number of year, with ``1``, ``53`` + weeks starting on Monday. + y Year, 2 digits. ``'99'`` + Y Year, 4 digits. ``'1999'`` + z Day of the year. ``0`` to ``365`` + Z Time zone offset in seconds. The ``-43200`` to ``43200`` + offset for timezones west of UTC is + always negative, and for those east of + UTC is always positive. + ================ ======================================== ===================== + +.. versionadded:: 1.2 + +The ``c`` and ``u`` format specification characters were added in Django 1.2. + +For example:: + + {{ value|date:"D d M Y" }} + +If ``value`` is a ``datetime`` object (e.g., the result of +``datetime.datetime.now()``), the output will be the string +``'Wed 09 Jan 2008'``. + +The format passed can be one of the predefined ones ``DATE_FORMAT``, +``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, or a +custom format that uses the format specifiers shown in the table above. Note +that predefined formats may vary depending on the current locale. + +Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, +for example, ``"es"``, then for:: + + {{ value|date:"SHORT_DATE_FORMAT" }} + +the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"`` +format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``). + +When used without a format string:: + + {{ value|date }} + +...the formatting string defined in the :setting:`DATE_FORMAT` setting will be +used, without applying any localization. + +.. versionchanged:: 1.2 + Predefined formats can now be influenced by the current locale. + +.. templatefilter:: default + +default +~~~~~~~ + +If value evaluates to ``False``, use given default. Otherwise, use the value. + +For example:: + + {{ value|default:"nothing" }} + +If ``value`` is ``""`` (the empty string), the output will be ``nothing``. + +.. templatefilter:: default_if_none + +default_if_none +~~~~~~~~~~~~~~~ + +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 will be the string ``"nothing"``. + +.. templatefilter:: dictsort + +dictsort +~~~~~~~~ + +Takes a list of dictionaries and returns that list sorted by the key given in +the argument. + +For example:: + + {{ value|dictsort:"name" }} + +If ``value`` is: + +.. code-block:: python + + [ + {'name': 'zed', 'age': 19}, + {'name': 'amy', 'age': 22}, + {'name': 'joe', 'age': 31}, + ] + +then the output would be: + +.. code-block:: python + + [ + {'name': 'amy', 'age': 22}, + {'name': 'joe', 'age': 31}, + {'name': 'zed', 'age': 19}, + ] + +.. templatefilter:: dictsortreversed + +dictsortreversed +~~~~~~~~~~~~~~~~ + +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. + +.. templatefilter:: divisibleby + +divisibleby +~~~~~~~~~~~ + +Returns ``True`` if the value is divisible by the argument. + +For example:: + + {{ value|divisibleby:"3" }} + +If ``value`` is ``21``, the output would be ``True``. + +.. templatefilter:: escape + +escape +~~~~~~ + +Escapes a string's HTML. Specifically, it makes these replacements: + + * ``<`` is converted to ``<`` + * ``>`` is converted to ``>`` + * ``'`` (single quote) is converted to ``'`` + * ``"`` (double quote) is converted to ``"`` + * ``&`` is converted to ``&`` + +The escaping is only applied when the string is output, so it does not matter +where in a chained sequence of filters you put ``escape``: it will always be +applied as though it were the last filter. If you want escaping to be applied +immediately, use the ``force_escape`` filter. + +Applying ``escape`` to a variable that would normally have auto-escaping +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. + +.. versionchanged:: 1.0 + 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. + +.. templatefilter:: escapejs + +escapejs +~~~~~~~~ + +.. versionadded:: 1.0 + +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" <b>escaping</b>"``, +the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E"``. + +.. templatefilter:: filesizeformat + +filesizeformat +~~~~~~~~~~~~~~ + +Format the value like a 'human-readable' file size (i.e. ``'13 KB'``, +``'4.1 MB'``, ``'102 bytes'``, etc). + +For example:: + + {{ value|filesizeformat }} + +If ``value`` is 123456789, the output would be ``117.7 MB``. + +.. templatefilter:: first + +first +~~~~~ + +Returns the first item in a list. + +For example:: + + {{ value|first }} + +If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. + +.. templatefilter:: fix_ampersands + +fix_ampersands +~~~~~~~~~~~~~~ + +.. versionchanged:: 1.0 + This is rarely useful as ampersands are now automatically escaped. See escape_ for more information. + +Replaces ampersands with ``&`` entities. + +For example:: + + {{ value|fix_ampersands }} + +If ``value`` is ``Tom & Jerry``, the output will be ``Tom & Jerry``. + +.. templatefilter:: floatformat + +floatformat +~~~~~~~~~~~ + +When used without an argument, rounds a floating-point number to one decimal +place -- but only if there's a decimal part to be displayed. For example: + +============ =========================== ======== +``value`` Template Output +============ =========================== ======== +``34.23234`` ``{{ value|floatformat }}`` ``34.2`` +``34.00000`` ``{{ value|floatformat }}`` ``34`` +``34.26000`` ``{{ value|floatformat }}`` ``34.3`` +============ =========================== ======== + +If used with a numeric integer argument, ``floatformat`` rounds a number to +that many decimal places. For example: + +============ ============================= ========== +``value`` Template Output +============ ============================= ========== +``34.23234`` ``{{ value|floatformat:3 }}`` ``34.232`` +``34.00000`` ``{{ value|floatformat:3 }}`` ``34.000`` +``34.26000`` ``{{ value|floatformat:3 }}`` ``34.260`` +============ ============================= ========== + +If the argument passed to ``floatformat`` is negative, it will round a number +to that many decimal places -- but only if there's a decimal part to be +displayed. For example: + +============ ================================ ========== +``value`` Template Output +============ ================================ ========== +``34.23234`` ``{{ value|floatformat:"-3" }}`` ``34.232`` +``34.00000`` ``{{ value|floatformat:"-3" }}`` ``34`` +``34.26000`` ``{{ value|floatformat:"-3" }}`` ``34.260`` +============ ================================ ========== + +Using ``floatformat`` with no argument is equivalent to using ``floatformat`` +with an argument of ``-1``. + +.. templatefilter:: force_escape + +force_escape +~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +Applies HTML escaping to a string (see the ``escape`` filter for details). +This filter is applied *immediately* and returns a new, escaped string. This +is useful in the rare cases where you need multiple escaping or want to apply +other filters to the escaped results. Normally, you want to use the ``escape`` +filter. + +.. templatefilter:: get_digit + +get_digit +~~~~~~~~~ + +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 will be ``8``. + +.. templatefilter:: iriencode + +iriencode +~~~~~~~~~ + +Converts an IRI (Internationalized Resource Identifier) to a string that is +suitable for including in a URL. This is necessary if you're trying to use +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 +~~~~ + +Joins a list with a string, like Python's ``str.join(list)`` + +For example:: + + {{ value|join:" // " }} + +If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string +``"a // b // c"``. + +.. templatefilter:: last + +last +~~~~ + +.. versionadded:: 1.0 + +Returns the last item in a list. + +For example:: + + {{ value|last }} + +If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string +``"d"``. + +.. templatefilter:: length + +length +~~~~~~ + +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 will be ``4``. + +.. templatefilter:: length_is + +length_is +~~~~~~~~~ + +Returns ``True`` if the value's length is the argument, or ``False`` otherwise. + +For example:: + + {{ value|length_is:"4" }} + +If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``. + +.. templatefilter:: linebreaks + +linebreaks +~~~~~~~~~~ + +Replaces line breaks in plain text with appropriate HTML; a single +newline becomes an HTML line break (``<br />``) and a new line +followed by a blank line becomes a paragraph break (``</p>``). + +For example:: + + {{ value|linebreaks }} + +If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joel<br />is a +slug</p>``. + +.. templatefilter:: linebreaksbr + +linebreaksbr +~~~~~~~~~~~~ + +Converts all newlines in a piece of plain text to HTML line breaks +(``<br />``). + +For example:: + + {{ value|linebreaksbr }} + +If ``value`` is ``Joel\nis a slug``, the output will be ``Joel<br />is a +slug``. + +.. templatefilter:: linenumbers + +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 +~~~~~ + +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 +~~~~~ + +Converts a string into all lowercase. + +For example:: + + {{ value|lower }} + +If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``. + +.. templatefilter:: make_list + +make_list +~~~~~~~~~ + +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. + +For example:: + + {{ value|make_list }} + +If ``value`` is the string ``"Joel"``, the output would be the list +``[u'J', u'o', u'e', u'l']``. If ``value`` is ``123``, the output will be the +list ``[1, 2, 3]``. + +.. templatefilter:: phone2numeric + +phone2numeric +~~~~~~~~~~~~~ + +Converts a phone number (possibly containing letters) to its numerical +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 +~~~~~~~~~ + +Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. + +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. + +Example:: + + You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}. + +For words that don't pluralize by simple suffix, you can specify both a +singular and plural suffix, separated by a comma. + +Example:: + + You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}. + +.. templatefilter:: pprint + +pprint +~~~~~~ + +A wrapper around `pprint.pprint`__ -- for debugging, really. + +__ http://docs.python.org/library/pprint.html + +.. templatefilter:: random + +random +~~~~~~ + +Returns a random item from the given list. + +For example:: + + {{ value|random }} + +If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``. + +.. templatefilter:: removetags + +removetags +~~~~~~~~~~ + +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 will be ``"Joel <button>is</button> a slug"``. + +Note that this filter is case-sensitive. + +If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the +output will be ``"<B>Joel</B> <button>is</button> a slug"``. + +.. templatefilter:: rjust + +rjust +~~~~~ + +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 +~~~~ + +Marks a string as not requiring further HTML escaping prior to output. When +autoescaping is off, this filter has no effect. + +.. note:: + + If you are chaining filters, a filter applied after ``safe`` can + make the contents unsafe again. For example, the following code + prints the variable as is, unescaped: + + .. code-block:: html+django + + {{ var|safe|escape }} + +.. templatefilter:: safeseq + +safeseq +~~~~~~~ + +Applies the :tfilter:`safe` filter to each element of a sequence. Useful in +conjunction with other filters that operate on sequences, such as +:tfilter:`join`. For example:: + + {{ some_list|safeseq|join:", " }} + +You couldn't use the :tfilter:`safe` filter directly in this case, as it would +first convert the variable into a string, rather than working with the +individual elements of the sequence. + +.. templatefilter:: slice + +slice +~~~~~ + +Returns a slice of the list. + +Uses the same syntax as Python's list slicing. See +http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice +for an introduction. + +Example:: + + {{ some_list|slice:":2" }} + +If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``. + +.. templatefilter:: slugify + +slugify +~~~~~~~ + +Converts to lowercase, removes non-word characters (alphanumerics and +underscores) and converts spaces to hyphens. Also strips leading and trailing +whitespace. + +For example:: + + {{ value|slugify }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``. + +.. templatefilter:: stringformat + +stringformat +~~~~~~~~~~~~ + +Formats the variable according to the argument, a string formatting specifier. +This specifier uses Python string formatting syntax, with the exception that +the leading "%" is dropped. + +See http://docs.python.org/library/stdtypes.html#string-formatting-operations +for documentation of Python string formatting + +For example:: + + {{ value|stringformat:"s" }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``. + +.. templatefilter:: striptags + +striptags +~~~~~~~~~ + +Strips all [X]HTML tags. + +For example:: + + {{ value|striptags }} + +If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the +output will be ``"Joel is a slug"``. + +.. templatefilter:: time + +time +~~~~ + +Formats a time according to the given format. + +Given format can be the predefined one ``TIME_FORMAT``, or a custom format, +same as the :tfilter:`date` filter. Note that the predefined format is locale- +dependant. + +The time filter will only accept parameters in the format string that relate +to the time of day, not the date (for obvious reasons). If you need to +format a date, use the :tfilter:`date` filter. + +For example:: + + {{ value|time:"H:i" }} + +If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be +the string ``"01:23"``. + +Another example: + +Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, +for example, ``"de"``, then for:: + + {{ value|time:"TIME_FORMAT" }} + +the output will be the string ``"01:23:00"`` (The ``"TIME_FORMAT"`` format +specifier for the ``de`` locale as shipped with Django is ``"H:i:s"``). + +When used without a format string:: + + {{ value|time }} + +...the formatting string defined in the :setting:`TIME_FORMAT` setting will be +used, without applying any localization. + +.. versionchanged:: 1.2 + Predefined formats can now be influenced by the current locale. + +.. templatefilter:: timesince + +timesince +~~~~~~~~~ + +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*). +For example, if ``blog_date`` is a date instance representing midnight on 1 +June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006, +then ``{{ blog_date|timesince:comment_date }}`` would return "8 hours". + +Comparing offset-naive and offset-aware datetimes will return an empty string. + +Minutes is the smallest unit used, and "0 minutes" will be returned for any +date that is in the future relative to the comparison point. + +.. templatefilter:: timeuntil + +timeuntil +~~~~~~~~~ + +Similar to ``timesince``, except that it measures the time from now until the +given date or datetime. For example, if today is 1 June 2006 and +``conference_date`` is a date instance holding 29 June 2006, then +``{{ conference_date|timeuntil }}`` will return "4 weeks". + +Takes an optional argument that is a variable containing the date to use as +the comparison point (instead of *now*). If ``from_date`` contains 22 June +2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "1 week". + +Comparing offset-naive and offset-aware datetimes will return an empty string. + +Minutes is the smallest unit used, and "0 minutes" will be returned for any +date that is in the past relative to the comparison point. + +.. templatefilter:: title + +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 +~~~~~~~~~~~~~ + +Truncates a string after a certain number of words. + +**Argument:** Number of words to truncate after + +For example:: + + {{ value|truncatewords:2 }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``. + +Newlines within the string will be removed. + +.. templatefilter:: truncatewords_html + +truncatewords_html +~~~~~~~~~~~~~~~~~~ + +Similar to ``truncatewords``, except that it is aware of HTML tags. Any tags +that are opened in the string and not closed before the truncation point, are +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 ``"<p>Joel is a slug</p>"``, the output will be +``"<p>Joel is ...</p>"``. + +Newlines in the HTML content will be preserved. + +.. templatefilter:: unordered_list + +unordered_list +~~~~~~~~~~~~~~ + +Recursively takes a self-nested list and returns an HTML unordered list -- +WITHOUT opening and closing <ul> tags. + +.. versionchanged:: 1.0 + 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 +``{{ var|unordered_list }}`` would return:: + + <li>States + <ul> + <li>Kansas + <ul> + <li>Lawrence</li> + <li>Topeka</li> + </ul> + </li> + <li>Illinois</li> + </ul> + </li> + +Note: the previous more restrictive and verbose format is still supported: +``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``, + +.. templatefilter:: upper + +upper +~~~~~ + +Converts a string into all uppercase. + +For example:: + + {{ value|upper }} + +If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``. + +.. templatefilter:: urlencode + +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 +~~~~~~ + +Converts URLs in plain text into clickable links. + +Note that if ``urlize`` is applied to text that already contains HTML markup, +things won't work as expected. Apply this filter only to *plain* text. + +For example:: + + {{ value|urlize }} + +If ``value`` is ``"Check out www.djangoproject.com"``, the output will be +``"Check out <a +href="http://www.djangoproject.com">www.djangoproject.com</a>"``. + +.. templatefilter:: urlizetrunc + +urlizetrunc +~~~~~~~~~~~ + +Converts URLs into clickable links, truncating URLs longer than the given +character limit. + +As with urlize_, this filter should only be applied to *plain* text. + +**Argument:** Length to truncate URLs to + +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>'``. + +.. templatefilter:: wordcount + +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 +~~~~~~~~ + +Wraps words at specified line length. + +**Argument:** number of characters at which to wrap the text + +For example:: + + {{ value|wordwrap:5 }} + +If ``value`` is ``Joel is a slug``, the output would be:: + + Joel + is a + slug + +.. templatefilter:: yesno + +yesno +~~~~~ + +Given a string mapping values for true, false and (optionally) None, +returns one of those strings according to the value: + +For example:: + + {{ value|yesno:"yeah,no,maybe" }} + +========== ====================== ================================== +Value Argument Outputs +========== ====================== ================================== +``True`` ``"yeah,no,maybe"`` ``yeah`` +``False`` ``"yeah,no,maybe"`` ``no`` +``None`` ``"yeah,no,maybe"`` ``maybe`` +``None`` ``"yeah,no"`` ``"no"`` (converts None to False + if no mapping for None is given) +========== ====================== ================================== + +Other tags and filter libraries +------------------------------- + +Django comes with a couple of other template-tag libraries that you have to +enable explicitly in your ``INSTALLED_APPS`` setting and enable in your +template with the ``{% load %}`` tag. + +django.contrib.humanize +~~~~~~~~~~~~~~~~~~~~~~~ + +A set of Django template filters useful for adding a "human touch" to data. See +:doc:`/ref/contrib/humanize`. + +django.contrib.markup +~~~~~~~~~~~~~~~~~~~~~ + +A collection of template filters that implement these common markup languages: + + * Textile + * Markdown + * reST (reStructuredText) + +See the :doc:`markup documentation </ref/contrib/markup>`. + +django.contrib.webdesign +~~~~~~~~~~~~~~~~~~~~~~~~ + +A collection of template tags that can be useful while designing a Web site, +such as a generator of Lorem Ipsum text. See :doc:`/ref/contrib/webdesign`. + +i18n +~~~~ + +Provides a couple of templatetags that allow specifying translatable text in +Django templates. It is slightly different from the libraries described +above because you don't need to add any application to the ``INSTALLED_APPS`` +setting but rather set :setting:`USE_I18N` to True, then loading it with +``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`. |