Les champs personnalisés permettent d’attribuer des informations supplémentaires au contenu d’un site web. Ces informations sont généralement connues sous le nom de métadonnées.

Les métadonnées sont des informations sur les informations. Dans le cas de WordPress, il s’agit d’informations associées aux articles, aux utilisateurs, aux commentaires et aux termes.

Étant donné la relation « many-to-one » des métadonnées dans WordPress, vos options sont assez illimitées. Vous pouvez avoir autant d’options de métadonnées que vous le souhaitez, et vous pouvez y stocker à peu près n’importe quoi.

-Facebook

Voici quelques exemples de métadonnées que vous pouvez joindre à un article à l’aide de champs personnalisés :

  • Les coordonnées géographiques d’un lieu ou d’un bien immobilier
  • La date d’un évènement
  • L’ISBN ou l’auteur d’un livre
  • L’humeur du jour de l’auteur

Et il y en a bien d’autres.

D’emblée, WordPress ne fournit pas un moyen facile d’ajouter et de gérer les champs personnalisés. Dans l’éditeur classique, les champs personnalisés sont affichés dans une boite placée en bas de la page, sous l’éditeur d’articles.

Champs personnalisés dans l'éditeur classique.
Champs personnalisés dans l’éditeur classique.

Dans Gutenberg, les champs personnalisés sont désactivés par défaut, mais vous pouvez les afficher en sélectionnant l’élément correspondant dans les réglages des articles.

Ajout du panneau des champs personnalisés à l'éditeur de blocs.
Ajout du panneau des champs personnalisés à l’éditeur de blocs.

Malheureusement, il n’existe aucun moyen d’afficher les métadonnées sur l’interface publique sans utiliser une extension ou se salir les mains avec du code.

Si vous êtes un utilisateur, vous trouverez plusieurs excellentes pextensions qui font le travail pour vous. Mais si vous êtes un développeur et que vous souhaitez tirer davantage parti des champs personnalisés de WordPress, les intégrer de manière transparente dans l’éditeur de blocs et les afficher sur l’interface publique de votre site web WordPress à l’aide d’un bloc Gutenberg personnalisé, alors vous êtes au bon endroit.

Donc, si vous vous demandez quelle est la meilleure façon d’utiliser les champs personnalisés WordPress à la fois dans Gutenberg et dans l’éditeur classique pour les développeurs WordPress, la réponse rapide est « la création d’une extension qui fonctionne à la fois pour l’éditeur classique et Gutenberg ».

Mais ne vous inquiétez pas trop. Si créer une extension pour gérer les champs personnalisés dans les deux éditeurs pourrait être un peu délicat, nous allons essayer de rendre le processus aussi simple que possible. Une fois que vous aurez compris les concepts que nous aborderons dans cet article, vous acquerrez les compétences nécessaires pour gérer les champs méta personnalisés dans Gutenberg et construire toutes sortes de sites web.

Note : Avant de faire quoi que ce soit, assurez-vous que vous avez une version à jour de Node.js sur votre ordinateur

Ceci étant dit, voici notre récapitulatif :

Créer un plugin de bloc avec l’outil officiel create-block

La première étape consiste à créer une nouvelle extnsion avec tous les fichiers et dépendances nécessaires pour enregistrer un nouveau type de bloc. L’extension block vous permettra de créer facilement un type de bloc personnalisé pour gérer et afficher des métadonnées personnalisées.

Pour créer un nouveau type de bloc, nous utiliserons l’outil officiel create-block. Pour un aperçu détaillé de l’utilisation de l’outil create-block, consultez notre article précédent sur le développement de blocs Gutenberg.

Ouvrez votre outil de ligne de commande, naviguez dans le répertoire plugins de votre site de développement WordPress et exécutez la commande suivante :

npx @wordpress/create-block

Lorsque vous y êtes invité, ajoutez les détails suivants :

  • La variante de modèle à utiliser pour ce bloc : dynamic
  • Le slug du bloc utilisé pour l’identification (également le nom du dossier de sortie) : metadata-block
  • L’espace de noms interne pour le nom du bloc (quelque chose d’unique pour vos produits) : meta-fields
  • Le titre d’affichage de votre bloc : Meta Fields
  • La courte description de votre bloc (facultatif) : Description du bloc
  • Le dashicon pour faciliter l’identification de votre bloc (facultatif) : book
  • Le nom de la catégorie pour aider les utilisateurs à naviguer et à découvrir votre bloc : widgets
  • Voulez-vous personnaliser l’extension WordPress ? Oui/Non

