Créer une page d'options d'administration avec l'API Settings

Ajouter une page de réglages dans l'administration est un besoin qui revient sur presque tout projet sur mesure : coordonnées à afficher, clé d'un service externe, activation d'une fonction, textes personnalisables. La tentation consiste à écrire un formulaire, à le traiter à la main et à enregistrer les valeurs. Cela fonctionne, et cela laisse passer les saisies non contrôlées, les soumissions falsifiées et les accès non autorisés. WordPress fournit une interface dédiée qui prend en charge l'enregistrement, la vérification du jeton, l'affichage des messages et la validation, pour un coût d'apprentissage d'une heure.

Ce que l'interface prend en charge

Comprendre ce que l'on gagne à employer le mécanisme prévu évite de le percevoir comme une complication inutile. Une page écrite à la main demande d'écrire soi même chaque garantie, et l'expérience montre qu'au moins l'une d'elles manque toujours. Les réglages natifs de l'administration reposent d'ailleurs sur cette même interface, comme nous le décrivons dans notre article sur le fonctionnement de l'onglet réglages dans WordPress.

Le traitement de la soumission

Le formulaire est envoyé vers un point d'entrée du cœur qui reconnaît le groupe de réglages déclaré et enregistre les champs correspondants. Aucun code de traitement n'est à écrire : la déclaration suffit. Cette prise en charge supprime d'un coup toute une famille d'erreurs, notamment les enregistrements partiels et les valeurs écrasées par mégarde. C'est le bénéfice le plus immédiat de l'approche. Il devient particulièrement sensible sur une page comportant une dizaine de champs, où le traitement manuel représenterait déjà plusieurs dizaines de lignes à maintenir.

Le jeton de sécurité

Le champ de vérification anti falsification est généré et contrôlé automatiquement. Sans lui, un tiers peut faire soumettre le formulaire depuis un autre site à un administrateur connecté, ce qui modifie les réglages à son insu. Cette faille est présente sur la quasi totalité des pages d'options écrites à la main. L'interface la ferme sans que le développeur ait à y penser, ce qui est exactement le rôle d'un cadre. C'est aussi l'argument le plus convaincant à avancer auprès d'un développeur réticent à changer ses habitudes.

La vérification des droits

Le point d'entrée contrôle que l'utilisateur dispose de la capacité requise pour modifier les réglages concernés. Cette capacité est déclarée à l'enregistrement de la page et elle doit être choisie avec soin. Retirer une entrée de menu ne protège rien, seule la vérification de capacité constitue un contrôle réel. Ce point mérite d'être rappelé, tant la confusion entre visibilité et droit est répandue. La capacité par défaut convient à la plupart des cas et elle mérite d'être réexaminée dès qu'un rôle intermédiaire doit accéder à la page.

Les messages de retour

Les messages de succès et d'erreur s'affichent selon la convention de l'administration, sans travail supplémentaire. Une fonction permet d'ajouter ses propres messages depuis la fonction de validation, ce qui donne un retour précis à l'utilisateur. Cette cohérence visuelle compte plus qu'on ne le croit : un message affiché à un autre endroit ou dans un autre style passe inaperçu. Les utilisateurs cherchent le retour à l'endroit habituel et concluent que rien ne s'est passé lorsqu'ils ne l'y trouvent pas.

La validation centralisée

Chaque option déclarée peut porter une fonction de validation appelée avant l'enregistrement. C'est le point d'entrée unique où contrôler et transformer la valeur, ce qui garantit qu'aucun chemin d'écriture ne le contourne. Cette centralisation est ce qui distingue une page fiable d'une page dont la validation dépend du formulaire employé. Elle vaut également lorsque la valeur est modifiée par un import ou par une ligne de commande. C'est précisément ce qui distingue une validation attachée à l'option d'une validation attachée au formulaire.

Ce qu'elle ne fait pas

L'interface ne construit pas l'affichage des champs, qui reste entièrement à la charge du développeur. Elle n'impose aucune structure de données et elle ne gère pas les réglages multi sites. Ces limites sont connues et elles n'enlèvent rien à son intérêt. Il faut simplement ne pas s'attendre à un générateur de formulaires, ce qui déçoit parfois au premier usage. Cette déception se dissipe dès que l'on a écrit sa propre fonction générique d'affichage de champ.

Construire la page pas à pas

La construction suit toujours le même enchaînement, qui tient en quatre appels de fonctions accrochés à deux actions distinctes.

Déclarer la page de menu

Une fonction ajoute une page sous un menu existant ou crée un menu de premier niveau, en précisant le titre, la capacité requise, l'identifiant de page et la fonction d'affichage. Placer la page sous le menu des réglages convient à la plupart des besoins et évite d'encombrer le menu principal. Créer une entrée de premier niveau se justifie lorsque le projet comporte plusieurs pages liées. Ce choix relève de l'ergonomie et il mérite une minute de réflexion. Un menu de premier niveau créé pour trois réglages encombre l'administration et agace les personnes qui l'utilisent quotidiennement.

