ldc-groupe/docs/DYNAMIC_PAGES.md

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
• Table des matières
• Configuration de pages
  • Informations globales
  • Contenu
    • Import JSON
    • Ajout manuel
    • Nouveau type de champs
  • Suppression
• Pages dynamiques
  • Informations globales
  • Accessibilité
  • Configuration
  • Restriction
• 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)

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: À savoir que ce même fichier .json doit correspondre à la structure d'une configuration afin de valider l'import (voir la structure ici). 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:

La seconde option est d'importer une configuration d'une autre langue précédemment renseignée: 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:

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:

• 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).

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

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.