Prenons un moment pour examiner ces détails et essayer de comprendre où ils sont utilisés.

  • Le slug du bloc utilisé pour l’identification définit le nom du dossier et le domaine de texte de l’extension
  • L’espace de noms interne pour le nom du bloc définit l’espace de noms interne du bloc et le préfixe de fonction utilisé dans tout le code de l’extension.
  • Le titre d’affichage de votre bloc définit le nom du plugin et le nom du bloc utilisé dans l’interface de l’éditeur.

La configuration peut prendre quelques minutes. Une fois le processus terminé, vous obtiendrez une liste des commandes disponibles.

L'extension de bloc a bien été installée.
L’extension de bloc a bien été installée.

Avant de passer à la section suivante, dans votre outil de ligne de commande, naviguez dans le dossier de votre extension et exécutez les commandes suivantes :

cd metadata-block
npm start

Vous êtes prêt à construire votre code. L’étape suivante consiste à modifier le fichier PHP principal de l’extension pour construire une boite méta pour l’éditeur classique.

Donc, avant de passer à la section suivante, installez et activez l’extension Classic Editor.

Ensuite, ouvrez l’écran Extensions et activez la nouvelle extension Meta Fields.

Activer les extensions.
Activer les extensions.

Ajouter une boite méta à l’éditeur classique

Dans le contexte de l’éditeur classique, une boite méta est un conteneur contenant des éléments de formulaire permettant de saisir des informations spécifiques, telles que l’auteur, les balises, les catégories, etc.

En plus des boites méta intégrées, les développeurs d’extensions peuvent ajouter un nombre quelconque de boites méta personnalisées pour inclure des éléments de formulaire HTML (ou tout contenu HTML) où les utilisateurs d’extensions peuvent saisir des données spécifiques aux extensions.

L’API de WordPress fournit des fonctions utiles pour enregistrer facilement des boites méta personnalisées afin d’inclure tous les éléments HTML dont votre plugin a besoin pour fonctionner.

Pour commencer, ajoutez le code suivant au fichier PHP de l’extension que vous venez de créer :

// register meta box
function meta_fields_add_meta_box(){
	add_meta_box(
		'meta_fields_meta_box', 
		__( 'Book details' ), 
		'meta_fields_build_meta_box_callback', 
		'post',
		'side',
		'default'
	 );
}

// build meta box
function meta_fields_build_meta_box_callback( $post ){
	  wp_nonce_field( 'meta_fields_save_meta_box_data', 'meta_fields_meta_box_nonce' );
	  $title = get_post_meta( $post->ID, '_meta_fields_book_title', true );
	  $author = get_post_meta( $post->ID, '_meta_fields_book_author', true );
	  ?>
	  <div class="inside">
	  	  <p><strong>Title</strong></p>
		  <p><input type="text" id="meta_fields_book_title" name="meta_fields_book_title" value="<?php echo esc_attr( $title ); ?>" /></p>	
		  <p><strong>Author</strong></p>
		  <p><input type="text" id="meta_fields_book_author" name="meta_fields_book_author" value="<?php echo esc_attr( $author ); ?>" /></p>
	  </div>
	  <?php
}
add_action( 'add_meta_boxes', 'meta_fields_add_meta_box' );

La fonction add_meta_box enregistre une nouvelle boite méta, tandis que la fonction callback construit le HTML à injecter dans la boite méta. Nous n’approfondirons pas ce sujet car il dépasse le cadre de notre article, mais vous trouverez tous les détails dont vous avez besoin ici, ici et ici.

L’étape suivante consiste à créer une fonction qui enregistre les données saisies par l’auteur chaque fois que le crochet save_post est déclenché (voir Ressources pour développeurs) :

// save metadata
function meta_fields_save_meta_box_data( $post_id ) {
	if ( ! isset( $_POST['meta_fields_meta_box_nonce'] ) )
		return;
	if ( ! wp_verify_nonce( $_POST['meta_fields_meta_box_nonce'], 'meta_fields_save_meta_box_data' ) )
		return;
	if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE )
		return;
	if ( ! current_user_can( 'edit_post', $post_id ) )
		return;

	if ( ! isset( $_POST['meta_fields_book_title'] ) )
		return;
	if ( ! isset( $_POST['meta_fields_book_author'] ) )
		return;

	$title = sanitize_text_field( $_POST['meta_fields_book_title'] );
	$author = sanitize_text_field( $_POST['meta_fields_book_author'] );

	update_post_meta( $post_id, '_meta_fields_book_title', $title );
	update_post_meta( $post_id, '_meta_fields_book_author', $author );
}
add_action( 'save_post', 'meta_fields_save_meta_box_data' );

