Explained Useage

At the beginning of your file include:

{% load macros %}

When you have a section of your template you want to repeat, but don’t want to have inherited or any other block tag-like functionality, define a macro as follows:

{% macro some_macro_name arg1 arg2 kwarg="default" %}
    {{ arg1 }} was the first argument.
    {{ arg2 }} was the second argument.

    {% if kwarg %}This is a {{ kwarg }}. {% endif %}
{% endmacro %}

Then when you want to use the macro, simply do:

{% use_macro some_macro_name "foo" "bar" kwarg="nondefault value" %}

which renders to:

foo was the first argument.
bar was the second argument.
This is a nondefault value.

Alternatively, you can save your macros in a separate file, e.g. “mymacros.html” and load it into the template with the tag {% loadmacros "mymacros.html" %} then use them with the {% use_macro ... %} tag.

All macros, including loaded ones, are local to the template file they are loaded into/defined in, and are not inherited through {% extends ... %} tags.

A more in-depth useage example:

{% macro test2args1kwarg arg1 arg2 baz="Default baz" %}
    {% firstof arg1 "default arg1" %}
    {% if arg2 %}{{ arg2 }}{% else %}default arg2{% endif %}
    {{ baz }}
{% endmacro %}


{% use_macro test2args1kwarg "foo" "bar" baz="KW" %}
<br>
{% use_macro test2args1kwarg num_pages "bar" %}
<br>
{% use_macro test2args1kwarg %}

foo bar KW
77 bar Default baz
default arg1 default arg2 Default baz

Extended Syntax

Sometimes you might want to include data that is rendered by the template engine, or longer data containing a lot of html in a macro. For this, the syntax of plugging arguments directly into the tag doesn’t really work, so instead of {% use_macro some_macro_name "arg" kwarg_name="value" %}, use the syntax below:

{% macro_block some_macro_name %}
    {% macro_arg %}
        arg
    {% endmacro_arg %}

    {% macro_kwarg kwname %}
        value
    {% endmacro_kwarg %}
{% endmacro_block %}

Note that with this syntax you no longer have to quote strings/arguments. If you have a mix of longer and shorter arguments, you can also use both syntaxes simultaneously:

{% macro_block some_macro_name "arg1" kwname1="value1" %}
    {% macro_arg %}
        arg2
    {% endmacro_arg %}

    {% macro_kwarg kwname2 %}
        value2
    {% endmacro_kwarg %}
{% endmacro_block %}