View Helpers

This page lists the view helpers available in your views. The full API Documentation covers all of the helpers in more detail.

These are the ones added by Proper. The builtin filters of Jinja are available too, except xmlattr, pprint and urlize.

All of these helpers can be also used in your views with the pipe operator. For example, {{value|format_date(args)}} instead of {{format_date(value, args)}}.

1. Format Dates

1.1 format_date

Formats a date/datetime according to the current locale and timezone.

format_date(date(2007, 4, 1), locale='en_US')
# => 'Apr 1, 2007'

format_date(date(2007, 4, 1, 15, 30), locale='en_US')
# => 'Apr 1, 2007, 3:30:00\u202fPM'

You can also specify a custom date pattern:

format_date(date(2007, 4, 1), "EEE, MMM d, ''yy", locale='en')
# => "Sun, Apr 1, '07"

See the format_date API Documentation for more information.

1.2 format_time

Formats a time according to the current locale and timezone.

format_time(time(15, 30), locale='en_US')
# => '3:30:00\u202fPM'

format_time(time(15, 30), format='short', locale='de_DE')
# => '15:30'

You can also specify a custom time pattern:

format_time(time(15, 30), "hh 'o''clock' a", locale='en')
# => "03 o'clock PM"

See the format_time API Documentation for more information.

1.3 format_timedelta

Formats a timedelta according to the rules of the given locale.

format_timedelta(timedelta(weeks=12), locale='en_US')
# => '3 months'

format_timedelta(timedelta(seconds=1), locale='es')
# => '1 segundo'

The granularity parameter can be provided to alter the lowest unit presented, which defaults to a second.

format_timedelta(timedelta(hours=3), granularity='day', locale='en_US')
# => '1 day'

See the format_timedelta API Documentation for more information.

1.4 format_interval

Formats an interval between two dates or times according to the timezone and locale's rules.

format_interval(time(5, 12), time(16, 24), "Hm", locale="en_GB")
# => '5:12–16:24'

format_interval(time(5, 12), time(16, 24), "hm", locale="en_US")
# => '5:12\u202fAM\u2009–\u20094:24\u202fPM'

format_interval(date(2016, 1, 15), date(2016, 1, 17), "yMd", locale="fi")
# => '15.–17.1.2016'

See the format_interval API Documentation for more information.

2. Format Numbers

For these helpers, the number formatted can be an integer, a float, a string, or a Decimal.

2.1 format_size

Format a byte count as a human-readable string with binary (1024) units.

format_size(120)
# => '120 Bytes'

format_size(1024)
# => '1 KB'

format_size(15_678)
# => '15.3 KB'

format_size(133_235_678)
# => '127 MB'

format_size(133_235_678, precision=5, locale="de")
# => '127,06 MB'

See the format_size API Documentation for more information.

2.2 format_decimal

Formats a number for a specific locale.

format_decimal(12_345.5, locale='en_US')
# => '12,345.5'

format_decimal(1.2345, locale='de')
# => '1,234'

See the format_decimal API Documentation for more information.

2.3 format_compact_decimal

Like format_decimal but in compact form.

format_compact_decimal(12_345, format_type="short", locale='en_US')
# => '12K'

format_compact_decimal(12_345, format_type="long", locale='en_US')
# => '12 thousand'

format_compact_decimal(12_345, format_type="short",
    locale='en_US', fraction_digits=2)
# => '12.34K'

See the format_compact_decimal API Documentation for more information.

2.4 format_currency

Formats a number as a currency value, following the locale's formatting rules.

format_currency(1_099.98, 'USD', locale='en_US')
# => '$1,099.98'

format_currency(1_099.98, 'USD', locale='es_CO')
# => 'US$1.099,98'

format_currency(1_099.98, 'EUR', locale='de_DE')
# => '1.099,98\xa0\u20ac'

See the format_currency API Documentation for more information.

2.5 format_compact_currency

Like format_currency but in compact form.

format_compact_currency(12_345, 'USD', locale='en_US')
# => '$12K'