Encore une fois, consultez la documentation en ligne pour plus de détails. Ici, nous nous contenterons de souligner l’underscore (_) qui précède la clé méta. Cela indique à WordPress de masquer les clés de ces champs personnalisés de la liste des champs personnalisés disponibles par défaut et rend vos champs personnalisés visibles uniquement dans votre boite méta personnalisée.

L’image ci-dessous montre à quoi ressemble la boite méta personnalisée dans l’éditeur classique :

Une boite méta personnalisée dans l'éditeur classique.
Une boite méta personnalisée dans l’éditeur classique.

Maintenant, si vous désactivez l’extension Classic Editor et vérifiez ce qui se passe dans l’éditeur de blocs, vous verrez que la boite méta apparaît et fonctionne toujours, mais pas exactement de la manière dont vous vous y attendez.

Notre objectif est de créer un système de gestion des métadonnées attachées aux articles de blog ou aux types de publications personnalisés qui s’intègre de manière transparente dans l’éditeur de blocs. Pour cette raison, le code présenté jusqu’à présent ne sera nécessaire que pour assurer la rétrocompatibilité avec l’éditeur classique.

Ainsi, avant de poursuivre, nous indiquerons à WordPress de supprimer la boite de métadonnées personnalisée de l’éditeur de blocs en ajoutant le drapeau __back_compat_meta_box à la fonction add_meta_box (voir aussi Drapeaux de compatibilité de la boite de métadonnées et compatibilité ascendante).

Revenons à la fonction de rappel qui enregistre la boite méta et modifions-la comme suit :

// register meta box
function meta_fields_add_meta_box(){
	add_meta_box(
		'meta_fields_meta_box', 
		__( 'Book details' ), 
		'meta_fields_build_meta_box_callback', 
		'post', 
		'side',
		'default',
		// hide the meta box in Gutenberg
		array('__back_compat_meta_box' => true)
	 );
}

Enregistrez le fichier de l’extension et retournez dans votre administration WordPress. Maintenant, vous ne devriez plus voir la boite méta personnalisée dans l’éditeur de blocs. Si vous réactivez l’éditeur classique à la place, votre boite méta personnalisée apparaitra à nouveau.

Ajouter des champs méta personnalisés à l’éditeur de bloc Gutenberg (trois options)

Dans nos articles précédents sur le développement de blocs Gutenberg, nous avons fourni des aperçus détaillés de l’éditeur, de ses parties, et de la façon de développer des blocs statiques et des blocs dynamiques.

Comme nous l’avons mentionné, dans cet article, nous allons aller un peu plus loin et discuter de la façon d’ajouter des champs méta personnalisés aux articles de blog.

Il existe plusieurs façons de stocker et d’utiliser les métadonnées des articles dans Gutenberg. Nous aborderons ici les points suivants :

Créer un bloc personnalisé pour stocker et afficher des champs méta personnalisés

Dans cette section, nous allons vous montrer comment créer et gérer des champs méta personnalisés à partir d’un bloc dynamique. Selon le manuel de l’éditeur de bloc, un champ méta d’article est un objet WordPress utilisé pour stocker des données supplémentaires sur un article et nous devons d’abord enregistrer un nouveau champ méta avant de pouvoir l’utiliser.

Enregistrer les champs méta personnalisés

Avant d’enregistrer un champ méta personnalisé, vous devez vous assurer que le type de publication qui l’utilisera prend en charge les champs personnalisés. En outre, lorsque vous enregistrez un champ méta personnalisé, vous devez définir le paramètre show_in_rest sur true.

Maintenant, revenons au fichier de l’extension. Ajoutez le code suivant :

/**
 * Register the custom meta fields
 */
function meta_fields_register_meta() {

    $metafields = [ '_meta_fields_book_title', '_meta_fields_book_author' ];

    foreach( $metafields as $metafield ){
        // Pass an empty string to register the meta key across all existing post types.
        register_post_meta( '', $metafield, array(
            'show_in_rest' => true,
            'type' => 'string',
            'single' => true,
            'sanitize_callback' => 'sanitize_text_field',
            'auth_callback' => function() { 
                return current_user_can( 'edit_posts' );
            }
        ));
    }  
}
add_action( 'init', 'meta_fields_register_meta' );

