Level 12: use template engine extensions¶
There are three possible ways to provide extensions for your template engine. Let’s take jinja2 as an example.
1. Ready made extensions¶
jinja2 comes with a lot of extensions. In order not to be the blocker in the middle, extensions is allowed in moban file to initialize jinja2 engine with desired extensions. Two extensions, expression-statement and loop-controls are enabled by default.
The extensions syntax is:
extensions: template_type: - template.engine.specific.extension
extensions: jinja2: - jinja2.ext.i18n
Please also note that the following extensions are included by default: jinja2.ext.do, jinja2.ext.loopcontrols
if you intend to use extensions for one off usage, please use ‘-e’ cli option. for example: moban -e jinja2=your_custom_jinja2_extension
2. Ad-hoc declaration¶
Let’s say you are fond of some existing functions, for example, ansible’s combine filter. With moban, you can immediately include it for your template via the following syntax:
extensions: jinja2: - filter:ansible.plugins.filter.core.combine - test:moban.externals.file_system.exists
$ moban -e jinja2=filter:module.path.filter_function jinja2=test:module.path.test_function jinja2=global:identifier=module.path.variable
you can do this:
$ moban -e jinja2=filter:module.path.filter_function \ jinja2=test:module.path.test_function \ jinja2=global:identifier=module.path.variable
3. Make your own extensions¶
You can choose to write an extension for the template type of your choice. For example, you can write a reusable extension for jinja2. moban will be able to load it as it is.
If you decide that you only want to write them for moban but for your own use, you can follow Level 7: Custom jinja filters, tests and globals and write your own. When you would like to make yours avaiable for all moban users, you can follow moban-jinja2-github and moban-ansible
Please go to docs/level-12-use-template-engine-extensions directory.
If you notice the file a.template, we are using a for loop control. This is because moban comes with two default extensions loop-controls and expression-statement.
Now, let us try to use the extension with. To do that, we have to enable the extension in the .moban.yml file following the above syntax. Now, the extension can be used in the jinja2 templates. One such example is shown in the b.template file.
For some extensions, you may need to define template environment parameters. In that case, you can take help of our user defined template types feature. Please read level-18 for more info. We have explained it using an example here.
Let us consider the example of jinja2_time. If you want to use datetime_format attribute, you need to specify the same using environmental parameters, i.e env.datetime_format = ‘%a, %d %b %Y %H:%M:%S’. In order to do this, you can specify datetime_format using environmental parameters, something like:
configuration: template_types: my_own_type: base_type: jinja2 file_extensions: - file_type_of_my_choice options: datetime_format: %a, %d %b %Y %H:%M:%S extensions: - jinja2_time.TimeExtension targets: - a.output: a.template.file_type_of_my_choice