rougail/docs/tutorial/disabled.rst

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).