register_post_meta enregistre une clé méta pour les types de publication spécifiés. Dans le code ci-dessus, nous avons enregistré deux champs méta personnalisés pour tous les types de publications enregistrés sur votre site web qui prennent en charge les champs personnalisés. Pour plus d’informations, consultez la référence de la fonction.

Une fois cela fait, ouvrez le fichier src/index.js de votre extension de bloc.

Enregistrez le type de bloc sur le client

Naviguez maintenant dans le dossier wp-content/plugins/metadata-block/src et ouvrez le fichier index.js:

import { registerBlockType } from '@wordpress/blocks';
import './style.scss';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata.name, {
	edit: Edit,
} );

Avec les blocs statiques, nous aurions également vu une fonctionsave. Dans ce cas, la fonction save est absente car nous avons installé un bloc dynamique. Le contenu affiché sur l’interface publique sera généré dynamiquement via PHP.

Créez le type de bloc

Naviguez vers le dossier wp-content/plugins/metadata-block/src et ouvrez le fichier edit.js. Vous devriez voir le code suivant (commentaires supprimés) :

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Meta Fields – hello from the editor!', 'metadata-block' ) }
		</p>
	);
}

Vous ajouterez ici le code permettant de générer le bloc à rendre dans l’éditeur.

La première étape consiste à importer les composants et les fonctions nécessaires à la construction du bloc. Voici la liste complète des dépendances :

import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls, RichText } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';
import { TextControl, PanelBody, PanelRow } from '@wordpress/components';
import './editor.scss';

Si vous avez lu nos articles précédents, vous devriez être familier avec un grand nombre de ces déclarationsimport. Nous n’en signalerons ici que quelques-unes :

import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';

Une fois que vous avez importé ces dépendances, voici comment vous allez useSelect et useEntityProp dans la fonction Edit():

const postType = useSelect(
		( select ) => select( 'core/editor' ).getCurrentPostType(),
		[]
	);
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );

Ce code fournit l’adresse actuelle postType, un objet de champs méta (meta), et une fonction setter pour les mettre à jour (setMeta).

Remplacez maintenant le code actuel de la fonction Edit() par le suivant :

export default function Edit() {
	const blockProps = useBlockProps();
	const postType = useSelect(
		( select ) => select( 'core/editor' ).getCurrentPostType(),
		[]
	);
	const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
	const bookTitle = meta[ '_meta_fields_book_title' ];
	const bookAuthor = meta[ '_meta_fields_book_author' ];
	const updateBookTitleMetaValue = ( newValue ) => {
		setMeta( { ...meta, _meta_fields_book_title: newValue } );
    };
	const updateBookAuthorMetaValue = ( newValue ) => {
		setMeta( { ...meta, _meta_fields_book_author: newValue } );
	};
return ( ... );
}

Encore une fois :

  • Nous avons utilisé useSelect pour obtenir le type de publication actuel.
  • useEntityProp renvoie un tableau de champs méta et une fonction setter pour définir de nouvelles valeurs méta.
  • updateBookTitleMetaValue et updateBookAuthorMetaValue sont deux gestionnaires d’événements pour enregistrer les valeurs des champs méta.

L’étape suivante consiste à construire le code JSX (JavaScript XML) renvoyé par la fonction Edit():

export default function Edit() {
	...
	return (
		<>
			<InspectorControls>
				<PanelBody 
					title={ __( 'Book Details' )}
					initialOpen={true}
				>
					<PanelRow>
						<fieldset>
							<TextControl
								label={__( 'Book title' )}
								value={ bookTitle }
								onChange={ updateBookTitleMetaValue }
							/>
						</fieldset>
					</PanelRow>
					<PanelRow>
						<fieldset>
							<TextControl
								label={ __( 'Book author' ) }
								value={ bookAuthor }
								onChange={ updateBookAuthorMetaValue }
							/>
						</fieldset>
					</PanelRow>
				</PanelBody>
			</InspectorControls>
			<div { ...blockProps }>
				<RichText 
					tagName="h3"
					onChange={ updateBookTitleMetaValue }
					allowedFormats={ [ 'core/bold', 'core/italic' ] }
					value={ bookTitle }
					placeholder={ __( 'Write your text...' ) }
				/>
				<TextControl
					label="Book Author"
					value={ bookAuthor }
					onChange={ updateBookAuthorMetaValue }
				/>
			</div>
		</>
	);
}

Le composant RichText fournit une entrée contentable, tandis que TextControl fournit de simples champs de texte.