format_compact_currency(123_456_789, 'USD', locale='en_US', fraction_digits=2)
# => '$123.46M'

format_compact_currency(123_456_789, 'EUR', locale='de_DE', fraction_digits=1)
# => '123,5\xa0Mio.\xa0€'

See the format_compact_currency API Documentation for more information.

2.6 format_percent

Return formatted percent value for a specific locale.

format_percent(0.34, locale='en_US')
# => '34%'

format_percent(25.1234, locale='en_US')
# => '2,512%'

format_percent(25.1234, locale='sv_SE')
# => '2\xa0512\xa0%'

See the format_percent API Documentation for more information.

3. Format Text

See the format_date API Documentation for more information.

3.1 format_list

Format the items in lst as a list.

format_list(['apples', 'oranges', 'pears'], locale='en')
# => 'apples, oranges, and pears'

format_list(['apples', 'oranges', 'pears'], locale='zh')
# => 'apples、oranges和pears'

format_list(['omena', 'peruna', 'aplari'], style='or', locale='fi')
# => 'omena, peruna tai aplari'

Available styles:

standard

A typical 'and' list for arbitrary placeholders. eg. "January, February, and March"

standard-short

A short version of an 'and' list, suitable for use with short or abbreviated placeholder values. eg. "Jan., Feb., and Mar."

or

A typical 'or' list for arbitrary placeholders. eg. "January, February, or March"

or-short

A short version of an 'or' list. eg. "Jan., Feb., or Mar."

unit

A list suitable for wide units. eg. "3 feet, 7 inches"

unit-short

A list suitable for short units eg. "3 ft, 7 in"

unit-narrow

A list suitable for narrow units, where space on the screen is very limited. eg. "3′ 7″"

Not all styles are necessarily available in all locales.

See the format_list API Documentation for more information.

3.2 truncate

Truncate a string to a specified length.

The length is specified with the second parameter (length) which defaults to 255. If the third parameter (killwords) is True the filter will cut the text at length. Otherwise it will discard the last word.

If the text was in fact truncated it will append an ellipsis sign ("..."). You can specify a different sign using the fourth (end) parameter.

Strings that only exceed the length by the tolerance margin given in the fifth (leeway) parameter will not be truncated.

truncate("foo bar baz qux", 9) }}
# -> "foo..."

truncate("foo bar baz qux", 9, True) }}
# -> "foo ba..."

truncate("foo bar baz qux", 11) }}
# -> "foo bar baz qux"

truncate("foo bar baz qux", 11, False, '...', 0) }}
# -> "foo bar..."

See the truncate API Documentation for more information.

4. Navigation

4.1 url_for

Builds a URL for the route with the given name, filling in placeholders with the given kwargs or with attributes of the given object.

url_for("Page.show", object=page)
# => "/pages/123"

url_for("Page.show", page_id=123, _anchor="section1")
# => "/pages/123#section1"

# The host is determined by the route's host constraint
# or by the application's default host.
url_for("Page.show", page_id=123, _full=True)
# => "http://www.example.com/pages/123#section1"

The URL is percent-encoded, so pass the values as they are, not encoded (an encoded "a%20b" would become a%2520b). In the path, every character is encoded except letters, digits, -._~ and /:@!$&'()*+,;=; the arguments that are not placeholders become the query string, encoded as a form (a space is +, a / is %2F). Each placeholder value must match the placeholder's format as a whole, or url_for raises BadRoutePlaceholder: "42abc" is not an <int>, a value with a / fits only a format that accepts it, such as <path>, and a value can't make a . or .. segment ("." or ".." for /files/:name), which browsers remove. The _anchor is percent-encoded as the path is (a ? stays as it is). See Values Are Checked and Percent-Encoded.

See the url_for API Documentation for more information.

4.2 url_is

Tells if the URL for the given route name and parameters is the same as the current URL as reported by current.request.path. This is useful for things like active links in navigation bars.

Only the paths are compared, percent-decoded and without trailing slashes: the query string and the #fragment are ignored, on both sides. Query parameters given to url_is are ignored too, so url_is("Photo.index", page=2) is True on any page of /photos.

