add_settings_field()

Définition : add_settings_field() déclare un champ dans une section de réglages WordPress. Son callback produit le contrôle HTML correspondant, tandis que la Settings API organise l’affichage et l’intégration du formulaire.

Terminologie

Terme officiel : add_settings_field()

Autres appellations : Champ de réglages

À quoi cela sert

Elle permet de relier une option WordPress à un champ accessible dans une page d’administration. Le développeur conserve la maîtrise du HTML du contrôle, mais bénéficie de l’organisation native en sections et tableaux.

Comment cela fonctionne

La fonction reçoit l’identifiant du champ, son titre, un callback de rendu, la page et l’identifiant de section. Elle n’enregistre pas la valeur toute seule : register_setting() doit couvrir l’option sauvegardée.

Dans quel contexte l’utiliser

À utiliser lorsqu’une option doit être modifiée depuis une page de réglages, avec un libellé clair et un affichage cohérent.

Exemple concret

Un plugin ajoute un champ de titre à une section déjà enregistrée sous le nom atoolpha_presentation.

Exemple de code commenté

<?php
add_action( 'admin_init', function () {
    add_settings_field(
        'atoolpha_demo_titre', 'Titre public',
        function () {
            $v = (string) get_option( 'atoolpha_demo_titre', '' );
            echo '<input type="text" name="atoolpha_demo_titre" value="' .
                esc_attr( $v ) . '">';
        },
        'atoolpha-demo-page', 'atoolpha_presentation'
    );
} );
// Prérequis : section et option déclarées ailleurs.

Explication pas à pas de l’exemple

Le champ lit la valeur existante puis l’insère dans value avec esc_attr(), adapté au contexte d’attribut HTML. La section et le paramètre doivent déjà être déclarés dans le même système de réglages.

Résultat attendu

La page peut afficher un champ de saisie prérempli. Son enregistrement dépend d’un formulaire Settings API complet et de register_setting().

Précautions et limites

Il faut ajouter une association label/for adaptée à l’accessibilité dans un formulaire final. Ne pas croire que le seul appel add_settings_field() suffit à sauvegarder la valeur.