Nous avons également créé un panneau latéral contenant deux champs de saisie à utiliser à la place des deux contrôles de formulaire inclus dans le bloc.

Enregistrez le fichier et retournez dans l’éditeur. Ajoutez le bloc Meta Fields à partir de l’inserteur de blocs et remplissez le titre du livre et l’auteur.

Un bloc personnalisé comprenant deux champs méta personnalisés.
Un bloc personnalisé comprenant deux champs méta personnalisés.

Vous remarquerez que chaque fois que vous modifiez la valeur du champ dans le bloc, la valeur du champ de texte correspondant dans la colonne latérale change également.

Ensuite, nous devons créer le code PHP qui génère le HTML à rendre sur l’interface publique.

Afficher le bloc sur le frontend

Ouvrez à nouveau le fichier PHP principal dans votre éditeur de code et réécrivez la fonction de rappel qui génère la sortie du bloc comme suit :

function meta_fields_metadata_block_block_init() {
	register_block_type(
		__DIR__ . '/build',
		array(
			'render_callback' => 'meta_fields_metadata_block_render_callback',
		)
	);
}
add_action( 'init', 'meta_fields_metadata_block_block_init' );

function meta_fields_metadata_block_render_callback( $attributes, $content, $block ) {
	
	$book_title = get_post_meta( get_the_ID(), '_meta_fields_book_title', true );
	$book_author = get_post_meta( get_the_ID(), '_meta_fields_book_author', true );
    
	$output = "";

	if( ! empty( $book_title ) ){
		$output .= '<h3>' . esc_html( $book_title ) . '</h3>';
	}
	if( ! empty( $book_author ) ){
		$output .= '<p>' . __( 'Book author: ' ) . esc_html( $book_author ) . '</p>';
	}
	if( strlen( $output ) > 0 ){
		return '<div ' . get_block_wrapper_attributes() . '>' . $output . '</div>';
	} else {
		return '<div ' . get_block_wrapper_attributes() . '>' . '<strong>' . __( 'Sorry. No fields available here!' ) . '</strong>' . '</div>';
	}
}

Ce code est assez explicite. Tout d’abord, nous utilisons get_post_meta pour récupérer les valeurs des champs méta personnalisés. Ensuite, nous utilisons ces valeurs pour construire le contenu du bloc. Enfin, la fonction de rappel renvoie le HTML du bloc.

Le bloc est prêt à être utilisé. Nous avons intentionnellement gardé le code de cet exemple aussi simple que possible, mais en utilisant les composants natifs de Gutenberg, vous pouvez construire des blocs plus avancés et tirer le meilleur parti des champs méta personnalisés de WordPress.

Un bloc personnalisé comprenant plusieurs champs méta.
Un bloc personnalisé comprenant plusieurs champs méta.

Dans notre exemple, nous avons utilisé les éléments h3 et p pour construire le bloc pour l’interface publique.

Mais vous pouvez afficher les données de plusieurs façons. L’image suivante montre une simple liste non ordonnée de champs méta.

Un exemple de bloc pour l'interface publique.
Un exemple de bloc pour l’interface publique.

Vous trouverez le code complet de cet exemple dans ce gist public.

Ajout d’un champ méta personnalisé dans la colonne latérale du document

La deuxième option consiste à attacher des champs méta personnalisés aux publications à l’aide d’une extension qui génère un panneau de réglages dans la colonne latérale du document.

Le processus est assez similaire à l’exemple précédent, sauf que dans ce cas, nous n’aurons pas besoin d’un bloc pour gérer les métadonnées. Nous allons créer un composant pour générer un panneau comprenant un ensemble de contrôles dans la colonne latérale du document en suivant ces étapes :

  1. Créer un nouveau plugin de bloc avec create-block
  2. Enregistrez une boite méta personnalisée pour l’éditeur classique
  3. Enregistrer les champs méta personnalisés dans le fichier principal du plugin via la fonction register_post_meta()
  4. Enregistrer un plugin dans le fichier index.js
  5. Construire le composant en utilisant les composants intégrés de Gutenberg

Créer un nouveau plugin de bloc avec l’outil create-block

Pour créer une nouvelle extension de bloc, suivez les étapes de la section précédente. Vous pouvez créer une nouvelle extension ou modifier les scripts que nous avons construits dans l’exemple précédent.

Enregistrer une boite méta personnalisée pour l’éditeur classique

Ensuite, vous devez enregistrer une boîte méta personnalisée pour assurer la rétrocompatibilité avec les sites web WordPress qui utilisent encore l’éditeur classique. Le processus est le même que celui décrit dans la section précédente.

