django.template.defaultfilters

module documentation

Default variable filters.

Variable	`register`	Undocumented
Function	`_property_resolver`	When arg is convertible to float, behave like operator.itemgetter(arg) Otherwise, chain __getitem__() and getattr().
Function	`add`	Add the arg to the value.
Function	`addslashes`	Add slashes before quotes. Useful for escaping strings in CSV, for example. Less useful for escaping JavaScript; use the `escapejs` filter instead.
Function	`capfirst`	Capitalize the first character of the value.
Function	`center`	Center the value in a field of a given width.
Function	`cut`	Remove all values of arg from the given string.
Function	`date`	Format a date according to the given format.
Function	`default`	If value is unavailable, use given default.
Function	`default_if_none`	If value is None, use given default.
Function	`dictsort`	Given a list of dicts, return that list sorted by the property given in the argument.
Function	`dictsortreversed`	Given a list of dicts, return that list sorted in reverse order by the property given in the argument.
Function	`divisibleby`	Return True if the value is divisible by the argument.
Function	`escape_filter`	Mark the value as a string that should be auto-escaped.
Function	`escapejs_filter`	Hex encode characters for use in JavaScript strings.
Function	`filesizeformat`	Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102 bytes, etc.).
Function	`first`	Return the first item in a list.
Function	`floatformat`	Display a float to a specified number of decimal places.
Function	`force_escape`	Escape a string's HTML. Return a new string containing the escaped characters (as opposed to "escape", which marks the content for later possible escaping).
Function	`get_digit`	No summary
Function	`iriencode`	Escape an IRI value for use in a URL.
Function	`join`	Join a list with a string, like Python's `str.join(list)`.
Function	`json_script`	Output value JSON-encoded, wrapped in a <script type="application/json"> tag.
Function	`last`	Return the last item in a list.
Function	`length`	Return the length of the value - useful for lists.
Function	`length_is`	Return a boolean of whether the value's length is the argument.
Function	`linebreaks_filter`	Replace 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>`).
Function	`linebreaksbr`	Convert all newlines in a piece of plain text to HTML line breaks (`<br>`).
Function	`linenumbers`	Display text with line numbers.
Function	`ljust`	Left-align the value in a field of a given width.
Function	`lower`	Convert a string into all lowercase.
Function	`make_list`	Return the value turned into a list.
Function	`phone2numeric_filter`	Take a phone number and converts it in to its numerical equivalent.
Function	`pluralize`	Return a plural suffix if the value is not 1, '1', or an object of length 1. By default, use 's' as the suffix:
Function	`pprint`	A wrapper around pprint.pprint -- for debugging, really.
Function	`random`	Return a random item from the list.
Function	`rjust`	Right-align the value in a field of a given width.
Function	`safe`	Mark the value as a string that should not be auto-escaped.
Function	`safeseq`	A "safe" filter for sequences. Mark each element in the sequence, individually, as safe, after converting them to strings. Return a list with the results.
Function	`slice_filter`	Return a slice of the list using the same syntax as Python's list slicing.
Function	`slugify`	Convert to ASCII. Convert spaces to hyphens. Remove characters that aren't alphanumerics, underscores, or hyphens. Convert to lowercase. Also strip leading and trailing whitespace.
Function	`stringfilter`	Decorator for filters which should only receive strings. The object passed as the first positional argument will be converted to a string.
Function	`stringformat`	Format the variable according to the arg, a string formatting specifier.
Function	`striptags`	Strip all [X]HTML tags.
Function	`time`	Format a time according to the given format.
Function	`timesince_filter`	Format a date as the time since that date (i.e. "4 days, 6 hours").
Function	`timeuntil_filter`	Format a date as the time until that date (i.e. "4 days, 6 hours").
Function	`title`	Convert a string into titlecase.
Function	`truncatechars`	Truncate a string after `arg` number of characters.
Function	`truncatechars_html`	Truncate HTML after `arg` number of chars. Preserve newlines in the HTML.
Function	`truncatewords`	Truncate a string after `arg` number of words. Remove newlines within the string.
Function	`truncatewords_html`	Truncate HTML after `arg` number of words. Preserve newlines in the HTML.
Function	`unordered_list`	Recursively take a self-nested list and return an HTML unordered list -- WITHOUT opening and closing <ul> tags.
Function	`upper`	Convert a string into all uppercase.
Function	`urlencode`	Escape a value for use in a URL.
Function	`urlize`	Convert URLs in plain text into clickable links.
Function	`urlizetrunc`	Convert URLs into clickable links, truncating URLs to the given character limit, and adding 'rel=nofollow' attribute to discourage spamming.
Function	`wordcount`	Return the number of words.
Function	`wordwrap`	Wrap words at `arg` line length.
Function	`yesno`	Given a string mapping values for true, false, and (optionally) None, return one of those strings according to the value:

Undocumented

def _property_resolver(arg):

When arg is convertible to float, behave like operator.itemgetter(arg) Otherwise, chain __getitem__() and getattr().

>>> _property_resolver(1)('abc')
'b'
>>> _property_resolver('1')('abc')
Traceback (most recent call last):
...
TypeError: string indices must be integers
>>> class Foo:
...     a = 42
...     b = 3.14
...     c = 'Hey!'
>>> _property_resolver('b')(Foo())
3.14

@register.filter(is_safe=False)
def add(value, arg):

Add the arg to the value.

@register.filter(is_safe=True)
@stringfilter
def addslashes(value):

Add slashes before quotes. Useful for escaping strings in CSV, for example. Less useful for escaping JavaScript; use the escapejs filter instead.

@register.filter(is_safe=True)
@stringfilter
def capfirst(value):

Capitalize the first character of the value.

@register.filter(is_safe=True)
@stringfilter
def center(value, arg):

Center the value in a field of a given width.

@register.filter
@stringfilter
def cut(value, arg):

Remove all values of arg from the given string.

@register.filter(expects_localtime=True, is_safe=False)
def date(value, arg=None):

Format a date according to the given format.

@register.filter(is_safe=False)
def default(value, arg):

If value is unavailable, use given default.

@register.filter(is_safe=False)
def default_if_none(value, arg):

If value is None, use given default.

@register.filter(is_safe=False)
def dictsort(value, arg):

Given a list of dicts, return that list sorted by the property given in the argument.

@register.filter(is_safe=False)
def dictsortreversed(value, arg):

Given a list of dicts, return that list sorted in reverse order by the property given in the argument.

@register.filter(is_safe=False)
def divisibleby(value, arg):

Return True if the value is divisible by the argument.

@register.filter('escape', is_safe=True)
@stringfilter
def escape_filter(value):

Mark the value as a string that should be auto-escaped.

@register.filter('escapejs')
@stringfilter
def escapejs_filter(value):

Hex encode characters for use in JavaScript strings.

@register.filter(is_safe=True)
def filesizeformat(bytes_):

Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102 bytes, etc.).

@register.filter(is_safe=False)
def first(value):

Return the first item in a list.

@register.filter(is_safe=True)
def floatformat(text, arg=-1):

Display a float to a specified number of decimal places.

If called without an argument, display the floating point number with one decimal place -- but only if there's a decimal place to be displayed:

num1 = 34.23234
num2 = 34.00000
num3 = 34.26000
{{ num1|floatformat }} displays "34.2"
{{ num2|floatformat }} displays "34"
{{ num3|floatformat }} displays "34.3"

If arg is positive, always display exactly arg number of decimal places:

{{ num1|floatformat:3 }} displays "34.232"
{{ num2|floatformat:3 }} displays "34.000"
{{ num3|floatformat:3 }} displays "34.260"

If arg is negative, display arg number of decimal places -- but only if there are places to be displayed:

{{ num1|floatformat:"-3" }} displays "34.232"
{{ num2|floatformat:"-3" }} displays "34"
{{ num3|floatformat:"-3" }} displays "34.260"

If arg has the 'g' suffix, force the result to be grouped by the THOUSAND_SEPARATOR for the active locale. When the active locale is en (English):

{{ 6666.6666|floatformat:"2g" }} displays "6,666.67"
{{ 10000|floatformat:"g" }} displays "10,000"

If arg has the 'u' suffix, force the result to be unlocalized. When the active locale is pl (Polish):

{{ 66666.6666|floatformat:"2" }} displays "66666,67"
{{ 66666.6666|floatformat:"2u" }} displays "66666.67"

If the input float is infinity or NaN, display the string representation of that value.

@register.filter(is_safe=True)
@stringfilter
def force_escape(value):

Escape a string's HTML. Return a new string containing the escaped characters (as opposed to "escape", which marks the content for later possible escaping).

@register.filter(is_safe=False)
def get_digit(value, arg):

Given a whole number, return the requested digit of it, where 1 is the right-most digit, 2 is the second-right-most digit, etc. Return 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.

@register.filter(is_safe=True)
@stringfilter
def iriencode(value):

Escape an IRI value for use in a URL.

@register.filter(is_safe=True, needs_autoescape=True)
def join(value, arg, autoescape=True):

Join a list with a string, like Python's str.join(list).

@register.filter(is_safe=True)
def json_script(value, element_id):

Output value JSON-encoded, wrapped in a <script type="application/json"> tag.

@register.filter(is_safe=True)
def last(value):

Return the last item in a list.

@register.filter(is_safe=False)
def length(value):

Return the length of the value - useful for lists.

@register.filter(is_safe=False)
def length_is(value, arg):

Return a boolean of whether the value's length is the argument.

@register.filter('linebreaks', is_safe=True, needs_autoescape=True)
@stringfilter
def linebreaks_filter(value, autoescape=True):

Replace 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>).

@register.filter(is_safe=True, needs_autoescape=True)
@stringfilter
def linebreaksbr(value, autoescape=True):

Convert all newlines in a piece of plain text to HTML line breaks (<br>).

@register.filter(is_safe=True, needs_autoescape=True)
@stringfilter
def linenumbers(value, autoescape=True):

Display text with line numbers.

@register.filter(is_safe=True)
@stringfilter
def ljust(value, arg):

Left-align the value in a field of a given width.

@register.filter(is_safe=True)
@stringfilter
def lower(value):

Convert a string into all lowercase.

@register.filter(is_safe=False)
@stringfilter
def make_list(value):

Return the value turned into a list.

For an integer, it's a list of digits. For a string, it's a list of characters.

@register.filter('phone2numeric', is_safe=True)
def phone2numeric_filter(value):

Take a phone number and converts it in to its numerical equivalent.

@register.filter(is_safe=False)
def pluralize(value, arg='s'):

Return a plural suffix if the value is not 1, '1', or an object of length 1. By default, use 's' as the suffix:

If value is 0, vote{{ value|pluralize }} display "votes".
If value is 1, vote{{ value|pluralize }} display "vote".
If value is 2, vote{{ value|pluralize }} display "votes".

If an argument is provided, use that string instead:

If value is 0, class{{ value|pluralize:"es" }} display "classes".
If value is 1, class{{ value|pluralize:"es" }} display "class".
If value is 2, class{{ value|pluralize:"es" }} display "classes".

If the provided argument contains a comma, use the text before the comma for the singular case and the text after the comma for the plural case:

If value is 0, cand{{ value|pluralize:"y,ies" }} display "candies".
If value is 1, cand{{ value|pluralize:"y,ies" }} display "candy".
If value is 2, cand{{ value|pluralize:"y,ies" }} display "candies".

@register.filter(is_safe=True)
def pprint(value):

A wrapper around pprint.pprint -- for debugging, really.

@register.filter(is_safe=True)
def random(value):

Return a random item from the list.

@register.filter(is_safe=True)
@stringfilter
def rjust(value, arg):

Right-align the value in a field of a given width.

@register.filter(is_safe=True)
@stringfilter
def safe(value):

Mark the value as a string that should not be auto-escaped.

@register.filter(is_safe=True)
def safeseq(value):

A "safe" filter for sequences. Mark each element in the sequence, individually, as safe, after converting them to strings. Return a list with the results.

@register.filter('slice', is_safe=True)
def slice_filter(value, arg):

Return a slice of the list using the same syntax as Python's list slicing.

@register.filter(is_safe=True)
@stringfilter
def slugify(value):

Convert to ASCII. Convert spaces to hyphens. Remove characters that aren't alphanumerics, underscores, or hyphens. Convert to lowercase. Also strip leading and trailing whitespace.

def stringfilter(func):

Decorator for filters which should only receive strings. The object passed as the first positional argument will be converted to a string.

@register.filter(is_safe=True)
def stringformat(value, arg):

Format the variable according to the arg, a string formatting specifier.

This specifier uses Python string formatting syntax, with the exception that the leading "%" is dropped.

See https://docs.python.org/library/stdtypes.html#printf-style-string-formatting for documentation of Python string formatting.

@register.filter(is_safe=True)
@stringfilter
def striptags(value):

Strip all [X]HTML tags.

@register.filter(expects_localtime=True, is_safe=False)
def time(value, arg=None):

Format a time according to the given format.

@register.filter('timesince', is_safe=False)
def timesince_filter(value, arg=None):

Format a date as the time since that date (i.e. "4 days, 6 hours").

@register.filter('timeuntil', is_safe=False)
def timeuntil_filter(value, arg=None):

Format a date as the time until that date (i.e. "4 days, 6 hours").

@register.filter(is_safe=True)
@stringfilter
def title(value):

Convert a string into titlecase.

@register.filter(is_safe=True)
@stringfilter
def truncatechars(value, arg):

Truncate a string after arg number of characters.

@register.filter(is_safe=True)
@stringfilter
def truncatechars_html(value, arg):

Truncate HTML after arg number of chars. Preserve newlines in the HTML.

@register.filter(is_safe=True)
@stringfilter
def truncatewords(value, arg):

Truncate a string after arg number of words. Remove newlines within the string.

@register.filter(is_safe=True)
@stringfilter
def truncatewords_html(value, arg):

Truncate HTML after arg number of words. Preserve newlines in the HTML.

@register.filter(is_safe=True, needs_autoescape=True)
def unordered_list(value, autoescape=True):

Recursively take a self-nested list and return an HTML unordered list -- WITHOUT opening and closing <ul> tags.

Assume the list is in the proper format. For example, if var contains: ['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']], then {{ var|unordered_list }} returns:

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

@register.filter(is_safe=False)
@stringfilter
def upper(value):

Convert a string into all uppercase.

@register.filter(is_safe=False)
@stringfilter
def urlencode(value, safe=None):

Escape a value for use in a URL.

The safe parameter determines the characters which should not be escaped by Python's quote() function. If not provided, use the default safe characters (but an empty string can be provided when all characters should be escaped).

@register.filter(is_safe=True, needs_autoescape=True)
@stringfilter
def urlize(value, autoescape=True):

Convert URLs in plain text into clickable links.

@register.filter(is_safe=True, needs_autoescape=True)
@stringfilter
def urlizetrunc(value, limit, autoescape=True):

Convert URLs into clickable links, truncating URLs to the given character limit, and adding 'rel=nofollow' attribute to discourage spamming.

Argument: Length to truncate URLs to.

@register.filter(is_safe=False)
@stringfilter
def wordcount(value):

Return the number of words.

@register.filter(is_safe=True)
@stringfilter
def wordwrap(value, arg):

Wrap words at arg line length.

@register.filter(is_safe=False)
def yesno(value, arg=None):

Given a string mapping values for true, false, and (optionally) None, return one of those strings according to the value:

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.