The `hidden` property

Objectives

In this section we will:

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

Reminder

Let’s summarize the configuration up to here

Whe have the proxy_mode configuration here:

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 family that is used in case of the "Manual proxy configuration" value of the proxy_mode variable has been chosen:

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.

The HTTPS mode

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

We are going to define two other variables for the HTTPS use only:

https_proxy.address

Type:: domainname

This is an address setting for the manual HTTPS configuration

https_proxy.port

Type:: port

This is a port setting for the manual HTTPS configuration

There are now 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:

context: A configuration is highly statefull and can change at any moment. Sometimes somes minor changes in the user datas may involve chain reactions in the whole configuration. The context is the state of the user datas at one moment. The set of the values of the variables at 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.

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

Let’s create a new variable, named use_for_https here:

use_for_https

Type:: boolean
Default:: true

This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS

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:

firefox/20-manual.yml

---
manual:

  use_for_https:
    description: Also use this proxy for HTTPS
    type: boolean
    default: true

Reminder

So now we have three new variables in the manual family (with its https_proxy subfamily) which express the manual mode of the http proxy configuration.

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

Question: shall we use the disabled property here?

Is it relevant to use the disabled property here?

answer: No! Because we need to use these variables at any 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.

We have to create a new property here.

The `hidden` property

hidden: A variable or family’s property is hidden if its value shall not be seen in a given context. 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:

The https_proxy subfamily with the hidden property

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

Warning

A hidden variable with the mandatory parameter set still shall have a defined value, even if it’s hidden.

If we choose the manual proxy configuration mode,

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

🛑 ERRORS
┣━━ The following variables are mandatory but have no value:
┗━━   - manual.http_proxy.address (HTTP address)

A contextual hidden family driven by a boolean variable

What we want is having this hidden property assigned dynamically depending on the use_for_https true or false value.

Here is how to achieve this:

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

Yes, it is possible to add a variable parameter to the hidden attribute.

A contextualized default value

A contextualized default value

A contextualized default value is a default value (of a variable) that is driven by another variable. This variable type and its parameters type are copied in the default value’s target variable.

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:

port:
  description: HTTPS Port
  type: port
  default: 8080

The dynamic setting of a default can be achieved in this way:

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

The default value is a pointer to another variable’s value. Here, the defaut value of manual.https_proxy.address points to manual.http_proxy.address.

This is the same thing for the default value of the manual.https_proxy.port variable, which points to the manual.http_proxy.port value.

We also say that the default value is calculated.

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 jinja code or a python function that calculates it.

Key points

Keywords

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

The hidden property

The context

The hidden property

A contextual hidden family driven by a boolean variable

A contextualized default value

The `hidden` property

The `hidden` property