Costruzione di un pannello impostazioni personalizzato per un tema WordPress è un'attività che può protrarsi per settimane. L'API delle Impostazioni di WordPress richiede la scrittura di una quantità enorme di codice boilerplate: registrazione, rendering dei campi, validazione, salvataggio. E quando il progetto è in fiamme, scrivere tutto questo da zero è un lusso ingiustificabile.

Redux Framework risolve questo problema in modo radicale: invece del lavoro manuale con l'API delle Impostazioni, descrivi i campi necessari in un file di configurazione e il framework si occupa di tutto il resto, rendering, validazione, escaping, import/export e persino CSS dinamico. Su WordPress.org il plugin ha più di 32 milioni di download e oltre un milione di installazioni attive, e questa non è inflazione da marketing, ma una conseguenza diretta del fatto che Redux fa risparmiare davvero settimane di sviluppo.

In questa guida, configurazione passo passo di Redux Framework da zero fino a un pannello opzioni tema funzionante, inclusa la dimostrazione dal vivo nel customizer e l'uso sicuro dei valori salvati nel frontend.

💡 Panoramica rapida:

• Installare Redux Framework: tre modi per integrarlo in un progetto WordPress
• Connettere il framework e creare un file di configurazione
• Impostare gli argomenti del pannello: posizione nel menu, customizer, Google Fonts
• Aggiungere sezioni e campi di input tramite l'API unificata di Redux
• Estrarre i valori salvati nei template del tema con protezione dagli errori

Cos'è Redux Framework e perché ti serve

Redux Framework è un framework di opzioni open source gratuito per temi e plugin WordPress. Costruito sopra l'API delle Impostazioni standard di WordPress, ma ne astrae completamente la complessità. Invece di dozzine di chiamate a register_setting, add_settings_field e settings_fields, scrivi un array dichiarativo in PHP e ottieni un pannello impostazioni reattivo e perfettamente funzionante con 49 tipi di campo tra cui scegliere.

Importante non confonderlo con la libreria JavaScript Redux per la gestione dello stato, sono prodotti completamente diversi con lo stesso nome. Il framework per WordPress è nato prima della libreria JS.

Capacità chiave che ottieni "out of the box":

• 49 tipi di campo: dal semplice testo e checkbox all'editor ACE, repeater, Google Maps, block sorter e slider per immagini;
• Output CSS automatico: per i campi tipografia, colore, gradiente, spaziatura, basta specificare un selettore CSS e Redux stesso genererà un foglio di stile con i Google Fonts;
• Integrazione con il Customizer: lo stesso argomento customizer => true, e l'intero pannello viene duplicato nel WordPress Customizer con anteprima dal vivo;
• Import/export impostazioni: strumento integrato per trasferire la configurazione tra siti;
• Compiler: un hook che si attiva quando un campo con il flag compile => true cambia, puoi, ad esempio, ricompilare SCSS;
• Validazione ed escaping: ogni valore passa attraverso una sanitizzazione corrispondente al tipo di campo, un campo di testo non accetterà un array, uno numerico filtrerà le stringhe.

Dal 2024 il framework si sviluppa sotto l'ala di Team Updraft (David Anderson, creatore di UpdraftPlus). Versione attuale, 4.5.11 (marzo 2026), piena compatibilità con WordPress 7.0 e PHP 8.5. Il progetto vive su redux.io, la documentazione sul sito della documentazione Redux.

Installare Redux Framework

Ci sono tre modi per aggiungere Redux a un progetto. La scelta dipende dall'architettura del tuo tema e da come prevedi di distribuirlo.

Come plugin separato

Installa Redux Framework dalla directory di WordPress.org come un normale plugin. Dopo l'attivazione il pannello opzioni non apparirà, il plugin fornisce solo l'API. Descrivi tutte le impostazioni in un file di configurazione all'interno del tuo tema.

