Templates, Tags and Filters

About this document

This document describes the templates, template tags and filters provided by the library.

Contents

See also the modules documentation.

Template files

It's possible to override any template by providing an equally named file inside an utils subdirectory somewhere in TEMPLATE_DIRS where Django can find it.

Template reference

utils/paginator.html

This is the template used by the template tag paginator. The template displays pagination links. See below for more information.

Template tags and filters

Template tags and filters are defined in modules contained inside the templatetags directory.

These can be loaded using {% load TAGMODULE %} in your templates.

Tag reference

paginator

{% load paginator %}

An inclusion tag, using the template utils/paginator.html.

This is a pagination template tag, to be used in conjunction with the default Django pagination mechanism and/or object list generic views (either the Django object_list built-in, or the versions provided by softwarefabrica.django.crud).

In addition to the context variables provided by the standard object_list generic view, this adds others for use in displaying first, adjacent and last page links.

Receives the optional arguments:

url
passed to the template as-is, it's used to pass the base url for page links. Defaults to the empty string.
adjacent_pages
number of adjacent pages to display (default is 2).
paginator_object_name
used to retrieve the django.core.paginator.Paginator object from the context (default is 'paginator').
page_object_name
used to retrieve the django.core.paginator.Page object from the context (default is 'page_obj').

The variables added to the context are:

url
same as the argument
paginator
django.core.paginator.Paginator object
page_obj
django.core.paginator.Page object
page_numbers
List of page numbers to display.
show_first
Boolean indicating that the first page is to be linked.
show_last
Boolean indicating that the last page is to be linked.
is_paginated
From generic view. A boolean representing whether the results are paginated.
hits
From generic view. Number of objects on the displayed page.
results_per_page
From generic view. Number of objects per page (if paginated).
page
From generic view. Current page number.
pages
From generic view. Total number of pages.
next
From generic view. The next page.
previous
From generic view. The previous page.
has_next
From generic view. True if there is a next page.
has_previous
From generic view. True if there is a previous page.
first_on_page
From generic view. The result number of the first object in the object_list (1-indexed).
last_on_page
From generic view. The result number of the last object in the object_list (1-indexed).
page_range
From generic view. A list of the page numbers (1-indexed).

Usage:

{% paginator %}

sitevars

{% load sitevars %}

Populates the template context with some variables from the project settings.

As an alternative method to this tag, it's also possible to use the template context processor context_vars provided in softwarefabrica.django.utils.viewshelpers (see the modules documentation).

The variables pushed into the context are:

basesite
value of Site.objects.get_current() when using the "sites" framework, None otherwise.
domain
the domain part of the Site when using the "sites" framework, the empty string otherwise.
static
the value of static_media_prefix(), which is settings.STATIC_MEDIA_PREFIX if defined, or in second instance settings.STATIC_URL, or finally "/static" (always with the trailing slash removed).
upload
value of settings.MEDIA_URL
admin
value of settings.ADMIN_MEDIA_PREFIX
images
same as static with a "/images" suffix
js
same as static with a "/js" suffix

Usage:

{% sitevars %}

urlsave

{% load urlsave %}

This is similar to Django url template tag, but it doesn't produce any output, and saves the result into a context variable.

Usage:

{% urlsave path.to.some_view arg1,arg2,name1=value1 as myurlvar %}

forward_query_param

{% load forward_query_param %}

Implements the forward_query_param template tag described in Paginating complex queries. It allows to propagate values of the request GET through forms.

Usage:

{% forward_query_param "MY_GET_VARIABLE" %}

(to be used inside a <form>...</form>).

Filter reference

in_list

NOT YET PROVIDED

{% load in_list %}

Returns a boolean indicating if its first argument is present in its second argument (typically a list or a tuple).

Usage:

{% if user|in_list:cool_people %}You're cool!{% else %}Don't lose hope :-){% endif %}

sanitize

NOT YET PROVIDED

{% load sanitize %}

Returns a sanitized version of its argument, with dangerous HTML code removed. Non dangerous tags (<p>, <i>, <strong>, <b>, <u>, <h1>, <h2>, <h3>, <pre>, <br>, <a>, <img>), are left in place. For <a> and <img> tags, the href attribute is stripped off inline Javascript code, if any.

Usage:

{{ user_text|sanitize }}