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. We will disable a whole family here (yes, a family can disapear in the outerspace). .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step by checking out the corresponding tag of the `rougail-tutorials` git repository. Each tag corresponds to a stage of progress in the tutorial. Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, this workshop page corresponds to the tags :tutorial:`v1.1_040 ` to :tutorial:`v1.1_044 ` in the repository. :: git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_040 A disabled family --------------------------------------------- First, a definition: .. glossary:: property A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...) of a family, a subfamily or a variable. These properties change the usual behavior of a variable or family. Here we are going to assign the `disabled` property to the `manual` family: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml :language: yaml :caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file .. %YAML 1.2 --- version: 1.1 manual: description: Manual proxy configuration disabled: true http_proxy: # HTTP Proxy address: description: HTTP address type: domainname params: allow_ip: true port: description: HTTP Port type: port default: 8080 .. raw:: html :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt .. rougail -m firefox/ -u yaml -yf config/02/config.yml The Rougail CLI outputs this: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html :class: output We can deduce that the `manual` family is not taken into account by Rougail. .. glossary:: disabled The disabled property is a property that can be assigned to a variable or a family. It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined. It simply doesn't exist. It is deactivated for the whole configuration. .. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled. If we still wanna try to assign values to variables that have been disabled: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/config.yml :language: yaml :caption: Here in the :file:`config/02/config.yml` user data file, we assign values to disabled variables If we launch the Rougail CLI: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt :class: terminal It outputs: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html :class: output Let's have a look at 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 These 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 `address` and `port` variables, there is no point in setting them. We could say that we disable them in order to expose the fact that we don't use them, but 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 in the `Manual proxy configuration` context only. Otherwise, **we need to disable them when they are not necessary**. If we fill them in, Rougail CLI will output a warning and the :term:`operator` will wonder : "what am I doing?". I shall fill and use in these variables only in the `Manual proxy configuration` context. .. important:: We need to **disable** variables or families that are not used in a given usage context. .. type-along:: Disabling a group of variables is disabling a family If we don't choose the manual mode, we need to **disable** these variables. Note that we've placed theses variables in the `http_proxy` subfamily. We can then disable the whole `manual` subfamily in order to disable the `http_proxy` family and all the variables that are placed in it. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/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 Notice the `disabled: true` parameter set in the `manual` family. A conditional disabled family ------------------------------ .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the `v1.1_041` version:: git switch --detach v1.1_041 What we need is a *dynamic setting* of the disable/enable property of the `manual` family. The idea in this section is to dynamically set the enable/disable tag according to the chosen context. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml :linenos: :language: yaml :caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled .. %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 FIXME : trouver une autre formulation et expliquer un peu plus, notamment le "when_not" .. note:: The `_.` Rougail's notation means the variable in the current workspace. We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. As the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. Let's launch the Rougail CLI on an empty user value file: .. raw:: html :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/cmd_ro.txt .. rougail -m firefox/ -u yaml -yf config/01/config.ym We have this output: .. raw:: html :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html .. 
╭──────────────────── Caption ─────────────────────╮
    │ Undocumented but modified variable Default value │
    ╰──────────────────────────────────────────────────╯
    Variables:
    ┗━━ 📓 Configure Proxy Access to the Internet: No proxy
We can see that the `manual` family and all the variables into it are not present. .. type-along:: Dynamically enabling the `manual` family Now if we choose **the manual mode**, that is the `Manual proxy configuration` value for the `proxy_mode`, things become slightly different. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yaml :linenos: :language: yaml :caption: The `proxy_mode`'s manual setting in the :file:`config/03/config.yaml` user datas file .. --- proxy_mode: Manual proxy configuration manual: http_proxy: address: http.proxy.net port: 3128 use_for_https: false 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 the `manual` family is activated (enabled). .. note:: Remember 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. FIXME expliquer ici mieux le "when_not" .. 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'` the `manual` family is disabled - if `proxy_mode == 'Manual proxy configuration'` the `manual` family is enabled **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