Macros
In Jinja, macros allow users to define reusable template code pieces. They are similar to functions or subroutines in traditional programming languages. Macros are useful for creating modular and maintainable templates. Jinja macros provide numerous advantages in templating and offer reusability, modularity, and consistency by reusing template components.
The pre-built report export templates include macros to facilitate easy modification. The specific macros available vary on the template.
Jinja macros and Word macros are two distinct concepts with different applications. Jinja macros are utilized for web templating and generating dynamic content, whereas Word macros are used for automating tasks and customizing Microsoft Word documents. These macros serve unique purposes and are programmed using different languages and environments.
PlexTrac does not use Word macros in any template.
Macro Structure
The basic syntax is as follows:
macro_name: The name of the macro. It can be any valid identifier.(arg1, arg2, ...): Optional arguments that are passed to the macro.{# Macro content here #}: Where the content of the macro is defined, which can include the Jinja template code.
Using a Macro
To use a macro, call it by its name and provide any required arguments:
For example:
{%p macro display_narrative(label,label_as_heading=true,heading_level = “h2”,error = true) %}
The macro's content will be inserted into the template when it is called, with any arguments replaced by the values provided.
Handling Arguments
Arguments are the values or parameters users can pass to macros when invoking these elements within a template. These arguments are pivotal in customizing the behavior, enabling users to supply dynamic data for processing or displaying within the template. Arguments may be values of any data type and mandatory or optional. Macros may have pre-defined values to use if no arguments are passed when calling the function.
Arguments may become mandatory if any argument's default value is changed beyond position 1.
In Jinja, positions refer to the order in which arguments are defined and expected when calling the macro. The positions determine where specific values should be provided when invoking the macro. Each argument in a macro has a designated position based on the order in which it appears in the macro's argument list.
For instance, when calling a macro such as my_macro_name(), which has no arguments (indicated by the empty parentheses), may still be a valid call. This is because default values can be defined for the macro's arguments, or these arguments may only affect the macro's behavior when explicitly used. However, arguments beyond the first position may only be passed if arguments are provided for all preceding positions.
In the example, if the argument in position one has a default value (e.g., "foobar") defined in the macro, changing the argument in position two would still require the user to provide an argument for position 1, even if it matches the default value. For instance, my_macro_name("foobar", true) it would be a valid call. In this case, the argument's value at position two is changed to true, but it is still necessary to provide a value for the argument at position one, even if it matches the default value of "foobar." This ensures that the arguments are correctly passed and maintains the intended behavior of the macro.
PlexTrac identifies which (if any) arguments are mandatory in the specific template documentation for each macro.
Inserting Macro Calls
Macro calls should be arranged in the Report Body section of the template and subsections of the report.
Last updated
