Update developers doc

DEVELOPERS.md

@@ -104,7 +104,7 @@ Le déploiement de ngHyd sous forme d'application de bureau se fait à l'aide d'
 
 `electron-builder.yml` contient la configuration de l'empaquetage pour les différentes plateformes cibles.
 
-Le dossier `electron` contient l'icône de l'application.
+Le dossier `src/assets/icons/electron/` contient l'icône de l'application.
 
 Le dossier `release` contient (entre autres) les paquets générés par electron-builder.
 
@@ -167,7 +167,6 @@ Dans ce nouveau dossier, créer le fichier `config.json`, comme suit :
     },
     {
         "type": "options",
-        "idCal": "Y",
         "help": "addition.html"
     }
 ]
@@ -175,13 +174,13 @@ Dans ce nouveau dossier, créer le fichier `config.json`, comme suit :
  
 Dans cet exemple, on définit un seul groupe de champs nommé arbitrairement "fs_addition", dans lequel on ajoute tous les paramètres de l'équation, désignés par leur symbole, qui doit correspondre au symbole fourni comme deuxième argument de `ParamDefinition()` dans JaLHyd.
 
-Le deuxième et dernier bloc contient les options pour ce module: le paramètre à calculer par défaut (`idCal`) qui peut être différent de celui choisi dans JaLHyd, et le lien vers la page de documentation pour ce module (`help`).
+Le deuxième et dernier bloc contient les options pour ce module: ici uniquement le lien vers la page de documentation pour ce module (`help`).
 
 Les options peuvent également contenir :
  * `defaultNodeType` : le type de section par défaut du module de calcul, pour les modules contenant une section
- * les valeurs par défaut des **propriétés** du module
- * les identifiants des listes déroulantes
- * l'aide associée aux résultats (voir ci-dessous)
+ * `selectIds` : les identifiants des listes déroulantes
+ * `resultsHelp` : l'aide associée aux résultats (voir ci-dessous)
+ * `calculateDisabled` : pour masquer le bouton Calculer (ex: module Espèce)
 
 #### champs
 
@@ -218,7 +217,7 @@ Différents éléments de la configuration peuvent contenir une clé `help` donn
  
 #### traduction
 
-Dans le dossier de configuration `src/app/calculators/addition`, créer les fichiers d'internationalisation, par exemple `fr.json` pour le français. Il doivent reprendre tous les identifiants utilisés dans le fichier de configuration (paramètres, groupes de champs, listes déroulantes…) et fournir leur traduction ainsi que leur unité si nécessaire, comme suit :
+Dans le dossier de configuration `src/app/calculators/addition`, créer les fichiers d'internationalisation, par exemple `fr.json` pour le français. Il doivent reprendre tous les identifiants utilisés dans le fichier de configuration (paramètres, groupes de champs, listes déroulantes…) et fournir leur traduction, comme suit :
 
 ```json
 {
@@ -226,15 +225,19 @@ Dans le dossier de configuration `src/app/calculators/addition`, créer les fich
 
   "A": "Premier nombre",
   "B": "Deuxième nombre",
-  "Y": "Somme",
-
-  "UNIT_A": "",
-  "UNIT_B": "",
-  "UNIT_Y": ""
+  "Y": "Somme"
 }
 ```
 
-Ici les mentions `UNIT_*` pourraient être omises.
+Si le module produit des résultats dont l'unité ne peut être déduite du modèle, ajouter des mentions `UNIT_*`  comme suit :
+```json
+{
+    …
+    "UNIT_V": "m/s",
+    "UNIT_YCOR": "m",
+    …
+}
+```
 
 ### thème
 
@@ -247,9 +250,15 @@ Dans les fichiers `locale/messages.*.json` :
  * ajouter deux champs pour le titre et le titre court du module de calcul. Par exemple pour un module "Addition" :
     * `"INFO_ADDITION_TITRE": "Addition de deux nombres"`
     * `"INFO_ADDITION_TITRE_COURT": "Addition"`
+ * pour le moteur de recherche (voir ci-dessous), ajouter un champ contenant des mots-clés :
+   * `"INFO_ADDITION_DESCRIPTION": "maths mathematics add plus sum"`
  * si le module produit des messages de log qui n'existaient pas jusqu'alors, ajouter leur traduction en utilisant la chaîne complète du code de message comme clé. Exemple :
     * `"ERROR_LOADING_SESSION": "Impossible de charger la session"`
 
