What are Macros in Jinja?

Macros in Jinja are similar to functions in other programming languages. They are used to encapsulate logic used to perform repeatable actions. Macros can take arguments or be used without them. Inside macros, we can use any of the Jinja features and constructs. The result of running a macro is some text. In other words, wherever we call a macro inside the template, it is replaced with the string/text resulting from calling the macro.

We can create reusable components of the code and then use them at multiple places by just calling the macro. We can even save a macro or a collection of macros in a separate Jinja file and then import the file into multiple other jinja files where we wish to use those macros. This is useful when we want to make changes. In case we use macros, we just have to modify the macro to implement the changes, otherwise, one would need to modify every place where the logic is explicitly written.

Syntax to create/define Macros in Jinja

{% macro macro_name(*args, **kwargs) %}
    < macro body >
{% endmacro %}

Start defining the macro with

{% macro macro_name(*args, **kwargs) %}

where “macro_name” is replaced with the name of the macro, *args is replaced with positional arguments of the macro (if any) and **kwargs is replaced with the keyword arguments of the macro. This is almost similar to python’s function defining syntax. Next, define the body of the macro which is normal Jinja syntax. Finally place the text “{% endmacro %}” where the body of the macro ends.

Calling Macros in Jinja

We can call the macro by its name inside the “{{ <expression goes here> }}” delimiter. For example, to call the macro named “macro_name”, we can write the following syntax at the place in jinja template file where we want its output text –

{{ macro_name() }}

If it takes some arguments, we can also pass these inside the parentheses like this –

{{ macro_name(arg1, arg2, ...., kwarg1 = value1, kwarg2 = value2, ...) }}

where argn represents nth positional argument and kwargn represents nth keyword argument. Both these are analogous to python’s positional and keyword arguments.

A Jinja Macro Without any Arguments

This section shows how to create a basic macro without any arguments. The macro just renders the string “Hello World” wherever it is called. Create a file named “helloMacro.jinja” in “templates” folder and a file named “helloMacro.py” in “jinjaTests” folder. “helloMacro.py” file will be used to render “helloMacro.jinja” template and print the rendered text to the screen. Here are the contents of “helloMacro.jinja” file –

helloMacro.jinja

{% macro hello() %}
Hello rendered from the macro hello().
{% endmacro %}
Some text rendered using a macro: {{hello()}}

First we define the macro named hello with empty parentheses since it accepts no arguments. Then we have some text in its body and we finally end it with the “{% endMacro %}” line as stated earlier. Next we call it in the last line as “hello()” inside the “{{ }}” delimiter as stated earlier.

Example

It is loading “helloMacro.jinja” file as template

Run the above file from the “jinjaTests” folder .

Output

Some text rendered using a macro:
Hello rendered from the macro hello().

A Jinja Macro with Arguments

This section shows how to create a basic macro with arguments. Create a file named “helloArgMacro.jinja” in “templates” folder and “helloArgMacro.py” in “jinjaTests” folder. The later one will be used to render the former template. Here are the contents of “helloArgMacro.jinja” file –

helloArgMacro.jinja

{% macro helloName(a,b,name = "no name") %}
Hello {{name}}.
Sum of {{a}} and {{b}} = {{a+b}}.
{% endmacro %}
Result of running the macro: {{helloName(1,2,name = "Geek")}}

Everything is same as the last example except that we are handling arguments: two positional arguments a and b and one keyword argument name. While defining the macro named helloName we defined these arguments inside parentheses as seen in the first line. We can access these arguments inside the macro-body and utilize them. Similarly, while calling helloName macro, we pass the values of these arguments. Remember this is very similar to Python arguments. We can even omit the values of keyword arguments in which case the default argument (here “no name” is the default) will be used. Here are the contents of “helloArgMacro.py” file –

We load the “helloArgMacro.jinja” file as template and render it.

Run the above file to see the output text on the screen.

Output

Result of running the macro:
Hello Geek.
Sum of 1 and 2 = 3.

If we remove the name argument while calling, we will get the output with the default value for name –

Output

Result of running the macro:
Hello no name.
Sum of 1 and 2 = 3.

Macros are a powerful functionality provided by Jinja, a text rendering engine for Python programming language. Macros in Jinja are similar to functions in other programming languages and help to implement the DRY Principle of programming (i.e., Don’t Repeat Yourself) in the Jinja templates by helping to avoid repeated code. It is fairly easy to use macros. This article intends to show how to use macros in Jinja. It assumes basic familiarity with Python programming language and Jinja.