← Voir tous les articlesGrégory TAUDINGrégory TAUDIN - 5 avr. 2022

Strapi : Comment concevoir une interface utilisateur de base et définir les paramètres ?

Bon retour parmi nous !

Jusqu'à présent, nous avons parlé de "Server API", la partie back-end de notre plugin Strapi. Dans cet nouvel article, il est temps de parler de la partie front-end : "Admin panel API".

Pour concevoir et ajouter des éléments front-end dans le plugin, vous devez connaître REACT. Toutes les interfaces de Strapi sont réalisées avec ce framework.

Jetons un coup d'œil rapide à la structure du dossier "admin" à l'intérieur du plugin.

|--admin
    |--components (inclut tous les composants REACT partagés par le plugin)
        |--Initializer
            |--index.js (Initialisateur de plugin Strapi nécessaire)
        |--PluginIcon
            |--index.js (Définition de l'icône du plugin)
    |--pages (Comprend toutes les pages du plugin)
        |--App
            |--index.js (Le composant d'application par défaut, vous pouvez définir ici le routage de votre interface utilisateur. La route par défaut enregistre le composant de la page d'accueil (voir ci-dessous))
        |--Homepage
            |--index.js (Le composant de page d'accueil par défaut. C'est la page affichée par défaut lorsque vous cliquez sur le menu du site d'administration de Strapi. La personnalisation commence ici.)
    |--translations (Dossier des ressources de traduction)
        |--en.json (Fichier de traduction EN)
        |--fr.json (Fichier de traduction FR, vous pouvez ajouter le vôtre ici)
    |--utils (Inclut quelques helpers)
        |--axiosInstance.js (Instance Axios (Axios est une bibliothèque permettant de faire des appels HTTP et autres))
        |--getTrad.js (helper pour obtenir facilement le texte de la traduction à partir de vos fichiers de traduction)
    |--index.js (Le point d'entrée du plugin. 2 fonctions importantes :
        register() -> avant l'enregistrement du plugin Strapi
        bootstrap() -> après l'enregistrement du plugin Strapi)
    |--pluginId.js (Helper pour récupérer facilement le package.json : pluginId)

Page d'accueil personnalisée du plugin

L'objectif de cette personnalisation est de mettre à jour la page d'accueil avec une interface utilisateur conforme à Strapi. Dans cette nouvelle page d'accueil, nous devons définir un en-tête comprenant un bouton pour accéder aux paramètres et un bouton pour lancer l'analyse de la structure des types de contenu de Strapi. Une fois l'analyse terminée, les résultats rempliront un tableau de données (DataGrid). Sur chaque ligne du tableau, nous ajouterons un bouton de modification pour ouvrir une fenêtre modale. Enfin, cette fenêtre modale permettra de mettre à jour le texte d'aide contextuel.

Pour mettre à jour la page d'accueil, ouvrez le fichier "api/src/plugins/awesome-help/admin/src/pages/HomePage/index.js". Vous remarquerez que la page met en œuvre certains composants de Strapi Design components. Tous les composants de l'interface utilisateur peuvent être trouvés sur ces deux sites de documentation :

Définition de la page d'accueil

Nous utilisons le composant <Main> our créer la mise en page de base.

Le composant <HeaderLayout> définit un en-tête de page Strapi standard. A l'intérieur, vous pouvez trouver 2 propriétés intéressantes :

  • primaryAction: il définit l'action principale de la page. Par exemple, dans la nouvelle page d'accueil, primaryAction lance le processus d'analyse. Vous remarquerez que nous passons directement le <Button> de Strapi UI à l'intérieur de la propriété.
  • secondaryAction: créer un bouton près du titre. Dans ce cas, nous avons placé un <Button> de Strapi UI avec une simple redirection vers la page de configuration du plugin (voir le chapitre suivant).

le <ContentLayout> définit le conteneur principal de la page. À l'intérieur, vous trouverez un chargeur <LoadingIndicatorPage> pour indiquer un changement de page.

Nous implémentons un composant Strapi DataGrid <HelpTable> pour afficher les résultats de l'analyse.

Pour écrire du texte dans l'interface d'administration de Strapi, vous devez utiliser le composant <Typography>. N'oubliez pas d'utiliser les règles conçues pour l'interface utilisateur de Strapi : https://design-system.strapi.io/typography

Pour le moment, les données sont simulées dans un tableau. Nous utiliserons des appels réels à l'API d'aide plus tard.

Isolation d'un composant :

Le composant <HelpTable> doit être isolé dans le dossier "api/src/plugins/awesome-help/admin/src/components/HelpTable" pour une meilleure division du code. Pour créer le nouveau composant, nous devons créer une classe de base appelée "HelpTable" et définir un type avec "HelpTable.defaultProps".

const HelpTable = ({data}) => { 
  return <></>;
}
HelpTable.defaultProps = { data: [] };

Dans votre type, vous définissez une propriété `data` de type tableau. Avec cette définition de type, vous pouvez écrire dans le contenu de la page d'accueil, ce code :

<HelpTable data={myData}></HelpTable>

Le DataGrid "HelpTable" est prêt à recevoir des données. Mais nous devons mettre à jour ces données : nous allons donc créer un nouveau composant pour afficher une fenêtre modale.

Dans le dossier "api/src/plugins/awesome-help/admin/src/components", créez un nouveau dossier "ModalForm" avec un fichier "index.js" à l'intérieur. Copiez et collez, à l'intérieur, le code ci-dessous :

Composant ModalForm

Cette nouvelle classe de composants possède trois propriétés :

  • help object: l'entité de l'objet d'aide à mettre à jour,
  • onToggle: une fonction qui affiche / cache la fenêtre modale,
  • onSave: une fonction qui enregistre l'objet d'aide mis à jour.

Nous utilisons les composants Strapi UI <ModalLayout>, <ModalHeader>, <ModalBody>, <ModalFooter> pour structurer la disposition, l'en-tête, le corps et le pied de page de la fenêtre modale.

Nous utilisons un composant "TextInput" pour saisir le contenu de l'aide contextuelle. Faites attention à l'événement onChange qui suit les modifications du champ.

Une fonction "useEffect" permet de définir un objet d'aide dans un hook d'état interne ([innerHelp, setInnerHelp]). Une fonction "handleSubmit" permet d'enregistrer l'objet d'aide mis à jour.

Revenons maintenant au code du composant HelpTable :

Composant final HelpTable

Nous avons ajouté un hook d'état ([isModalOpened, setIsModalOpen]) pour gérer la fenêtre modale. Nous avons également ajouté un hook d'état pour gérer la ligne sélectionnée ([selectedRow, setSelectedRow]) lorsque l'utilisateur clique sur le bouton crayon dans le DataGrid. Enfin, dans le code REACT, nous avons ajouté le composant <ModalForm> avec les 3 propriétés demandées :

  • onToggle qui fait référence à la fonction "handleToggle".
  • onSave qui fait référence à la fonction "handleSave".
  • Help qui fait référence à l'état "selectRow".

Lorsque nous enregistrons l'objet d'aide dans le faux tableau, nous utilisons la fonction "toggleNotification" du plugin Strapi-helper pour notifier l'utilisateur en cas de succès ou d'erreur.

Le code final de HomePage :

Page HomePage finale

Rendu de la Homepage

Analyse en cours

Le composant "HelpTable" avec de fausses données

Le composant "ModalForm" pour éditer une ligne

La page d'accueil est désormais compatible avec Strapi UI et fonctionne !

Paramètres

Pour enregistrer nos paramètres, nous devons revenir à "Server API" et créer une API de paramètres. Une fois cela fait, nous créerons un proxy dans l'Admin front-end pour appeler cette API back-end.

Nous devons enregistrer un seul paramètre : l'activation des informations. Si ce paramètre est vrai, l'aide contextuelle sera affichée dans les documents. S'il est faux, l'aide contextuelle sera désactivée.

Nous devons créer une nouvelle route, un nouveau contrôleur et enfin un nouveau service. Vous remarquerez que le type de cette API est "admin". Le front-end peut appeler directement le back-end sans permission.

La route des paramètres :

Route des paramètres

Le verbe GET permet d'obtenir les paramètres actuels et le verbe POST de mettre à jour les paramètres actuels, c'est simple !

Le contrôleur des paramètres :

Contrôleur des paramètres

Le contrôleur se contente d'appeler le service et de renvoyer le résultat.

Enfin, le service des paramètres :

Service des paramètres

strapi.store : cette fonction de Strapi nous permet de stocker certaines données du plugin et doit être appelée à chaque fois que nous devons accéder/écrire des paramètres.

  • La fonction getSettings détecte si les paramètres existent et les crée (si ce n'est pas le cas) dans le store.
  • La fonction setSettings définit les paramètres et les récupère automatiquement dans le store.

N'oubliez pas de référencer route, controller et service dans Strapi (voir l'article précédent).

Revenons dans le dossier "admin/src", quelles sont les étapes suivantes ?

  1. Nous devons créer un proxy pour appeler le backend depuis le frontend.
  2. Nous devons créer un composant pour afficher, sauvegarder ou mettre à jour les paramètres du plugin.

Créez un nouveau dossier "proxy" dans "api/src/plugins/admin/src/api/settings-proxy" et mettez-y le code ci-dessous :

Proxy des paramètres d'administration

Avec l'aide du plugin Strapi-Helper, nous avons utilisé la fonction request qui permet d'obtenir facilement le back-end "settings-api". Comme le type de settings-api est "admin", nous n'avons pas besoin d'ajouter "api" dans l'URL.

Nous sommes prêts à créer la page de configuration et à l'injecter dans le site web de Strapi Admin !

Page de paramètre

Pour créer notre nouvelle page, nous devons créer un dossier dans "api/src/plugins/awesome-help/admin/src/pages/Settings". À partir de ce dossier, créez un fichier "index.js".

Insérez le code ci-dessous dans le fichier :

Définition de la page de paramètre

Explications du code :

  • La fonction useEffect est appelée lorsque le composant est monté par REACT. La fonction "SettingsProxy.get()" récupère les paramètres du store et utilise le hook d'état pour interagir avec REACT (https://reactjs.org/docs/hooks-reference.html#usestate) => Lorsque le hook lie les paramètres, le contrôle <ToggleInput> est automatiquement configuré.
  • La fonction handleSubmit appelle la fonction "SettingsProxy.set()" pour stocker les paramètres.

Dans la partie UI, nous utilisons le composant <Box> : un simple conteneur hautement personnalisable. Un composant <Stack> pour empiler les composants internes. Une <Grid> pour organiser les contrôles. Enfin, un composant de contrôle <ToggleInput> avec un événement "onChange" pour basculer la propriété de paramètre "enabled".

La dernière étape consiste à enregistrer la page dans Strapi. Ouvrez le fichier "index.js" dans "api/src/plugins/awesome-help/admin/src". Ce fichier est le point d'entrée du plugin "Awesome Help". Repérez la fonction "register". Vous remarquerez certaines fonctions intéressantes comme :

  • "app.addMenuLink" permet d'injecter des éléments dans le menu de gauche de Strapi.
  • "app.registerPlugin" permet d'injecter le plugin dans le site de base de l'administration de Strapi.

Avant cette fonction, nous allons insérer un nouveau code pour créer une section de paramètres et ainsi utiliser notre page de paramètres.

La fonction createSettingSection en action !

Nous ajoutons par cette fonction 2 entrées : la principale : "Awesome Help" et une enfant : "General settings". Cette dernière ouvre la page "pages/Settings".

Consultez le site web de Strapi Admin, allez dans Settings / Awesome Help / General Settings, vous trouverez la page des paramètres !

Page de paramètre

Un ToogleNotification!

Parfait, exactement le comportement que nous attendions !

Mission accomplie !

Nous avons créé une page d'accueil personnalisée, une page de configuration injectée et enfin une API de configuration !

Et n'oubliez pas notre GIT pour obtenir le code : https://github.com/ExFabrica/strapi-stories/tree/develop/part-3

À bientôt !