Intégrer une page d’options dans un plugin WordPress

Développer une page d’options pour sa propre extension WordPress peut s’avérer un vrai parcours du combattant, surtout si on essaie de réinventer la roue en utilisant uniquement l’API WordPress d’options.

Heureusement pour nous, de nombreuses librairies & plugins permettent de faciliter la création de ces pages : Redux Framework, ACF, Pods, CMB2… la liste est longue.

Attardons nous aujourd’hui sur Carbon Fields et apprenons à développer une page d’options modulaire pour notre plugin WordPress, pleine de hooks !

Une page d’options flexible pour plugin WordPress

Démonstration

Principe général

L’excellente librairie Carbon Fields est une vraie pépite d’or pour simplifier notre vie de développeur — comme ACF et d’autres ressources précieuses de l’écosystème WordPress.

Cette librairie open-source permet entre autre de :

• créer des groupes de champs remplis de champs complexes
• définir des conditions d’affichage de ces metaboxes
• les assigner à différentes entités WordPress pour sauvegarder des métadonnées de posts, de taxonomies, de commentaires, d’utilisateurs, de menus de navigation
• créer des blocs Gutenberg uniquement avec du PHP

Une autre précieuse fonctionnalité de Carbon Fields est de pouvoir créer des pages d’options en quelques lignes de code et profiter des multiples types de champs : WYSIWYG, upload d’image, champ relationnel, carte Google Maps, etc.

Plongeons dans le code !

L’intégralité du code détaillé ici est paqueté dans un plugin WordPress disponible sur GitHub. Il est décortiqué ci-dessous, étape par étape.

1. Inclure Carbon Fields, dépendance Composer

<?php
function load_carbonfields() {
	require_once plugin_dir_path( __FILE__ ) . '/vendor/autoload.php';
	\Carbon_Fields\Carbon_Fields::boot();
}
add_action( 'after_setup_theme', __NAMESPACE__ . '\\load_carbonfields' );

Après avoir exécuté la commande composer install à la racine de l’extension, la librairie Carbon Fields sera installée comme dépendance de notre projet.

Ce code permet :

1. d’inclure l’autoloader Composer pour charger cette dépendance,
2. d’initialiser Carbon Fields pour profiter de ses super-pouvoirs

2. Enregistrer une page d’options d’admin WordPress

<?php
function options_initialize_admin_page() {
	$tabs = apply_filters( 'msk_plugin_options_tabs', [] );
	
    if ( empty( $tabs ) ) {
		return;
	}
    
	$theme_options = Container::make( 'theme_options', __( 'Options du plugin', 'msk-plugin' ) );
	$theme_options->set_page_file( 'plugin-mosaika' );
	$theme_options->set_page_menu_title( __( 'Plugin Mosaika.fr', 'msk-plugin' ) );
	$theme_options->set_page_menu_position( 31 );
	$theme_options->set_icon( 'dashicons-palmtree' );
    
	foreach ( $tabs as $tab_slug => $tab_title ) {
		$theme_options->add_tab(
			esc_html( $tab_title ),
			apply_filters( "msk_plugin_options_fields_tab_{$tab_slug}", [] )
		);
	}
}
add_action( 'carbon_fields_register_fields', __NAMESPACE__ . '\\options_initialize_admin_page' );

Tout d’abord, il nous faut créer le « conteneur » de nos metaboxes et champs, à savoir notre page d’options. On l’enregistre grâce à Container::make( 'theme_options').

On en profite pour utiliser de nombreuses méthodes de cette classe Container pour :

• définir le slug de notre page
• changer son titre dans le menu d’admin
• modifier sa position dans le menu d’admin
• changer son icône Dashicons

Enfin, on boucle sur une variable $tabs afin d’enregistrer les onglets composant cette page d’options. Comme vous l’aurez remarqué en haut de fonction, cette variable n’est qu’un simple tableau vide pour l’instant, mais elle est rendue disponible globalement via un filtre.

