Des composants Gutenberg dans mes pages d'option - WordCamp Bretagne - Jb Audras

Dans ce talk technique, j’évoque les possibilités disponibles pour construire des pages d’options de sites et d’extensions.

Après un rapide tour d’horizon de ce qui se fait actuellement, je me suis focalisé particulièrement sur l’implémentation des composants Gutenberg. Ils permettent d’obtenir rapidement et efficacement des pages d’options qualitatives, riches en fonctionnalités, uniformisées par rapport à l’éditeur et efficaces en termes d’utilisabilité, de maintenabilité et de sécurité.

Transcript

1. Des composants Gutenberg dans mes pages d’options Pour une administration aux petits oignons
2. @audrasjb Core Committer @ WordPress.org Directeur Technique @ Whodunit demat !
3. Les pages d’options sur WP API Settings de WordPress Pros : natif Cons : limites UI, pas future-proof Cʼest la méthode old school : stable et native, mais rudimentaire Advanced Custom Fields Pros : facile à implémenter, complet, stable Cons : produit tiers inadapté aux extensions Sans doute la méthode la plus utilisée pour les sites sur-mesure Les frameworks : Carbon Fields, wp-optionskit Pros : complet, fait pour les extensions, composer-ready Cons : framework tiers, maintenabilité Une méthode qui a fait ses preuves chez les auteur·ices dʼextensions Les générateurs : GenerateWP, WP Turbo… Pros : fait gagner du temps, utilise du natif Cons : maîtrise du code ? Des outils utiles pour gagner du temps, mais pas forcément de la structuration
4. Gutenberg, au delà de l’éditeur de contenu Des blocs pour le contenu des publications Des blocs pour la mise en page du site Mais aussi des éléments d’interface ! Interface dʼédition unifiée par un design system Technologies « modernes » Accessibilité et perfs gérées élément par élément on m’a pas trop demandé mon avis mais bon ok les geeks yolo balek
5. Un kit de composants d’interface prêts à l’emploi Lʼéquipe Make/Design maintient le kit UI de WordPress Objectifs - Le futur de lʼadmin WP - Ne pas réinventer la roue - Cohérence des interfaces Un fichier Figma que vous pouvez dupliquer pour vos projets : https://tinyurl.com/wcbzh-jb-figma
6. L’admin WP est en train de changer…
7. Revenons à nos oignons… Une page d’option avec les composants de Gutenberg
8. Une bibliothèque de composants documentés Le storybook Gutenberg Objectifs - Centraliser les composants - Documenter leur utilisation - Visualisation indépendante - Exemples dʼimplémentation - Checks accessibilité Un storybook accessible en ligne : wordpress.github.io/gutenberg (lib utilisée : storybook.js.org)
9. Conversion d’une extension existante vers le kit UI de WordPress
12. Ce que nous allons produire
13. Bâtissons notre petite extension « wcbzh » Kalon vat !
14. Objectif de notre projet « wcbzh » Une page dʼoption pour afficher un bandeau promo en front, avec : La possibilité dʼactiver/désactiver le message Un panneau « message » avec : - Un message textuel Un panneau « apparence » avec : - Un sélecteur de position (haut/bas) - La possibilité dʼajouter une animation - Choix dʼune couleur de fond
15. Identifier les composants à utiliser Champ texte : TextControl / TextareaControl Liste déroulante : SelectControl Choix : CheckboxControl / RadioControl / ToggleControl Couleurs : ColorPicker / ColorPalette Sections : Panel, TabPanel
16. Phase de démarrage Installer npm Initialiser les fichiers du projet /plugins/wcbzh/ index.php package.json src/ index.js index.scss Contenu du package.json :
17. Compilation du projet /plugins/wcbzh/ index.php package.json package-lock.json src/ index.js index.scss build/ index.js index.css index.asset.php node_modules/ {le bordel habituel} Le répertoire /build est créé et mis à jour à partir de /src lors de la compilation via la commande run build ou run start $ npm install @wordpress/scripts --save-dev $ npm run build Initialiser wp-script et créer un premier build :
18. Enqueue des scripts index.php Le fichier index.asset.php permet dʼobtenir la liste des dépendances et la version courante dynamiquement
19. Déclaration de la page d’options index.php function wcbzh_add_option_page( ) { add_options_page( __( 'WCBZH options', 'wcbzh' ), __('WCBZH', 'wcbzh' ), 'manage_options', 'wcbzh', 'wcbzh_options_page' ); } add_action( 'admin_menu', 'wcbzh_add_option_page' );
20. Initialisation de la page d’options index.php function wcbzh_options_page( ) { printf( '<h1>' . esc_html__( 'WordCamp Bretagne', 'wcbzh' ) . '</h1>' . '<div class="wrap" id="wcbzh-settings">%s</div>', esc_html__( 'Loading…', 'wcbzh' ) ); }
21. Initialisation JSX /build/index.js import domReady from '@wordpress/dom-ready'; import { createRoot } from '@wordpress/element'; import { __ } from '@wordpress/i18n'; const SettingsPage = () => { return <div>Demat!</div>; }; domReady( () => { const root = createRoot( document.getElementById( 'wcbzh-settings' ) ); root.render( <SettingsPage /> ); } );
22. Création du squelette de la page à l'aide des panels import { Panel, PanelBody, PanelRow } from '@wordpress/components'; return ( <> <Panel> <PanelBody title={ 'Contenu du message' } initialOpen={ false } > <PanelRow> <div>Message : textarea</div> </PanelRow> </PanelBody> <PanelBody title={ 'Apparence du message' } initialOpen={ false } > <PanelRow> <div>Position : select ('top', 'bottom')</div> </PanelRow> <PanelRow> <div>Couleur : colorpicker</div> </PanelRow> </PanelBody> </Panel> </> );
23. Ajout d’une feuille de style personnalisée /build/index.js index.php import './index.scss'; Si pas besoin de css custom, alors juste : wp_enqueue_style( 'wp-components' );
24. Gestion de l’état des composants /build/index.js import { useState } from '@wordpress/element'; Gestion des états de chaque composant avec des instances de useState Les états sont stockés dans un custom hook useSettings Transmission de useSettings et de chacun des états qui y sont déclarés à SettingsPage, la fonction de rendu de la page dʼoption
25. 1er composant : TextareaControl /build/index.js import { TextareaControl } from '@wordpress/components'; On crée un composant MessageControl qui sera une instance personnalisée du composant natif TextareaControl Puis on ajoute le composant MessageControl à la place du placeholder utilisé au départ
26. Rendu du champ Message Cʼest cool mais ce serait bien que ça enregistre !
27. Le bouton d’enregistrement /build/index.js import { Button } from '@wordpress/components'; On crée un composant SaveButton qui renvoie une instance du composant natif Button On ajoute le composant après les panels
28. On progresse…
29. La déclaration des réglages dans WP index.php Les réglages seront accessibles en utilisant la fonction native get_option( 'wpbzh' ) qui renverra un tableau contenant chacun des paramètres On définit ici la valeur par défaut des champs On déclare un schéma de structure pour que WP sʼoccupe de la validation des valeurs Enfin, on rend nos réglages disponibles via le endpoint Settings de lʼAPI REST https://developer.wordpress.org/rest-api/reference/settings/
30. Récupérer les valeurs des champs /build/index.js import { useEffect } from '@wordpress/element'; import apiFetch from '@wordpress/api-fetch'; Le hook useEffect permet de déclencher une action au chargement de lʼécran Ici, on fait un appel apiFetch au endpoint Settings de lʼAPI REST afin de récupérer la valeur du champ message du réglage wcbzh, quʼon associe à setMessage Cʼest lʼéquivalent de faire get_option() en PHP sauf quʼici on passe par lʼAPI REST
31. Enregistrer les valeurs des champs /build/index.js On crée une fonction saveSettings utilisant apiFetch pour enregistrer les valeurs de nos champs via lʼAPI REST Puis on fait appel à cette fonction au clic sur le bouton précédemment ajouté dans lʼinterface
32. Récupération des données en front Il suffit dʼutiliser la fonction WP get_option() Ici on implémente notre message via le hook wp_body_open index.php
33. Pour aller plus loin… On complète notre extension avec : - Gestion de lʼaffichage ou non du bandeau : ToggleControl - Gestion de la position du bandeau : SelectControl - Utilisation ou non dʼune animation : ToggleControl - Sélecteur de couleurs : ColorPicker - Notification dʼenregistrement des réglages : NoticeList Le projet entier est disponible sur github.com/audrasjb/wcbzh
34. Trugarez! Des questions ? Pen Hir - sept 2024 ♥