jinja
This commit is contained in:
gwen
parent
13b77b38f6
commit
78aa9a057a
1 changed files with 31 additions and 250 deletions
|
|
@ -36,13 +36,6 @@ Playing with Jinja
|
||||||
|
|
||||||
We are going to embed some `jinja templating code <https://jinja.palletsprojects.com/en/stable/>`_ in our structure file.
|
We are going to embed some `jinja templating code <https://jinja.palletsprojects.com/en/stable/>`_ in our structure file.
|
||||||
|
|
||||||
.. questions:: What about a `Jinja` calculation?
|
|
||||||
|
|
||||||
The :term:`Jinja` templating language enables some complex calculation.
|
|
||||||
We can code more complex behavior that hiding or disabling a variable depending on the value of another variable,
|
|
||||||
as we saw before.
|
|
||||||
|
|
||||||
|
|
||||||
.. glossary::
|
.. glossary::
|
||||||
|
|
||||||
Jinja
|
Jinja
|
||||||
|
|
@ -51,6 +44,13 @@ as we saw before.
|
||||||
we are using Jinja in a classical way, that is, Jinja allows us to handle different cases,
|
we are using Jinja in a classical way, that is, Jinja allows us to handle different cases,
|
||||||
for example with the `if` statement.
|
for example with the `if` statement.
|
||||||
|
|
||||||
|
|
||||||
|
.. questions:: What about a `Jinja` calculation?
|
||||||
|
|
||||||
|
The :term:`Jinja` templating language enables some complex calculation.
|
||||||
|
For example we can code more complex behavior for hiding or disabling a variable, that is
|
||||||
|
not only depending on the value of another variable as we saw before.
|
||||||
|
|
||||||
A conditional hidden family with Jinja
|
A conditional hidden family with Jinja
|
||||||
---------------------------------------
|
---------------------------------------
|
||||||
|
|
||||||
|
|
@ -183,7 +183,7 @@ then we have a warning:
|
||||||
so cannot access to "HTTPS address",
|
so cannot access to "HTTPS address",
|
||||||
it will be ignored when loading from the YAML file "config/01/config.yml"
|
it will be ignored when loading from the YAML file "config/01/config.yml"
|
||||||
|
|
||||||
It is interesting here to launch the Rougail CLI in the :term:`read write mode`:
|
What is interesting here is to launch the Rougail CLI in the :term:`read write mode`:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
|
|
@ -198,270 +198,51 @@ Then we have an error:
|
||||||
because has property "hidden"
|
because has property "hidden"
|
||||||
(HTTPS is same has HTTP)
|
(HTTPS is same has HTTP)
|
||||||
|
|
||||||
FIXME
|
.. note:: Note that we can see the "HTTPS is same has HTTP" string (the one that was present in the jinja code)
|
||||||
|
as an explanation inside the error message.
|
||||||
We can hide or disable some variables or families with other techniques than
|
|
||||||
pointing on a variable's value.
|
|
||||||
|
|
||||||
Let's reason on the previous HTTPS proxy configuration's manual mode:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
manual:
|
|
||||||
|
|
||||||
use_for_https:
|
|
||||||
description: Also use this proxy for HTTPS
|
|
||||||
default: true
|
|
||||||
|
|
||||||
https_proxy:
|
|
||||||
type: family
|
|
||||||
description: HTTPS Proxy
|
|
||||||
hidden:
|
|
||||||
variable: manual.use_for_https
|
|
||||||
|
|
||||||
|
|
||||||
This is extracted from the proxy's manual configuration we discussed before.
|
.. type-along:: What can be calculated?
|
||||||
|
|
||||||
We see here that there is an `https_proxy` family that is going to be hidden
|
|
||||||
depending on the value of another variable:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
https_proxy:
|
|
||||||
type: family
|
|
||||||
hidden:
|
|
||||||
variable: manual.use_for_https
|
|
||||||
|
|
||||||
Now we could write it like that:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
manual:
|
|
||||||
|
|
||||||
use_for_https:
|
|
||||||
description: Also use this proxy for HTTPS
|
|
||||||
default: true
|
|
||||||
|
|
||||||
https_proxy:
|
|
||||||
description: HTTPS Proxy
|
|
||||||
type: family
|
|
||||||
hidden:
|
|
||||||
type: jinja
|
|
||||||
jinja: |
|
|
||||||
{% if rougail.manual.use_for_https %}
|
|
||||||
the HTTPS Proxy family is hidden
|
|
||||||
{% endif %}
|
|
||||||
|
|
||||||
Yes, it's done in a more complicated (but more powerful) way.
|
|
||||||
Let's explain this a little:
|
|
||||||
|
|
||||||
We have replaced this simple hidden property declaration:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
hidden:
|
|
||||||
variable: manual.use_for_https
|
|
||||||
|
|
||||||
by this (more complicated) hidden property declaration:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
hidden:
|
|
||||||
type: jinja
|
|
||||||
jinja: |
|
|
||||||
{% if rougail.manual.use_for_https %}
|
|
||||||
the HTTPS Proxy family is hidden
|
|
||||||
{% endif %}
|
|
||||||
|
|
||||||
The fact is that it has same result, but here we have more possibilities.
|
|
||||||
The hidden process is done by a calculation.
|
|
||||||
|
|
||||||
Another jinja calculation type sample
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
We can now hide or disable some variables or families with other techniques than
|
|
||||||
pointing on a variable's value.
|
|
||||||
|
|
||||||
Let's reason upon the proxy's manual configuration we discussed before.
|
|
||||||
We have the :file:`dict/02-proxy_manual.yml` structure file:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
:caption: the :file:`structfile/02-proxy_manual.yml` file
|
|
||||||
|
|
||||||
---
|
|
||||||
version: '1.1'
|
|
||||||
manual:
|
|
||||||
description: Manual proxy configuration
|
|
||||||
type: family
|
|
||||||
disabled:
|
|
||||||
type: jinja
|
|
||||||
jinja: |
|
|
||||||
{% if rougail.proxy.proxy_mode != 'Manual proxy configuration' %}
|
|
||||||
the proxy mode is not manual
|
|
||||||
{% endif %}
|
|
||||||
|
|
||||||
.. questions:: Question
|
|
||||||
|
|
||||||
**question**: OK then. What happens when you select the "Manual proxy configuration"?
|
|
||||||
|
|
||||||
Here if the user selects the "Manual proxy configuration" proxy mode,
|
|
||||||
the the `manual` family will be disabled. This is what the jinja code says.
|
|
||||||
Let's explain it more precisely.
|
|
||||||
|
|
||||||
|
|
||||||
.. note:: The "the proxy mode is not manual" output is be used in the log outputs
|
|
||||||
for example while
|
|
||||||
|
|
||||||
What can be calculated?
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
We have seen that the `disabled` or `hidden` properties could be calculated.
|
We have seen that the `disabled` or `hidden` properties could be calculated.
|
||||||
The default values can be calculated too.
|
The default values can be calculated too. We'll see a bunch of examples later on.
|
||||||
|
|
||||||
.. todo:: montrer un exemple de valeur par défaut calculées (type jinja)
|
Let's reason on the previous HTTPS proxy configuration's manual mode settings:
|
||||||
|
|
||||||
.. todo:: montrer aussi ici des exemples de calculs de valeurs variables, ce qui est un des usages principaux de jinja
|
|
||||||
|
|
||||||
Using jinja in a dynamic family declaration
|
|
||||||
-----------------------------------------------
|
|
||||||
|
|
||||||
Let's come back to the previous section's FIXME `dynamic family example <conditional_hidden_family>`
|
|
||||||
|
|
||||||
In a dynamic family, as seen before, you have the possibility to name your identifier. In the classic declaration,
|
|
||||||
the identifier's variable is named "identifier" by default. Sounds logical:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
"{{ identifier }}_proxy":
|
|
||||||
description: "{{ identifier }} Proxy"
|
|
||||||
dynamic:
|
|
||||||
- HTTPS
|
|
||||||
- SOCKS
|
|
||||||
|
|
||||||
Here the identifer's variable takes the value of the `dynamic` family parameter.
|
|
||||||
|
|
||||||
.. type-along:: Using a jinja calculation with a parameter
|
|
||||||
|
|
||||||
We have the possibility to use a given variable variable inside a jinja calculation:
|
|
||||||
|
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/20-manual.yml
|
|
||||||
:language: yaml
|
|
||||||
:caption: firefox/20-proxy.yml
|
|
||||||
|
|
||||||
..
|
|
||||||
manual:
|
|
||||||
|
|
||||||
use_for_https:
|
use_for_https:
|
||||||
description: Also use this proxy for HTTPS
|
|
||||||
default: true
|
default: true
|
||||||
|
|
||||||
"{{ identifier }}_proxy":
|
https_proxy:
|
||||||
description: "{{ identifier }} Proxy"
|
type: family
|
||||||
dynamic:
|
description: HTTPS Proxy
|
||||||
- HTTPS
|
|
||||||
- SOCKS
|
|
||||||
hidden:
|
hidden:
|
||||||
jinja: |
|
variable: _.use_for_https
|
||||||
{% if my_identifier == 'HTTPS' and manual.use_for_https %}
|
|
||||||
HTTPS is same has HTTP
|
|
||||||
{% endif %}
|
|
||||||
params:
|
|
||||||
my_identifier:
|
|
||||||
type: identifier
|
|
||||||
description: |
|
|
||||||
in HTTPS case if "manual.use_for_https" is set to True
|
|
||||||
|
|
||||||
address:
|
We see here that the `https_proxy` family is be hidden
|
||||||
description: "{{ identifier }} address"
|
depending on the value of another variable. This is what we saw before,
|
||||||
default:
|
how to hide a variable.
|
||||||
variable: manual.http_proxy.address
|
|
||||||
|
|
||||||
port:
|
Now we can code the same behavior in a somehow different way:
|
||||||
description: "{{ identifier }} port"
|
|
||||||
default:
|
|
||||||
variable: manual.http_proxy.port
|
|
||||||
|
|
||||||
version:
|
|
||||||
description: SOCKS host version used by proxy
|
|
||||||
choices:
|
|
||||||
- v4
|
|
||||||
- v5
|
|
||||||
default: v5
|
|
||||||
disabled:
|
|
||||||
type: identifier
|
|
||||||
when: 'HTTPS'
|
|
||||||
|
|
||||||
This can be done by defining a `my_identifier` variable.
|
|
||||||
|
|
||||||
This jinja variable comes from the `params` parameter of the `hidden` property.
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
params:
|
|
||||||
my_identifier:
|
|
||||||
type: identifier
|
|
||||||
|
|
||||||
Here the `hidden` property's value is defined by a jinja calculation.
|
|
||||||
In this jinja calculation we have a `my_identifier` jinja variable.
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
https_proxy':
|
||||||
|
description: HTTPS Proxy
|
||||||
hidden:
|
hidden:
|
||||||
jinja: |
|
jinja: |-
|
||||||
{% if my_identifier == 'HTTPS' and manual.use_for_https %}
|
{% if _.use_for_https %}
|
||||||
HTTPS is same has HTTP
|
HTTPS is same has HTTP
|
||||||
{% endif %}
|
{% endif %}
|
||||||
params:
|
|
||||||
my_identifier:
|
|
||||||
type: identifier
|
|
||||||
description: |
|
|
||||||
in HTTPS case if "manual.use_for_https" is set to True
|
|
||||||
|
|
||||||
.. type-along:: The `when` and `when_not` parameter notation
|
This code has the same result but yes, it's done in a more complicated way.
|
||||||
|
We have replaced this simple `hidden` property variable parameter by
|
||||||
|
a jinja parameter. The hidden process is done by a calculation.
|
||||||
|
|
||||||
.. todo:: ça devrait être sur une autre page. déplacer cela ailleurs
|
The fact is that it has same result, but it wil open more possibilities.
|
||||||
|
|
||||||
Handling the SOCKS version
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
Now we need to handle the SOCKS version as show in the firefox configuration screenshot:
|
|
||||||
|
|
||||||
.. image:: images/firefox_soks_version.png
|
|
||||||
|
|
||||||
|
|
||||||
We'll just add a choice variable with a default value and a disabled property:
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
|
|
||||||
version:
|
|
||||||
description: SOCKS host version used by proxy
|
|
||||||
choices:
|
|
||||||
- v4
|
|
||||||
- v5
|
|
||||||
default: v5
|
|
||||||
disabled:
|
|
||||||
type: identifier
|
|
||||||
when: 'HTTPS'
|
|
||||||
|
|
||||||
There is still something new about this YAML, though. It is the `when` parameter
|
|
||||||
of the `disabled` property. You have two possible notations: `when` or `when_not`.
|
|
||||||
These two notations are just a short hand of what we could express in jinja as
|
|
||||||
this code:
|
|
||||||
|
|
||||||
.. code-block:: jinja
|
|
||||||
|
|
||||||
{% if identifier == 'HTTPS' %}
|
|
||||||
when the identifer equals 'HTTPS' then the SOCKS version is disabled
|
|
||||||
{% endif %}
|
|
||||||
|
|
||||||
And the `when_not` parameter is just the logical opposite.
|
|
||||||
|
|
||||||
Here is the final version of our YAML dynamic family:
|
|
||||||
|
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/20-manual.yml
|
|
||||||
:language: yaml
|
|
||||||
:caption: firefox/20-proxy.yml
|
|
||||||
|
|
||||||
|
FIXME
|
||||||
|
|
||||||
.. keypoints:: Key points
|
.. keypoints:: Key points
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue