From 8d7dde7bcc90bfd1e55fe1b40937427d96c6fc9b Mon Sep 17 00:00:00 2001 From: gwen Date: Sat, 31 May 2025 14:14:19 +0200 Subject: [PATCH] boolean type and hidden property --- docs/tutorial/boolean.rst | 77 +++++++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 31 deletions(-) diff --git a/docs/tutorial/boolean.rst b/docs/tutorial/boolean.rst index c318bb642..ef4ef6a5b 100644 --- a/docs/tutorial/boolean.rst +++ b/docs/tutorial/boolean.rst @@ -1,15 +1,16 @@ -A new variable which has the `boolean` type -=============================================== +The `hidden` property +======================= .. objectives:: Objectives - In this section we will learn: + In this section we will: - - how to make a boolean type variable - - how to reuse some value of a variable - (in this use case we will reuse the HTTP configuration variables values for the HTTPS configuration) + - 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:: Reminders +.. prerequisites:: Reminder Let's summarize the configuration up to here @@ -31,7 +32,7 @@ Whe have the `proxy_mode` configuration here: - Automatic proxy configuration URL default: No proxy -With the manual subfamily in case of the "Manual proxy configuration" configuration option has been chosen: +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 @@ -59,9 +60,11 @@ With the manual subfamily in case of the "Manual proxy configuration" configurat type: port default: 8080 -.. type-along:: The HTTPS mode +OK then. Let's continue our proxy's configuration. -Now we will focus on configuring the HTTPS mode in case of "Manual proxy 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 @@ -77,30 +80,38 @@ Let's set two other variables for the HTTPS use only: This is a port setting for the manual HTTPS configuration -- So we have 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 +- 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. -.. type-along:: What do we want to reuse? +The context +-------------- -Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode? -It depends on the context. +Let's introduce a new Rougail concept here: .. glossary:: context - A configuration is highly statefull and can change at any moment. + 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, this term also refers + 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. + that is, the deeply **statefull** aspects of a data set. -A new `boolean` type variable -------------------------------- -We have a new variable, named `use_for_https` here: +.. 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` @@ -108,6 +119,10 @@ We have a new variable, named `use_for_https` here: 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 @@ -123,13 +138,13 @@ Its description in the structure file gives us this: type: boolean default: true -.. type-along:: Update of the context +.. prerequisites:: Reminder - So now we have three new variables in the manual mode of the http proxy configuration. + 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 + :caption: `firefox/20-manual.yml` .. --- @@ -158,17 +173,17 @@ And with this :confval:`use_for_https` boolean variable, there are two possibili - 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: disabled? +.. questions:: Question: shall we use the `disabled` property here? Is it relevant to use the :term:`disabled property ` here? - **answer**: No! Because we *need* to use these variables at any case, + **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. +Let's introduce here a new concept here. The hidden property --------------------- @@ -213,7 +228,7 @@ Now we can set a `hidden` property to the `https_proxy` family: The whole `https_proxy` family has been set to `hidden` here. -.. type-along:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value +.. important:: A `hidden` variable with the `mandatory` parameter set still shall have a defined value If we choose the manual proxy configuration mode, @@ -241,11 +256,11 @@ Rougail will raise an error: ┗━━ - manual.http_proxy.address (HTTP address) -A conditional hidden family with a boolean variable --------------------------------------------------------- +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. -How to achieve this. +Here is how to achieve this. It is possible to add a `variable` parameter to the `hidden` attribute like this: