Créer une page de réglage pour une extension WordPress

Je poursuis le travail sur la création d’une extension « best practice » généré dans l’article précédent (Créer une extension WordPress ; Partie 1) de cette série. Une extension sur laquelle le webmaster ne peut pas intervenir n’est pas très intéressante puisqu’elle oblige à modifier le code à chaque fois qu’un paramètre change. J’explore donc ici la manière de créer une page de réglage pour l’extension. J’utilise l’API « settings » de WordPress car c’est une méthode plus sûre (la « sanitation » des données est assurée par WordPress).

Mes sources d’information

L’extension au départ

L’extension est au stade où je l’ai laissée dans le premier article de cette série :

Premier essai

J’ai fait plusieurs essais avant celui-ci mais à chaque fois j’avais un « petit » problème dont je n’arrivais pas trouver la solution. Je préfère donc repartir de zéro pour comprendre. J’ai tout simplement copié le contenu du « gist » de Anna et je l’ai placé dans un fichier «  clea-add-button-settings-page.php  » du répertoire /admin. Dans le fichier principal de l’extension (clea-add-button.php), j’ai ajouté la ligne require_once CLEA_ADD_BUTTON_DIR_PATH . 'admin/clea-add-button-settings-page.php';  et j’ai rechargé la fenêtre de mon navigateur.

Une page de réglage « My Plugin Options » apparaît sous « réglages » (la copie d’écran correspond à ce qui est affiché une fois que j’ai enregistré une première fois des données) :

Essai 1 de page de réglage d'une extension
Essai 1 de page de réglage d’une extension

Et dans la base de données, la table « prefix-options » contient une nouvelle ligne (option_name = my-plugin-settings), qui contient :

C’est donc exactement ce que je cherche à faire. Reste maintenant à le faire mieux !

Qu’est-ce que je veux faire ?

Je veux obtenir une page de réglage avec plusieurs sections et des champs qui pourraient être présentés sous forme de texte court, de texte long (textarea), de cases à cocher (radio ou checkbox), de liste déroulante, d’un éditeur wysiwig pour des textes sophistiqués et d’un sélecteur de couleur (color picker).

Je voudrais aussi pouvoir définir les sections et les champs dans des « arrays » (tableaux) et générer automatiquement la page de réglages.

Enfin, je voudrais qu’une case à cocher permette d’afficher des éléments de débogage à la fin de la page de réglages si je le souhaite.

Etape 1 : générer automatiquement l’exemple ci-dessus

Je vais modifier le gist de Anna pour générer automatiquement sa page de réglages avec moins de code.

Respecter les bonnes pratiques :

La première chose que je fais, c’est de remplacer ‘textdomain’ par ‘clea-add-button’ et de mettre un préfixe  clea_add_button_ devant toutes les fonctions.

regrouper la définition des sections et champs, automatiser la génération

J’ai regroupé la définition des sections à la fin, dans la fonction clea_add_button_settings_sections_val() . Idem pour la définition des champs, dans la fonction clea_add_button_settings_sections_val() .

Ainsi la fonction clea_add_button_admin_init()  ne contient plus qu’une boucle « foreach », qui lit les arrays de sections ou champs à générer et les génère.

Ajouter d’autres arguments pour les champs

Il faut que j’ajoute des arguments à chaque champs :

  • ‘type’ : dans l’exemple dont je pars, tous les champs sont des textes courts. Comme je ne veux pas avoir autant de fonctions que de champs pour les afficher, il faut que le programme sache quel est le type du champs pour savoir comment le restituer.
  • ‘helper’ : un texte qui aidera l’utilisateur à comprendre comment faire son réglage.
  • ‘default’ : qui permettra de définir une valeur si l’utilisateur n’en définit pas.

Chaque champs doit pouvoir être défini par un array contenant les 5 éléments obligatoires et les trois nouveaux.

Je me suis inspirée de cet article de Smashing Magazine pour faire ça.

Dans la fonction qui génère les champs, j’ajoute une dernière valeur qui correspondra à $args, le 6ème élément de la fonction add_settings_field.

Et dans la fonction field_1_1_callback() , j’ajoute $argument comme élément reçu, ainsi que l’affichage du contenu de cette variable (c’est un array, j’utilise print_r)  :

Et ça fonctionne !

Page de réglage d'une extension WordPress : affichage des arguments de add_settings_field
Page de réglage d’une extension WordPress : affichage des arguments de add_settings_field

Regrouper les fonctions « callback » pour les sections

Il n’y a pas beaucoup de sections en général mais ce n’est pas la peine de créer autant de fonctions que de sections.

Je crée donc une fonction clea_add_button_settings_section_callback( $args )  (que je n’oublie pas de déclarer comme ‘section_callbk’ dans la définition des sections) :

Et mes sections s’affichent correctement.

Regrouper les fonctions « callback » pour les champs

Je vais faire la même chose maintenant pour les champs, en remplaçant les 4 fonctions correspondant aux 4 champs par une seule.

En faisant afficher l’array des arguments transmis à la fonction « callback » des champs, j’ai vu que cet array est composé comme suit :

une fonction « callback » pour les champs définis actuellement (des textes) contient les 4 lignes suivantes :

Il va falloir que je remplace tout ce qui est spécifique au champs 1-1 par des variables, pour que ça s’applique à tous les champs :

Cette ligne va chercher la valeur enregistrée pour toutes les options d’un nom défini lorsque nous avons exécuté la commande ‘register_setting’, au début de la fonction clea_add_button_admin_init() . C’est une valeur fixe que je laisse telle quelle pour l’instant (ce n’est certainement pas une bonne idée de laisser un nom si générique, sans préfixe spécifique).

Là on voit que « field_1_1 » correspond au contenu de $args[field_id].

Cette ligne lit la valeur attribuée à l’option et la met dans la variable « value ». On ne la change pas puisque $field n’est plus fixe.

Ne change pas non plus. Ma fonction clea_add_button_settings_field_callback( $args  ) va donc contenir quasiment la même chose qu’avant mais elle sera utilisable par tous les champs :

Maintenant je supprime les 4 fonctions callback des 4 champs définis et dans la définition des champs, je remplace le contenu de ‘field_callbk’ par le nom de la fonction collective.

J’obtiens bien l’affichage de mon formulaire, mais pas des valeurs déjà enregistrées. Et il y a 4 PHP notices. La première notification signale Undefined index: field-1-1  en ligne 128 de clea-add-button-settings-page.php. Les trois autres sont identiques et portent sur les 3 autres champs.

C’est en fait « normal » : je me suis trompée en définissant l’array des champs. J’ai mis des id de type ‘field-1-1’ alors que Anna, l’auteure du Gist dont je m’inspire utilisais field_1_1… Il m’a suffi d’enregistrer une valeur pour que tout rentre dans l’ordre.

Et voilà, j’obtiens exactement le même résultat qu’Anna mais même si j’ajoute des dizaines de paramètres, les fonctions qui les restituent resteront uniques. C’est plus « élégant », mais surtout ça réduit fortement le risque d’erreur si j’ajoute un nouveau paramètre car le code est beaucoup plus lisible.

le fichier ‘clea-add-button-settings-page.php’ (le seul modifié) est dans ce « commit », sur github. Vous pouvez également récupérer l’extension à ce stade dans ce fichier zip : clea-add-button V0.1 (zip).

Et maintenant ?

Dans des articles à venir, il faudra voir comment ajouter d’autres types de champs, comment charger des feuilles de style, comment faire utiliser un template de l’extension…

Mais d’abord, il faut voir comment on peut plus facilement déboguer. C’est l’objet du prochain article de cette série [the-series).

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *