add documentation for embedded show/hide

source/development/user-interface/js-functions.rst

@@ -162,3 +162,100 @@ Example usage: here, we would like to catch for element inside a CV form, where
        }
    });
 
+Handling encapsulated show/hide elements
+========================================
+
+This module allow to handle encapsulated show/hide elements. For instance :
+
+* in a first checkbox list, a second checkbox list is shown if some element is checked ;
+* in this second checkbox list, a third input is shown if some element is checked inside the second checkbox list.
+
+As a consequence, if the given element in the first checkbox list is unchecked, the third input must also be hidden.
+
+Example: when a situation professionnelle is ``en activite``, the second element ``type contrat`` must be shown if ``en_activite`` is checked. Inside ``type_contrat``, ``type_contrat_aide`` should be shown when ``contrat_aide`` is checked.
+
+.. code-block:: html
+
+        <div id="situation_prof">
+            <input type="radio" name="situationProfessionnelle" value="" checked="checked" />
+            <input type="radio" name="situationProfessionnelle" value="sans_emploi" />
+            <input type="radio" name="situationProfessionnelle" value="en_activite" />
+        </div>
+        
+        
+        <div id="type_contrat">
+            <input type="checkbox" name="typeContrat[]" value="cdd" /> 
+            <input type="checkbox" name="typeContrat[]" value="cdi" />
+            <input type="checkbox" name="typeContrat[]" value="contrat_aide" />
+        </div>
+        
+        <div id="type_contrat_aide">
+            <input type="text" name="typeContratAide" />
+        </div>
+
+The JS code will be:
+
+.. code-block:: javascript
+
+   import { ShowHide } from 'ShowHide/show_hide.js';
+   // we search for the element within the DOM
+   // NOTE: all the elements should be searched before instanciating the showHides. 
+   // if not, the elements **may** have disappeared from the DOM
+
+   var
+       situation_prof = document.getElementById('situation_prof'),
+       type_contrat = document.getElementById('type_contrat'),
+       type_contrat_aide = document.getElementById('type_contrat_aide'),
+       ;
+
+   // the first show/hide will apply on situation_prof
+   new ShowHide({
+       // the id will help us to keep a track of the element
+       id: 'situation_prof_type_contrat',
+       froms: [situation_prof],
+       container: [type_contrat],
+       test: function(froms) {
+           for (let f of froms.values()) {
+               for (let input of f.querySelectorAll('input').values()) {
+                   if (input.value === 'en_activite') {
+                       return input.checked;
+                   }
+               }
+           }
+           
+           return false;
+       }
+   });
+
+   // the show/hide will apply on "contrat aide"
+   var show_hide_contrat_aide = new ShowHide({
+       froms: [type_contrat],
+       container: [type_contrat_aide],
+       test: function(froms) {
+           for (let f of froms.values()) {
+               for (let input of f.querySelectorAll('input').values()) {
+                   if (input.value === 'contrat_aide') {
+                       return input.checked;
+                   }
+               }
+           }
+           
+           return false;
+       }
+   });
+
+   // we handle here the case when the first show-hide is changed: the third input must also disappears
+   window.addEventListener('show-hide-hide', function (e) {
+       if (e.detail.id = 'situation_prof_type_contrat') {
+           // we force the 3rd element to disappears
+           show_hide_contrat_aide.forceHide();
+       }
+   });
+
+   // when the first show-hide is changed, it makes appears the second one.
+   // we check here that the second show-hide is processed.
+   window.addEventListener('show-hide-show', function (e) {
+       if (e.detail.id = 'situation_prof_type_contrat') {
+           show_hide_contrat_aide.forceCompute();
+       }
+   });