ldc-groupe/docs/DYNAMIC_PAGES.md
2026-03-09 16:01:29 +01:00

111 lines
No EOL
8.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Introduction
Cette documentation est destinée à décrire le fonctionnement des modèles **DynamicPage** et **PageConfig** ainsi que leurs relations.
Ces deux modèles sont associés à des CRUDs qui leur sont respectifs, chacun dédié à un usage précis. En effet, **PageConfig** est utilisé afin de définir les champs nécessaires dans une page alors que le modèle **DynamicPage** sert à renseigner les données pour ces mêmes champs d'une configuration associée.
# Table des matières
- [Introduction](#introduction)
- [Table des matières](#table-des-matières)
- [Configuration de pages](#configuration-de-pages)
- [Informations globales](#informations-globales)
- [Contenu](#contenu)
- [Import JSON](#import-json)
- [Ajout manuel](#ajout-manuel)
- [Nouveau type de champs](#nouveau-type-de-champs)
- [Suppression](#suppression)
- [Pages dynamiques](#pages-dynamiques)
- [Informations globales](#informations-globales)
- [Accessibilité](#accessibilité)
- [Configuration](#configuration)
- [Restriction](#restriction)
- [Informations supplémentaires](#informations-supplémentaires)
# Configuration de pages
Comme évoqué précédemment, le CRUD **PageConfig** est destiné à configurer toutes les futures pages qui lui seront associées en définissant chaque champs.
*En tout premier lieu, il est recommandé de créer une configuration de page si vous voulez ajouter une nouvelle page spécifique.*
## Informations globales
Lors de la création ou l'édition d'une configuration de page, des champs classiques vous seront proposés comme:
- le **libellé**, pour identifier la configuration courante,
- et la **vue spécifique à associer**, qui correspond au chemin du fichier à utiliser (*attention à bien respecter l'architecture sans préciser l'extension*)
![informations globales](./assets/dynamic_pages/config_global_informations.png)
## Contenu
Par la suite, nous avons le cœur du sytème à savoir le paramètrage d'une configuration. C'est ici que l'on définit chaque champs qui sera à renseigner via le CRUD **DynamicPage**.
Plusieurs manières sont disponibles afin de réaliser cette démarche.
### Import JSON
La première est de passer par un import d'un contenu .json:
![options du contenu (import)](./assets/dynamic_pages/content_options_import.png)
À savoir que ce même fichier .json doit correspondre à la structure d'une configuration afin de valider l'import ([voir la structure ici](#ajout-manuel)). Si ce n'est pas le cas, vous avez toujours la possibilité de la modifier dans l'éditeur json qui s'ouvrira si vous choisissez cette option:
![éditeur json](./assets/dynamic_pages/json_editor.png)
La seconde option est d'importer une configuration d'une autre langue précédemment renseignée:
![options du contenu (lang)](./assets/dynamic_pages/content_options_lang.png)
Par exemple, si vous êtes en train de définir une configuration pour la langue anglaise qui se calque sur la configuration française, vous pouvez utiliser cette option (*attention cette action écrasera votre configuration courante*).
Étant donné que chaque configuration peut être différentes entre elles, et au vu des informations nécessaires, elle est sauvegardée en base sous un type json, ce qui facilite l'export si vous avez besoin de l'importer dans un autre projet par exemple:
![options du contenu (export)](./assets/dynamic_pages/content_options_export.png)
### Ajout manuel
Vous avez néanmoins la possibilité de créer votre propre configuration de zéro en choisissant la voie manuelle.
Pour ce faire, plusieurs informations sont nécessaires afin de définir un champs:
![champs spécifique](./assets/dynamic_pages/custom_field.png)
- le **libellé**, afin d'identifier le champs côté back-office,
- la **clé**, qui est utilisé pour le traitement de l'information (unique et non éditable),
- le **type**, pour définir quel sorte de champs à utiliser (enum **DynamicFieldTypes**),
- et enfin la **validation** à appliquer sous forme de string (peut s'additionner à des règles définies en dur comme pour les Enums ou les Wysiwyg).
Pour chaque champs définis, vous pouvez modifier l'ordre d'affichage qui sera aussi ajouté en base, et copier le nom du champs si besoin. À savoir que chaque champs est préfixé par son type (par exemple `string_` ou `boolean_`) ce qui permet un traitement différent si nécessaire lors de l'enregistrement (notamment pour les types `image_` ou `wysiwyg_`).
### Nouveau type de champs
Vous avez la liste des champs disponibles dans l'enum **DynamicFieldTypes** avec leur traduction ainsi que leur validation respective. À savoir que si vous souhaitez ajouter de nouveau champs, ceux-ci étant spécifiques au projet, plusieurs modifications sont à prendre en compte:
- définir une nouvelle entrée dans l'enum **DynamicFieldTypes** pour la sélection,
- modifier la méthode `recursiveRules()` dans la classe **UpdateDynamicFieldRequest** afin de prendre en compte ce nouveau champs lors de l'enregistrement, en utilisant la validation par défaut définie l'enum pour ce champs (avec possibilité d'ajout de règles permanentes),
- ajouter une `factory` spécifique pour ce nouveau type dans la classe **DynamicPageFactory**, utile pour les seeders,
- et enfin, insérer l'input dans le composant `DynamicInputs` afin d'avoir un rendu visuel de ce nouveau champs.
## Suppression
Comme beaucoup de modèles, **PageConfig** hérite du trait `SoftDeletes`. Lorsqu'un modèle est archivé/supprimé, toutes les pages associées se retrouvent elles aussi archivées/supprimées.
# Pages dynamiques
## Informations globales
Lors de la création ou l'édition d'une page dynamique, des champs classiques vous seront proposés comme:
- le **libellé**, pour identifier la configuration courante,
- et le **status**, qui correspond à l'état de publication de la page (enum **PageStatusEnum**).
![informations globales](./assets/dynamic_pages/page_global_informations.png)
## Accessibilité
Chaque page peut être accessible via une url différente. En effet, plusieurs choix s'offrent à vous, définir la page en tant que:
- **page enfant** à une autre page publiée, donc une association simple `belongsTo`, cette dernière verra son url affectée par cette association, par exemple si je définie ma page courante comme étant enfant à une page XXX, l'url pour accéder à cette page sera https://domain.fr/XXX/page-courante (attention si vous dépublié la page XXX, toutes les pages associées seront elles aussi dépubliée, si la page parente passe en tant qu'archive, la page courante deviendra orpheline),
- **page simple** accessible via un slug unique (se basant sur le titre courant),
- **page racine**, dans ce cas là, aucune page parente ni de chemin ne peuvent être renseigné, cette page servira donc de page d'accueil (et une seule page ne peut être définie en tant que racine à la fois).
![informations globales](./assets/dynamic_pages/accessibility.png)
## Configuration
C'est dans cette partie que l'on associe une configuration à notre page courante. Au changement de l'association, on met à jour le contenu donc les champs présents en dessous sont instantanément mis à jour.
Si aucune configuration n'est associée, un wysiwyg traductible par défaut est disponible et prend la place de la configuration dans le champs json `content` de la table.
## Restriction
Étant donné que ce CRUD est accessible pour les administrateurs, certaines pages doivent être requises, c'est pourquoi on défini des pages par défaut dans les seeders.
Si une page dynamique nouvellement créée doit être permanente, ce champs de restriction empêche la suppression de cette dernière ainsi que le changement de status (les concepteurs peuvent néanmoins accéder à ce bouton).
# Informations supplémentaires
## Traduction
Ces deux CRUDs, associés aux modèles **DynamicPage** et **PageConfig**, sont soumis à l'internationnalisation. Il est donc possible d'avoir une configuration de page ainsi que des valeures totalement différentes en fonction de la locale pour une même page.
## Récursivité
Après avoir développé un certain nombre de champs de base (string, wysiwyg, boolean, etc.), nous avons identifié le besoin d’un élément itératif permettant de gérer une liste d’éléments. Par exemple, offrir aux clients la possibilité d’ajouter entre 2 et 6 éléments d’un même type.
Un travail conséquent a donc été réalisé afin de prendre en charge non seulement des groupes de champs (préfixés par list_), mais également la gestion de plusieurs niveaux de profondeur : sous-groupes, sous-sous-groupes, etc.
Cela a impliqué la mise en place d’un système récursif, aussi bien du côté de la configuration des pages que du côté du renseignement et de la gestion des valeurs dans les dynamic pages.