On pourra ainsi la construire « ailleurs » dans les fonctions suivantes, simplifiant ainsi cette première fonction dont la seule responsabilité est d’enregistrer notre conteneur.

Cette même flexibilité — via un filtre — est utilisée dans notre boucle enregistrant les onglets de la page d’options : le filtre dynamique msk_plugin_options_fields_tab_{$tab_slug} va nous permettre d’enregistrer les champs de chaque onglet via d’autres fonctions.

Un mot sur les hooks et la modularité qu’ils offrent

En plus de séparer les responsabilités dans des fonctions distinctes (pour lister les onglets et pour lister les champs de chaque onglet), l’usage de filtres permet une modularité précieuse et appréciée des développeurs WordPress.

Car qui dit hook dit possibilité de modifier une logique et la personnaliser selon ses besoins grâce à du code additionnel ! En optant pour ces filtres, on offre la possibilité aux utilisateurs/dévs de notre plugin :

1. de modifier/supprimer des réglages de notre extension. C’est sans doute peu désiré mais peut parfois s’avérer utile (changer une tournure ou cacher un réglage pour certains utilisateurs novices par exemple)
2. d’ajouter des onglets et des champs via un code tiers. Très utile pour permettre à quiconque de développer des « add-ons » de votre plugin WordPress par exemple et ainsi charger son propre onglet avec ses propres champs dans NOTRE page d’options.

C’est ainsi que fonction en grande partie WooCommerce : une logique initiale « de base » est développée mais des actions et des filtres dûment placés dans le code source permettent de modifier ce comportement par défaut pour l’étendre via d’autres extensions ou du code sur-mesure.

3. Enregistrer les onglets de la page d’options

<?php
function options_set_tabs( $tabs ) {
	return [
		'general'  => __( 'Général', 'msk-plugin' ),
		'social'   => __( 'Réseaux sociaux', 'msk-plugin' ),
		'advanced' => __( 'Avancé', 'msk-plugin' ),
	];
}
add_filter( 'msk_plugin_options_tabs', __NAMESPACE__ . '\\options_set_tabs' );

Maintenant que notre page d’options est prête et que notre « code maître » initialise le tableau blanc, on va profiter des filtres à disposition pour peindre ce tableau.

La première chose à faire et de définir les onglets composant notre page d’options. On se hooke sur msk_plugin_options_tabs pour injecter un tableau d’onglets.

Chaque élément de ce tableau associatif indique :

• le « slug » (ou identifiant) de l’onglet, défini via la clé de l’élément
• le titre de l’onglet, défini via la valeur de l’élément

Notez bien l’importance de ce slug : il est utilisé dans notre filtre dynamique msk_plugin_options_fields_tab_{$tab_slug} et nous servira dans l’étape suivante pour définir les champs de chaque onglet.

4. Charger les champs de chaque onglet

<?php
function options_general_tab_theme_fields() {
	$fields = [];

	$fields[] = Field::make( 'rich_text', 'champ_riche', __( 'Champs WYSIWYG', 'msk-plugin' ) );
	$fields[] = Field::make( 'select', 'champ_select', __( 'Champs menu déroulant', 'msk-plugin' ) )
				->set_options( [
					'option1' => __( 'Option n°1', 'msk-plugin' ),
					'option2' => __( 'Option n°2', 'msk-plugin' ),
					'option3' => __( 'Option n°3', 'msk-plugin' ),
					'option4' => __( 'Option n°4', 'msk-plugin' ),
				] );
    
	return $fields;
}
add_filter( 'msk_plugin_options_fields_tab_general', __NAMESPACE__ . '\\options_general_tab_theme_fields', 10 );

Comme expliqué à l’instant, on injecte maintenant une logique sur notre filtre dynamique. Pourquoi dynamique ? Car la définition des champs d’un onglet de slug ABC se fera via le filtre msk_plugin_options_fields_tab_ABC !