Pro: il tema rimane leggero (il core del framework non appesantisce l'archivio); il framework si aggiorna indipendentemente tramite il meccanismo standard di WordPress.

Contro: il tuo tema richiede la presenza di un plugin di terze parti, l'utente deve installarlo e attivarlo separatamente; senza il plugin il pannello impostazioni scompare e devi prevedere un fallback sicuro nel codice del tema.

Nel core del tema

Copia la cartella ReduxCore all'interno del tuo tema e connettila in functions.php. Il framework diventa parte integrante del tema, l'utente non deve installare un plugin aggiuntivo.

Pro: il pannello impostazioni appare come una parte nativa del tema, l'utente non installa nulla di aggiuntivo.

Contro: la dimensione dell'archivio del tema cresce di circa 2 MB; ogni aggiornamento del framework richiede un aggiornamento del tema da parte tua; il plugin Theme Check potrebbe emettere avvisi.

In un plugin tema dipendente

Approccio consigliato per i temi premium. Crea un plugin companion separato per il tuo tema (è comodo anche per mantenervi custom post types, shortcode, widget) e incorpora Redux al suo interno. Nel functions.php del tema aggiungi un controllo per la presenza di questo plugin tramite TGMPA o un meccanismo simile.

Pro: architettura pulita (la funzionalità del tema è separata dalla presentazione); il framework non appesantisce l'archivio del tema; gli aggiornamenti del framework non influenzano direttamente il codice del tema.

Contro: richiede la scrittura e la manutenzione di un plugin separato; soglia d'ingresso leggermente più alta per altri sviluppatori che dovranno orientarsi nel progetto.

La configurazione di Redux non dipende dal metodo di installazione, i passaggi successivi sono identici per qualsiasi variante.

Configurazione generale: connettere il framework

All'interno del plugin Redux Framework (o dell'archivio scaricato dal sito ufficiale Redux) trova la cartella ReduxCore, contiene l'intero core.

Crea una cartella nel tuo plugin (o tema), ad esempio optionpanel, e copia al suo interno il contenuto di ReduxCore. Metti accanto un file config.php vuoto, descriveremo tutte le sezioni e i campi del pannello al suo interno.

Ora connetti il framework. Nel file principale del plugin (o nel functions.php del tema) aggiungi:

1
<?php
2
if ( ! class_exists( 'Redux' ) ) {
3
    require_once plugin_dir_path( __FILE__ ) . 'optionpanel/ReduxCore/framework.php';
4
}

Il controllo class_exists evita un errore fatale se un'altra parte del sito ha già caricato Redux (per esempio, tramite un plugin separato). Se il framework è assente, il pannello delle impostazioni semplicemente non verrà caricato e il sito continuerà a funzionare.

Dopo questo puoi procedere con la creazione di sezioni e campi.

Creazione del pannello opzioni

Argomenti del framework

Per prima cosa, imposta una variabile globale per memorizzare tutte le impostazioni, servirà per estrarre i valori nei template del tema:

1
$opt_name = 'mytheme_options';

Il prefisso è obbligatorio, evita conflitti di nome con altri plugin che usano Redux. Buona pratica: brandname_themename.

Ora assembliamo l'array degli argomenti. Ecco una configurazione minima funzionante:

1
$args = array(
2
    'opt_name'             => $opt_name,
3
    'display_name'         => 'Theme Settings',
4
    'display_version'      => '1.0.0',
5
    'menu_type'            => 'submenu',
6
    'allow_sub_menu'       => true,
7
    'menu_title'           => 'Theme Settings',
8
    'page_title'           => 'Theme Settings Panel',
9
    'page_parent'          => 'themes.php',
10
    'page_permissions'     => 'manage_options',
11
    'page_slug'            => 'theme_options',
12
    'dev_mode'             => false,
13
    'update_notice'        => false,
14
    'customizer'           => true,
15
    'save_defaults'        => true,
16
    'show_import_export'   => true,
17
    'async_typography'     => true,
18
    'admin_bar'            => true,
19
    'global_variable'      => $opt_name,
20
);
21
 
22
Redux::set_args( $opt_name, $args );

Analisi degli argomenti chiave:

• menu_type: submenu, il pannello apparirà dentro la voce di menu «Aspetto»; menu, voce separata di primo livello nell'amministrazione;
• customizer: true abilita la duplicazione di tutti i campi nel Personalizzatore di WordPress con anteprima dal vivo, l'utente vede le modifiche prima di salvare;
• dev_mode: abilitalo durante lo sviluppo (debug esteso, importazione demo), ma disattivalo assolutamente prima del rilascio;
• update_notice: sempre false per temi e plugin con Redux integrato, i tuoi utenti non devono ricevere notifiche sugli aggiornamenti del framework separatamente dal tuo prodotto;
• show_import_export: aggiunge uno strumento per trasferire tutte le impostazioni tra siti con un clic.

Per l'elenco completo di oltre 40 argomenti consulta la guida agli argomenti.

Aggiunta di sezioni e campi

Una sezione è un gruppo logico di campi (scheda nella schermata delle impostazioni). Sezione minima:

1
Redux::set_section( $opt_name, array(
2
    'title'  => 'Site Header',
3
    'id'     => 'header_section',
4
    'icon'   => 'dashicons-heading',
5
    'fields' => array(
6
        array(
7
            'id'       => 'header_logo',
8
            'type'     => 'media',
9
            'title'    => 'Logo',
10
            'subtitle' => 'Upload logo image',
11
            'default'  => array( 'url' => get_template_directory_uri() . '/images/logo.png' ),
12
        ),
13
        array(
14
            'id'      => 'sticky_header',
15
            'type'    => 'switch',
16
            'title'   => 'Sticky Header',
17
            'default' => true,
18
        ),
19
    ),
20
) );

Icone delle sezioni: Redux 4.x supporta le Dashicon integrate di WordPress (elenco completo su developer.wordpress.org). Per icone personalizzate usa classi CSS del tuo set di icone (per esempio, Font Awesome).

Ogni campo è un array associativo con le chiavi obbligatorie id, type e title. Esempi di tipi comunemente usati:

1
// Select with search
2
array(
3
    'id'      => 'sidebar_layout',
4
    'type'    => 'select',
5
    'title'   => 'Sidebar Layout',
6
    'options' => array(
7
        'right' => 'Sidebar Right',
8
        'left'  => 'Sidebar Left',
9
        'none'  => 'No Sidebar',
10
    ),
11
    'default' => 'right',
12
),
13
 
14
// RGBA color picker
15
array(
16
    'id'      => 'accent_color',
17
    'type'    => 'color_rgba',
18
    'title'   => 'Accent Color',
19
    'default' => array(
20
        'color' => '#2271b1',
21
        'alpha' => 1,
22
    ),
23
),
24
 
25
// Typography with Google Fonts
26
array(
27
    'id'          => 'body_typography',
28
    'type'        => 'typography',
29
    'title'       => 'Text Font',
30
    'google'      => true,
31
    'font-backup' => true,
32
    'line-height' => true,
33
    'font-size'   => true,
34
    'default'     => array(
35
        'font-family' => 'Inter',
36
        'font-size'   => '16px',
37
    ),
38
),

Per creare una sottosezione aggiungi l'argomento 'subsection' => true, il campo apparirà come una scheda nidificata dentro la sezione padre.

Elenco di tutti i 49 tipi con esempi di configurazione nella sezione tipi di campo della documentazione di Redux.

Utilizzare le opzioni nel tema

Redux memorizza tutti i valori in una variabile globale, la stessa che hai specificato in $opt_name. Per ottenere un valore in un template, devi prima dichiararla globale. Ma la dichiarazione global diretta fuori da una funzione o azione è una cattiva pratica. L'approccio corretto:

1
function mytheme_get_option( $option_id, $default = '' ) {
2
    global $mytheme_options;
3
    return isset( $mytheme_options[ $option_id ] ) ? $mytheme_options[ $option_id ] : $default;
4
}

La funzione wrapper fa due cose: previene il PHP Notice "undefined index" quando si accede a una chiave inesistente e fornisce un valore di fallback. Nel template l'utilizzo appare così:

1
$logo = mytheme_get_option( 'header_logo' );
2
if ( ! empty( $logo['url'] ) ) {
3
    echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( get_bloginfo( 'name' ) ) . '">';
4
}