If a current URL is not given, it defaults to current.request.path. This is useful if you want to compare to a different URL than the current request's path, for example when you are building a link to a section in the same page and want to compare against that URL instead. curr_url is a URL as in a link, percent-encoded (/tags/a%20b):

url_is("Page.show", page_id=123, curr_url="/pages/123#section1")
# => True

url_is("Page.show", page_id=123, curr_url="/pages/123?tab=photos")
# => True

url_is("Page.show", page_id=123, curr_url="/pages")
# => False

See the url_is API Documentation for more information.

4.3 url_startswith

Tells if the current URL, as reported by current.request.path, starts with the URL for the given route name and parameters, segment by segment (/photography does not start with /photo). Paths are compared as in url_is. This is useful for things like active links to sections in navigation bars.

url_startswith("Page.show", page_id=123, curr_url="/pages/123#section1")
# => True

url_startswith("Page.show", page_id=123, curr_url="/pages/123/edit")
# => True

url_startswith("Page.show", page_id=123, curr_url="/pages/")
# => False

Every path starts with the URL of a route at /, so for a "Home" link use url_is.

See the url_startswith API Documentation for more information.

4.4 dom_id

Generate a stable id for a collection of objects and/or strings, suitable for use in HTML element ids.

All parts will be converted to strings and joined with underscores. If a part is an object, its class name and primary key (if available) will be used to generate a string for that part. Composite primary keys are also supported.

dom_id(Post.get(45))                     # => "post_45"
dom_id(Post.get(45), "edit")             # => "post_45_edit"
dom_id(Post.get(45), "edit", "special")  # => "post_45_edit_special"

If there is no primary key, the class name is prefixed with "new_" instead.

dom_id(Post.create())  # => "new_post"

If the object has a to_key() method, it will be used to get the key instead of the primary key. This allows you to customize the key generation for privacy-sensitive or more complex models. If it returns a composite key (tuple), the parts will be joined with underscores.

However, if this method returns None, False, or an empty value, the object will be treated as if it has no primary key.

If the object is a class rather than an instance, only the class name is used:

dom_id(Post)            # => "post"
dom_id(Post, "custom")  # => "post_custom"

5. Assets

5.1 assets.render_css

Uses the assets.collect_css() list to generate an HTML fragment with <link rel="stylesheet" href="{url}"> tags.

See the render_css API Documentation for more information.

5.2 assets.render_js

Uses the assets.collect_js() list to generate an HTML fragment with <script type="module" src="{url}"></script> tags.

See the render_js API Documentation for more information.

5.3 assets.render

Calls assets.render_css() and assets.render_js() to generate an HTML fragment with <link rel="stylesheet" href="{url}"> and <script type="module" src="{url}"></script> tags.

See the render_assets API Documentation for more information.

5.4 assets.collect_css

Returns a list of CSS files for the component and its children.

See the collect_css API Documentation for more information.

5.5 assets.collect_js

Returns a list of JS files for the component and its children.

See the collect_js API Documentation for more information.

5.6 render_importmap

Render a script tag containing the import map for the app's assets.

An import map is a JSON object that maps module specifiers to URLs, allowing you to use bare module specifiers in your JavaScript code. For example, with the following import map:

<script type="importmap">
{
    "imports": {
        "my-lib": "/static/my-lib.js"
    }
}
</script>

You can import my-lib in your JavaScript code like this:

import { something } from "my-lib";

The render_importmap function generates a script tag with the import map based on the app's configuration. It looks for an IMPORT_MAP configuration variable, which should be a dictionary mapping module specifiers to asset paths or URLs.

See the render_importmap API Documentation for more information.

6. Turbo

6.1 frame / turbo_frame

Generates an HTML fragment with a <turbo-frame> tag.

See the Turbo Documentation for more information.

6.2 stream / turbo_stream

Generates an HTML fragment with a <turbo-stream> tag.

See the Turbo Documentation for more information.