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 .. 
🛑 ERRORS
    ┗━━ cannot access to optiondescription "manual" (Manual proxy configuration) because has property 
        "disabled"
    ╭────────────────────────── Caption ──────────────────────────╮
    │ Variable                           Default value            │
    │ Undocumented variable              Modified value           │
    │ Undocumented but modified variable (Original default value) │
    ╰─────────────────────────────────────────────────────────────╯
    Variables:
    ┗━━ 📓 proxy_mode: Manual proxy configuration (No proxy)
.. 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).