⌨️ Come aggiungere la tua sezione alla pagina delle impostazioni di WordPress

Standard WordPress le pagine delle impostazioni, «Generale», «Lettura», «Discussione», coprono le esigenze di base di un sito. Ma appena scrivi un plugin o personalizzi un tema per un cliente, il set di campi predefinito non basta più. Ti serve un blocco con le tue opzioni: una chiave API, il testo del footer, un toggle per una modalità.

Creare una pagina di amministrazione separata per soli due campi è sproporzionato. È molto più pulito aggiungere una propria sezione a una pagina delle impostazioni esistente, proprio dove si trovano le opzioni standard di WordPress. L'API delle Impostazioni mette a disposizione un'unica funzione per questo: add_settings_section.

Vediamone sintassi, parametri e costruiamo un esempio funzionante con una sezione e un campo, dall'hook admin_init fino all'output nel pannello di amministrazione. Nessuna astrazione superflua: solo ciò che puoi copiare ed eseguire in autonomia.

💡 Panoramica rapida:

• Definisci la pagina di destinazione (generale, lettura, scrittura, discussione, media o una personalizzata), ti servirà il suo slug nel quarto parametro
• Registra la sezione con add_settings_section() sull'hook admin_init: fornisci un ID, un titolo e una callback per il testo descrittivo
• Collega i campi alla sezione con add_settings_field() e salva l'opzione stessa con register_setting()
• Chiama do_settings_sections() nella callback della pagina per le pagine personalizzate, la sezione verrà renderizzata automaticamente

Cos'è l'API delle Impostazioni e perché ti serve

L'API delle Impostazioni è comparsa in WordPress 2.7 ed è rimasta da allora il metodo standard per aggiungere impostazioni al pannello di amministrazione. L'idea è semplice: invece di produrre manualmente un <form> e gestire $_POST, descrivi sezioni e campi tramite funzioni, e WordPress stesso renderizza il markup, gestisce il salvataggio e verifica il nonce.

I tre pilastri dell'API delle Impostazioni:

• register_setting(), registra un'opzione in wp_options;
• add_settings_section(), crea un blocco (sezione) con un titolo;
• add_settings_field(), aggiunge un campo specifico a una sezione.

È add_settings_section la responsabile del "contenitore", il blocco visivo che raggruppa più campi sotto un'intestazione comune nella pagina delle impostazioni. Senza di essa, semplicemente non c'è dove collocare i campi.

Sintassi di add_settings_section

La firma della funzione è concisa, quattro parametri obbligatori e un array opzionale:

1
add_settings_section(
2
    string $id,
3
    string $title,
4
    callable $callback,
5
    string $page,
6
    array  $args = array()
7
);

La funzione non restituisce nulla. Registra la sezione nell'array globale $wp_settings_sections, da cui WordPress la recupera quando do_settings_sections() viene chiamato sulla pagina di destinazione. Se chiami add_settings_section senza un successivo do_settings_sections su una pagina personalizzata, la sezione silenziosamente non viene renderizzata.

Una sfumatura importante: add_settings_section descrive solo il blocco. I campi stessi vengono aggiunti da chiamate separate a add_settings_field, specificando l'ID della sezione nel quinto parametro. Senza campi, la sezione resta un involucro vuoto, cosa a volte utile per una spiegazione testuale, ma nella pratica almeno un campo viene quasi sempre affiancato.

Parametri della funzione, cosa passare

$id (stringa, obbligatorio), lo slug univoco della sezione. Usa lettere minuscole, numeri e underscore: my_plugin_main_section. Specificherai questo stesso ID in add_settings_field per "agganciare" il campo alla sezione, e compare anche nell'attributo HTML id del tag contenitore.

$title (stringa, obbligatorio), il titolo della sezione che vede l'amministratore. Viene emesso come <h2> all'interno della pagina delle impostazioni. Scrivilo in linguaggio chiaro per l'amministratore: «Настройки интеграции с CRM», non my_plugin_crm_settings.

$callback (callable, obbligatorio), il nome della funzione che emette il testo descrittivo tra il titolo della sezione e i campi. Firma: function my_callback($args), dove $args è un array con le chiavi id, title e callback. Se non serve alcuna spiegazione, passa '__return_false'.

