wp_enqueue_scripts e admin_enqueue_scripts in WordPress: Guida Completa

Quando sviluppi temi o plugin WordPress, uno degli aspetti più importanti è gestire correttamente CSS e JavaScript. WordPress mette a disposizione due hook fondamentali per questo: wp_enqueue_scripts e admin_enqueue_scripts. Anche se sembrano simili, hanno scopi diversi e vanno usati al momento giusto.

Cos’è wp_enqueue_scripts

wp_enqueue_scripts è un hook front-end, utilizzato per caricare stili e script sul lato pubblico del sito (cioè ciò che vedono gli utenti).

Sintassi base

add_action('wp_enqueue_scripts', 'mio_script_frontend');

function mio_script_frontend() {
    // CSS
    wp_enqueue_style('nome-stile', get_template_directory_uri() . '/css/mio-stile.css', array(), '1.0.0', 'all');

    // JavaScript
    wp_enqueue_script('nome-script', get_template_directory_uri() . '/js/mio-script.js', array('jquery'), '1.0.0', true);
}

Parametri principali

• Nome handle: un identificativo univoco (nome-stile o nome-script).
• URL file: percorso del file da caricare.
• Dipendenze: array di altri script o stili da caricare prima.
• Versione: utile per il caching.
• Media/posizione: per i CSS è il media type (all, screen, ecc.), per JS se deve essere in footer (true) o header (false).

Importante: non includere mai CSS o JS direttamente con <link> o <script> nel tema/plugin. WordPress gestisce versioni, conflitti e caricamento corretto tramite questi hook.

Cos’è admin_enqueue_scripts

admin_enqueue_scripts è invece dedicato al back-end, cioè l’area di amministrazione di WordPress. Serve quando vuoi aggiungere stili o script personalizzati solo nell’admin, per esempio per pagine di plugin o campi personalizzati.

Sintassi base

add_action('admin_enqueue_scripts', 'mio_script_admin');

function mio_script_admin($hook_suffix) {
    // Controlla su quale pagina admin sei
    if ($hook_suffix != 'toplevel_page_mio-plugin') {
        return;
    }

    // CSS
    wp_enqueue_style('nome-stile-admin', plugin_dir_url(__FILE__) . 'css/admin.css', array(), '1.0.0');

    // JavaScript
    wp_enqueue_script('nome-script-admin', plugin_dir_url(__FILE__) . 'js/admin.js', array('jquery'), '1.0.0', true);
}

Nota sul parametro $hook_suffix

Il parametro $hook_suffix permette di limitare il caricamento solo a certe pagine admin, evitando di appesantire l’intero backend con script inutili. Questo è un accorgimento fondamentale per plugin professionali.

Differenze chiave tra i due hook

Best Practice

1. Non caricare tutto ovunque: limita script e stili solo dove servono.
2. Usa dipendenze: evita conflitti con jQuery o altri script.
3. Versioning: cambia la versione dei file quando li modifichi, così WordPress forza il refresh del browser.
4. Footer per JS: salvo casi particolari, carica gli script nel footer (true) per velocizzare il caricamento della pagina.