+### moteur de recherche
+
+Le moteur de recherche présent sur la page de liste des modules permet de filtrer les modules par mots-clés. Les termes saisis sont comparés avec les valeurs suivantes : titre, titre court, description (voir ci-dessus).
+
 ### classes de formulaire personnalisées
 
 En général la classe `FormulaireDefinition` est suffisante pour gérer un nouveau module, et est instanciée automatiquement par `FormulaireService` lors de la création d'un nouveau module.
@@ -270,7 +279,7 @@ case CalculatorType.MacroRugoCompound:
 
 Les listes déroulantes sont toujours associées à des **propriétés** du Nub.
 
-En général les valeurs autorisées sont tirées de l'**enum** correspondant, d'après le tableau `Session.enumFromProperty` de JaLHyd. Pour les autres cas, voir les paragraphes "si la liste est associée à…" ci-dessous.
+En général les valeurs autorisées sont tirées de l'**enum** correspondant, d'après le tableau `Session.enumFromProperty` de JaLHyd. Pour les autres cas, voir les paragraphes "source" et "liste déroulante personnalisée" ci-dessous.
 
 #### configuration
 
@@ -305,9 +314,9 @@ Dans le fichier de configuration du module, ajouter la définition des listes d
 
 **IMPORTANT** : les id doivent être de la forme `select_`_`unmotclesansespacenitirets`_
 
-#### si la liste n'est pas associée à un enum
+#### source
  
-Une liste déroulante peut être associée à une **source**, qui détermine quels sont les choix possibles.
+Une liste déroulante telle que décrite ci-dessus peut être associée à une **source**, qui détermine quels sont les choix possibles. Ceci est utile lorsque les choix possibles ne proviennent pas d'un `enum`. Pour autant ce n'est pas équivalent à la méthode "liste déroulante personnalisée" décrite au chapitre suivant (ces deux techniques devraient être fusionnées).
 
 Pour ajouter une source, modifier la méthode `loadEntriesFromSource()` de la classe `SelectField`, dans le fichier `src/app/formulaire/elements/select-field.ts`.
 
@@ -338,6 +347,111 @@ Puis dans le fichier de configuration du module, déclarer la source :
     …
 ```
 
+#### liste déroulante personnalisée
+
+Il est possible de personnaliser complètement le comportement d'une liste déroulante pour des cas plus complexes, en utilisant l'élément de formulaire `SelectCustom`.
+
+De telles listes doivent être déclarées dans la configuration du module en utilisant le type `select_custom`, un identifiant de `source` (identique à celui vu au chapitre précédent, mais attention : il se comporte différemment) et l'identifiant de la liste doit être mentionné dans l'option `customSelectIds` (et non `selectIds`).
+
+Exemple pour la cible du Solveur :
+```json
+…
+"fields": [
+    {
+        "id": "select_target_nub",
+        "type": "select_custom",
+        "source": "solveur_target"
+    },
+    …
+]
+…
+{
+    "type": "options",
+    "customSelectIds": [ "select_target_nub", … ],
+    …
+}
+```
+
+Dans le fichier `src/app/formulaire/elements/select-field-custom.ts`, remplir les méthodes `populate()` (définit les choix possibles) et `initSelectedValue()` (affecte la valeur actuellement définie dans le modèle).
+
+
+Exemple pour la cible du Solveur : `populate()`
+```typescript
+case "solveur_target": // Solveur, module cible (à calculer)
+    // find all Nubs having at least one link to another Nub's result
+    candidateNubs =
+        Session.getInstance().getDownstreamNubs().concat(
+            Session.getInstance().getUpstreamNubsHavingExtraResults()
+        ).filter(
+            (element, index, self) => self.findIndex((e) => e.uid === element.uid) === index
+        );
+    for (const cn of candidateNubs) {
+        const nub = fs.getFormulaireFromId(cn.uid);
+        if (nub) {
+            const calc = nub.calculatorName;
+            let label = calc;
+            // calculated param
+            if (cn.calculatedParam !== undefined) {
+                const varName = fs.expandVariableName(cn.calcType, cn.calculatedParam.symbol);
+                label += ` / ${varName} (${cn.calculatedParam.symbol})`;
+            }
+            this.addEntry(new SelectEntry(this._entriesBaseId + cn.uid, cn.uid, decodeHtml(label)));
+        } else {
+            // silent fail, this Solveur nub was probably loaded before all the candidate nubs are done loading
+        }
+    }
+    break;
+```
+
+Comme au chapitre précédent, il s'agit d'ajouter des options de type `SelectEntry` à l'aide de la méthode `addEntry()`.
+
+Exemple pour la cible du Solveur : `initSelectedValue()`
+```typescript
+case "solveur_target": // Solveur, module cible (à calculer)
+    const ntc = (nub as Solveur).nubToCalculate;
+    if (ntc !== undefined) {
+        this.setValueFromId(this._entriesBaseId + ntc.uid);
+    }
+    break;
+```
+
+Ici il s'agit de choisir la bonne option du sélecteur, en fonction de la valeur courante de la propriété dans le modèle.
+
+Enfin, ce type de liste déroulante nécessite une classe de formulaire personnalisée, dans laquelle la méthode `update()` doit être enrichie.
+
+Exemple dans `src/app/formulaire/definition/form-solveur.ts`, pour la cible du Solveur :
+
+```typescript
+public update(sender: IObservable, data: any) {
+    …
+    if (sender instanceof SelectFieldCustom) {
+        if (sender.id === "select_target_nub" && data.action === "select") {
+            // update Solveur property: Nub to calculate
+            try {
+                // if searchedParam is set to a value that won't be available anymore
+                // once nubToCalculate is updated, setPropValue throws an error, but
+                // nubToCalculate is updated anyway; here, just inhibit the error
+                this._currentNub.properties.setPropValue("nubToCalculate", data.value.value);
+            } catch (e) { }
+            // refresh targetted result selector
+            const trSel = this.getFormulaireNodeById(this._targettedResultSelectId) as SelectField;
+            if (trSel) {
+                (trSel.parent as FieldSet).updateFields();
+                // trick to re-set observers
+                this.completeParse(false);
+            }
+            // refresh parameters selector
+            this.refreshParameterEntries();
+        }
+        …
+    }
+    …
+}
+```
+
+Ici on écoute l'événement généré par l'objet `SelectFieldCustom`, et on agit en conséquence : affecter la propriété concernée, et rafraîchir un champ dépendant.
+
+
 #### si l'affichage de certains champs dépend du choix dans la liste
 
 Les listes dont l'identifiant est déclaré dans le fichier de configuration du module déclencheront, lorsque leur valeur change, un effacement des résultats du module et une mise à jour de tous les "fieldset" du formulaire.
@@ -384,7 +498,12 @@ Puis dans les options, déclarer  ce sélecteur et ajouter "defaultNodeType" :
 
 ### si le module agrège des modules enfants
 
-La traduction des variables des modules enfants doit aussi être ajoutée dans les fichiers de langues, dans le dossier de configuration du module.
+La traduction des variables des modules enfants doit être ajoutée dans les fichiers de langues principaux de l'application, sous la forme `INFO_LIB_CODEVARIABLE`. Par exemple :
+```json
+{
+    "INFO_LIB_CDCUNGE": "Coefficient de débit"
+}
+```
 
 #### si ces modules enfants sont répétables ("fs_container")
 
@@ -469,7 +588,17 @@ Dans la configuration du module, dans le "fieldset_template", ajouter un sélect
             "id": "select_loidebit",
             "type": "select",
             "property": "loiDebit",
-            "source": "device_loi_debit"
+            "source": "device_loi_debit",
+            "help": {
+                "Orifice_OrificeSubmerged": "structures/orifice_noye.html",
+                "SeuilRectangulaire_WeirVillemonte": "structures/kivi.html",
+                "SeuilRectangulaire_WeirSubmergedLarinier": "structures/fente_noyee.html",
+                "SeuilRectangulaire_WeirCunge80": "structures/cunge_80.html",
+                "VanneRectangulaire_GateCunge80": "structures/cunge_80.html",
+                "SeuilTriangulaire_TriangularWeirFree": "structures/dever_triang.html",
+                "SeuilTriangulaire_TriangularWeirBroad": "structures/dever_triang.html",
+                "SeuilTriangulaireTrunc_TriangularTruncWeirFree": "structures/dever_triang_tronque.html"
+            }
         }
 ```
 
@@ -487,7 +616,14 @@ Dans les options, déclarer  les sélecteurs :
 
 Pour chaque langue, ajouter un fichier .md dans les dossiers `docs/*/calculators`, puis placer ce nouveau fichier dans la hiérarchie de la documentation, en ajoutant son chemin dans les fichiers `mkdocs-*.yml`.
 
-Lier ce fichier au module via la clé `help` du bloc d'options de la configuration du module. Exemple pour un fichier de documentation dont le chemin est `calculators/math/addition.md` : `"help" : "math/addition.html"` (MkDocs convertit les fichiers MarkDown en HTML)
+Lier ce fichier au module via la clé `help` du bloc d'options de la configuration du module. Exemple pour un fichier de documentation dont le chemin est `calculators/math/addition.md` :
+```json
+{
+    …
+    "help" : "math/addition.html"
+}
+```
+(MkDocs convertit les fichiers MarkDown en HTML)
 
 ### tests unitaires