View source for Controlling whitespace in Jinja2 templates

[[File:Jinja-logo-sidebar.png|right]]

For background perspective, '''[https://jinja.palletsprojects.com Jinja]''' is used as a templating system by various Python projects like Django, Flask, or Ansible. 

From the Jinja2 documentation, there are two options to control whitespace in Jinja templates:

*<code>trim_blocks</code>
*<code>lstrip_blocks</code>

But actually, there's more to it. [https://jinja.palletsprojects.com/en/3.1.x/templates/ The "Template Designer Documentation"] specifically for [https://jinja.palletsprojects.com/en/3.1.x/templates/#whitespace-control whitespace control] is inadequate. That's why I wrote this article.

==Jinja in Ansible==
In [[Ansible]]'s Template module, you can see in the source code

*[https://github.com/search?q=repo%3Aansible%2Fansible%20trim_blocks&type=code trim_blocks defaults to true]
*[https://github.com/search?q=repo%3Aansible%2Fansible%20lstrip_blocks&type=code lstrip_blocks defaults to false]

But what does this mean? What do these options do? And how do I use them in my Ansible templates?

'''trim blocks''' means the first newline after a block is removed (block, not variable tag!)

'''lstrip blocks''' <ref><code>lstrip</code> stands for "left strip". It is a function in Python, as well as R and Ruby. Like <code>ltrim</code> in PHP or <code>trimStart</code> in JavaScript. nb. Jinja also has a [https://jinja.palletsprojects.com/en/3.1.x/templates/#list-of-builtin-filters built-in filter] named <code>[https://jinja.palletsprojects.com/en/3.1.x/templates/#jinja-filters.trim trim]</code> that is used to strip characters from the beginning and end of a string.</ref> means leading spaces and tabs are stripped from the start of a line to a block.

So, I can read words, but without context nor further example and explanation, I can't decode what "from the start of a line to a block" means.


==In the task==
In at least v2.9 of Ansible, the Template module has options to specify both.

*[https://docs.ansible.com/ansible/2.9/modules/template_module.html 2.9 docs for the template module]
*[https://docs.ansible.com/ansible/latest/modules/template_module.html latest docs for the template module]
**[https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html#parameter-lstrip_blocks parameter lstrip_blocks]
**[https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html#parameter-trim_blocks parameter trim_blocks]

==In the template file==
As the '''very first line''' of your template file, you can use a magic comment directive to control the behavior of the Ansible Template module 
<code>#jinja2: trim_blocks: "true", lstrip_blocks: "true"</code><ref>It's unclear whether the boolean value(s) to be quoted. I believe it was a bug that is now fixed - meaning they can be bare.</ref>

==By hand==

I was so frustrated by the lack of clear examples '''that showed all variants''', I created a project on GitHub called '''[https://github.com/freephile/test-jinja test-jinja]''' that does exactly that. (Inspiration from https://github.com/ansible/ansible/pull/37478)

You could also use the [https://github.com/qn7o/jinja2-live-parser jinja2 live parser] project to interactively preview jinja.

If you're confused about Variable notation and how those are defined in templates, see https://jinja.palletsprojects.com/en/3.1.x/templates/#variables

==Debugging==
Just put <code>{% debug %}</code> somewhere in your template file. This didn't work for me in Ansible 2.9


== More ==
Bloomreach Engagement is a commercial Web product that uses Jinja for templating. So they have a pretty good [https://documentation.bloomreach.com/engagement/docs/jinja-syntax reference guide].{{References}}

[[Category:Ansible]]
[[Category:Templating]]
[[Category:Python]]