Enregistrer les options

Chaque option est déclarée avec son groupe, son nom et ses arguments, dont la fonction de validation et la valeur par défaut. Le groupe rassemble les options d'une même page et il est ce que le formulaire déclare au moment de la soumission. Employer un préfixe propre au projet dans les noms d'options évite les collisions avec d'autres extensions. Cette convention paraît anodine et elle évite des conflits difficiles à diagnostiquer. Deux extensions déclarant une option portant le même nom se contredisent silencieusement, sans qu'aucune erreur n'apparaisse.

Déclarer les sections

Une section regroupe des champs sous un titre et une description facultative. Elle structure visuellement la page et elle permet de séparer les réglages par thème. Deux ou trois sections suffisent sur une page ordinaire, au delà il vaut mieux envisager des onglets ou plusieurs pages. Une page de réglages comportant quarante champs sans regroupement est inutilisable en pratique. La description de section est par ailleurs l'endroit idéal pour expliquer à quoi sert l'ensemble du bloc.

Déclarer les champs

Chaque champ est associé à une section et à une fonction produisant son affichage. Cette fonction écrit le balisage du champ, avec sa valeur courante lue depuis l'option correspondante. C'est la partie la plus verbeuse du travail et elle se factorise facilement, une fonction générique prenant le type et le nom en paramètres suffisant pour la plupart des cas. Ce petit investissement paie dès la troisième page construite. Prévoir quelques types courants, texte, nombre, case à cocher, liste et zone de texte, couvre la quasi totalité des besoins rencontrés.

Afficher le formulaire

La fonction d'affichage de la page ouvre un formulaire pointant vers le point d'entrée du cœur, appelle les fonctions produisant les champs cachés du groupe, puis celles produisant les sections et les champs, et termine par le bouton d'envoi. Ces quatre appels tiennent en dix lignes. La structure est toujours la même, ce qui rend la page très rapide à écrire une fois le mécanisme compris. Conserver un modèle de page dans ses notes ramène la construction à un copier coller suivi de quelques adaptations.

Accrocher au bon moment

L'ajout de la page de menu et l'enregistrement des réglages se font sur deux actions différentes, la première lors de la construction du menu et la seconde lors de l'initialisation de l'administration. Se tromper d'accroche produit une page qui s'affiche sans enregistrer, ou l'inverse. Le symptôme est reconnaissable : le formulaire s'affiche correctement et le bouton d'envoi renvoie une page d'erreur. C'est l'erreur de débutant la plus fréquente sur ce sujet, et les mécanismes concernés sont détaillés dans notre article sur les actions dans WordPress et le développement avec les hooks.

Valider les saisies correctement

C'est la partie qui distingue une page correcte d'une page dangereuse, et celle qui demande le plus d'attention.

Ne jamais faire confiance à la saisie

Un utilisateur disposant du droit de modifier les réglages reste un utilisateur dont le compte peut être compromis. Une valeur enregistrée sans contrôle et affichée ensuite sur le site public constitue un vecteur d'injection classique. La règle vaut donc y compris dans l'administration, contrairement à ce que l'on entend parfois. Une valeur enregistrée aujourd'hui peut être affichée pendant des années sur des milliers de pages. Ce principe est développé dans notre article sur la validation côté serveur sans bibliothèque.

Choisir la fonction adaptée au type

Le cœur fournit des fonctions de nettoyage par type de donnée : texte simple, adresse électronique, adresse web, entier, clé. Employer celle qui correspond au champ plutôt qu'une fonction générique produit une validation plus stricte et plus lisible. Un champ censé contenir un nombre doit être converti en nombre, pas simplement nettoyé de ses balises. Cette rigueur évite qu'une valeur inattendue ne provoque un comportement étrange en aval. Elle rend aussi le code plus lisible, la fonction employée documentant à elle seule le type attendu.

Contrôler les valeurs admissibles

Une liste déroulante n'empêche pas l'envoi d'une valeur absente de la liste, le formulaire pouvant être modifié côté navigateur. La fonction de validation doit vérifier que la valeur reçue appartient bien à l'ensemble attendu et retomber sur la valeur par défaut sinon. Ce contrôle tient en une ligne et il est presque toujours omis. Il vaut pour toutes les listes, cases à cocher et boutons radio. Une simple vérification d'appartenance à un tableau de valeurs admises suffit et elle se factorise facilement.

Le cas du HTML autorisé

Un champ destiné à recevoir du texte enrichi ne peut pas être nettoyé comme du texte simple, sous peine de perdre la mise en forme. Une fonction dédiée permet de filtrer selon une liste blanche de balises et d'attributs autorisés. Définir cette liste explicitement, plutôt que d'employer la liste par défaut, donne un contrôle précis sur ce qui est accepté. C'est le seul cas où l'échappement à l'affichage ne suffit pas. Il faut aussi se demander si le besoin de texte enrichi est réel, un champ de texte simple couvrant la majorité des usages.

