From 88a9487c47b59106cf1f4f23391f16295bd3e443 Mon Sep 17 00:00:00 2001
From: Sofian Pujo <sofian.pujo@veremes.com>
Date: Thu, 13 Jun 2024 15:16:04 +0200
Subject: [PATCH] Doc HTML + JSON
---
.../administrator/rapports/definition_html.md | 72 ++++++++++++-
doc/source/administrator/rapports/index.rst | 3 +-
.../rapports/informations_generales.md | 19 ++--
.../administrator/rapports/objet_json.md | 102 +++++++++++++++++-
4 files changed, 184 insertions(+), 12 deletions(-)
diff --git a/doc/source/administrator/rapports/definition_html.md b/doc/source/administrator/rapports/definition_html.md
index 721aab23..658e0c0d 100644
--- a/doc/source/administrator/rapports/definition_html.md
+++ b/doc/source/administrator/rapports/definition_html.md
@@ -1 +1,71 @@
-# Définition HTML
\ No newline at end of file
+# Définition du modèle HTML
+
+Un rapport est défini selon un modèle HTML qui est renseigné dans l'interface de création ou de modification.
+
+## Intégrer une valeur dynamique dans le rapport
+
+Lorsqu'un rapport est lié à une couche, il est possible d'insérer une valeur dynamique à partir des champs de celle-ci. Pour cela, il faut indiquer le champ précédé par "BO." et le tout entouré d'accolades.
+
+**Exemple :**
+
+Si dans la couche "Ville" il y a un champ "nom_ville", il est possible d'utiliser **{{BO.nom_ville}}** dans le rapport. Cette balise sera alors remplacée par la valeur du champ "nom_ville" de l'objet courant.
+
+```html
+<p>{{BO.nom_ville}}</p>
+```
+
+### Variables disponibles
+
+En plus des variables possibles à renseigner depuis la couche associée, les rapports de vMap disposent d'un ensemble de variables disponibles par défaut. Pour les utiliser, il suffit de les insérer en les entourant de doubles accolades (**{{..}}**).
+
+- **date** : date du jour
+- **date_hour** : date et heure du jour
+- **layer_sources** : sources des couches
+- **map_legend** : légende de la carte principale
+- **user_name** : nom de l'utilisateur
+- **user_login** : login de l'utilisateur
+- **user_company** : société de l'utilisateur
+- **user_department** : service de l'utilisateur
+- **user_email** : adresse mail de l'utilisateur
+- **user_id** : identifiant de l'utilisateur
+
+## Intégrer une valeur dynamique à l'aide d'une boucle
+
+Dans certains cas, vous pourriez avoir besoin d'itérer à travers une liste d'objets pour afficher des données dynamiques dans votre rapport. Pour cela, vous pouvez utiliser la syntaxe `ng-repeat` dans votre modèle HTML.
+
+Voici comment procéder :
+
+1. Assurez-vous que les données que vous souhaitez afficher dans votre boucle sont disponibles sous forme d'un [Objet JSON](objet_json.md).
+2. Utilisez la syntaxe `ng-repeat` dans votre modèle HTML pour itérer à travers la liste d'objets.
+3. À chaque itération de la boucle, accédez aux propriétés de l'objet actuel pour afficher les données dans votre rapport.
+
+### Exemple :
+
+Supposons que vous ayez une liste d'objets représentant des intersections de routes, et vous souhaitez afficher les détails de chaque intersection dans votre rapport. Voici comment vous pourriez le faire en utilisant AngularJS `ng-repeat` :
+
+```html
+<div ng-repeat="intersection in intersections">
+ <!-- Afficher les détails de chaque intersection -->
+ <p>Nom de l'intersection : {{intersection.nom}}</p>
+ <p>Nombre de routes : {{intersection.nombre_routes}}</p>
+ <!-- Ajoutez d'autres détails selon vos besoins -->
+</div>
+```
+
+Dans cet exemple :
+
+- ng-repeat="intersection in intersections" indique que vous itérez à travers la liste d'intersections stockée dans la variable intersections.
+- {{intersection.nom}}, {{intersection.nombre_routes}}, etc., représentent les propriétés de chaque objet intersection que vous affichez dans votre rapport.
+
+## Intégrer une image dynamiquement
+
+Il est possible d'intégrer une image dans un rapport en utilisant la balise HTML **img** et en modifiant la source dynamiquement. Deux formats sont alors pris en compte :
+
+- Lien (de type https://...)
+- Base 64 (de type data:image/png;base64,...)
+
+<u>Exemple :</u>
+```html
+<img src="https://www.example.com/image.png" alt="Description de l'image">
+<img src="data:image/png;base64,..." alt="Description de l'image">
+```
\ No newline at end of file
diff --git a/doc/source/administrator/rapports/index.rst b/doc/source/administrator/rapports/index.rst
index e1b5374a..9fb28341 100644
--- a/doc/source/administrator/rapports/index.rst
+++ b/doc/source/administrator/rapports/index.rst
@@ -3,7 +3,8 @@ Mode Rapport
--------------
-La configuration générale de vMap2 présente 3 sous-sections :
+Le mode rapport permet d'administrer les rapports disponibles dans l'application.
+Il permet de paramétrer les différents rapports, d'indiquer le modèle et de lui indiquer comment le compléter.
============================================
diff --git a/doc/source/administrator/rapports/informations_generales.md b/doc/source/administrator/rapports/informations_generales.md
index 6a62eac8..f27e1c9b 100644
--- a/doc/source/administrator/rapports/informations_generales.md
+++ b/doc/source/administrator/rapports/informations_generales.md
@@ -1,18 +1,19 @@
# Informations générales
-Dans vMap, un rapport est un document qu'il est possible de générer à partir de 2 endroits :
+Un rapport est un document personnalisable permettant d'afficher diverses informations selon les besoins des utilisateurs. Il peut être généré à partir de deux endroits dans l'application :
- Le requêteur
- Edition d'un objet métier
-Afin qu'un rapport soit disponible, il est nécessaire d'en créer un à partir du menu "Rapports".
+Pour qu'un rapport soit disponible, il est nécessaire de le créer à partir du menu "Rapports".
Lors de la création d'un rapport, plusieurs paramètres doivent être renseignés :
-- **Nom du rapport** : Il s'agit du nom qui sera affiché dans les différentes listes de sélection du rapport.
-- **Format de la page** : Plusieurs formats sont pris en charge allant de A0 à A4.
-- **Orientation du document** : Indique si le rapport doit être au format **portrait** ou **paysage**
-- **Format de sortie** : Extension du document téléchargé après sa génération (Exemple : PDF)
-- **Couche** : Un rapport doit être associé à une et une seule couche pour laquelle il sera disponible. Par exemple, si un rapport doit pouvoir être généré lors de la sélection d'un objet de la couche "Ville" sur la carte, il faut associer ce rapport à la couche "Ville" également.
-- **Rapport sur plusieurs éléments dans un fichier** : Lors d'une sélection multiple, il est possible de demander une génération d'un rapport sur plusieurs éléments. Ce paramètre permet d'indiquer si l'application doit générer un rapport par élément (Non) ou bien un seul rapport avec tous les éléments à l'intérieur de celui-ci (Oui).
-- **Active les styles d'impression** : Si activé, lorsqu'un utilisateur demande de générer un rapport, une fenêtre modale s'ouvrira afin de demander quel style d'impression utiliser.
\ No newline at end of file
+- **Nom du rapport** : Nom affiché dans les différentes listes de sélection du rapport.
+- **Format de la page** : Formats pris en charge allant de A0 à A4.
+- **Orientation du document** : Format **portrait** ou **paysage**.
+- **Format de sortie** : Extension du document téléchargé après sa génération (par exemple : PDF).
+- **Couche** : Le rapport doit être associé à une couche unique pour laquelle il sera disponible. Par exemple, si un rapport doit être généré lors de la sélection d'un objet de la couche "Ville" sur la carte, il faut associer ce rapport à la couche "Ville".
+- **Rapport sur plusieurs éléments dans un fichier** : En cas de sélection multiple, ce paramètre indique si l'application doit générer un rapport par élément (Non) ou un seul rapport contenant tous les éléments (Oui).
+- **Active les styles d'impression** : Si activé, une fenêtre modale s'ouvrira lorsque l'utilisateur demandera la génération d'un rapport, pour sélectionner le style d'impression à utiliser.
+- **Définition HTML** : Voir [Définition du modèle HTML](definition_html.md).
\ No newline at end of file
diff --git a/doc/source/administrator/rapports/objet_json.md b/doc/source/administrator/rapports/objet_json.md
index 76ac9f9e..f86709b6 100644
--- a/doc/source/administrator/rapports/objet_json.md
+++ b/doc/source/administrator/rapports/objet_json.md
@@ -1 +1,101 @@
-# Objet JSON
\ No newline at end of file
+# Objet JSON
+
+Pour générer des rapports dynamiques, l'application utilise des objets JSON définis selon une structure spécifique. Cette section explique la structure et les différents types de données que vous pouvez inclure dans ces objets JSON.
+
+## Exemple d'objet JSON
+
+```json
+[
+ {
+ "type": "map",
+ "target": "#map_container",
+ "map_id": 10,
+ "resolution_coeff": 1,
+ "scale_target": "map_scale"
+ },
+ {
+ "type": "webservice",
+ "params": {
+ "schema": "s_cadastre",
+ "table": "v_vmap_parcelle",
+ "filter": "{\"column\":\"id_par\", \"compare_operator\":\"=\", \"value\": \"{{BO.id_par}}\"}"
+ },
+ "target": "#parcel_details"
+ },
+ {
+ "type": "webservice",
+ "ressource": "/cadastre/ficheurbanisme",
+ "params": {
+ "ID_PAR": "{{BO.id_par}}"
+ },
+ "target": "#urbanism_report"
+ },
+ {
+ "type": "image",
+ "imageUrl": "https://example.com/images/logo.png",
+ "target": "#sig_logo"
+ },
+ {
+ "type": "object",
+ "content": {
+ "company": "Ma_compagnie"
+ },
+ "target": "#sig_info"
+ }
+]
+```
+
+## Explication des champs
+
+1. **Type de ressource (`type`)** :
+
+- Détermine le type de ressource représentée par l'objet JSON.
+- Valeurs possibles : "map", "webservice", "image", "object".
+
+2. **Cible (`target`)** :
+
+- Identifie l'élément HTML où les données seront appliquées ou affichées.
+- **Important** : L'élément HTML cible doit avoir un identifiant (id) correspondant à la valeur de target.
+- **Exemple** : Si votre JSON contient "target": "#map_container", votre HTML doit inclure un élément avec id="map_container" :
+```html
+<div id="map_container">
+ <!-- Contenu de la carte -->
+</div>
+```
+
+3. **Map (`type: "map"`)** :
+
+- **map_id** : Identifiant de la carte.
+- **resolution_coeff** : Coefficient de résolution de la carte.
+- **scale_target** : Élément cible pour l'échelle de la carte.
+
+4. **Webservice (`type: "webservice"`)** :
+ - Il y a deux possibilités pour ce type de ressource :
+ 1. **Utilisation d'une table locale de la base de données de l'application** :
+ - **params** :
+ - **schema** : Schéma de la base de données.
+ - **table** : Table de la base de données.
+ - **filter** : Filtre pour la requête SQL. Le filtre doit être sous forme de chaîne de caractères avec les guillemets échappés, comme suit :
+ ```json
+ "{\"column\":\"user_id\", \"compare_operator\":\"=\", \"value\": \"{{BO.user_id}}\"}"
+ ```
+ - **column** : Nom de la colonne à filtrer.
+ - **compare_operator** : Opérateur de comparaison. Les opérateurs disponibles sont :
+ - `=`, `!=`, `<>`, `>=`, `<=`, `>`, `<`, `IN`, `NOT IN`, `IS NULL`, `IS NOT NULL`, `LIKE`, `INTERSECT`.
+ - **value** : Valeur à comparer, qui peut inclure une variable dynamique telle que `{{BO.user_id}}`.
+ 2. **Utilisation d'une route externe** :
+ - **ressource** : Chemin de la ressource du webservice.
+ - **params** : Les paramètres nécessaires pour la route. Ces paramètres dépendent des besoins spécifiques de la route externe et peuvent inclure des variables dynamiques. Exemple :
+ ```json
+ {
+ "category": "electronics"
+ }
+ ```
+
+5. **Image (`type: "image"`)** :
+ - **imageUrl** : URL de l'image à intégrer.
+ - **target** : Élément HTML cible pour afficher l'image.
+
+6. **Objet (`type: "object"`)** :
+ - **content** : Contenu de l'objet, peut inclure diverses propriétés.
+ - **target** : Élément cible pour appliquer les propriétés de l'objet.
--
GitLab