Template Creation Tips, Tricks and Troubleshooting

Things you should know and best practices for creating your .docx custom template

Take Small Bites!

Jinja2 is a powerful scripting language, but syntax is strictly enforced and debugging can be challenging if multiple errors are present. Test early and often, and save your test templates with versioning to make reversion to a known-good state easy.

Comment Your Code

Jinja2 supports commenting, either inline or multi-line. Commenting out sections of code is a very useful method for debugging. Use the following syntax:

{# Your comments here #}
{#
Everything between the brace/hash comment syntax will be commented out
#}

Use Indenting To Format Your Code

When creating a template, Word is your text editor. But that doesn't mean you shouldn't use standard code hygiene. You will find yourself using deeply nested conditionals to iterate and search for values in your PlexTrac data - indenting will help you identify where you haven't properly closed a conditional statement.

Tip: From the Home Ribbon, select the arrow at the bottom-right of the Paragraph sub-menu:

Next, choose the "Tabs" button and change the default tab stops to 0.2". This will prevent your code from wrapping once you are several layers into a conditional nest.

Learn to Use Macros (Functions) Early

Jinja2 supports the use of functions, which it refers to as "macros." Macros make it easy to re-use code within your document, and make troubleshooting easier by reducing the number of potential occurrances of a bug. Samples of macros can be found in the code library.

Understand Common Errors

Incorrectly Terminated Conditionals

The most common error occurs when a conditional statement is not correctly terminated. There are several possible causes for this error.

Curly Brace vs. Brackets

Most Jinja2 commands begin and end with some variation of a curly brace and a percentage sign. It is common to accidentally use a bracket instead of a curly brace:

{%p if "Recommendation" in item.label %} {# Correctly terminated command #}
{%p if "Impact" in tag %] {# Incorrectly terminated with a bracket #}

If you suspect this bug, using the Find feature in Word to search for "#]" can often help you locate the bug.

Terminating Without the "p" Modifier

Jinja2 commands will result in the insertion of newline characters into your export if the commands are not escaped using the "p" modifier immediately after the percent symbol. In some circumstances, closing the conditional (using endif, endfor, etc) without the p modifier can result in the conditional statement not closing:

{%p if tag == "initial_access" %}
{{ tag.value }}
{% endif %} {# this should be closed with {%p endif %} #}

Nonetype References

Anytime that you are referencing a field which is optional (e.g. References, Affected Assets, any custom field), you should include code to check for the presence of the field before attempting to reference it. If you attempt to reference a field that does not exist, you may encounter a "Nonetype" error. For example, this code:

{%p for reference in p.references %}
{{ reference }}
{%p endfor %}

will throw the following error if any findings do not have a value in the References field: