rougail/docs/tutorial/practice1.rst

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

.. objectives:: Objectives

   Now it's your turn.
   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 two 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 variables in the firefox configuration's widget:

.. image:: images/practice_twovars.png

These two variables are highlighted here in the lower part of the firefox configuration's widget:

.. image:: images/firefox130.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_130 <src/tag/1.1_130/README.md>` to :tutorial:`1.1_132 <src/tag/1.1_132/README.md>`
    in the repository.

    ::

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

A conditional disabled boolean variable
-------------------------------------------------------------

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

.. exercise:: Exercice

    - choose a file name that respect the :ref:`file naming and organizing convention <namingconvention>`
    - define an appropriate variable name # FIXME pas de convention pour le nom des familles/variables ?
    - the Firefox description is in negative mode, which is not a good practice for us, we rewrite it in positive mode
    - the variable is a boolean with the default value `true` (the opposite of unchecked option)
    - the variable is available for all proxy mode choice by user, so disable it only when the `proxy mode` is "No proxy".

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_130/firefox/50-prompt_authentication.yml
       :language: yaml
       :caption: The :file:`firefox/50-prompt_authentication.yml` a conditional disabled boolean variable

    - Here we choosed to name the new structure file `firefox/50-prompt_authentication.yml`, the file containing the two variables definition,
    - this variable is true by default,
    - this variable shall be :term:`disabled` if the `proxy_mode` variable is set to `"No proxy"`.

.. 
    %YAML 1.2
    ---
    version: 1.1
    
    prompt_authentication:
      description: Prompt for authentication if password is saved
      default: true
      disabled:
        variable: _.proxy_mode
        when: No proxy
    ...

A Jinja conditional disabled boolean variable
-------------------------------------------------

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

.. exercise:: Exercice

    - choice a file name that respect the :ref:`file naming and organizing convention <namingconvention>`
    - define an appropriate variable name # FIXME pas de convention pour le nom des familles/variables ?
    - the description will be the Firefox description 
    - the variable is a boolean with the default value `false` (unchecked option)
    - the variable is only available with the "Manual proxy configuration" proxy mode and when the proxy socks version is not v4.


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_131 <src/tag/v1.1_131/README.md>` version::
     
          git switch --detach v1.1_131

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

.. solution:: Solution

    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_131/firefox/55-proxy_dns_socks5.yml
       :language: yaml
       :caption: The :file:`firefox/55-proxy_dns_socks5.yml` a Jinja conditional disabled boolean variable

.. 
    %YAML 1.2
    ---
    version: 1.1
    
    proxy_dns_socks5:
      description: Use proxy DNS when using SOCKS v5
      default: false
      disabled:
        jinja: |-
          {{ _.proxy_mode != "Manual proxy configuration" or _.manual.socks_proxy.version == 'v4' }}
        return_type: boolean
        description: |-
          if "_.proxy_mode" is not "Manual proxy configuration"
          or "_.manual.socks_proxy.version" is "v4"
    ...