disabled / hidden
This commit is contained in:
gwen
parent
0008d03772
commit
9f2299ee3e
4 changed files with 329 additions and 17 deletions
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
The variables
|
||||
-----------------
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,16 @@ Disabling things
|
|||
.. objectives:: Objectives
|
||||
|
||||
In this section we will see what a disabled variable or family is, and why it can be interesting
|
||||
to assign the `disabled` property to a variable or a family.
|
||||
to assign the `disabled` property to a variable or a family. We'll also learn the difference
|
||||
between disabling and hiding families or variables.
|
||||
|
||||
We will disable a whole family here (yes, a family can disapear in the outerspace).
|
||||
We will:
|
||||
|
||||
- `disable` a whole family here (yes, a family can disapear in the outerspace!)
|
||||
- use a new family or variable's property: the `hidden` property
|
||||
- reuse a value of a variable for another variable
|
||||
(in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS).
|
||||
|
||||
|
||||
.. prerequisites:: Prerequisites
|
||||
|
||||
|
|
@ -29,7 +36,8 @@ Disabling things
|
|||
A disabled family
|
||||
---------------------------------------------
|
||||
|
||||
First, a definition:
|
||||
Disabling and hiding are two families or variables properties. Let's begin with
|
||||
defining what a property is:
|
||||
|
||||
.. glossary::
|
||||
|
||||
|
|
@ -114,7 +122,7 @@ It outputs:
|
|||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html
|
||||
:class: output
|
||||
|
||||
We can see that the Rougail CLI is warning us that the variables we are trying to assign values on are disabled.
|
||||
We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled.
|
||||
That is to say, they are not taken into account at the :term:`configuration` level.
|
||||
|
||||
If we have a closer look at our use case, we have a choice between five options
|
||||
|
|
@ -319,7 +327,7 @@ Here is the new :file:`20-manual.yml` file:
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/20-manual.yml` structure file with the `https_proxy` family.
|
||||
:caption: The updated `manual` family in the :file:`firefox/20-manual.yml` structure file with the `https_proxy` family.
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
|
|
@ -345,19 +353,315 @@ Here is the new :file:`20-manual.yml` file:
|
|||
|
||||
This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol.
|
||||
|
||||
Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`.
|
||||
We want to offer the possibility of providing the same proxy configuration for the HTTP and the HTTPS requests.
|
||||
|
||||
A conditional hidden family
|
||||
----------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_043` version::
|
||||
|
||||
git switch --detach v1.1_043
|
||||
|
||||
Here is an example with different user values for handling HTTP and HTTPS:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/config.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false
|
||||
|
||||
..
|
||||
---
|
||||
proxy_mode: Manual proxy configuration
|
||||
manual:
|
||||
http_proxy:
|
||||
address: http.proxy.net
|
||||
port: 3128
|
||||
use_for_https: false
|
||||
https_proxy:
|
||||
address: https.proxy.net
|
||||
|
||||
If we launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:class: terminal
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/cmd_ro.txt
|
||||
|
||||
..
|
||||
rougail -m firefox/ -u yaml -yf config/01/config.yml
|
||||
|
||||
We have this output:
|
||||
|
||||
.. raw:: html
|
||||
:class: output
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/output_ro.html
|
||||
|
||||
..
|
||||
<pre>╭────────────── Caption ───────────────╮
|
||||
│ Variable <span style="color: #ffd700">Default value</span> │
|
||||
│ <span style="color: #00aa00">Modified value</span> │
|
||||
│ (⏳ Original default value) │
|
||||
╰──────────────────────────────────────╯
|
||||
Variables:
|
||||
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
|
||||
<span style="color: #5c5cff">┃ </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No
|
||||
<span style="color: #5c5cff">┃ </span>proxy)
|
||||
<span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┃ </span>file "config/01/config.yml"
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff"> </span>"config/01/config.yml" (⏳ 8080)
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span>the YAML file "config/01/config.yml" (⏳ true)
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📂 https_proxy (HTTPS Proxy)
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span>file "config/01/config.yml"
|
||||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">8080</span>
|
||||
</pre>
|
||||
|
||||
Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`.
|
||||
We want to offer the possibility of providing an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols.
|
||||
|
||||
Here is an example with identical HTTP and HTTPS proxy configuration:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/config.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true
|
||||
|
||||
..
|
||||
---
|
||||
proxy_mode: Manual proxy configuration
|
||||
manual:
|
||||
http_proxy:
|
||||
address: http.proxy.net
|
||||
port: 3128
|
||||
use_for_https: true
|
||||
|
||||
Let's launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:class: terminal
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/cmd_ro.txt
|
||||
|
||||
..
|
||||
rougail -m firefox/ -u yaml -yf config/02/config.yml
|
||||
|
||||
We have this output:
|
||||
|
||||
.. raw:: html
|
||||
:class: output
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html
|
||||
|
||||
FIXME: il y a un <span> dans le <pre>
|
||||
|
||||
..
|
||||
<pre>> [!CAUTION]
|
||||
>
|
||||
> - manual (Manual proxy configuration)
|
||||
> - https_proxy (HTTPS Proxy)
|
||||
> - address (HTTPS address): :stop_sign: <span style="color: #C23636">mandatory variable but is inaccessible and has no value</span>
|
||||
</pre>
|
||||
|
||||
We are going to see how to point HTTPS variables to HTTPS variables
|
||||
|
||||
A conditional hidden family
|
||||
----------------------------
|
||||
|
||||
Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.
|
||||
|
||||
.. image:: images/firefox_manual_https.png
|
||||
|
||||
We have added two other variables for the HTTPS use only:
|
||||
|
||||
.. confval:: https_proxy.address
|
||||
:type: `domainname`
|
||||
|
||||
This is an address setting for the manual HTTPS configuration
|
||||
|
||||
.. confval:: https_proxy.port
|
||||
:type: `port`
|
||||
|
||||
This is a port setting for the manual HTTPS configuration
|
||||
|
||||
We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
|
||||
In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.
|
||||
|
||||
Let's introduce a new Rougail concept here:
|
||||
|
||||
.. glossary::
|
||||
|
||||
context
|
||||
|
||||
A :term:`configuration` is highly statefull and can change at any moment.
|
||||
Sometimes somes minor changes in the :term:`user datas <user data>` may involve chain reactions
|
||||
in the whole :term:`configuration`.
|
||||
The **context** is the state of the user datas at one moment, the set of the values of the variables
|
||||
at a given moment. This term also refers to the ability of a system to handle
|
||||
the *statefull* state of a configuration.
|
||||
It expresses the transition between one situation to another situation,
|
||||
that is, the deeply **statefull** aspects of a data set.
|
||||
|
||||
|
||||
.. type-along:: A new variable which has the `boolean` type
|
||||
|
||||
The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
|
||||
is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.
|
||||
|
||||
Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
|
||||
Well, it depends on the :term:`context`.
|
||||
|
||||
We have added a new variable, named `use_for_https` here:
|
||||
|
||||
.. confval:: use_for_https
|
||||
:type: `boolean`
|
||||
:default: `true`
|
||||
|
||||
This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS
|
||||
|
||||
.. questions:: Question: how does it work?
|
||||
|
||||
How will this variable drive the reuse of HTTP data to HTTPS data?
|
||||
|
||||
With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two:
|
||||
|
||||
- The http proxy's configuration will be reused for the https proxy's configuration
|
||||
- The http proxy's will not be reused for the https proxy's configuration
|
||||
|
||||
.. questions:: Question: shall we use the `disabled` property here?
|
||||
|
||||
Is it relevant to use the :term:`disabled property <disabled>` here?
|
||||
|
||||
**answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case,
|
||||
we simply have to point their values in one direction or another depending on this or that context,
|
||||
that's why it is absolutely not a question of deactivating them. The `manual.https_proxy.address`
|
||||
and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode.
|
||||
|
||||
Let's introduce a new concept here:
|
||||
|
||||
.. glossary::
|
||||
|
||||
hidden
|
||||
|
||||
A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`.
|
||||
Anyway, these variables can be used if the context evolves. This is the main difference
|
||||
between the `hidden` and the `disabled` properties (with the `disabled` property, the variables are *deactivated*.
|
||||
|
||||
Now we can set a `hidden` property to the `https_proxy` family:
|
||||
|
||||
Here is our new :file:`20-manual.yml` structure file:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_043/firefox/20-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
|
||||
|
||||
We have now a `hidden` property assigned to the `https_proxy` family.
|
||||
The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has
|
||||
a `variable` target parameter: `variable: _.use_for_https`
|
||||
|
||||
.. prerequisites:: Reminder
|
||||
|
||||
The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent
|
||||
family.
|
||||
|
||||
Variable type and parameters type are copied with default value
|
||||
------------------------------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_044` version::
|
||||
|
||||
git switch --detach v1.1_044
|
||||
|
||||
.. discussion:: A contextualized default value
|
||||
|
||||
A contextualized default value is a default value (of a variable) that is driven by another variable.
|
||||
This variable type and its parameters type are copied in the default value's target variable.
|
||||
|
||||
There is something left in the https configuration mode of the proxy:
|
||||
|
||||
- if the use of the proxy variables for https are the same of the proxy variables for http,
|
||||
that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK.
|
||||
- if the use of the proxy variables for https **are not** the same of the proxy variables for http,
|
||||
we would like to set their default values to the http proxy variables values.
|
||||
|
||||
The dynamic setting of a default can be achieved in this way: the default value is a pointer to another variable's value.
|
||||
Here, the defaut value of `manual.https_proxy.address` points to `manual.http_proxy.address`.
|
||||
|
||||
This is the same thing for the default value of the `manual.https_proxy.port` variable,
|
||||
which points to the `manual.http_proxy.port` value.
|
||||
|
||||
We also say that the default value is *calculated*.
|
||||
|
||||
.. glossary::
|
||||
|
||||
calculated
|
||||
|
||||
We say that a variable's value or a default variable's value is calculated
|
||||
when there is a pointer which refers to another variable's value
|
||||
or if there is some :term:`jinja` code or a python function that calculates it.
|
||||
|
||||
To summarize the HTTP and HTTPS configuration in the manual use case context,
|
||||
here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` structure files:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/10-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/10-manual.yml` structure file with the `http_proxy` family and the `disabled` property
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
description: Manual proxy configuration
|
||||
disabled:
|
||||
variable: _.proxy_mode
|
||||
when_not: Manual proxy configuration
|
||||
|
||||
http_proxy: # HTTP Proxy
|
||||
|
||||
address:
|
||||
description: HTTP address
|
||||
type: domainname
|
||||
params:
|
||||
allow_ip: true
|
||||
|
||||
port:
|
||||
description: HTTP Port
|
||||
type: port
|
||||
default: 8080
|
||||
...
|
||||
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/20-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
|
||||
use_for_https: true # Also use this proxy for HTTPS
|
||||
|
||||
https_proxy:
|
||||
description: HTTPS Proxy
|
||||
hidden:
|
||||
variable: _.use_for_https
|
||||
|
||||
address:
|
||||
description: HTTPS address
|
||||
default:
|
||||
variable: __.http_proxy.address
|
||||
|
||||
port:
|
||||
description: HTTPS Port
|
||||
default:
|
||||
variable: __.http_proxy.port
|
||||
...
|
||||
|
||||
|
||||
.. keypoints:: Key points progress
|
||||
|
|
@ -369,9 +673,17 @@ A conditional hidden family
|
|||
- if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled
|
||||
- if the `proxy_mode` variable's value is `'Manual proxy configuration'` then the `manual` family is enabled
|
||||
|
||||
- FIXME add the hidden steps
|
||||
|
||||
We have arrived at the end of the proxy's manual configuration's section.
|
||||
|
||||
**Keywords**
|
||||
|
||||
- We now know what a *property* is, we have seen in details the :term:`disabled` property
|
||||
- We can target a variable's value in the `disabled` property's value,
|
||||
we call it a variable based contextual disabled family
|
||||
- The :term:`hidden` property set to a family
|
||||
- The fact that a property can be set dynamically
|
||||
- The conditional dependency of a `hidden` property that depends on a `boolean` variable.
|
||||
- A calculated default value
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
The `hidden` property
|
||||
=======================
|
||||
|
||||
|
|
@ -245,8 +247,6 @@ If we choose the manual proxy configuration mode,
|
|||
Note that in this context, if we don't set a value to the `manual.http_proxy.address` mandatory variable, even if it is `hidden`,
|
||||
Rougail will raise an error:
|
||||
|
||||
.. todo:: Ce raw html là est sur manual.http_proxy.address et pas manual.https_proxy.address
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/output_ro.html
|
||||
:class: error-box
|
||||
|
|
@ -295,9 +295,8 @@ Here is how to achieve this:
|
|||
|
||||
Yes, it is possible to add a `variable` parameter to the `hidden` attribute.
|
||||
|
||||
A contextualized default value
|
||||
---------------------------------
|
||||
|
||||
Variable type and parameters type are copied with default value
|
||||
------------------------------------------------------------------
|
||||
|
||||
.. discussion:: A contextualized default value
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,6 @@ Let's dive into this **configuration options validation** use case.
|
|||
family
|
||||
domainname
|
||||
disabled
|
||||
hidden
|
||||
dynfam
|
||||
calculation
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue