DEVELOPERS.md

# Documentation ngHyd pour les développeurs

Voir aussi : 

 * [ngHyd installation instructions](README.md)
 * [JaLHyd developers documentation](https://gitlab.irstea.fr/cassiopee/jalhyd/blob/master/DEVELOPERS.md)

## Description

ngHyd est une interface Web pour [JaLHyd](https://gitlab.irstea.fr/cassiopee/jalhyd) écrite en Angular/typescript.

Elle est déclinée à l'aide d'Electron et Cordova sous forme d'application hors-ligne pour Linux, Mac, Windows et Android.

Les tests unitaires sont réalisés avec Protractor.

La documentation est générée avec Mkdocs.

## Pile logicielle

 * typescript
 * angular
 * angular-material
 * protractor
 * electron
 * cordova
 * mkdocs

## Prérequis

### pour le développement

 * nodejs / npm
 * python (pour mkdocs)
 * wine (pour Electron / windows)
 * java (pour cordova / Android)
 * SDK Android (pour cordova / Android)

### pour l'exécution

 * version Web : une connexion Internet et un navigateur à jour (Firefox, Chrome/Chromium, Safari, Edge…)
 * version hors-ligne : Linux, MacOS, Windows 7 ou plus récent, Android 7 ou plus récent
 
## Grands principes

### interface

ngHyd propose deux vues principales : la **page d'accueil** `/list` qui permet de créer de nouveaux modules de calcul, et la **vue module** `/calculator/{id}` qui affiche un des modules de la session.

Une **barre de navigation** en haut de l'écran permet de passer d'un module à l'autre, et de revenir à la page d'accueil.

Un **volet latéral** permet d'accéder à des commandes et vues supplémentaires.

L'interface s'appuie sur les principes de **material design** et de **responsive design**. Le contenu est supposé s'afficher correctement à partir d'une largeur d'écran de **360px**.

### modèle

L'état de la session, des modules, des paramètres et des résultats numériques est conservé par JaLHyd. Seules les représentations graphiques sont conservées par la couche ngHyd.

Pour chaque module chargé en session, un arbre d'objets partant d'une instance de `FormulaireDefinition` représente la structure des éléments à l'écran : groupes de champs (répétables ou non), champs, listes déroulantes. Ces éléments sont déclarés dans les fichiers du dossier `src/app/formulaire`.

#### formulaires

Les formulaires dérivent de `FormulaireBase`. Lors de leur instanciation, ils se chargent de lire leur configuration (voir "configuration/modules" ci-dessous) et instancier les éléments enfants qui y sont déclarés : groupes de champs ("fieldset"), groupes de champs répétables ("fieldset_container"), paramètres d'entrée ("ngparam"), listes déroulantes ("select_field"). Ensuite le formulaire est lié au Nub de JaLHyd correspondant au module créé.

Chaque formulaire est associé à une instance d'une classe `FormCompute*` et une instance d'une classe `FormResult*`. La première est chargée d'exécuter le Nub de JaLHYd associé au formulaire, et de transmettre les résultats de calcul à la seconde. La seconde est chargée d'organiser les résultats (par défaut les grouper en résultats fixes / résultats variés) afin de faciliter leur représentation par les composants graphiques.

### configuration

#### générale

La configuration générale se trouve dans `src/app/config.json`.

Dans `params` on trouve les valeurs par défaut des réglages.

Dans `themes` on trouve l'organisation des modules en thèmes sur la page d'accueil. Dans chaque thème, la clé `calculators` doit contenir une liste de valeurs numériques correspondant à des éléments de l'enum `CalculatorType` de JaLHyd. Un même module peut être présent dans plusieurs thèmes. Si un module n'est présent dans aucun thème, il apparaîtra automatiquement dans un thème "autres" qui n'est visible que dans un tel cas.

#### modules

Chaque module de calcul JaLHyd doit être configuré dans `src/app/calculators`, dans un dossier portant le nom du module.

Le fichier de configuration principal est `src/app/calculators/lemodule/lemodule.config.json` (exemple pour le module "bief" : `src/app/calculators/bief/bief.config.json`). Il contient la liste des composants graphiques à afficher à l'écran, de haut en bas (généralement des "fieldset"), la répartition des paramètres du module dans ces éléments, et un bloc de configuration à la fin.

Pour chaque langue, un fichier supplémentaire est présent contenant les traductions contextualisées pour le module (voir "langues et traduction" plus bas).

### exemples de sessions

Des exemples de sessions prêtes à charger sont présents sous forme de fichiers JSON dans `src/app/examples`. Lors de l'ajout d'un nouveau fichier d'exemple, celui-ci doit être référencé dans la méthode `get exampleFiles()` dans le fichier `src/app/components/calculator-list.component.ts`. Ces exemples sont affichés sur la page d'accueil dans la dernière carte, lorsqu'aucun module n'a encore été créé.

### langues et traduction

Les chaînes de l'application sont traduites à l'aide du service `I18nService`, méthodes `localizeText()` pour les chaînes en général et `localizeMessage()` pour les messages de log de JaLHyd.

Les traductions doivent être placées dans les fichiers de langues du dossier `src/locale`.

Lorsqu'un module de calcul a besoin d'une traduction contextualisée, par exemple dans le cas d'une variable ayant le même symbole que dans d'autres modules de calcul, les traductions doivent être placées dans `src/app/calculators/lemodule/lemodule.lalangue.json` (exemple pour le module "bief" en anglais : `src/app/calculators/bief/bief.en.json`).

### electron

Le déploiement de ngHyd sous forme d'application de bureau se fait à l'aide d'Electron. Les fichiers concernés sont `main.js`, `electron-builder.yml`, les dossier `electron` et `release`.

`main.js` est le fichier de "bootstrap" d'Electron. Il contient la création de la fenêtre de l'application, et le mécanisme de détection de mises à jour. Pour débugger, on peut décommenter `win.webContents.openDevTools()`.

`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 `release` contient (entre autres) les paquets générés par electron-builder.

### cordova

Le déploiement de ngHyd sous forme d'application mobile se fait à l'aide de Cordova. Les fichiers et dossiers concernés sont `hooks`, `platforms`, `plugins`, `config.xml`, et les différentes icônes .png présentes dans `src`.

### documentation

La documentation est générée à l'aide de MkDocs.

Les fichiers source pour une langue donnée se trouvent dans le dossier `docs-lang` (ex: `docs-fr`). Pour traduire la documentation dans une autre langue, il faut recopier l'intégralité des fichiers source puis les traduire. Afin de faciliter les liens de l'application vers la documentation, les noms des fichiers ne sont pas traduits et restent en français pour toutes les langues.

L'organisation hiérarchique de la documentation est définie dans les fichiers `mkdocs-lang.yml` (ex: `mkdocs-fr.yml`).

### tests unitaires

Les tests unitaires dits "end-to-end" ou "e2e" sont réalisés avec Protractor, basé sur Selenium et fourni avec Angular. Les tests se trouvent dans le dossier `e2e` et sont configurés dans `protractor.conf.js`.

Bien qu'elle soit supposée fonctionner avec d'autres navigateurs, l'exécution des tests n'est garantie qu'avec Chrome / Chromium. Le pilote Selenium pour Chrome ("chromedriver") posant parfois problème, `protractor.conf.js` contient une astuce qui recherche le pilote dans le système avant de le rechercher dans node_modules.

Pour plus d'informations sur les problèmes liés à la version du pilote Selenium pour Chrome, consulter le chapitre "chromedriver version in e2e tests" dans la documentation développeurs (en anglais).

### scripts

Le dossier `scripts` contient des scripts d'aide à la compilation, utilisés par les commandes `npm` déclarées dans `package.json`.

## Ajouter un module de calcul

Dans cet exemple nous considérerons le module fictif "Addition" proposé dans la documentation de JaLHyd (voir ci-dessous), tout en ajoutant des informations utiles pour des cas plus complexes.

### JaLHyd

Voir la [documentation JaLHyd pour les développeurs](https://gitlab.irstea.fr/cassiopee/jalhyd/blob/master/DEVELOPERS.md) (en anglais)

### configuration du module

Créer les fichiers de configuration du module de calcul :

Dans `src/app/calculators`, créer un dossier portant le nom du module : `src/app/calculators/addition`. Dans ce nouveau dossier,  créer le fichier `addition.config.json`, comme suit :
 
```json
[
    {
        "id": "fs_addition",
        "type": "fieldset",
        "fields": [
            "A",
            "B",
            "Y"
        ]
    },
    {
        "type": "options",
        "idCal": "Y",
        "help": "addition.html"
    }
]
```
 
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`).

Les options peuvent également contenir :
 * `defaultNodeType` : le type de noeud par défaut du module de calcul. Ce champ sert par exemple pour les sections paramétrées à déterminer le type de section à afficher lors de la création du module. Si ce champ est absent, sa valeur est `ComputeNodeType.None`.
 * les valeurs par défaut des **propriétés** du module
 * les identifiants des listes déroulantes

#### inscription du nouveau module 

Dans le constructeur de `FormulaireService` dans le fichier `src/app/services/formulaire.service.ts`, ajouter une entrée dans `this.calculatorPaths` pour fournir le préfixe des fichiers de configuration :

```typescript
this.calculatorPaths[CalculatorType.Addition] = "addition";
```

#### aide contextuelle

Différents éléments de la configuration peuvent contenir une clé `help` donnant l'URL de l'aide pour l'élément de l'interface graphique concerné :

 * pour un champ de saisie numérique : `{... "type": "input", "id": "ID", "help": "aide.html", ...}` (remplace la forme courte `"ID"`)
 * pour n'importe quelle entrée d'un champ de type "select" : `{... "type": "select", "help": "aide.html", ...}`
 * pour des entrées spécifiques d'un champ de type "select" : `{... "type": "select", "help": { "IdDeLOption": "aide.html", ...}, ...}` (se référer au fichier de traduction du module pour la liste des ID des options, par exemple "SeuilTriangulaireTrunc_TriangularTruncWeirFree")
 * pour un groupe de champs ("fieldset") : `{... "type": "fieldset", "help": "aide.html", ...}`
 * pour tous les groupes de champs d'un groupe de champs répétable ("fieldset_template") : `{... "type": "fieldset_template", "help": "aide.html", ...}`
 * pour l'entête d'un groupe de champs répétables ("template_container") : `{... "type": "template_container", "help": "aide.html", ...}`
 * éventuellement l'URL de l'aide pour un résultat en particulier, dans le bloc d'options de la configuration :
	```json
	{
		"type": "options",
		…
		"resultsHelp": {
			"HG": "devalaison/grille.html#hauteur-de-grille"
	}
	```
 
#### traduction

Dans le dossier de configuration `src/app/calculators/addition`, créer les fichiers d'internationalisation, par exemple `addition.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 :

```json
{
  "fs_addition": "Paramètres de l'équation",

  "A": "Premier nombre",
  "B": "Deuxième nombre",
  "Y": "Somme",

  "UNIT_A": "",
  "UNIT_B": "",
  "UNIT_Y": ""
}
```

Ici les mentions `UNIT_*` pourraient être omises.

### thème

Dans `config.json`, ajouter si nécessaire le numéro de `CalculatorType` à un ou plusieurs thèmes afin de classer le module sur la page de liste; dans le cas contraire le nouveau module apparaîtra dans une section "Autres".

### traduction du titre et des messages de log

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"`
 * 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"`

### classes de formulaire personnalisées

En général la classe `FormulaireBase` est suffisante pour gérer un nouveau module, et est instanciée automatiquement par `FormulaireService` lors de la création d'un nouveau module. Elle agrège des instances de `FormComputeFixedVar` et `FormResultFixedVar`.

Mais dans des cas plus complexes, par exemple si le module contient des listes déroulantes ou des sous-modules, répétables ou non, il est nécessaire de créer de nouvelles classes de formulaires dérivées de celles-ci.

Dans un tel cas, créer la classe du formulaire dans un nouveau fichier, dans le dossier `src/app/formulaire/definition` Par exemple `form-macrorugo-compound.ts`.

Si les mécanismes de calcul ou de récupération des résultats doivent être modifiés, créer les classes nécessaires dans le dossier `src/app/formulaire/definition`, par exemple `form-compute-macrorugo-compound.ts` et `form-result-macrorugo-compound.ts`. Sinon, agréger des classes `FormCompute*` et `FormResult*` existantes.

Si une nouvelle classe de formulaire a été créée, ajouter un `case` dans la méthode `newFormulaire()` de `FormulaireService`, dans `src/app/services/formulaire.service.ts`. Exemple :

```typescript
case CalculatorType.Trigo:
  f = new FormulaireTrigo();
  break;
```

### 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.

#### si ces modules enfants sont répétables ("fs_container")

Il est nécessaire de créer une nouvelle classe de formulaire dérivée de `FormulaireBase` (voir "classes de formulaire personnalisées" ci-dessus), en s'inspirant de `FormulaireMacrorugoCompound` par exemple. Notamment, implémenter ou surcharger les méthodes :

 * `createFieldset()`
 * `moveFieldsetUp()`
 * `moveFieldsetDown()`
 * `removeFieldset()`
 * `completeParse()`
 * `update()` (action "newFieldset")

Dans la méthode `create()` de `CalculatorListComponent`, dans le fichier `src/app/components/calculator-list/calculator-list.component.ts`, ajouter la création d'un enfant par défaut. Exemple pour `MacrorugoCompound` :

```typescript
if (f instanceof FormulaireMacrorugoCompound) {
  for (const e of f.allFormElements) {
    if (e instanceof FieldsetContainer) {
        e.addFromTemplate(0, 0, f.mrcNub.children[0]);
        break;
    }
  }
}
```

Dans cet exemple, on ajoute l'interface pour le premier enfant du Nub (instancié par JaLHyd), à l'élément de formulaire de type `FieldsetContainer` (ici, il n'y en a qu'un).

Ajouter ensuite la création de fieldsets pour les enfants existants, dans la méthode `createFormulaire()` de `FormulaireService`, dans le fichier `src/app/services/formulaire.service.ts`. Exemple pour `ParallelStructures` :

```typescript
if (f.currentNub instanceof ParallelStructure) {
  for (const struct of f.currentNub.structures) {
    for (const e of f.allFormElements) {
      if (e instanceof FieldsetContainer) {
        e.addFromTemplate(0, undefined, struct);
      }
    }
  }
}
```

Dans chaque fichier de langue du dossier `src/locale`, ajouter les traductions pour le nom du type d'enfant (voir la documentation développeurs de JaLHyd), au singulier et au pluriel sous les clés `INFO_CHILD_TYPE_typedenfant` et `INFO_CHILD_TYPE_typedenfant_PLUR`. Par exemple pour le type d'enfant `Macrorugo` en français :

```json
"INFO_CHILD_TYPE_MACRORUGO": "radier",
"INFO_CHILD_TYPE_MACRORUGO_PLUR": "radiers",
```

### si le formulaire comprend des listes déroulantes

Il est nécessaire de créer une nouvelle classe de formulaire dérivée de `FormulaireBase` (voir "classes de formulaire personnalisées" ci-dessus), en s'inspirant de FormulaireTrigo par exemple. Notamment, implémenter ou surcharger les méthodes :

 * `afterParseFieldset()`
 * `parseOptions()`
 * `update()` (appeler `reset()` lors de l'action "propertyChange")

#### configuration

Dans le fichier de configuration du module, ajouter la définition des listes déroulantes dans "fields" notamment leur **source** (voir "sources" plus bas), ainsi que leur valeur par défaut dans le "fieldset" parent. Exemple dans `trigo.config.json`

```json
{
  "id": "fs_trigo",
  "type": "fieldset",
  "defaultOperation": "COS",
  "defaultUnit": "DEG",
  "fields": [
    {
      "id": "select_operation",
      "type": "select",
      "source": "trigo_operation"
    },
    {
      "id": "select_unit",
      "type": "select",
      "source": "trigo_unit"
    }
  ]
},
```

Dans ce même fichier de configuration, dans le dernier élément "options", ajouter une entrée par liste déroulante :

```json
…
{
  "type": "options",
  "operationSelectId": "select_operation",
  "unitSelectId": "select_unit",
  …
```
 
#### sources
 
Chaque liste déroulante est associée à une **source** (voir "configuration" plus haut), qui détermine quels sont les choix possibles. Pour ajouter une source, modifier la méthode `parseConfig()` de la classe `SelectField`, dans le fichier `src/app/formulaire/elements/select-field.ts`. Exemple pour "trigoOperation" :

```typescript
case "trigo_operation": // (cos, sin…)
  for (let j = 0; j < Object.keys(TrigoOperation).length / 2; j++) {
    this.addEntry(new SelectEntry(this._entriesBaseId + j, j));
  }
  break;
```

#### lien avec les propriétés

Les listes déroulantes doivent être liées à des **propriétés** du Nub. Pour ce faire, modifier la classe `FieldSet` dans le fichier `src/app/formulaire/elements/fieldset.ts` comme suit (exemple pour le module `Trigo`).

Ajouter un `case` dans la fonction `updateFields()`

```typescript
case "fs_trigo": // Trigo
  this.setSelectValueFromProperty("select_operation", "trigoOperation");
  this.setSelectValueFromProperty("select_unit", "trigoUnit");
  break;
```

Ajouter un `case` dans la fonction `update()`

```typescript
case "select_operation": // Trigo
  this.setPropValue("trigoOperation", data.value.value);
  break;
case "select_unit": // Trigo
  this.setPropValue("trigoUnit", data.value.value);
  break;
```

Dans la fonction `parseConfig()`, ajouter un appel par à `setPropertyValueFromConfig()` pour chaque liste déroulante.

```typescript
  this.setPropertyValueFromConfig(json, "defaultOperation", "trigoOperation", TrigoOperation);
  this.setPropertyValueFromConfig(json, "defaultUnit", "trigoUnit", TrigoUnit);
```
 
### documentation

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)

### tests unitaires

Plusieurs tests unitaires passent en revue les modules pour les tester un par un. Pour que le nouveau module soit testé, son `CalculatorType` doit être ajouté à la liste dans le fichier `e2e/tested_calctypes.ts`.