Se il pannello delle impostazioni non è ancora configurato (ad esempio, l'utente ha attivato il tema ma non ha installato il plugin dipendente), $mytheme_options sarà un array vuoto e mytheme_get_option() restituirà silenziosamente $default, senza una sfilza di avvisi nel debug.log.

Per i CSS dinamici usa la capacità integrata di Redux, specifica l'argomento output nella configurazione del campo:

1
array(
2
    'id'     => 'body_bg_color',
3
    'type'   => 'color',
4
    'title'  => 'Background Color',
5
    'output' => array( 'background-color' => 'body' ),
6
),

Redux genererà e incorporerà automaticamente la regola CSS <style>body{background-color:#fff;}</style>, senza una sola riga di codice manuale.

Il processo di installazione e configurazione dei campi è mostrato chiaramente in questo video tutorial: dal collegamento del framework alla creazione della prima sezione con select e switch:

⁉️🤔 Domande frequenti

In cosa Redux Framework differisce da Carbon Fields, ACF Options Pages e altre soluzioni?

Redux offre 49 tipi di campo "pronti all'uso" (contro circa 25 di Carbon Fields e circa 30 di ACF Pro) ed è focalizzato specificamente sui pannelli delle impostazioni del tema, non sui campi meta dei post. ACF Options Pages è un componente aggiuntivo sopra il motore dei campi meta, mentre Redux è stato progettato fin dall'inizio per i pannelli delle opzioni: import/export integrato, compilatore, anteprima dal vivo nel customizer, CSS dinamici con Google Fonts. Carbon Fields è più vicino nello spirito, ma richiede Composer e namespace, cosa che in diversi ambienti di hosting rappresenta una barriera. Conclusione: se usi già ACF per i campi meta, prendi ACF Options Pages per evitare di moltiplicare gli enti; se costruisci un tema da zero e hai bisogno di un potente pannello delle opzioni, Redux ti darà più funzionalità gratuitamente.

Redux Framework funziona con i temi a blocchi (Full Site Editing)?

Sì, ma con alcune precisazioni. Redux espone il pannello delle impostazioni attraverso l'interfaccia classica di amministrazione (Settings API), non tramite l'editor del sito. Per un approccio ibrido, tema a blocchi più pannello Redux per le impostazioni globali (colori, tipografia, script di analytics), la combinazione funziona. A partire dalla versione 4.5.11 l'integrazione diretta con theme.json non è implementata: i valori devono essere estratti nei template tramite mytheme_get_option() e inseriti in linea come variabili CSS. Per un ambiente FSE puro dove tutte le impostazioni dovrebbero risiedere nell'editor del sito, Redux è ridondante; per temi classici e ibridi, è una delle migliori opzioni.

Cosa fare se Redux entra in conflitto con un altro plugin che usa la stessa libreria?

Questo è un problema noto di "doppia inclusione". Il controllo if ( ! class_exists( 'Redux' ) ) prima di require_once garantisce che il framework venga caricato esattamente una volta: WordPress esegue il PHP in sequenza e il primissimo require_once rende innocue le chiamate successive. Se il tuo tema e un plugin di terze parti includono entrambi Redux, si caricherà la copia inizializzata per prima e i pannelli di entrambi i prodotti continueranno a funzionare. Con una differenza significativa nelle versioni major è possibile un'incompatibilità a livello API, risolvibile aggiornando la parte rimasta indietro alla release corrente.

Serve una licenza per usare Redux Framework in un tema commerciale?

No. Redux è distribuito sotto GPLv2, la stessa licenza di WordPress. Puoi includere liberamente il framework in temi e plugin commerciali, venderli su ThemeForest, distribuirli attraverso il tuo sito. L'unica restrizione GPLv2, che le opere derivate devono essere anch'esse sotto GPLv2, si applica al codice sorgente, non al contenuto del sito dell'utente finale. Redux Pro (campi aggiuntivi, customizer esteso, supporto prioritario) è un prodotto a pagamento separato, non necessario per il funzionamento del framework.

Cosa fare se dopo un aggiornamento di WordPress il pannello Redux smette di aprirsi?

Scenario: dopo un aggiornamento major di WP schermata bianca sulla pagina delle impostazioni del tema. Ordine delle azioni: per prima cosa, verifica di avere una versione di Redux non inferiore alla 4.5.11 (compatibilità con WP 7.0). Secondo, per un minuto abilita 'dev_mode' => true e guarda l'output degli errori PHP nella schermata delle impostazioni, Redux in modalità dev mostra un log dettagliato. Terzo, se l'errore proviene da un campo specifico, controlla se stai usando un tipo deprecato (search rimosso in Redux 3.x, divide rinominato). L'elenco aggiornato dei campi è sempre nella documentazione di Redux.

Vale la pena usare Redux Framework nel 2026

Redux Framework è un prodotto maturo e attivamente supportato, dietro al quale ci sono 32 milioni di download e una community di oltre 270 contributor su GitHub. Se stai costruendo un tema WordPress classico o ibrido e hai bisogno di un pannello delle impostazioni con un ricco set di campi, anteprima dal vivo nel customizer e CSS dinamici, Redux ti farà risparmiare settimane di sviluppo e ti darà un risultato conforme agli standard di sicurezza WordPress (PHPCS, escaping, validazione).

Architetturalmente il modo migliore per integrarlo è estrarre il framework in un plugin tema dipendente tramite require_once con controllo class_exists. Questo garantisce sia una base di codice pulita, sia protezione dai conflitti di doppia inclusione, sia un percorso di aggiornamento trasparente.

Quando Redux non serve: stai realizzando un tema leggero senza pannello delle impostazioni; lavori in un ambiente FSE puro (tema a blocchi con theme.json); hai già ACF distribuito con Options Pages per i campi meta. In questi casi includere Redux per un solo pulsante on/off è come sparare ai passeri con un cannone: il framework aggiungerà circa 2 MB alla dimensione del tema senza un beneficio proporzionale.

Prima di iniziare a lavorare dai un'occhiata alla documentazione ufficiale sul sito degli sviluppatori Redux e al repository su GitHub, lì puoi anche segnalare un bug o proporre una funzionalità. Se hai bisogno di aiuto con un tipo di campo o un argomento specifico, scrivi nei commenti, lo risolviamo insieme.