Enregistrer les champs méta personnalisés dans le fichier principal du plugin

L’étape suivante consiste à enregistrer les champs méta personnalisés dans le fichier principal de l’extension via la fonction register_post_meta(). Là encore, vous pouvez suivre l’exemple précédent.

Enregistrer un plugin dans le fichier index.js

Une fois que vous avez terminé les étapes précédentes, il est temps d’enregistrer une extension dans le fichier index.js pour rendre un composant personnalisé.

Avant d’enregistrer l’extension, créez un dossier components dans le dossier src de l’extension. Dans le dossier components, créez un nouveau fichier MetaBox.js. Vous pouvez choisir le nom que vous jugez bon pour votre composant. Veillez simplement à respecter les meilleures pratiques de nommage dans React.

Avant de continuer, installez le module@wordpress/plugins à partir de votre outil de ligne de commande.

Arrêtez le processus (mac), installez le module et relancez le processus :

^C
npm install @wordpress/plugins --save
npm start

Une fois fait, ouvrez le fichier index.js de votre extension et ajoutez le code suivant.

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import MetaBox from './components/MetaBox';

Ce code est assez explicite. Cependant, nous voulons prendre un moment pour nous attarder sur les deux déclarations import pour les lecteurs qui n’ont pas de compétences avancées en React.

Avec la première déclaration import, nous avons mis le nom de la fonction entre crochets. Avec la deuxième déclaration import, le nom du composant n’est pas entouré de crochets.

Ensuite, enregistrez votre extension :

registerPlugin( 'metadata-plugin', {
	render: MetaBox
} );

registerPlugin enregistre simplement une extension. La fonction accepte deux paramètres :

  • Une chaîne unique qui identifie l’extension
  • Un objet de paramètres d’extension. Notez que la propriété render doit être spécifiée et doit être une fonction valide.

Construire le composant en utilisant les composants intégrés de Gutenberg

Il est temps de construire notre composant React. Ouvrez le fichier MetaBox.js (ou peu importe comment vous l’avez appelé) et ajoutez les déclarations d’importation suivantes :

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
import { PanelRow, TextControl, DateTimePicker } from '@wordpress/components';
  • La fonction compose effectue la composition de fonctions, ce qui signifie que le résultat d’une fonction est transmis à une autre fonction.Avant de pouvoir utiliser compose, vous devrez peut-être installer le module correspondant : 
    npm install @wordpress/compose --save

    Nous verrons la fonction compose en action dans un instant.

  • withSelect et withDispatch sont deux composants d’ordre supérieur qui vous permettent de récupérer ou d’envoyer des données depuis ou vers WordPress. withSelect est utilisé pour injecter des accessoires dérivés de l’état en utilisant des sélecteurs enregistrés, withDispatch est utilisé pour envoyer des accessoires en utilisant des créateurs d’actions enregistrés.
  • PluginDocumentSettingPanel rend les éléments dans la barre latérale du document (voir le code source sur Github).

Ensuite, vous allez créer le composant permettant d’afficher le panneau de la boîte méta dans la colonne latérale du document. Dans votre fichier MetaBox.js, ajoutez le code suivant :

