359 lines
10 KiB
ReStructuredText
359 lines
10 KiB
ReStructuredText
A new variable which has the `boolean` type
|
||
===============================================
|
||
|
||
.. objectives:: Objectives
|
||
|
||
In this section we will learn:
|
||
|
||
- how to make a boolean type variable
|
||
- how to reuse some value of a variable
|
||
(in this use case we will reuse the HTTP configuration variables values for the HTTPS configuration)
|
||
|
||
.. prerequisites:: Reminders
|
||
|
||
Let's summarize the configuration up to here
|
||
|
||
Whe have the `proxy_mode` configuration here:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/00-proxy.yml
|
||
:language: yaml
|
||
:caption: firefox/00-proxy.yml
|
||
|
||
..
|
||
---
|
||
proxy_mode:
|
||
description: Configure Proxy Access to the Internet
|
||
choices:
|
||
- No proxy
|
||
- Auto-detect proxy settings for this network
|
||
- Use system proxy settings
|
||
- Manual proxy configuration
|
||
- Automatic proxy configuration URL
|
||
default: No proxy
|
||
|
||
With the manual subfamily in case of the "Manual proxy configuration" configuration option has been chosen:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/10-manual.yml
|
||
:language: yaml
|
||
:caption: firefox/10-manual.yml
|
||
|
||
..
|
||
---
|
||
manual:
|
||
description: Manual proxy configuration
|
||
disabled:
|
||
variable: proxy_mode
|
||
when_not: 'Manual proxy configuration'
|
||
|
||
http_proxy:
|
||
description: HTTP Proxy
|
||
|
||
address:
|
||
description: HTTP address
|
||
type: domainname
|
||
params:
|
||
allow_ip: true
|
||
|
||
port:
|
||
description: HTTP Port
|
||
type: port
|
||
default: 8080
|
||
|
||
.. type-along:: The HTTPS mode
|
||
|
||
Now we will focus on configuring the HTTPS mode in case of "Manual proxy configuration".
|
||
|
||
.. image:: images/firefox_manual_https.png
|
||
|
||
Let's set 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
|
||
|
||
- So we have 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
|
||
|
||
.. type-along:: What do we want to reuse?
|
||
|
||
Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
|
||
It depends on the context.
|
||
|
||
.. glossary::
|
||
|
||
context
|
||
|
||
A configuration is highly statefull and can change at any moment.
|
||
Sometimes somes minor changes in the :term:`user datas` involves chain reactions
|
||
in the whole :term:`configuration`.
|
||
The context is the state of the user datas at one 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.
|
||
|
||
A new `boolean` type variable
|
||
-------------------------------
|
||
|
||
We have a new variable, named `use_for_https` here:
|
||
|
||
.. confval:: use_for_https
|
||
:type: `boolean`
|
||
:default: `true`
|
||
|
||
This is a setting that enables to reuse the HTTP proxy configuration for HTTPS
|
||
|
||
Its description in the structure file gives us this:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/20-manual.yml
|
||
:language: yaml
|
||
:caption: firefox/20-manual.yml
|
||
|
||
..
|
||
---
|
||
manual:
|
||
|
||
use_for_https:
|
||
description: Also use this proxy for HTTPS
|
||
type: boolean
|
||
default: true
|
||
|
||
.. type-along:: Update of the context
|
||
|
||
So now we have three new variables in the manual mode of the http proxy configuration.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/firefox/20-manual.yml
|
||
:language: yaml
|
||
:caption: firefox/20-manual.yml
|
||
|
||
..
|
||
---
|
||
manual:
|
||
|
||
use_for_https:
|
||
description: Also use this proxy for HTTPS
|
||
default: true
|
||
|
||
https_proxy:
|
||
description: HTTPS Proxy
|
||
|
||
address:
|
||
description: HTTPS address
|
||
type: domainname
|
||
params:
|
||
allow_ip: true
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
type: port
|
||
default: 8080
|
||
|
||
And 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: disabled?
|
||
|
||
Is it relevant to use the :term:`disabled property <disabled>` here?
|
||
|
||
**answer**: No! Because we *need* to use these variables at any case,
|
||
we simply have to point their values in one direction or another depending on this or that context.
|
||
|
||
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 here a new concept.
|
||
|
||
The hidden property
|
||
---------------------
|
||
|
||
.. glossary::
|
||
|
||
hidden
|
||
|
||
A variable or family's property is hidden if its value shall not be seen in a given consistency.
|
||
Anyway, these variables can be used again if the context evolves. This is the main difference
|
||
between the `hidden` and the `disabled` properties.
|
||
|
||
Now we can set a `hidden` property to the `https_proxy` family:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/firefox/20-manual.yml
|
||
:language: yaml
|
||
:caption: The `https_proxy` subfamily with the `hidden` property
|
||
:name: HiddenPropertySubfamily
|
||
|
||
..
|
||
---
|
||
manual:
|
||
|
||
use_for_https:
|
||
description: Also use this proxy for HTTPS
|
||
default: true
|
||
|
||
https_proxy:
|
||
description: HTTPS Proxy
|
||
hidden: true
|
||
|
||
address:
|
||
description: HTTPS address
|
||
type: domainname
|
||
params:
|
||
allow_ip: true
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
type: port
|
||
default: 8080
|
||
|
||
The whole `https_proxy` family has been set to `hidden` here.
|
||
|
||
.. type-along:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value
|
||
|
||
If we choose the manual proxy configuration mode,
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/03/config.yaml
|
||
:language: yaml
|
||
:caption: The Manual proxy configuration value is set
|
||
|
||
..
|
||
---
|
||
proxy_mode: Manual proxy configuration
|
||
|
||
|
||
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
|
||
|
||
..
|
||
<pre>🛑 ERRORS
|
||
<span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
|
||
<span style="color: #ff0000">┗━━ </span> - manual.http_proxy.address (HTTP address)
|
||
</pre>
|
||
|
||
A conditional hidden family with a boolean variable
|
||
--------------------------------------------------------
|
||
|
||
But we want this `hidden` property to be assigned dynamically depending on the `use_for_https` `true` or `false` value.
|
||
How to achieve this.
|
||
|
||
It is possible to add a `variable` parameter to the `hidden` attribute like this:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_034/firefox/20-manual.yml
|
||
:language: yaml
|
||
:caption: The hidden property now depends on the value of `manual.use_for_https`
|
||
|
||
..
|
||
---
|
||
manual:
|
||
|
||
use_for_https:
|
||
description: Also use this proxy for HTTPS
|
||
default: true
|
||
|
||
https_proxy:
|
||
description: HTTPS Proxy
|
||
hidden:
|
||
variable: manual.use_for_https
|
||
|
||
address:
|
||
description: HTTPS address
|
||
type: domainname
|
||
params:
|
||
allow_ip: true
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
type: port
|
||
default: 8080
|
||
|
||
A calculated default value
|
||
-------------------------------
|
||
|
||
|
||
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.
|
||
|
||
By now, the default settings are set like this:
|
||
|
||
.. code-block:: yaml
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
type: port
|
||
default: 8080
|
||
|
||
|
||
|
||
The dynamic setting of a default can be achieved in this way:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_035/firefox/20-manual.yml
|
||
:language: yaml
|
||
:caption: A default variable's value dynamically set
|
||
|
||
..
|
||
---
|
||
manual:
|
||
|
||
use_for_https:
|
||
description: Also use this proxy for HTTPS
|
||
default: true
|
||
|
||
https_proxy:
|
||
description: HTTPS Proxy
|
||
hidden:
|
||
variable: manual.use_for_https
|
||
|
||
address:
|
||
description: HTTPS address
|
||
type: domainname
|
||
params:
|
||
allow_ip: true
|
||
default:
|
||
variable: manual.http_proxy.address
|
||
|
||
port:
|
||
description: HTTPS Port
|
||
type: port
|
||
default:
|
||
variable: manual.http_proxy.port
|
||
|
||
.. note:: This is just a pointer to another variable's value.
|
||
|
||
The default values of the https address and port are pointing to the value of
|
||
the `manual.http_proxy.address` and the `manual.http_proxy.port` variables.
|
||
|
||
.. 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.
|
||
|
||
.. keypoints:: Key points
|
||
|
||
**Keywords**
|
||
|
||
- 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
|
||
|
||
**Progress**
|
||
|
||
We have arrived at the end of the proxy's manual configuration's section.
|