django-templateaddons’s documentation!¶

assign¶

The {% assign %} template tag is useful when you want to capture some template code output and use the result later.

It captures whatever is between the {% assign %} and {% endassign %} pair.

It takes two optional input parameters:

• name. A string. The context variable name where to store the result. Defaults to “assign”.
• silent. A boolean. Whether to only capture the output or both capture and display it. Defaults to False.

The following template code:

{% load assign %}
{% assign name="sample_code" %}1234{% endassign %}
5678
{{ sample_code }}

... gives the following output:

5678
1234

Note: the {% assign %} template tag allows you to override the value of an existing context variable, so choose the “name” parameter with care.

The default value for the “name” parameter is “assign”. This means that we could have written the previous example as below:

{% load assign %}
{% assign %}1234{% endassign %}
5678
{{ assign }}

You can set the “silent” parameter to False if you want to capture and display the output at the same time. The following template code:

{% load assign %}
{% assign name="sample_code" silent=0 %}1234{% endassign %}
5678
{{ sample_code }}

... gives the following output:

1234
5678
1234

counter¶

The {% counter %} template tag is useful when you want to use a custom counter. It can be used outside a specific loop, or used over multiple loops...

The {% counter %} template tag accepts several optional parameters:

• name. A string. It identifies the counter. Default value is ‘default’.
• start. An integer. The value of the counter at the very first call. Default value is 0.
• step. An integer. The increment or decrement amount. Default value is 1.
• ascending. A boolean. Whether the counter is incremented (True) or decremented (False). Default value is True.
• silent. Whether to render (False) or not (True) the current counter value. Default value is False.
• assign. A string. If not empty, the current value of the counter is assigned to the context variable with the corresponding name. Default value is “” (do not assign).

Notice that the start, ascending and step values are only parsed on counter initialization.

The list of available counters is stored in the context, under the variable name settings.TEMPLATEADDONS_COUNTERS_VARIABLE, which is “_templateaddons_counters” by default.

headingcontext¶

With cascading templates, includes and bases, some parts of template code could be reused in different heading contexts.

As an example, consider the following “home page” code in home.html:

<h1>My beautiful website</h1>
<h2>News</h2>
<p>... links to news ...</p>

And consider the following “news page” code in news.html

<h1>News</h1>
<p>... links to news ...</p>

You cannot reuse (include) news.html code into home.html, because the heading level does not match.

The “headingcontext” template tag allows you to solve this problem. Here is modified home.html:

{% load heading %}
<h1>My beautiful website</h1>
{% headingcontext %}
{% include "news.html" %}
{% endheadingcontext %}

Ok. Now, what if the news.html code was using h5 in place of h1 like that:

<h5>News</h5>
<p>... links to news ...</p>

You can use the additional “source_level” parameter in home.html:

{% load heading %}
<h1>My beautiful website</h1>
{% headingcontext source_level=5 %}
{% include "news.html" %}
{% endheadingcontext %}

This causes all heading of level 5 and greater in news.html to be relative to the current heading level (2).

You can use nested {% headingcontext %}{% endheadingcontext %} calls. As an example, news.html could be:

<h5>News</h5>
<p>... links to news ...</p>
{% load heading %}
{% headingcontext source_level=3 target_level=6 %}
{% include "another_template_fragment_which_contains_some_h3.html" %}
{% endheadingcontext %}

Notice the use of the additional “target_level” parameter, which forces ouput levels to start at 6.

You can read the provided test cases to observe what does this template tag at tests.HeadingContextTemplateTagTestCase.

javascript_assign¶

Use it as container of each Javascript code fragment needed in your templates. You should create separate {% javascript_assign %} blocks for each call to a Javascript library.

javascript_render¶

Use it to render the Javascript code fragments previously registered in {% javascript_assign %} blocks.

javascript_reset¶

Call it to empty the Javascript code fragments previously registered in {% javascript_assign %} blocks. In general use case, you display Javascript code once, so you do not need to use this tag.

replace¶

This template tag provides a simple string replacement functionality. The following template code...:

{% load replace %}
{% replace search="pa" replacement="to" %}pamato{% endreplace %}

... gives the following output:

tomato

The “search” parameter is considered as a regular expression by default (options re.UNICODE and re.DOTALL are enabled).

If you do not want to use regular expression, use the enable_regexp=0 parameter. The following template code...:

{% load replace %}
{% replace search="(to)" replacement="au" %}(to)to{% endreplace %}
{% replace search="(to)" replacement="au" use_regexp=0 %}(to)to{% endreplace %}

... gives the following output:

(au)au
auto

You can also use backreferences in the replacement parameter. The following template code...:

{% load replace %}
{% replace search="([a-z]+)" replacement="*\1*" %}123abc456def{% endreplace %}

... gives the following output:

123*abc*456*def*

Notice, if you write the previous template code in Python code (i.e. as a string), then backreference syntax is \1 rather than 1.