Renvoyer un message utile

Une valeur rejetée doit produire un message expliquant ce qui n'allait pas, et non un enregistrement silencieux de la valeur précédente. Une fonction permet d'ajouter ce message depuis la validation, où il s'affichera avec les autres retours. Cette attention à l'utilisateur est ce qui distingue une page agréable d'une page frustrante. Elle coûte deux lignes par champ. Le message doit indiquer ce qui est attendu plutôt que constater l'erreur, ce qui permet à l'utilisateur de corriger du premier coup. Préciser le format attendu, avec un exemple, réduit à presque rien le nombre de tentatives infructueuses.

Échapper aussi à l'affichage

La validation à l'enregistrement ne dispense pas de l'échappement au moment de l'affichage, sur la page de réglages comme sur le site public. Les deux protections sont complémentaires : la première contrôle ce qui entre, la seconde protège contre ce qui aurait pu entrer par un autre chemin. Une valeur modifiée directement en base, par un script ou par une importation, n'a jamais traversé la validation. C'est la raison pour laquelle l'échappement à l'affichage reste la règle absolue. Elle ne coûte rien et elle protège contre des chemins d'écriture que personne n'avait anticipés.

Aller plus loin proprement

Quelques pratiques rendent la page maintenable et évitent les difficultés qui apparaissent au bout de deux ans.

Regrouper les options en un tableau

Enregistrer une option unique contenant un tableau de valeurs, plutôt qu'une option par champ, réduit le nombre d'enregistrements en base et simplifie la lecture. Cette approche demande une validation traitant le tableau entier, ce qui est parfaitement supporté. Elle est préférable dès que la page compte plus de cinq champs. Le gain devient sensible au chargement, une seule lecture remplaçant plusieurs. Il facilite également l'export et l'import des réglages, l'ensemble tenant dans une seule valeur.

Prévoir des valeurs par défaut

Une option jamais enregistrée n'existe pas en base, et sa lecture renvoie une valeur vide ou fausse selon la fonction employée. Déclarer une valeur par défaut à l'enregistrement de l'option, et la passer également à la lecture, évite les comportements erratiques avant la première sauvegarde. Ce détail est source de nombreux signalements de bogues inexistants. Il se règle une fois pour toutes. Le passage de la valeur par défaut à la lecture est le point le plus souvent oublié, la déclaration seule ne suffisant pas dans tous les contextes.

Gérer les onglets

Au delà d'une dizaine de champs, des onglets améliorent nettement la lisibilité. Ils s'obtiennent en déclarant plusieurs groupes de réglages et en affichant les sections correspondantes selon un paramètre d'adresse. La construction reste simple et elle demande un peu de rigueur dans le nommage. Chaque onglet doit disposer de son propre groupe, faute de quoi la soumission d'un onglet efface les valeurs des autres. Cette organisation vaut mieux que de multiplier les pages de menu. Elle conserve une adresse unique pour l'ensemble des réglages, ce qui simplifie la documentation destinée au client.

Documenter chaque champ

La description accompagnant un champ est lue par la personne qui l'utilisera, souvent des mois après sa création. Y indiquer à quoi sert la valeur, où elle s'affiche et quel format est attendu supprime la majorité des questions. Cette description se déclare avec le champ et elle coûte une phrase. Son absence transforme chaque réglage en devinette. Un champ intitulé identifiant sans autre précision provoquera systématiquement une question, six mois plus tard.

Prévoir la désinstallation

Les options enregistrées survivent à la désactivation de l'extension qui les a créées, ce qui laisse des résidus en base. Un fichier de désinstallation supprimant les options du projet, exécuté lors de la suppression, referme proprement le cycle. Cette attention est appréciée et elle est rarement présente sur les développements sur mesure. Elle mérite d'être proposée systématiquement lorsque le code est livré sous forme d'extension, puisqu'elle ne coûte que quelques lignes.

Ne pas réinventer l'existant

Beaucoup de besoins se traitent avec les réglages natifs plutôt qu'avec une page dédiée : coordonnées du site, options de lecture, format des dates. Vérifier ce que le cœur propose déjà avant de construire évite du code inutile. Une page de réglages est justifiée par des valeurs propres au projet, jamais par la reproduction de ce qui existe. Cette question mérite d'être posée avant d'écrire la première ligne. Elle conduit régulièrement à réduire de moitié le nombre de champs initialement prévus, ce qui simplifie autant le développement que l'usage. La méthode consiste à demander, pour chaque champ envisagé, qui le modifiera et à quelle fréquence, deux questions dont l'absence de réponse claire justifie presque toujours de retirer le champ.