rougail/docs/tutorial/boolean.rst

The `hidden` property
=======================

.. objectives:: Objectives

   In this section we will:
   
   - use a new family or variable's property: the `hidden` property
   - create a new variable's type: `boolean`
   - reuse a value of a variable for another variable
     (in this use case we will reuse the HTTP configuration variables values for the HTTPS configuration).

.. prerequisites:: Reminder

   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 that is used in case of the `"Manual proxy configuration"` value of the `proxy_mode` variable 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

OK then. Let's continue our proxy's configuration.

.. type-along:: The HTTPS mode

Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.

.. 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 two very similar variables, 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.

The context 
--------------

Let's introduce a new Rougail concept here:

.. glossary:: 

   context
   
       A :term:`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. The set of the values of the variables
       in a given 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 of a data set.


.. type-along:: A new variable which has the `boolean` type

The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.

Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
Well, it depends on the :term:`context`. 

Let's create 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

.. questions:: Question: how does it work? 

   How will this variable drive the reuse of HTTP data to HTTPS data?

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

.. prerequisites:: Reminder

   So now we have three new variables in the `manual` family which expresses 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: shall we use the `disabled` property here?

   Is it relevant to use the :term:`disabled property <disabled>` here? 
   
   **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use 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 here. 

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.

.. important:: 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 driven by a boolean variable
-----------------------------------------------------------

But we want this `hidden` property to be assigned dynamically depending on the `use_for_https` `true` or `false` value.
Here is 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.