Template Tags

add_form_widget_attr

Adds widget attributes to a bound form field.

This is helpful if you would like to add a certain class to all your forms (i.e. form-control to all form fields when you are using Bootstrap):

{% load libs_tags %}
{% for field in form.fields %}
    {% add_form_widget_attr field 'class' 'form-control' as field_ %}
    {{ field_ }}
{% endfor %}

The tag will check if the attr already exists and only append your value. If you would like to replace existing attrs, set replace=1:

{% add_form_widget_attr field 'class' 'form-control' replace=1 as field_ %}

block_anyfilter

Turns any template filter into a blocktag.

Usage:

{% load libs_tags %}
{% block_anyfilter django.template.defaultfilters.truncatewords_html 15 %}
    // Something complex that generates html output
{% endblockanyfilter %}

This is useful when you are working with django-cms’ render_placeholder tag, for example. That tag is unfortunately not an assignment tag, therefore you can’t really do anything with the output. Imagine you want to show a list of latest news and for each news a little excerpt based on the content placeholder. That placeholder could contain anything, like images and h1 tags but you really just want to show the first ten words without images or any styles. Now you can do this:

{% block_anyfilter django.template.defaultfilters.truncatewords_html 15 %}
{% block_anyfilter django.template.defaultfilters.striptags %}
{% render_placeholder news_entry.content %}

{% endblockanyfilter %}

{% endblockanyfilter %}

calculate_dimensions

calculate_dimensions is a way to auto-correct thumbnail dimensions depending on the images format. The required args are am image instance, the length of the long image side and finally the length of the short image side.

Usage Example with easy_thumbnails:

{% load libs_tags thumbnail %}
{% calculate_dimensions image 320 240 as dimensions%}
<img src="{% thumbnail image dimensions %}" />

It then ouputs 320x240 if the image is landscape and 240x320 if the image is portait.

call

call is an assignemnt tag that allows you to call any method of any object with args and kwargs, because you do it in Python all the time and you hate not to be able to do it in Django templates.

Usage:

{% load libs_tags %}
{% call myobj 'mymethod' myvar foobar=myvar2 as result %}
{% call myobj 'mydict' 'mykey' as result %}
{% call myobj 'myattribute' as result %}
{{ result }}

concatenate

Concatenates the given strings.

Usage:

{% load libs_tags %}
{% concatenate "foo" "bar" as new_string %}
{% concatenate "foo" "bar" divider="_" as another_string %}

The above would result in the strings “foobar” and “foo_bar”.

exclude

exclude is a filter tag that allows you to exclude one queryset from another.

Usage:

{% load libs_tags %}
{% for clean_obj in qs|exclude:dirty_qs %}
    {{ clean_obj }}
{% endfor %}

get_content_type

get_content_type is a simple template filter to return the content type of an object or to return one of the content type’s fields.

This might be very useful if you want to e.g. call a URL, which needs a content object as a keyword argument.

In order to use it, just import the tag library and set the tag:

{% load libs_tags %}
<a href="{% url "review_content_object" content_type=user|get_content_type:'model' object_id=user.pk %}">Review this user!</a>

As you can see, you can provide a field argument to return the relevant content type’s field.

get_form_field_type

Returns the widget type of the given form field.

This can be helpful if you want to render form fields in your own way (i.e. following Bootstrap standards).

Usage:

{% load libs_tags %}
{% for field in form %}
    {% get_form_field_type field as field_type %}
    {% if "CheckboxInput" in field_type %}
        <div class="checkbox">
            <label>
                // render input here
            </label>
        </div>
    {% else %}
        {{ field }}
    {% endif %}
{% endfor %}

get_range

get_range behaves just like Python’s range function and allows you to iterate over ranges in your templates:

{% load libs_tags %}
{% for item in 5|get_range %}
    Item number {{ item }}
{% endfor %}

You can also calculate the difference between your value and a max value. This is useful if you want to fill up empty space with items so that the total amount of items is always max_num:

{% load libs_tags %}
{% for item in object_list.count|get_range %}
    // render the actual items
{% endfor %}
{% for item in object_list.count|get_range:10 %}
    // render the placeholder items to fill up the space
{% endfor %}

get_range_around

Returns a range of numbers around the given number.

This is useful for pagination, where you might want to show something like this:

<< < ... 4 5 (6) 7 8 .. > >>

In this example 6 would be the current page and we show 2 items left and right of that page.

Usage:

{% load libs_tags %}
{% get_range_around page_obj.paginator.num_pages page_obj.number 2 as pages %}

The parameters are:

  1. range_amount: Number of total items in your range (1 indexed)
  2. The item around which the result should be centered (1 indexed)
  3. Number of items to show left and right from the current item.

get_verbose

get_verbose is a simple template tag to provide the verbose name of an object’s specific field.

