docs(propertyerror)

docs/structured_data/data_integrity.rst

@@ -22,6 +22,8 @@ The values of the variables must be individually of good quality.
    typing
    variable_validation
 
+.. _access_control:
+
 Access control
 ~~~~~~~~~~~~~~
 

docs/tutorial/index.rst

@@ -61,6 +61,7 @@ Let's dive into this **configuration options validation** use case.
    multiple
    document
    practice1
+   propertyerror
    practice2
    validators
    namespace

docs/tutorial/jinja.rst

@@ -1,3 +1,5 @@
+.. _tutorial_jinja:
+
 Playing with Jinja 
 ====================
 

docs/tutorial/propertyerror.rst

@@ -0,0 +1,57 @@
+.. _tutorial_propertyerror:
+
+The Jinja propertyerror test
+============================
+
+.. objectives:: Objectives
+
+   In a :ref:`Jinja-type calculation <tutorial_jinja>`, it is possible to test if a variable is accessible (there is no :ref:`access_control` problem).
+
+.. 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 tag :tutorial:`v1.1_140 <src/tag/v1.1_140/README.md>` in the repository:
+
+    ::
+   
+       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
+       git switch --detach v1.1_140
+
+For now, the variable `proxy_dns_socks5` defines these access controls as follows:
+
+- if the `proxy_mode` variable is not set to `"Manual proxy configuration"`
+- if socks version is `v4`.
+
+.. 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`
+
+In principle it works, but is that really what we want? We mean, do we want to disable it based on the proxy_mode variable?
+
+No, we actually want to make this variable available if the socks version is accessible and equals v4.
+
+Disabled a variable when an other variable is disabled
+-------------------------------------------------------
+
+The most suitable syntax in Jinja for checking the status of a variable is to use the `concept of a test <https://jinja.palletsprojects.com/en/stable/templates/#tests>`_.
+
+Rougail offers a custom test that will verify correct access to the variable.
+
+This test is call `propertyerror`.
+
+Here is how one could write the Jinja using this feature:
+
+.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_140/firefox/55-proxy_dns_socks5.yml
+   :language: yaml 
+   :caption: The :file:`firefox/55-proxy_dns_socks5.yml` structure file with some Jinja code in the `hidden` property
+
+.. keypoints:: Key points
+
+   We have seen that we can use the test `propertyerror` in Jinja template.