The disabled property

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.

Reminder

A disabled property assigned to a family

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.

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:

../_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 address and 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.

disabling the address and 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.

The http_proxy subfamily in the firefox/10-manual.yml structure file
 1---
 2manual:
 3  description: Manual proxy configuration
 4  disabled: true
 5
 6  http_proxy:
 7    description: HTTP Proxy
 8
 9    address:
10      description: HTTP address
11      type: domainname
12      params:
13        allow_ip: true
14
15    port:
16      description: HTTP Port
17      type: port
18      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.

The manual setting in the config/03/config.yaml user datas file
1---
2proxy_mode: Manual proxy configuration
3manual:
4  http_proxy:
5    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:

rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml

As expected, we encounter an error:

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

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.

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:

The manual family in the firefox/10-manual.yml structure file with a conditional disabled property
 1---
 2manual:
 3  description: Manual proxy configuration
 4  disabled:
 5    type: variable
 6    variable: proxy_mode
 7    when_not: 'Manual proxy configuration'
 8
 9  http_proxy:
10    description: HTTP Proxy
11
12    address:
13      description: HTTP address
14      type: domainname
15      params:
16        allow_ip: true
17
18    port:
19      description: HTTP Port
20      type: port
21      default: 8080

Explanation

Here we have the disabled property like this:

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.

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 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 family named manual and a sub family named http_proxy

  • And we have now two variables: proxy_mode and address.

  • We have dynamically disabled the manual family (and the http_proxy sub family).