This can be useful when you are creating a DetailView for an object where, for some reason you don’t want to use a ModelForm. Instead of using the {% trans %} tag to create your labels and headlines that are related to the object’s fields, you can now obey the DRY principle and re-use the translations that you have already done on the model’s field’s verbose_name attributes.

In order to use it, just import the tag library and set the tag:

{% load libs_tags %}
<ul>
    <li>
        <span>{{ news|get_verbose:"date" }}</span>
    </li>
    <li>
        <span>{{ news|get_verbose:"title" }}</span>
    </li>
</ul>

get_query_params

Allows to change (or add) one of the URL get parameter while keeping all the others.

Usage:

{% load libs_tags %}
{% get_query_params request "page" page_obj.next_page_number as query %}
<a href="?{{ query }}">Next</a>

You can also pass in several pairs of keys and values:

{% get_query_params request "page" 1 "foobar" 2 as query %}

You often need this when you have a paginated set of objects with filters.

Your url would look something like /?region=1&gender=m. Your paginator needs to create links with &page=2 in them but you must keep the filter values when switching pages.

If you want to remove a special parameter, you can do that by setting it’s value to !remove:

{% get_query_params request "page" 1 "foobar" "!remove" as query %}

get_site

get_site returns the current site.

In order to use it, just import the tag library and set the tag:

{% load libs_tags %}
{% get_site as site %}

is_context_variable

Checks if a given variable name is already part of the template context.

This is useful if you have an expensive templatetag which might or might not have been called in a parent template and you also need it in some child templates.

You cannot just check for {% if variable_name %} because that would equal to False in all cases:

  • if the variable does not exist
  • if the variable exists but is None
  • if the variable exists but is False
  • if the variable exists but is 0

This tag allows you to do something like this:

{% is_context_variable 'variable_name' as variable_exists %}
{% if not variable_exists %}
    {% expensive_templatetag as variable_name %}
{% endif %}
{{ variable_name }}

load_context

load_context allows you to load any python module and add all it’s attributes to the current template’s context. This is very useful for the RapidPrototypingView, for example. You would be able to create the template without having any view providing a useful context (because the view might not exist, yet). But as a template designer you might already know that the view will definitely return a list of objects and that list will be called objects and each object will have a name attribute.

Here is how you would use it:

  • create a file yourproject/context/__init__.py
  • create a file yourproject/context/home.py. A good convention would be to name these context modules just like you would name your templates.

Now create the context that you would like to use in your home.html template:

# in object_list.py:
objects = [
    {'name': 'Object 1', },
    {'name': 'Object 2', },
]

Now create your template:

# in home.html
{% load libs_tags %}
{% load_context "myproject.context.home" %}

{% for object in objects %}
    <h1>{{ object.name }}</h1>
{% endfor %}

This should allow your designers to create templates long before the developers have finished the views.

render_analytics_code

The same as render_analytics_code but uses the new syntax and always uses anonymize IP.

Usage:

{% load libs_tags %}
...
<head>
...
{% render_analytics_code %}
</head>

save

save allows you to save any variable to the context. This can be useful when you have a template where different sections are rendered depending on complex conditions. If you want to render <hr /> tags between those sections, it can be quite difficult to figure out when to render the divider and when not.

Usage:

{% load libs_tags %}
...
{% if complex_condition1 %}
    // Render block 1
    {% save "NEEDS_HR" 1 %}
{% endif %}

{% if complex_condition2 %}
    {% if NEEDS_HR %}
        <hr />
        {% save "NEEDS_HR" 0 %}
    {% endif %}
    // Render block 2
    {% save "NEEDS_HR" 1 %}
{% endif %}

sum

Adds the given value to the total value currently held in key.

Use the multiplier if you want to turn a positive value into a negative and actually substract from the current total sum.

Usage:

{% sum "MY_TOTAL" 42 -1 %}
{{ MY_TOTAL }}

set_context

NOTE: It turns out that this implementation only saves to the current template’s context. If you use this in a sub-template, it will not be available in the parent template. Use our save tag for manipulating the global RequestContext.

set_context allows you to put any variable into the context. This can be useful when you are creating prototype templates where you don’t have the full template context, yet but you already know that certain variables will be available later:

{% load libs_tags %}
{% set_context '/dummy-url/' as contact_url %}
{% blocktrans with contact_url=contact_url %}
Please don't hesitate to <a href="{{ contact_url }}">contact us</a>.
{% endblocktrans %}

verbatim

verbatim is a tag to render x-tmpl templates in Django templates without losing the code structure.

Usage:

{% load libs_tags %}
{% verbatim %}
{% if test1 %}
    {% test1 %}
{% endif %}
{{ test2 }}
{% endverbatim %}

The output will be:

{% if test1 %}
    {% test1 %}
{% endif %}
{{ test2 }}