Skip to content
Snippets Groups Projects
Commit 31851818 authored by mathias.chouet's avatar mathias.chouet
Browse files

Update developers doc

parent f23bc481
No related branches found
No related tags found
No related merge requests found
Pipeline #137703 passed
Stage: jalhyd
    Stage: install
      Stage: test
        Stage: build
          Stage: release-linux
            Stage: release-windows
              Stage: release-mac
                Stage: release-android
                  Hide whitespace changes
                  Inline Side-by-side
                  Showing
                  with 24 additions and 29 deletions
                  DEVELOPERS.md
                  + 24
                  − 29
                  View file @ 31851818
                  ......@@ -68,39 +68,37 @@ Chaque formulaire est associé à une instance d'une classe `FormCompute*` et un
                  #### générale
                  La configuration générale se trouve dans `app/config.json`.
                  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, i apparaîtra automatiquement dans un thème "autres" qui n'est visible que dans un tel cas.
                  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 `app/calculators`, dans un dossier portant le nom du module.
                  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 `app/calculators/lemodule/lemodule.config.json` (exemple pour le module "bief" : `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.
                  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 `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 `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éé.
                  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 `locale`.
                  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 `app/calculators/lemodule/lemodule.lalangue.json` (exemple pour le module "bief" en anglais : `app/calculators/bief/bief.en.json`).
                  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. 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()`.
                  `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.
                  ......@@ -110,7 +108,7 @@ Le dossier `release` contient (entre autres) les paquets générés par electron
                  ### 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` et `config.xml`.
                  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
                  ......@@ -142,7 +140,7 @@ Voir la [documentation JaLHyd pour les développeurs](https://gitlab.irstea.fr/c
                  Créer les fichiers de configuration du module de calcul :
                  Dans `app/calculators`, créer un dossier portant le nom du module : `app/calculators/addition`. Dans ce nouveau dossier, créer le fichier `addition.config.json`, comme suit :
                  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
                  [
                  ......@@ -172,8 +170,6 @@ Les options peuvent également contenir :
                  * les valeurs par défaut des **propriétés** du module
                  * les identifiants des listes déroulantes
                  Ces options sont utilisées par exemple dans `bief.config.json`.
                  #### 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 :
                  ......@@ -190,7 +186,7 @@ Différents éléments de la configuration peuvent contenir une clé `help` donn
                  * 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 _fieldset_ d'un _fieldset_template_: `{... "type": "fieldset_template", "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
                  ......@@ -208,15 +204,15 @@ Dans le dossier de configuration `src/app/calculators/addition`, créer les fich
                  ```json
                  {
                  "fs_addition": "Paramètres de l'équation",
                  "fs_addition": "Paramètres de l'équation",
                  "A": "Premier nombre",
                  "B": "Deuxième nombre",
                  "Y": "Somme",
                  "A": "Premier nombre",
                  "B": "Deuxième nombre",
                  "Y": "Somme",
                  "UNIT_A": "",
                  "UNIT_B": "",
                  "UNIT_Y": ""
                  "UNIT_A": "",
                  "UNIT_B": "",
                  "UNIT_Y": ""
                  }
                  ```
                  ......@@ -238,15 +234,15 @@ Dans les fichiers `locale/messages.*.json` :
                  ### 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 es instances de `FormComputeFixedVar` et `FormResultFixedVar`.
                  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/concrete/`/ Par exemple `form-macrorugo-compound.ts`.
                  Dans un tel cas, créer la classe du formulaire dans un nouveau fichier, dans le dossier `src/app/formulaire/definition/concrete` 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`, dand `src/app/services/formulaire.service.ts`. Exemple :
                  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:
                  ......@@ -258,7 +254,7 @@ case CalculatorType.Trigo:
                  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)
                  #### 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 :
                  ......@@ -298,7 +294,7 @@ if (f.currentNub instanceof ParallelStructure) {
                  }
                  ```
                  Dans chaque fichier de langue du dossier `src/locale`, ajouter les traductions pour le nom 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 :
                  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",
                  ......@@ -400,5 +396,4 @@ Lier ce fichier au module via la clé `help` du bloc d'options de la configurati
                  ### 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.
                  \ No newline at end of file
                  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`.
                  0% or .
                  You are about to add 0 people to the discussion. Proceed with caution.
                  Finish editing this message first!
                  Please register or to comment