On utilise cette fois Field::make pour ajouter des champs CarbonFields dans un onglet. La documentation officielle vous permettra de découvrir la variété de champs à disposition dans cette librairie. Son usage de base se fait comme suit :

• en premier paramètre, on indique le type de champ que l’on souhaite crééer
• en second paramètre, on définit l’identifiant de ce champ qui nous permettra de récupérer sa valeur plus tard
• en troisième paramètre, on indique le nom/titre affiché avant le champ

Dans notre exemple ci-dessus, on enregistre un champ WYSIWYG (rich_text) et un menu déroulant (select) pour peupler notre premier onglet « Général ».

Jetez un œil au plugin final sur GitHub pour voir tous les champs d’examples présentés dans chaque onglet et quelques options disponibles.

On peut notamment :

• indiquer qu’un champ est requis avec set_required(true)
• changer sa taille avec set_width(...)
• indiquer un texte explicatif du champ avec set_help_text()

Gardez le sens des priorités

Notez la priorité à 10 lors de notre fonction options_general_tab_theme_fields. En indiquant une telle priorité, on offre à d’autres développeurs la possibilité d’injecter d’autres champs via le hook msk_plugin_options_fields_tab_general à l’endroit où ils le souhaitent :

• avant nos champs enregistrés ci-dessus s’ils injectent leur propre fonction avec une priorité inférieure à 10
• après nos champs enregistrés s’ils injectent leur propre fonction avec une priorité supérieure à 10

5. Inclure du contenu promotionnel dans la barre latérale

Et voila ! Nous venons de créer une belle page d’options pour notre extension WordPress, et ce sans s’être embêté avec la Settings API native de WordPress.

Pour couronner le tout, voyons comment ajouter un contenu additionnel dans la sidebar de cette page pour, par exemple, faire la promotion de la version premium du plugin ou proposer des liens vers la documentation.

<?php
function display_content_after_sidebar() {
	?>
	<h3>Coucou, je suis un contenu extra !</h3>
	<?php
}
add_action( 'carbon_fields_container_options_du_plugin_after_sidebar', __NAMESPACE__ . '\\display_content_after_sidebar' );

Sur cette page d’admin présentant nos réglages, Carbon Fields offre plusieurs hooks intéressants :

• carbon_fields_container_{$id}_before_fields pour afficher du contenu avant l’affichage des champs de CF
• carbon_fields_container_{$id}_after_fields pour afficher du contenu après l’affichage des champs de CF
• carbon_fields_container_{$id}_before_sidebar pour afficher du contenu dans la sidebar avant la boîte d’enregistrement de CF
• carbon_fields_container_{$id}_after_sidebar pour afficher du contenu dans la sidebar après la boîte d’enregistrement de CF

C’est cette dernière action que nous utilisons ici afin d’inclure du contenu additionnel en bas de sidebar. Avec un peu de HTML et de CSS, on peut par exemple afficher une boîte pour promouvoir la version premium de notre plugin WordPress et ce directement via la page de réglages de ce dernier.

6. Récupérer et utiliser la valeur d’un réglage

<?php
$value = carbon_get_theme_option( 'champ_riche' );
echo wp_kses_post( $value );

Enfin, quel intérêt d’offrir une page d’options si on ne peut pas se servir des réglages définis par l’utilisateur ailleurs dans notre plugin ?

Manipuler ces valeurs se fait via l’utilisation de la fonction carbon_get_theme_option() en passant en paramètre l’identifiant du champ concerné. Simple comme bonjour !

Conclusion

J’espère que cet article vous aura fait apprécier l’usage de Carbon Fields comme librairie pour facilement développer une page d’options dans votre extension WordPress.

Cet article aura également tenté de présenter une logique de développement WordPress évolutive et modulable grâce à un fin usage de hooks. Essayez de garder cette flexibilité à l’esprit lorsque vous codez : vous et vos utilisateurs vous remercieront à l’avenir !