$page (stringa, obbligatorio), lo slug della pagina delle impostazioni in cui aggiungere la sezione. Pagine native di WordPress: general, reading, writing, discussion, media. Per una pagina personalizzata, lo slug passato a add_options_page(). ⚠ Le pagine misc e privacy sono state rimosse dal core (deprecate), WordPress reindirizzerà automaticamente misc → general, privacy → reading, ma è meglio non fare affidamento su questo comportamento.

$args (array, opzionale, da WordPress 6.1.0), un array per personalizzare il contenitore HTML della sezione:

L'argomento $args funziona solo quando viene chiamato do_settings_sections(). Se per errore si usa do_settings_fields(), l'array viene ignorato e before_section/after_section silenziosamente non hanno effetto.

Esempio pratico: una sezione con un campo nella pagina «Generale»

Mettiamo insieme uno snippet pronto all'uso per functions.php o per il tuo plugin. Il codice aggiunge una sezione «Impostazioni sito vetrina» alla pagina options-general.php con un campo di testo, ad esempio per un numero di telefono nel footer.

1
/**
2
 * Adds a custom section and field to the «General» page.
3
 */
4
function sdstudio_add_visiting_card_section() {
5
    // 1. Section
6
    add_settings_section(
7
        'visiting_card_section',               // Section ID
8
        'Visiting Card Settings',             // Title
9
        'sdstudio_visiting_card_section_cb',   // Callback explanation
10
        'general',                             // «General» page
11
        array(
12
            'before_section' => '<div class="visiting-card-wrapper">',
13
            'after_section'  => '</div>',
14
        )
15
    );
16
 
17
    // 2. Field
18
    add_settings_field(
19
        'footer_phone',                        // Field ID
20
        'Footer Phone Number',                    // Label
21
        'sdstudio_footer_phone_field_cb',      // Callback — renders <input>
22
        'general',                             // Same page
23
        'visiting_card_section'                // Which section to attach to
24
    );
25
 
26
    // 3. Registering the option
27
    register_setting( 'general', 'footer_phone' );
28
}
29
add_action( 'admin_init', 'sdstudio_add_visiting_card_section' );
30
 
31
/**
32
 * Explanatory text above the section fields.
33
 */
34
function sdstudio_visiting_card_section_cb( $args ) {
35
    ?>
36
    <p id="<?php echo esc_attr( $args['id'] ); ?>">
37
        Contact details displayed in the site footer.
38
    </p>
39
    <?php
40
}
41
 
42
/**
43
 * Renders a text input field.
44
 */
45
function sdstudio_footer_phone_field_cb() {
46
    $value = get_option( 'footer_phone', '' );
47
    printf(
48
        '<input type="text" id="footer_phone" name="footer_phone" value="%s" class="regular-text" />',
49
        esc_attr( $value )
50
    );
51
}

Dopo aver aggiunto il codice, vai nel pannello di amministrazione: Impostazioni → Generale, e sotto i campi standard vedrai la sezione «Impostazioni sito vetrina» con il campo «Telefono footer». Salva la pagina e il valore verrà scritto in wp_options.

Il codice va inserito nel functions.php del tema attivo o, più correttamente, in un plugin separato. Un plugin sopravvive a un cambio di tema, mentre functions.php no. Se la sezione serve solo quando un tema specifico è attivo, functions.php è accettabile; in tutti gli altri casi, solo un plugin.

L'argomento $args: cosa è cambiato in WordPress 6.1

Prima della versione 6.1, add_settings_section aveva esattamente quattro parametri e bisognava "ritoccare" il contenitore della sezione via CSS tramite ID, oppure intervenire sul buffer di output. A partire dalla 6.1, è stato aggiunto un quinto parametro $args, e ora l'incorniciatura HTML si imposta direttamente alla registrazione della sezione:

• before_section, un div contenitore o un banner esplicativo PRIMA del contenuto;
• after_section, un tag di chiusura o un suggerimento DOPO il contenuto;
• section_class, una classe personalizzata se la classe standard form-table non basta.

Un esempio con banner esplicativo e classe personalizzata:

