Practice
================================

.. objectives:: Objectives

   Now it's your turn again.
   Try making some Rougail.
   At the same time, if you get stuck, you have the solutions in the Rougail tutorial
   code repository.

   There is nothing new in the three next Firefox variables. So it is the time to practice what we've learned until now.

   This page is divided in two parts for each variable:

   - Explain what we want to implement
   - Propose to you a solution

   The best for you is to do this job on your own and compare your work to our propositions.

Here are the two first variables in the Firefox configuration's widget:

.. image:: images/practice_threevars.png

The third appears only if we enable DNS over HTTPS with a custom providers, we have to set a `Custom DNS URL`.

These three variables are highlighted here in the lower part of the Firefox configuration's widget:

.. image:: images/firefox160.png

.. prerequisites:: Prerequisites

    - We assume that Rougail's library is :ref:`installed <installation>` on your computer.

    - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
      by checking out the corresponding tag of the `rougail-tutorials` git repository.
      Each tag corresponds to a stage of progress in the tutorial.
      Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.

    If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
    this workshop page corresponds to the tags :tutorial:`1.1_160 <src/tag/1.1_160/README.md>` to :tutorial:`1.1_162 <src/tag/1.1_162/README.md>`
    in the repository.

    ::

       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach 1.1_160

A boolean variable
------------------

What do we want to be implemented
'''''''''''''''''''''''''''''''''''

.. exercise:: Exercice

    You need to think about:

    - choose a file name that respect the :ref:`file naming and organizing convention <filenamingconvention>`
    - define an appropriate family and variable name, have a look at our :ref:`variable naming convention <namingconvention>`
    - we will set the variable in a family (with others variable later) to separate this purpose
    - the family and variable `description` parameter will be the Firefox description
    - the variable is a :ref:`boolean <tutorial_boolean_variable>` with the default value `false` (unchecked option)
    - the family and variable are always available, it's not directly related to the proxy choice

Our solution
'''''''''''''''''''''''''''''''

Please unroll the "Solution" widget to see our solution:

.. solution:: Solution

    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_160/firefox/60-dns_over_https.yml
       :language: yaml
       :caption: The :file:`firefox/60-dns_over_https.yml` a boolean variable

    - Here we choosed to name the new structure file `firefox/60-dns_over_https.yml`,
      the file containing the `dns_over_https` family and the `enable_dns_over_https` variable definition
    - this variable is a :ref:`boolean <tutorial_boolean_variable>` with the default value `false`

..
    %YAML 1.2
    ---
    version: 1.1
    
    dns_over_https:  # DNS over HTTPS
    
      enable_dns_over_https: false  # Enable DNS over HTTPS
    ...

A choice variable
-----------------

What do we want to be implemented
'''''''''''''''''''''''''''''''''''

.. exercise:: Exercice

    You need to think about:

    - this variable will be in the same file as the first one
    - define an appropriate variable name, have a look at our :ref:`variable naming convention <namingconvention>`
    - we will set the variable in the previous family
    - the variable `description` parameter will be the Firefox description
    - the variable is a :ref:`choice <tutorial_choice>` with the following proposal: `Cloudflare`, `NextDNS` and `Custom`
    - this variable shall be :ref:`disabled <tutorial_disabled>` if the `enable_dns_over_https` variable is `false`.

Our solution
'''''''''''''''''''''''''''''''

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the :tutorial:`v1.1_161 <src/tag/v1.1_161/README.md>` version::

          git switch --detach v1.1_161

Please unroll the "Solution" widget to see our solution:

.. solution:: Solution

    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_161/firefox/60-dns_over_https.yml
       :language: yaml
       :caption: The :file:`firefox/60-dns_over_https.yml` a choice variable

    - Here we choosed to name the new structure file `firefox/60-dns_over_https.yml`,
      the file containing the `dns_over_https` family and the `enable_dns_over_https` variable definition
    - this variable is false by default
    - this variable is :ref:`disabled <tutorial_disabled>` if `enable_dns_over_https` is `false`

..
    %YAML 1.2
    ---
    version: 1.1
    
    dns_over_https:  # DNS over HTTPS
    
      enable_dns_over_https: false  # Enable DNS over HTTPS
    
      provider:
        description: Use Provider
        choices:
          - Cloudflare
          - NextDNS
          - Custom
        default: Cloudflare
        disabled:
          variable: _.enable_dns_over_https
          when: false
    ...


A web_address variable
----------------------

What do we want to be implemented
'''''''''''''''''''''''''''''''''''

.. exercise:: Exercice

    You need to think about:

    - this variable will be in the same file as the two others
    - define an appropriate variable name, have a look at our :ref:`variable naming convention <namingconvention>`
    - we will set the variable in the previous family
    - the variable `description` parameter will be the Firefox description
    - the variable is a `web_address`
    - this variable shall be :ref:`disabled <tutorial_disabled>` if the `provider` variable is not `Custom`
    - the variable `provider` could be :ref:`disabled <tutorial_disabled>` too


Our solution
'''''''''''''''''''''''''''''''

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the :tutorial:`v1.1_162 <src/tag/v1.1_162/README.md>` version::

          git switch --detach v1.1_162

Please unroll the "Solution" widget to see our solution:

.. solution:: Solution

    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_162/firefox/60-dns_over_https.yml
       :language: yaml
       :caption: The :file:`firefox/60-dns_over_https.yml` a choice variable

    - Here we choosed to name the new structure file `firefox/60-dns_over_https.yml`,
      the file containing the `custom_dns_url` variable definition
    - this is a :ref:`web_address <tutorial_web_address>` variable
    - this variable is :ref:`disabled <tutorial_disabled>` if `provider` has :ref:`an access property error <tutorial_propertyerror>` and `provider` has not the value "Custom"

..
    %YAML 1.2
    ---
    version: 1.1
    
    dns_over_https:  # DNS over HTTPS
    
      enable_dns_over_https: false  # Enable DNS over HTTPS
    
      provider:
        description: Use Provider
        choices:
          - Cloudflare
          - NextDNS
          - Custom
        default: Cloudflare
        disabled:
          variable: _.enable_dns_over_https
          when: false
    
      custom_dns_url:
        description: Custom DNS URL
        type: web_address
        disabled:
          jinja: |-
            {{ _.provider is propertyerror or _.provider != 'Custom' }}
          return_type: boolean
          description: if "_.provider" is not "Custom"
    ...