236 lines
7.8 KiB
ReStructuredText
236 lines
7.8 KiB
ReStructuredText
The `disabled` property
|
|
========================
|
|
|
|
.. objectives:: Objectives
|
|
|
|
In this section we will learn:
|
|
|
|
- what a *property* is
|
|
- how to disable a family (yes, a family can disapear in the outerspace)
|
|
- explain the `disabled` property
|
|
|
|
We will see what is a disabled variable or family is, and why it is interesting to do that.
|
|
|
|
.. prerequisites:: Reminder
|
|
|
|
- We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily.
|
|
|
|
A disabled property assigned to a family
|
|
---------------------------------------------
|
|
|
|
|
|
.. glossary::
|
|
|
|
property
|
|
|
|
A property is a state (disabled, frozen, read_write, read_only, hidden ...)
|
|
of a family, a subfamily or a variable. These properties may vary
|
|
depending on the context.
|
|
|
|
.. glossary::
|
|
|
|
disabled
|
|
|
|
The disabled property is a property of a variable or a family that is kind of deactivated
|
|
for the whole configuration.
|
|
|
|
Let's come back to our use case, we have a choice between five options
|
|
in order to set the proxy mode:
|
|
|
|
.. image:: images/firefox_01.png
|
|
|
|
The five choices are:
|
|
|
|
- No proxy
|
|
- Auto-detect proxy settings for this network
|
|
- Use system proxy settings
|
|
- Manual proxy configuration
|
|
- Automatic proxy configuration URL
|
|
|
|
If the `Manual proxy configuration` is not selected, we don't need to set
|
|
the :confval:`address` and :confval:`port` variables, there is no point
|
|
in setting them. It's not just that: if we fill them in, there might be a problem in the overall integrity of the configuration. We shall fill and use in these variables
|
|
only in the `Manual proxy configuration` context. Otherwise, **we need to disable them when they are not necessary**.
|
|
|
|
.. important:: We need to have the ability to **disable** variables that are not used
|
|
in a given context.
|
|
|
|
.. type-along:: disabling the :confval:`address` and :confval:`port` variables
|
|
|
|
If we don't choose the manual mode, we need to **disable** these variables.
|
|
They are not used anymore.
|
|
|
|
Note that we've placed theses variables in the `http_proxy`
|
|
subfamily. We can then disable the whole `http_proxy` subfamily in order to
|
|
disable the variables that are placed in it.
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/firefox/10-manual.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file
|
|
|
|
..
|
|
---
|
|
manual:
|
|
description: Manual proxy configuration
|
|
disabled: true
|
|
|
|
http_proxy:
|
|
description: HTTP Proxy
|
|
|
|
address:
|
|
description: HTTP address
|
|
type: domainname
|
|
params:
|
|
allow_ip: true
|
|
|
|
port:
|
|
description: HTTP Port
|
|
type: port
|
|
default: 8080
|
|
|
|
|
|
We can see here the `disabled: true` parameter set in the `manual` family.
|
|
|
|
A conditional disabled family
|
|
------------------------------
|
|
|
|
.. warning:: In this section, we will **intentionally** create an inconsistency in the configuration
|
|
in order to explore the `disabled` property's behavior.
|
|
|
|
|
|
We are going to
|
|
|
|
- select **the manual mode** value for the `proxy_mode`
|
|
- assing the `example.net` value to the `address` validate in the user data file.
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/config.yaml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The manual setting in the :file:`config/03/config.yaml` user datas file
|
|
|
|
..
|
|
---
|
|
proxy_mode: Manual proxy configuration
|
|
manual:
|
|
http_proxy:
|
|
address: example.net
|
|
|
|
.. warning:: Remember that the `manual` family is disabled, so are the variables it contains.
|
|
|
|
|
|
Now let's validate the consitency of the configuration:
|
|
|
|
.. code-block:: text
|
|
:class: terminal
|
|
|
|
rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml
|
|
|
|
As expected, we encounter an error:
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/output_ro.html
|
|
:class: error-box
|
|
|
|
..
|
|
<pre>🛑 ERRORS
|
|
<span style="color: #ff0000">┗━━ </span>cannot access to optiondescription "manual" (Manual proxy configuration) because has property
|
|
<span style="color: #ff0000"> </span>"disabled"
|
|
╭────────────────────────── Caption ──────────────────────────╮
|
|
│ Variable <span style="color: #ffd700">Default value</span> │
|
|
│ <span style="color: #5c5cff">Undocumented variable</span> Modified value │
|
|
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
|
|
╰─────────────────────────────────────────────────────────────╯
|
|
Variables:
|
|
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
|
|
</pre>
|
|
|
|
.. questions:: Question
|
|
|
|
How to avoid these error messages?
|
|
|
|
Contextual setting of a property
|
|
------------------------------------
|
|
|
|
To avoid this type of error, what we need is a *dynamic setting* of the disable/enable property of the `manual` family.
|
|
|
|
.. type-along:: The conditional disabled property
|
|
|
|
If the manual mode for the proxy is not selected, then the `manual` family shall be disabled.
|
|
On the other hand, if the manual proxy's configuration mode is selected,
|
|
then we need to activate (enable) the `manual` family.
|
|
|
|
And we understand that this activation/deactivation of the `manual` family
|
|
depends on the value of the `proxy_mode` variable.
|
|
|
|
In rougail, we can set a property's value **depending on** the value of another variable. That is, **it is conditioned by** another variable.
|
|
|
|
Here is how we can achieve this:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_028/firefox/10-manual.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The `manual` family in the :file:`firefox/10-manual.yml` structure file with a conditional disabled property
|
|
|
|
..
|
|
---
|
|
manual:
|
|
description: Manual proxy configuration
|
|
disabled:
|
|
type: variable
|
|
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
|
|
|
|
.. rubric:: Explanation
|
|
|
|
Here we have the `disabled` property like this:
|
|
|
|
.. code-block:: yaml
|
|
|
|
disabled:
|
|
type: variable
|
|
variable: proxy_mode
|
|
when_not: 'Manual proxy configuration'
|
|
|
|
Here the `disabled` property **depends on** the value of another variable.
|
|
The `variable` parameter allows you to define the name of the target variable on which the `disabled` property depends.
|
|
|
|
|
|
.. keypoints:: Key points progress
|
|
|
|
**summary**
|
|
|
|
We have the ability to build a contextual setting:
|
|
|
|
- if `proxy_mode` is not `'Manual proxy configuration'` it disables the `manual` family
|
|
- if `proxy_mode == 'Manual proxy configuration'` it enables the `manual` family
|
|
|
|
**Keywords**
|
|
|
|
- the :term:`property` concept
|
|
- the `disabled` property
|
|
- the `variable` target property
|
|
- a disabled variable or family
|
|
- raising a configuration's consistency error
|
|
- a variable based contextual disabled family
|
|
|
|
**Progress**
|
|
|
|
- we have a :term:`family` named `manual` and a sub family named `http_proxy`
|
|
- And we have now two variables: :confval:`proxy_mode` and :confval:`address`.
|
|
- We have dynamically disabled the `manual` family (and the `http_proxy` sub family).
|
|
|