const MetaBox = ( { postType, metaFields, setMetaFields } ) => {

	if ( 'post' !== postType ) return null;

	return(
		<PluginDocumentSettingPanel 
			title={ __( 'Book details' ) } 
			icon="book"
			initialOpen={ false }
		>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_title }
					label={ __( "Title" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_author }
					label={ __( "Author" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<TextControl 
					value={ metaFields._meta_fields_book_publisher }
					label={ __( "Publisher" ) }
					onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
				/>
			</PanelRow>
			<PanelRow>
				<DateTimePicker
					currentDate={ metaFields._meta_fields_book_date }
					onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
					__nextRemoveHelpButton
					__nextRemoveResetButton
				/>
			</PanelRow>
		</PluginDocumentSettingPanel>
	);
}

const applyWithSelect = withSelect( ( select ) => {
	return {
		metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
		postType: select( 'core/editor' ).getCurrentPostType()
	};
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
	return {
		setMetaFields ( newValue ) {
			dispatch('core/editor').editPost( { meta: newValue } )
		}
	}
} );

export default compose([
	applyWithSelect,
	applyWithDispatch
])(MetaBox);

Décomposons ce code.

  • L’élémentPluginDocumentSettingPanel rend un nouveau panneau dans la colonne latérale du document. Nous définissons le titre (« Book Details » et l’icône, et définissons initialOpen sur false, ce qui signifie que le panneau est initialement fermé.
  • Dans PluginDocumentSettingPanel, nous avons trois champs de texte et un élément DateTimePicker qui permet à l’utilisateur de définir la date de publication.
  • withSelect donne accès à la fonction select que nous utilisons pour récupérer metaFields et postType. withDispatch donne accès à la fonction dispatch, qui permet de mettre à jour les valeurs des métadonnées.
  • Enfin, la fonction compose nous permet de composer notre composant avec les composants d’ordre supérieur withSelect et withDispatch. Cela donne au composant l’accès aux propriétés metaFields et postType et à la fonction setMetaFields.

Enregistrez votre fichier MetaBox.js et créez un nouvel article dans votre site de développement WordPress et jetez un coup d’œil à la colonne latérale du document. Vous devriez voir le nouveau panneau Book Details.

Un panneau de boite méta personnalisé dans Gutenberg.
Un panneau de boite méta personnalisé dans Gutenberg.

Maintenant, exécutez vos tests. Définissez les valeurs de vos champs méta personnalisés et enregistrez la publication. Rechargez ensuite la page et vérifiez si les valeurs que vous avez saisies sont bien en place.

Ajoutez le bloc que nous avons construit dans la section précédente et vérifiez si tout fonctionne correctement.

Ajout d’une colonne latérale personnalisée pour gérer les métadonnées des publications

Si vous avez un grand nombre de champs méta personnalisés à ajouter à vos articles ou à vos types de publication personnalisés, vous pouvez également créer une colonne latérale de réglages personnalisés spécifiquement pour votre extension.

Le processus est très similaire à l’exemple précédent, donc si vous avez compris les étapes abordées dans la section précédente, vous n’aurez aucune difficulté à créer une colonne latérale personnalisée pour Gutenberg.

Encore une fois :

  1. Créer un nouveau plugin de bloc avec create-block
  2. Enregistrer un champ méta personnalisé pour l’éditeur classique
  3. Enregistrer les champs méta personnalisés dans le fichier principal du plugin via la fonction register_post_meta()
  4. Enregistrer un plugin dans le fichier index.js
  5. Construire le composant en utilisant les composants intégrés de Gutenberg

Créer un nouveau plugin de bloc avec l’outil create-block

Encore une fois, pour créer une nouvelle extension de bloc, suivez les étapes présentées ci-dessus. Vous pouvez créer une nouvelle extension ou modifier les scripts construits dans les exemples précédents.

Enregistrer une boîte méta personnalisée pour l’éditeur classique

Enregistrez maintenant une boîte méta personnalisée pour assurer la rétrocompatibilité avec les sites web WordPress qui utilisent encore l’éditeur classique. Le processus est le même que celui décrit dans la section précédente.

Enregistrer les champs méta personnalisés dans le fichier principal du plugin

Enregistrez les champs méta personnalisés dans le fichier principal du plugin via la fonction register_post_meta().

Enregistrer un plugin dans le fichier index.js

Créez maintenant un fichier CustomSidebar.js vide dans votre dossier components.

Une fois cela fait, modifiez votre fichier index.js comme suit :

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import CustomSidebar from './components/CustomSidebar';
// import MetaBox from './components/MetaBox';

registerPlugin( 'metadata-block', {
    render: CustomSidebar
} );

Avec le code ci-dessus, nous importons d’abord le composant CustomSidebar, puis nous indiquons à la fonction registerPlugin de rendre le nouveau composant.

Construire le composant en utilisant les composants intégrés de Gutenberg

Ensuite, ouvrez le fichier CustomSidebar.js et ajoutez les dépendances suivantes :

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post';
import { PanelBody, PanelRow, TextControl, DateTimePicker } from '@wordpress/components';

Vous devriez remarquer que nous importons deux nouveaux composants :

  • PluginSidebar ajoute une icône dans la barre d’outils Gutenberg qui, lorsqu’on clique dessus, affiche une colonne latérale comprenant le contenu enveloppé dans l’élément<PluginSidebar /> (Le composant est également documenté sur GitHub).
  • PluginSidebarMoreMenuItem rend un élément de menu sous Extensions dans le menu déroulant More Menu et peut être utilisé pour activer le composant PluginSidebar correspondant (voir également sur GitHub).

Vous pouvez maintenant construire votre composant personnalisé :

const CustomSidebar = ( { postType, metaFields, setMetaFields } ) => {
        
    if ( 'post' !== postType ) return null;

    return (
        <>
            <PluginSidebarMoreMenuItem 
                target="metadata-sidebar" 
                icon="book"
            >
                Metadata Sidebar
            </PluginSidebarMoreMenuItem>
            <PluginSidebar 
                name="metadata-sidebar" 
                icon="book" 
                title="My Sidebar"
            >
                <PanelBody title="Book details" initialOpen={ true }>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_title }
                            label={ __( "Title" ) }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_author }
                            label={ __("Author", "textdomain") }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <TextControl 
                            value={ metaFields._meta_fields_book_publisher }
                            label={ __("Publisher", "textdomain") }
                            onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
                        />
                    </PanelRow>
                    <PanelRow>
                        <DateTimePicker
                            currentDate={ metaFields._meta_fields_book_date }
                            onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
                            __nextRemoveHelpButton
                            __nextRemoveResetButton
                        />
                    </PanelRow>
                </PanelBody>
            </PluginSidebar>
        </>
    )
}

L’étape finale est la composition du composant avec les composants d’ordre supérieur withSelect et withDispatch:

const applyWithSelect = withSelect( ( select ) => {
    return {
        metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
        postType: select( 'core/editor' ).getCurrentPostType()
    };
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
    return {
        setMetaFields ( newValue ) {
            dispatch('core/editor').editPost( { meta: newValue } )
        }
    }
} );

export default compose([
    applyWithSelect,
    applyWithDispatch
])(CustomSidebar);

Enregistrez vos modifications, puis vérifiez l’interface de l’éditeur. Si vous ouvrez le menu déroulant Options, vous verrez un nouvel élément Metadata Sidebar sous la section Extensions. En cliquant sur ce nouvel élément, vous activerez votre toute nouvelle colonne latérale personnalisée.

Le composant PluginSidebarMoreMenuItem ajoute un élément de menu sous Options - Extensions.
Le composant PluginSidebarMoreMenuItem ajoute un élément de menu sous Options – Extensions.

La même chose se produit lorsque vous cliquez sur l’icône de livre dans le coin supérieur droit.

La colonne latérale des réglages.
La colonne latérale des réglages.

Retournez maintenant sur votre site de développement, et créez un nouvel article de blog. Remplissez vos champs méta, puis ajoutez le bloc au canevas de l’éditeur. Il devrait inclure les mêmes valeurs méta que vous avez saisies dans votre colonne latérale personnalisée.

Enregistrez l’article et prévisualisez la page sur l’interface publique. Vous devriez voir votre fiche comprenant le titre du livre, l’auteur, l’éditeur et la date de publication.

Vous trouverez le code complet de cet article dans ce gist public.

Lectures supplémentaires

Dans cet article, nous avons abordé de nombreux sujets, des sélecteurs aux composants d’ordre supérieur et bien plus encore. Nous avons également mis en lien les principales ressources que nous avons utilisées comme référence tout au long de l’article.

Mais si vous souhaitez plonger plus profondément dans ces sujets, vous pouvez également consulter les ressources supplémentaires suivantes :

Documentation Gutenberg et ressources officielles de WordPress

Plus de ressources officielles

Ressources supplémentaires de la communauté

Lectures utiles du site Kinsta

Résumé

Dans ce troisième article de notre série sur le développement des blocs Gutenberg, nous avons abordé de nouveaux sujets avancés qui devraient rendre plus complet le tableau esquissé dans les articles précédents sur le développement des blocs dynamiques et statiques.

Vous devriez maintenant être en mesure de tirer parti du potentiel des champs personnalisés dans Gutenberg et de créer des sites web WordPress plus avancés et plus fonctionnels.

Mais ce n’est pas tout. Grâce aux compétences que vous avez acquises dans nos articles sur le développement de blocs, vous devriez également avoir une bonne idée de la façon de développer des composants React en dehors de WordPress. Après tout, Gutenberg est un SPA basé sur React.

Et maintenant, c’est à vous de jouer ! Avez-vous déjà créé des blocs Gutenberg qui utilisent des champs méta personnalisés ? Partagez vos créations avec nous dans les commentaires ci-dessous.

Carlo Daniele Kinsta

Carlo is a passionate lover of webdesign and front-end development. He has been playing with WordPress for more than 20 years, also in collaboration with Italian and European universities and educational institutions. He has written hundreds of articles and guides about WordPress, published both on Italian and international websites, as well as on printed magazines. You can find him on LinkedIn.