In WordPress, invece di aggiungerli semplicemente all’header, bisogna seguire un metodo chiamato accodamento (“enqueueing”), che è un modo standardizzato di gestire i propri asset con il bonus aggiuntivo della gestione delle dipendenze. Scoprite come farlo in questo articolo utilizzando wp_enqueue_scripts.

Come Funziona l’Accodamento

Ci sono due passaggi da seguire quando si accoda uno script o uno stile. Prima lo si registra – cioè dite a WordPress che c’è – e poi lo si accoda, eventualmente inserendolo nell’header o subito prima del tag di chiusura del body.

Il motivo di avere due passaggi riguarda la modularità. A volte dovrete far sapere a WordPress dell’esistenza di una risorsa, ma potreste non volerla utilizzare su ogni pagina. Ad esempio: se state creando uno shortcode gallery personalizzato che fa uso di Javascript, in realtà dovete caricare il file JS solo quando viene utilizzato lo shortcode – probabilmente non su ogni pagina.

Il modo per farlo è registrare prima lo script e di accodarlo solo quando viene mostrato lo shortcode (lettura suggerita: Guida Definitiva agli Shortcode di WordPress).

Le Basi dell’Accodamento Con wp_enqueue_scripts

Per accodare gli script e gli stili nel front-end è necessario utilizzare l’hook wp_enqueue_scripts. All’interno della funzione agganciata è possibile utilizzare le funzioni wp_register_script(), wp_enqueue_script(), wp_register_style() e wp_enqueue_style().

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_register_style( 'custom-gallery', plugins_url( '/css/gallery.css' , __FILE__ ) );
    wp_register_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ) );

    wp_enqueue_style( 'custom-gallery' );
    wp_enqueue_script( 'custom-gallery' );
}

Nell’esempio qui sopra, ho registrato e accodato gli asset all’interno della stessa funzione, il che è un po’ ridondante. In effetti, è possibile utilizzare le funzioni di registrazione e di accodamento per registrare e accodare contemporaneamente, utilizzando gli stessi argomenti che si utilizzano nelle funzioni di registrazione:

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_style( 'custom-gallery', plugins_url( '/css/gallery.css' , __FILE__ ) );
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ) );
}

Se dovessi separare le due funzioni, lo farei utilizzando hook diversi. In un esempio reale, potremmo utilizzare l’hook wp_enqueue_scripts per registrare gli asset e la funzione dello shortcode per accodarli.

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_register_style( 'custom-gallery', plugins_url( '/css/gallery.css' , __FILE__ ) );
    wp_register_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ) );

}

add_shortcode( 'custom_gallery', 'custom_gallery' );

function custom_gallery( $atts ){

    wp_enqueue_style( 'custom-gallery' );
    wp_enqueue_script( 'custom-gallery' );

    // Gallery code here
}

Gestire le Dipendenze

Il meccanismo di enqueueing di WordPress ha un supporto integrato per la gestione delle dipendenze, grazie all’utilizzo del terzo argomento di entrambe le funzioni wp_register_style() e wp_register_script(). È anche possibile utilizzare subito le funzioni di enqueuing se non è necessario separarle.

Il terzo parametro è un array degli script e degli stili registrati, che devono essere caricati prima che l’asset corrente sia accodato. Il nostro esempio si baserebbe molto probabilmente su jQuery, quindi specifichiamolo:

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ), array( 'jquery' ) );
}

Non c’è bisogno di registrare o accodare jQuery, perché fa già parte di WordPress. Potete trovare un elenco di script e stili disponibili in WordPress nel Codex.

Se avete delle vostre dipendenze, dovrete registrarle, altrimenti i vostri script non verranno caricati. Ecco un esempio:

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ), array( 'jquery' ) );
    wp_enqueue_script( 'custom-gallery-lightbox', plugins_url( '/js/gallery-lightbox.js' , __FILE__ ), array( 'custom-gallery' ) );
}

Supponiamo che il primo script sia una galleria, il secondo una sua estensione che fa aprire le immagini in una lightbox. Si noti che, anche se il nostro secondo script si basa su jQuery, non è necessario specificarlo, in quanto il nostro primo script caricherà già jQuery. Detto questo, può essere una buona idea dichiarare tutte le dipendenze, solo per assicurarsi che nulla possa rompersi se ci si dovesse dimenticare di includere una dipendenza.

WordPress ora sa di quali script abbiamo bisogno e può calcolare l’ordine in cui devono essere aggiunti alla pagina.

Ogni volta che è possibile caricare gli script nel footer, bisognerebbe farlo. Questo aumenta i tempi di caricamento apparente delle pagine e può impedire che il vostro sito web si blocchi durante il caricamento degli script, specialmente se contengono chiamate AJAX.

Il meccanismo di accodamento può aggiungere script al footer utilizzando il quinto parametro (il quarto è un opzionale numero di versione). L’esempio sopra riportato farebbe caricare gli script nel footer se modifichiamo leggermente il codice.

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ), array( 'jquery' ), '1.0', true );
    wp_enqueue_script( 'custom-gallery-lightbox', plugins_url( '/js/gallery-lightbox.js' , __FILE__ ), array( 'custom-gallery', 'jquery' ), '1.0', true );
}

Specificare true come quinto parametro collocherà gli script nel footer, utilizzando false, o omettendo il parametro, gli script saranno aggiunti all’header. Come ho detto prima, quando è possibile, caricate gli script nel footer.

Specificare i Media degli Stili

Con il quinto parametro delle funzioni register/enqueue è possibile controllare il tipo di supporto per il quale è stato definito lo script (stampa, schermo, palmare, ecc.). Utilizzando questo parametro, si può limitare il caricamento degli stili ad uno specifico tipo di supporto, il che è un piccolo trucco di ottimizzazione.

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_register_style( 'custom-gallery-print', plugins_url( '/css/gallery.css' , __FILE__ ), array(), '1.0', 'print' );

}

Per un elenco completo dei tipi di media che possono essere utilizzati, date un’occhiata alle specifiche di CSS.

Riepilogo

Accodare gli asset è un ottimo modo di gestirli. Dà a voi, e ad altri creatori di temi e plugin, un maggiore controllo sul sistema nel suo complesso e vi solleva dalla gestione delle dipendenze.

Se questo non fosse sufficiente, è il modo migliore per aggiungere i vostri asset. Molti marketplace e la stessa repository di WordPress non approveranno il vostro lavoro se non seguite questo metodo.

Daniel Pataki

"Ciao, mi chiamo Daniel, sono il CTO di Kinsta. Forse avete già visto il mio nome su Smashing Magazine, WPMU Dev, Tuts+ e altre riviste di WordPress/Sviluppo. Oltre a WordPress e PHP, trascorro la maggior parte del mio tempo con Node, React, GraphQL e altre tecnologie nello spazio Javascript.
Quando non lavoro per creare la migliore soluzione di hosting dell'universo, colleziono giochi da tavolo, gioco a calcio balilla in ufficio, viaggio o suono la chitarra e canto in una band piuttosto scadente."