1
add_settings_section(
2
    'api_keys_section',
3
    'API Keys',
4
    'sdstudio_api_keys_section_cb',
5
    'general',
6
    array(
7
        'before_section' => '<div class="notice notice-info inline"><p>Store keys in wp-config.php, override here only.</p></div>',
8
        'after_section'  => '',
9
        'section_class'  => 'api-keys-section',
10
    )
11
);

Cosa è importante ricordare: after_section non viene emesso se la sezione è vuota, cioè quando al suo interno non ci sono campi registrati. Se conti su un </div> di chiusura, assicurati che almeno un campo sia aggiunto tramite add_settings_field. E soprattutto: usa do_settings_sections(), non do_settings_fields(), perché quest'ultima ignorerà completamente $args.

Prima di usare before_section / after_section, verifica la versione di WordPress, su siti precedenti alla 6.1 passare il quinto parametro causerà un errore fatale. Un approccio sicuro: avvolgi la chiamata in un controllo global $wp_version o usa function_exists per verificare la presenza degli hook.

⁉️🤔 Domande frequenti

Posso saltare add_settings_section e aggiungere i campi direttamente?

Formalmente no. I campi si registrano con add_settings_field() e il quinto parametro di questa funzione richiede un ID di sezione. Se la sezione non esiste, il campo non verrà renderizzato. Per un campo singolo, puoi creare una sezione con titolo vuoto e callback '__return_false', la sezione sarà invisibile e il campo funzionerà.

Qual è la differenza tra add_settings_section e add_settings_field?

Una sezione è un contenitore con titolo e testo descrittivo. Un campo è un elemento di input specifico (input, select, checkbox) all'interno di una sezione. Una sezione può contenere un numero qualsiasi di campi, tutti raggruppati sotto un'unica intestazione e salvati con un solo clic del pulsante «Salva».

Cosa succede se specifico uno slug di pagina inesistente in $page?

La sezione verrà registrata in $wp_settings_sections ma non sarà mai renderizzata, perché WordPress non sa su quale pagina emetterla. Non ci sarà alcun errore, la sezione resterà semplicemente "sospesa nel vuoto". Verifica lo slug: per le pagine native è general / reading / writing / discussion / media; per quelle personalizzate, lo slug esatto di add_menu_page o add_options_page.

Posso aggiungere una sezione alla pagina di un altro plugin?

Sì, se conosci il suo slug di pagina. Passalo in $page e la sezione apparirà nella pagina delle impostazioni dell'altro plugin. Ma è una soluzione fragile: l'autore del plugin può cambiare lo slug in un aggiornamento e la tua sezione "cadrà". Usala solo per progetti propri o quando non ci sono alternative.

Cosa fa l'hook admin_init e perché add_settings_section si chiama lì?

admin_init si attiva a ogni richiesta al pannello di amministrazione PRIMA che la pagina venga renderizzata. È il momento giusto per registrare le impostazioni: sezioni e campi devono essere dichiarati prima che WordPress inizi ad assemblare il form. Se chiami add_settings_section più tardi, ad esempio dentro la callback della pagina, la sezione non entrerà in $wp_settings_sections e non verrà mostrata.

Una tua sezione o una pagina separata, cosa scegliere

Aggiungere una sezione a general è più semplice: meno codice e l'utente vede le impostazioni nello stesso posto in cui modifica il titolo del sito. Ma quando le opzioni sono più di tre o quattro, la sezione appesantisce la pagina standard e confonde l'amministratore.

La regola è semplice: una o due opzioni, logicamente legate alla pagina generale (telefono footer, chiave API per i commenti), usa una sezione su general. Tre o più opzioni, funzionalità autonome (uno slider, integrazione CRM, una griglia prezzi), usa una pagina separata con add_options_page(). In entrambi i casi, add_settings_section è il mattone fondamentale da cui parte l'assemblaggio.

Prima di copiare il codice, assicurati che WordPress sia aggiornato all'ultima versione. L'array $args, section_class e i contenitori before_section/after_section richiedono almeno la 6.1, mentre la funzione stessa è presente nel core dalla versione 2.7. Due decenni di retrocompatibilità non sono un motivo per restare su un motore obsoleto.