Des composants Gutenberg dans mes pages d’options
Pour une administration aux petits oignons
@audrasjb�
Core Committer @ WordPress.org
Directeur Technique @ Whodunit
demat !
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
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
Un kit de composants d’interface prêts à l’emploi
L’équipe Make/Design maintient le kit UI de WordPress
Objectifs
Un fichier Figma que vous pouvez dupliquer pour vos projets : https://tinyurl.com/wcbzh-jb-figma
L’admin WP est en train de changer…
Revenons à nos oignons…�
Une page d’option avec les composants de Gutenberg
Une bibliothèque de composants documentés
Le storybook Gutenberg
Objectifs
Un storybook accessible en ligne : wordpress.github.io/gutenberg
(lib utilisée : storybook.js.org)
Conversion d’une �extension existante �vers le kit UI �de WordPress
Ce que nous allons produire
Bâtissons notre petite �extension « wcbzh »
Kalon vat !
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 panneau « apparence » avec :
Identifier les composants à utiliser
Champ texte : TextControl / TextareaControl
Liste déroulante : SelectControl
Choix : CheckboxControl / RadioControl / ToggleControl
Couleurs : ColorPicker / ColorPalette
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 :
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 :
Enqueue des scripts
index.php
Le fichier index.asset.php permet d’obtenir la liste des dépendances et la version courante dynamiquement
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' );
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' )
);
}
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 /> );
} );
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>
</>
);
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' );
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
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
Rendu du champ Message
C’est cool mais ce serait bien que ça enregistre !
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
On progresse…
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/
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
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
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
Pour aller plus loin…
On complète notre extension avec :
Le projet entier est disponible sur github.com/audrasjb/wcbzh
Trugarez!
Des questions ?
Pen Hir - sept 2024 ♥️