Structure d'un module

July 3, 2026 · View on GitHub

Structure d'un module

La configuration

  • config.json (configuration-générale)
  • module.json (configuration du module)
  • site.json (configuration des sites)
  • group_site.json (configuration des groupes de sites)
  • visit.json (configuration des visites)
  • observation.json (configuration des observations)
  • observation_detail.json (configuration des détails des observations)
  • nomenclature.json (pour l'ajout de nomenclatures spécifiques au sous-module)
  • synthese.sql (vue pour la synchronisation avec la synthèse) voir

S'ajoute à ces fichiers, des fichiers de config de types de site que l'on devra associer aux sous modules installés.

Pour cela , il faut créer les types de sites via l'interface administrateur (voir les deux imags ci dessous) .

Images représentant l'interface administrateur au niveau du menu "Types de site"

Menu dans interface admin pour les types de site

Config dans interface admin pour les types de site

Ces types de site , une fois créés pourront être associés au sous module dans la configuration du module.

Image représentant la configuration du module avec l'association aux types de sites

Association des types de site au sous module

Les exports

  • exports
    • csv
      • fichiers sql qui permettent de définir les vues qui serviront aux exports csv
      • le nommage des vues doit être "v_export_<module_code>_<method>
        • <method> est une chaine de caractère qui permet de caractériser différentes vues et différents exports pour un module
    • pdf
      • fichiers html/img/css
        • ces fichiers definissent un template pour l'export pdf et tous les assets nécessaires (images, style, etc..)

Pour chaque fichier, les valeurs prises par défaut sont celles du fichier de même nom présent dans le répertoire config/monitoring/generic.

Le fichier img.jpg servira de vignette du sous-module sur la page d'accueil du module Monitoring. Le format paysage est à privilégier. Pour chacune un lien symbolique est créé automatiquement dans le répertoire media/monitorings/<module_code>.jpg de GeoNature.

Configuration générale

Dans le fichier config.json :

  • tree définit les relations entre les objets
    {
        "tree": {
            "module": {
                "site": {
                    "visit": {
                        "observation": {
                            "observation_detail": null
                        },
                    },
                }
            }
        }
    }

Configuration des objets

Dans le fichier module.json, deux variables doivent obligatoirement être définies dans ce fichier :

  • module_code: un nom cours, en minuscule et simple, par exemple cheveches ou oedic pour les protocoles chevêches ou oedicnèmes.
  • module_desc: une description succinte du module.

Dans le cas général (module.json, site.json, visit.json, observation.json) on peut redéfinir au besoin certaines variables.

  • label : permet de nommer les objets, par exemple "Site" pour site,
  • description_field_name : le nom du champ qui servira à décrire le site (pour le titre du site), par exemple :
    • "visit_date_min" pour une visite,
    • "base_site_name" pour un site;
  • geometry_type: pour les sites seulement, peut prendre la valeur Point, LineString ou Polygon.
  • b_draw_sites_group : pour spécifier si l'on veut afficher un contour autour des sites d'un groupe de site. Ce paramètre est également configurable dans l'interface de configuration du module.

Les variables display_properties et display_list sont à définir pour indiquer quelles variables seront affichées (pour la page d'un objet ou pour les listes et dans quel ordre).

Si display_list n'est pas défini, il prend la valeur de display_properties.

Par exemple :

    "display_properties": [
      "visit_date_min",
      "observers",
      "meteo",
      "comments",
      "nb_observations"
    ]

Les schémas génériques

Les schémas des variables génériques sont définis dans le repertoire config/monitoring/generic dans les fichiers correspondant aux objets et dans la variable generic.

Pour la suite nous prendrons exemple sur la configuration des sites, qui sera similaire aux autres objets dans les grandes lignes.

Par exemple dans le fichier site.json de ce repertoire on trouve la variable "generic" :

"id_base_site": {
    "type_widget": "text",
    "attribut_label": "Id site",
    "hidden": true
},
"id_module": {
    "type_widget": "text",
    "attribut_label": "ID Module",
    "hidden": true
},

Chaque entrée de la variable generic est le nom d'une variable ("id_base_site", "id_nomenclature_type_site", etc...)

  • les attributs obligatoires :
    • type_widget : renseigne à la fois sur la nature de la variable et sur son type d'input, pour plus de détails sur les différentes possibilités, voir le paragraphe Définir une nouvelle variable.
    • attribut_label : associe un nom à la variable, comme "Type de site" pour id_nomenclature_type_site,
  • les attributs facultatifs :
    • hidden : permet de cacher la variable ou l'input du formulaire
    • value : permet d'attribuer une valeur par défaut
    • required : permet de rendre un input obligatoire
    • definition : permet d'ajouter une définiton à la variable pour aider l'utilisateur
  • les attributs spéciaux :
    • type_util: peut prendre pour valeur "user", "nomenclature", "dataset" ou "taxonomy". Permet d'indiquer qu'il s'agit ici d'un identifiant (exemple : nomenclature) et de traiter cette variable en fonction.

On peut mettre en valeur de ces attributs des données de la configuration du module.

Pour cela il faut utiliser les variables suivantes :

  • __MONITORINGS_PATH
  • __MODULE.ID_LIST_TAXONOMY
  • __MODULE.MODULE_CODE
  • __MODULE.ID_MODULE
  • __MODULE.ID_LIST_OBSERVER
  • __MODULE.TAXONOMY_DISPLAY_FIELD_NAME
  • __MODULE.TYPES_SITE
  • __MODULE.IDS_TYPES_SITE
  • __MODULE.CD_NOM

qui peuvent servir dans la définition des formulaires (en particulier pour les datalist). Voir ci dessous

Liste des widgets disponibles

WidgetsCommentaire
textTexte sur une seule ligne
textareaTexte sur une plusieurs lignes
radioChoix multiples uniques
selectListe de choix unique
timeHeure
number-
multiselectListes de choix multiples
htmlInsertion d'un bloc html
nomenclatureListe avec vocabulaire controlé de GeoNature
taxonomySelection d'un taxon
observersSelection d'un observateur
dateSélection d'une date
datalistListe dont les items sont fournies par une API (externe ou interne à GN)

Listes des paramètres disponibles par type de widgets :

WidgetsParamètresCommentaire
Tousattribut_labelLabel du formulaire
TousdefinitionAjoute une tooltip avec le contenu de ce paramètre (le paramètre link_definition ne doit pas être défini)
TousrequiredBooléen : permet de rendre obligatoire cet input
ToushiddenBooléen : permet de cacher un formulaire
Touslink_definitionAjoute un lien vers l'addresse pointé par ce paramètre. Le paramètre definition doit également être définit
Touspattern_messageAjoute un texte en rouge sous le formulaire explicitant une erreur sur le champ
TousvalueValeur par défaut du formulaire
select / multiselect / checkbox / radiovaluesValeurs de choix proposées. Attend une tableau de valeur ou un tableau clé/valeur [{"value": "my_database_value", "label": "my_display_value"}]
selectnoNullOptionDésactive la valeur vide ("-") des choix d'un select
numberminValeur minimum de l'input
numbermaxValeur maximum de l'input
nomenclaturecode_nomenclature_typeCode de la nomenclature à afficher
nomenclaturecd_nomenclaturesListe des codes nomenclatures à afficher (afin d'éliminer certains items de nomenclatures que l'on ne veut pas pour ce sous-module)
nomenclature / dataset / observersmulti_selectBooléan : permet de seléctionner plusieurs items dans la liste de valeurs
datasetmodule_codeLimite aux jeu de données associés à ce module
htmlhtmlContenu du bloc html

Définir une nouvelle variable

Pour définir une nouvelle variable ou aussi redéfinir une caractéristique d'une variable générique, il faut créer une variable nommée specific dans les fichiers site.json, visit.json ou observation.json afin de définir le schéma spécifique pour cet objet.

  • texte : une variable facultative
"nom_contact": {
    "type_widget": "text",
    "attribut_label": "Nom du contact"
}
  • entier : exemple avec un numéro du passage compris entre 1 et 2 est obligatoire
"num_passage": {
    "type_widget": "number",
    "attribut_label": "Numéro de passage",
    "required": true,
    "min": 1,
    "max": 2
}
  • utilisateur : Il est possible de choisir des observateurs de deux manières différentes. Soit les observateurs sont issus d'une liste d'observateurs (voir observers ci dessous) soit on choisit de renseigner textuellement une liste d'observateurs (avec le champ observers_txt )
"observers": {
    "attribut_label": "Observateurs",
    "type_widget": "observers",
    "type_util": "user",
    "code_list": "__MODULE.ID_LIST_OBSERVER",
    "hidden": false,
    "required": true
},
"observers_txt": {
      "hidden": true,
      "required": false
},

Par défaut c'est la liste d'observateurs lié au sous module qui est choisi. Si l'on veut plutôt renseigner des observateurs textuellement il suffit d'inverser les champs hidden et required entre observers et observers_txt.

Il est important d'ajouter "type_util": "user".

  • nomenclature : un choix obligatoire parmi une liste définie par un type de nomenclature
"id_nomenclature_nature_observation": {
    "type_widget": "nomenclature",
    "attribut_label": "Nature de l'observation",
    "code_nomenclature_type": "OED_NAT_OBS",
    "required": true,
    "type_util": "nomenclature"
},

La variable "code_nomenclature_type": "OED_NAT_OBS", définit le type de nomenclature.

Il est important d'ajouter "type_util": "nomenclature",.

  • liste : une liste déroulante simple, non basée sur une nomenclature
"rain": {
    "type_widget": "select",
    "required": true,
    "attribut_label": "Pluie",
    "values": ["Absente", "Intermittente", "Continue"]
},

Il est possible de définir une valeur par défaut pré-selectionnée
avec le paramètre `value` (exemple : `"value": "Absente"`).
  • radio : bouton radio pour un choix unique parmi plusieurs possibilités
"beginner": {
    "type_widget": "radio",
    "attribut_label": "Débutant",
    "values": ["Oui", "Non"]
},
  • taxonomie : une liste de taxons
"cd_nom": {
    "type_widget": "taxonomy",
    "attribut_label": "Taxon",
    "type_util": "taxonomy",
    "required": true,
    "id_list": "__MODULE.ID_LIST_TAXONOMY"
},

La variable "id_list": "__MODULE.ID_LIST_TAXONOMY" définit la liste de taxons.

Il est important d'ajouter "type_util": "taxonomy",.

  • dataset : une liste de jeux de données
        "id_dataset": {
            "type_widget": "dataset",
            "attribut_label": "Jeu de données",
            "type_util": "dataset",
            "required": true,
            "module_code": "__MODULE.MODULE_CODE",
        },

La variable "module_code": "__MODULE.MODULE_CODE" permet de selectionner uniquement les jeux de données associés au module.

Il est important d'ajouter "type_util": "dataset",.

Redéfinir une variable existante

Dans plusieurs cas, on peut avoir besoin de redéfinir un élément du schéma.

On rajoutera cet élément dans notre variable specific et cet élément sera mis à jour :

  • Changer le label d'un élément et le rendre visible et obligatoire

      "visit_date_max": {
      "attribut_label": "Date de fin de visite",
      "hidden": false,
      "required": true
  }

  • Donner une valeur par défaut à une nomenclature et cacher l'élément

    Dans le cas où la variable type_widget est redéfinie, il faut redéfinir toutes les variables.

    "id_nomenclature_sex": {
        "type_widget": "text",
        "attribut_label": "Sexe",
        "type_util": "nomenclature",
        "value": {
            "code_nomenclature_type": "SEXE",
            "cd_nomenclature": "6"
        },
        "hidden": true
    }
  • Donner au composant "type de site" les types de sites définis dans le module comme valeur par défaut et cacher l'élément
 "types_site": {
      "default": "__MODULE.IDS_TYPE_SITE", 
      "hidden": true
    }

Il est important d'ajouter "type_util": "nomenclature",.

Pour renseigner la valeur de la nomenclature, on spécifie :

  • le type de nomenclature "code_nomenclature_type" (correspond au champs mnemonique du type)
  • le code de la nomenclature "cd_nomenclature"

datalists

Pour pouvoir faire des composants de type select à partir d'une API, on peut utiliser le composant datalist.

Les options supplémentaires pour ce widget :

  • api : API qui fournira la liste
  • application : GeoNature ou TaxHub permet de préfixer l'API avec l'URL de l'API de l'application
  • keyValue : champs renvoyé
  • keyLabel : champs affiché
  • type_util : nomenclature, dataset, user : pour le traitement des données par ailleurs
  • data_path : si l'API renvoie les données de la forme data: [<les données>] alors data_path = "data"
  • filters : permet de filtrer les données reçues ({field_name: [value1, value2, ...]})
  • default : permet de donner une valeur par defaut ("default": {"cd_nomenclature": "1"} permettra de récupérer le premier objet de la liste qui correspond)
  • nullDefault : quand mis a true permet d'ajouter une option vide -- Aucun -- avec la valeur null en base. Necessite required: false
  • orderBy : permet de trier les valeurs par ordre alphabétiques avec asc ou desc

Par exemple :

  • Nomenclature avec sous-liste et valeur par defaut
"id_nomenclature_determination_method": {
    "type_widget": "datalist",
    "attribut_label": "Méthode de détermination",
    "api": "nomenclatures/nomenclature/METH_DETERMIN",
    "application": "GeoNature",
    "keyValue": "id_nomenclature",
    "keyLabel": "label_fr",
    "data_path": "values",
    "type_util": "nomenclature",
    "required": true,
    "default": {
        "cd_nomenclature": "1"
    }
},
  • Groupe de sites
    "id_sites_group": {
        "type_widget": "datalist",
        "attribut_label": "Groupe de sites",
        "hidden": true,
        "type_util": "sites_group",
        "keyValue": "id_sites_group",
        "keyLabel": "sites_group_name",
        "api": "__MONITORINGS_PATH/list/__MODULE.MODULE_CODE/sites_group?id_module=__MODULE.ID_MODULE&fields=id_sites_group&fields=sites_group_name",
        "application": "GeoNature"
    },
  • Utilisateur
"observers": {
    "type_widget": "datalist",
    "attribut_label": "Observateurs",
    "api": "users/menu/__MODULE.ID_LIST_OBSERVER",
    "application": "GeoNature",
    "keyValue": "id_role",
    "keyLabel": "nom_complet",
    "type_util": "user",
    "multiple": true,
    "required": true
},

Les paramètres dynamiques

Il est possible de définir des fonctions javascript (sous forme de chaine de caractères) qui peuvent modifier les comportements et valeurs du formulaire.

Ce cas n'est pris en compte que pour les composants spécifiques, ou pour les composants redéfinis dans specific

Il est possible de définir des fonctions à deux niveaux:

  • au niveau de chaque champ du formulaire
  • au niveau global au formulaire (via la fonction change)

Les variables accessibles en fonction des différents contextes sont les suivantes :

  • value : la valeur du formulaire. Dans le contexte d'un champ specific
  • attribut_name : du composant concerné. Dans le contexte d'un champ specific
  • objForm : Formulaire. Dans le contexte de la fonction change
  • meta : Dictionnaire de données additionnelles, contient les données suivantes. Dans tout les contextes
    • nomenclatures: liste des nomenclatures utilisées. Dictionnaire avec id_nomenclature comme clé.
    • dataset : liste des jdds disponibles pour l'utilisateur et le module
    • id_role : identifiant de l'utilisateur courant
    • bChainInput: si on enchaîne les relevés
    • parents: Objets parents. Permet de récupérer les valeurs définies dans le parents.

La chaîne de caractère qui décrit la fonction doit être de la forme suivante :

    "hidden": "({value, attribut_name, }) => { return value.id == 't' }"

Le format JSON ne permet pas les sauts de ligne dans les chaînes de caractère, et pour avoir plus de lisibilité, quand la fonction est plus complexe, on peut aussi utiliser un tableau de chaîne de caractères :

    "hidden": [
        "({value, attribut_name, }) => {",
        "return value.id == 't'",
        "}"
    ]

Exemples champs des formulaires

  • Afficher le composant test2 et le rendre obligatoire seulement si test1 a pour valeur t :
"specific": {
    "test": {
        "type_widget": "text",
        "attribut_label": "Test"
        },
        "test2": {
        "type_widget": "text",
        "attribut_label": "Test 2",
        "hidden": "({value}) => value.test != 't'",
        "required": "({value}) => value.test != 't'"
        }
}
  • Ajouter un champ pour renseigner la profondeur d'une grotte si le type de site est une grotte (cd_nomenclature '1')

Dans le fichier site.json

"specific": {
    ...
    "profondeur_grotte": {
    "type_widget": "number",
    "attribut_label": "Profondeur de la grotte",
    "hidden": "({value, meta}) => meta.nomenclatures[value.id_nomenclature_type_site] || {}).cd_nomenclature !== '1'",
    "required": "({value, meta}) => (meta.nomenclatures[value.id_nomenclature_type_site] || {}).cd_nomenclature === '1'"
    }
    ...
}

Le paramêtre value ne peut pas être dynamique, pour changer la valeur des variables en fonction d'autres variables, on peut définir change dans la config. Voir ci dessous

Exemples variable change

On peut y définir une fonction qui sera appelée chaque fois que le formulaire change.

Exemple utilisation de objForm Un exemple (module.json du module test) :

{
    "module_label":"Test",
    "module_desc":"Module de test pour le module de suivi générique",
    "specific": {
        "test": {
            "type_widget": "text",
            "attribut_label": "Test"
        },
        "test2": {
            "type_widget": "text",
            "attribut_label": "Test 2 (hidden)",
            "hidden": "({value}) => value.test != 't'"
        },
        "test3": {
            "type_widget": "text",
            "attribut_label": "Test 3 (change)"
        }
    },
    "change": [
        "({objForm, meta}) => {",
            "const test3 = '' + (objForm.value.test || '') + '_' + (objForm.value.test2 || '');",
            "if (!objForm.controls.test3.dirty) {",
                "objForm.patchValue({test3})",
            "}",
        "}",
        ""
    ]
}

Ici on donne à la variable test3 la valeur <test>_<test2>. Le test !objForm.controls.test3.dirty permet de ne modifier la variable que si l'utilisateur ne l'a pas modifié manuellement.

Exemple valeur par défaut en fonction des valeurs du formulaire parent Il est possible avec meta de récupérer les données du niveau supérieur. Voici un exemple sur la réutilisation de valeurs au niveau du site pour pré-remplir les champs au niveau de la visite:

Fichier de configuration du niveau site:

{
 ...
"specific": {
   ...
  "occ_sol": {
    "attribut_label": "OS",
    "type_widget": "select",
    "values": [...],
    "required": true,
    "hidden": false
  },
  "gestion":{
    "attribut_label": "Gestion",
    "type_widget": "select",
    "values": [...],
    "required": true,
    "hidden": false
  }
}

Fichier de configuration du niveau visite:

{
  ...
  "specific": {
     ...
    "occ_sol": {
      "attribut_label": "Occupation du sol à grande échelle",
      "type_widget": "select",
      "values": [...],
      "required": true,
      "hidden": false
    },
    "gestion":{
      "attribut_label": "Gestion",
      "type_widget": "select",
      "values": [...],
      "required": false,
      "hidden": false
    }
  },
  "change": [
      "({objForm, meta}) => {",
        "const occ_sol = (meta.parents.site.properties.occ_sol);",
        "const gestion = (meta.parents.site.properties.gestion);",
        "(objForm.value.occ_sol == (null || undefined)  && meta.parents.site.properties.occ_sol != (null || undefined) ? objForm.patchValue({occ_sol}) : '');",
        "(objForm.value.gestion == (null || undefined) ? objForm.patchValue({gestion}) : '');",
    "}",
    ""
  ]
}

Nomenclature

Le fichier nomenclature.json permet de renseigner les nomenclatures spécifiques à chaque sous-module.

Elles seront insérées dans la base de données lors de l'installation du sous-module (si elles n'existent pas déjà).

Exemple de fichier :

{
"types": [
    {
    "mnemonique": "TEST_METEO",
    "label_default": "Météo",
    "definition_default": "Météo (protocôle de suivi test)"
    }
],
"nomenclatures": [
    {
    "type":"TEST_METEO",
    "cd_nomenclature": "METEO_B",
    "mnemonique": "Beau",
    "label_default": "Beau temps",
    "definition_default": "Beau temps (test)"
    },
    {
    "type":"TEST_METEO",
    "cd_nomenclature": "METEO_M",
    "mnemonique": "Mauvais",
    "label_default": "Mauvais temps",
    "definition_default": "Mauvais temps (test)"
    }
]
}

Attention : si une nomenclature de même type et cd_nomenclature existe déjà elle ne sera pas modifiée.

Configuration de la carte

Il est possible d'afficher des popups sur la carte et de choisir la valeur à afficher.

Pour cela éditez le fichier de configuration associé (module.json, site.json, visite.json) et rajoutez la variable suivante :

"map_label_field_name": <nom_du_champs>,

NB : pour ajouter une popup sur la liste des sites, éditez le fichier module.json, pour la liste des visites le fichier site.json etc....

Exports

Il est possible de configurer des exports (CSV ou PDF).

PDF

Les fichiers de template (.html) et assets (images, style, etc..) pour l'export PDF sont à placer dans le dossier <module_code>/exports/pdf/

  • Dans le fichier de config d'un objet (par exemple sites_group.json:

    • ajouter la variable export_pdf:
"export_pdf": [
    {
        "template": "fiche_aire.html",
        "label": "Export PDF"
    }
]
  • Dans les fichiers template on a accès à la variable data, un dictionnaire contenant :
    • static_pdf_dir : chemin du dossier des assets de l'export pdf
    • map_image : l'image tirée de la carte leaflet
    • monitoring_object.properties : propriété de l'objet courant
  • La commande geonature monitorings process_export_pdf <module_code> permet de :
    • placer les fichier de template en .html (lien symbolique) dans le dossier <geonature>/backend/template/modules/monitorings/<module_code>
    • placer les fchiers d'assets dans le dossier static : <geonature>/backend/media/monitorings/<module_code>/exports/pdf

CSV

Les fichiers .sql qui définissent les vues pour l'export CSV sont placés dans le dossier <module_code>/exports/csv/.

  • Dans le fichier de config du module (module.json) ou d'un objet (par exemple sites_group.json) :

    • ajouter la variable export_csv:
"export_csv": [
    { "label": "Format standard CSV", "type":"csv" , "method": "standard" , "filter_dataset": true},
    { "label": "Format analyses CSV", "type":"csv" , "method": "analyses" }
],
  • Paramètres :
    • label : Nom de l'export
    • method : Nom de la vue sans le code du module
    • filter_dataset (true|false) : Ajoute le filtre des datasets. Dans ce cas il faut que la vue ait un champ id_dataset
  • La commande geonature monitorings process_export_csv <module_code> permet de :
    • exécuter tous les fichiers SQL de ce répertoire
    • les vues doivent être nommées v_export_<module_code>_<method>