Difference between revisions of "Controlling whitespace in Jinja2 templates"
(Created page with "right For background perspective, '''[https://jinja.palletsprojects.com Jinja]''' is used as a templating system by various Python projects li...") |
(link to project on GitHub) |
||
| (One intermediate revision by the same user not shown) | |||
| Line 4: | Line 4: | ||
From the Jinja2 documentation, there are two options to control whitespace in Jinja templates: | From the Jinja2 documentation, there are two options to control whitespace in Jinja templates: | ||
| − | * <code>trim_blocks</code> | + | |
| − | * <code>lstrip_blocks</code> | + | *<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. | 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 == | + | ==Jinja in Ansible== |
In [[Ansible]]'s Template module, you can see in the source code | 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] | + | *[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? | But what does this mean? What do these options do? And how do I use them in my Ansible templates? | ||
| Line 23: | Line 25: | ||
| − | == In the task == | + | ==In the task== |
In at least v2.9 of Ansible, the Template module has options to specify both. | In at least v2.9 of Ansible, the Template module has options to specify both. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == In the template file == | + | *[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 | 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> | <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 == | + | ==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 | 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 == | + | ==Debugging== |
| − | Just put <code>{% debug %}</code> somewhere in your template file. | + | Just put <code>{% debug %}</code> somewhere in your template file. This didn't work for me in Ansible 2.9 |
| + | |||
| − | {{References}} | + | == 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:Ansible]] | ||
[[Category:Templating]] | [[Category:Templating]] | ||
[[Category:Python]] | [[Category:Python]] | ||
Latest revision as of 15:46, 12 April 2024
For background perspective, 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:
trim_blockslstrip_blocks
But actually, there's more to it. The "Template Designer Documentation" specifically for whitespace control is inadequate. That's why I wrote this article.
Jinja in Ansible[edit | edit source]
In Ansible's Template module, you can see in the source code
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 [1] 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[edit | edit source]
In at least v2.9 of Ansible, the Template module has options to specify both.
In the template file[edit | edit source]
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
#jinja2: trim_blocks: "true", lstrip_blocks: "true"[2]
By hand[edit | edit source]
I was so frustrated by the lack of clear examples that showed all variants, I created a project on GitHub called test-jinja that does exactly that. (Inspiration from https://github.com/ansible/ansible/pull/37478)
You could also use the 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[edit | edit source]
Just put {% debug %} somewhere in your template file. This didn't work for me in Ansible 2.9
More[edit | edit source]
Bloomreach Engagement is a commercial Web product that uses Jinja for templating. So they have a pretty good reference guide.== References ==
- ↑
lstripstands for "left strip". It is a function in Python, as well as R and Ruby. Likeltrimin PHP ortrimStartin JavaScript. nb. Jinja also has a built-in filter namedtrimthat is used to strip characters from the beginning and end of a string. - ↑ 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.
