Quando si desidera personalizzare un tema WordPress andando oltre la modifica delle opzioni predefinite previste dal suo autore, la necessità di aggiungere o rimuovere css e javascript è una delle prime da affrontare. Esistono ovviamente varie soluzioni per ottenere il risultato, ma è opportuno distinguere quelle che rientrano nelle buone pratiche di sviluppo in WordPress, che è sempre consigliato seguire (soprattutto per chi si sta avvicinando al template editing per le prime volte). In una semplice pagina html l’aggiunta di un file .js o .css avviene tramite una chiamata da aggiungersi nelle sezioni head o nel footer (per i javascript), con istruzioni come queste:
<link rel="stylesheet" type="text/css" href="css/style.css">
<script src="js/script.js"></script>
È quindi facile, una volta che si è presa confidenza con i principali file di template di un tema, pensare di ricorrere allo stesso metodo e inserire istruzioni come queste in header.php o footer.php. Sebbene questa soluzione possa funzionare in alcuni casi (ad esempio per l’aggiunta dello script per Google Analytics) è da considerarsi in generale una pratica scorretta quando si lavora in WordPress. Questo perché WordPress offre un sistema piuttosto semplice per l’aggiunta e la gestione di file esterni di questo tipo. Il metodo di WordPress permette maggiore ordine, pulizia del codice e soprattutto la gestione di dipendenze tra i vari script, che diventa sempre più importante man mano che aumenta la complessità del progetto.
Esistono anche dei plugin dedicati alla risoluzione di questo problema (ad esempio Header and Footer Scripts). Comprendere tuttavia il semplice codice necessario in WordPress per l’aggiunta di file esterni permette di utilizzare un metodo più diretto ed essenziale, utilizzabile sia nell’editing di temi che nello sviluppo di plugins. Vediamo quindi come implementare la soluzione standard:
Registrazione
La pratica standard più lineare prevede, come prima passo per l’aggiunta di javascript e css, una fase di registrazione, in cui semplicemente comunichiamo a WordPress la posizione del file sul server e tutte le informazioni necessarie per la sua gestione. Questa processo è gestito da due semplici funzioni:
wp_register_script() // Per i file javascript
wp_register_css() // Per i css
Vediamo i dettagli di queste funzioni, come sono illustrate nel Codex di Wordpress, a cominciare da wp_register_script():
wp_register_script ($handle, $src, $deps, $ver, $in_footer)
Nota: Per chi ha ancora poca familiarità con Php, questa è una linea di codice esemplificativa di come utilizzare la funzione wp_register_script, che illustra tutti gli argomenti necessari al suo utilizzo all’interno del codice. Gli argomenti sono quelli tra parentesi ($handle, $src, $deps, $ver, $in_footer), preceduti dal segno $ in quanto variabili di Php. In altri termini quando vorremo utilizzare questa funzione dovremo inserirla nel codice chiamandola per nome: wp_register_script () ed aggiungere tra le parentesi, separandole tra virgole, tutte le informazioni richieste (anche dette argomenti).
Vediamo uno per uno i parametri richiesti dalla funzione:
- $handle = Una stringa di testo. Si tratta di un argomento obbligatorio. L’handle non è altro che il nome con cui faremo riferimento allo specifico script che stiamo aggiungendo in funzioni future, come vedremo tra poco. Potrebbe essere un nome qualsiasi, ma per una questione di ordine è consigliato di scegliere un nome intuitivo che ricordi quello del file in questione (ad esempio se il file si chiama responsive_menu.js, potremmo registrarlo con l’handler responsive_menu), scrivendo:
wp_register_script( ‘responsive _menu’, ‘/js/responsive_menu.js’);
L’handler deve essere univoco, ovvero avere un nome unico utilizzato esclusivamente per lo script che si vuole aggiungere e in nessun altra funzione di registrazione seguente. - $src = Un’altra stringa di testo, contente la url, assoluta o relativa del file che vogliamo aggiungere. Anche questo campo è obbligatorio. In alternativa alla url è possibile inserire il valore FALSE, solo nel caso in cui lo script sia un alias di altri script da cui dipende.
-
$deps = Questo è un argomento facoltativo, utile per la gestione delle dipendenze menzionata prima. Si tratta di un array che dovrà contenere una lista di handle di altri script precedentemente registrati, sempre con wp_register_script. Riprendendo l’esempio precedente, se volessimo aggiungere un secondo script (diciamo responsive_sub_menu), dipendente da responsive_menu, scriveremmo:
wp_register_script( ‘responsive_sub_menu’, ‘/js/responsive_sub_menu.js’, array = (‘responsive_menu’) );
Dove responsive_menu è stato aggiunto seguendo le istruzioni scritte nell’esempio precedente. Se volessimo che responsive_sub_menu fosse dipendente da più script, magari aggiungendo un’altra dipendenza a uno script con handle “responsive_page”, scriveremmo:wp_register_script( ‘responsive_sub_menu’, ‘/js/responsive_sub_menu.js’, array = (‘responsive_menu’, ‘responsive_page’ )
- $vers = Un argomento facoltativo. Si tratta di una stringa che specifica la versione dello script che stiamo aggiungendo, se necessario (la versione viene aggiunta alla url per il reperimento del file quando la richiesta a questo viene aggiunta nel codice, ad esempio per esigenze di cache busting . Può essere impostato anche a FALSE (valore di default) o NULL. Nel primo caso viene aggiunta la versione di WordPress correntemente installata, nel secondo nessuna versione in assoluto.
- $in_footer = Ultimo argomento, facoltativo e piuttosto esplicativo nel nome. Si tratta di un valore booleano, impostato di default a FALSE. Con questo valore lo script verrà aggiunto nella sezione head della pagina. Se impostato a TRUE invece verrà aggiunto nel footer (scelta spesso consigliata, dove possibile, per esigenze di ottimizzazione delle prestazioni del sito).
Avendo visto tutti i dettagli di wp_register_script(), vediamo velocemente la funzione equivalente per la registrazione di CSS, ovvero wp_register_style()
wp_register_style($handle, $src, $deps, $ver, $media)
Per quanto riguarda gli argomenti $handle, $src, $deps, $ver vale esattamente quanto detto per wp_register_scripts, al posto di $in_footer (inutile per i css) abbiamo l’argomento $media:
- $media = Argomento opzionale deve contenere una stringa di testo che ci permette di definire se utilizzare il foglio di stile specificamente per determinati dispositivi, o meglio “media”. Ad esempio ‘all'(valore di default), ‘print’ e ‘screen’. Accetta anche media queries, come ‘(orientation: portrait)’ and ‘(max-width: 640px)’. Questo argomento trova quindi la sua utilità anche nello sviluppo di versioni mobile di un sito internet, o in generale per ogni esigenza di responsive.
Enqueuing
Terminata la fase di registrazione il file non sarà ancora aggiunto e caricato nella pagina. Come si accennava prima abbiamo semplicemente comunicato a WordPress le informazioni che riguardano il file da aggiungere, ma non abbiamo ancora dato l’istruzione per caricarlo. Per completare l’aggiunta sono necessari due ulteriori passaggi, più lineari del primo. Prima fase è l’enqueuing, mediante la quale comunichiamo che il file deve essere “messo in coda” con gli altri. Se abbiamo registrato gli script, questa fase può essere completata con una semplice istruzione:
wp_enque_script( $handle ) // Per i file javascript wp_enque_style( $handle ) // Per i css
Dove a $handle corrisponde ovviamente il valore definito nella funzione di registrazione. Riprendendo l’esempio di prima, per responsive_menu.js avremmo:
wp_enque_script(‘responsive _menu’) ;
Nota: È possibile registrare lo script anche mediante queste funzioni, dato che accettano in verità gli stessi parametri di wp_register_script() e wp_register_style(), ovvero scrivendole ad esempio in questo modo:
wp_enque_script( ‘responsive_sub_menu’, ‘/js/responsive_sub_menu.js’, array = (‘responsive_menu’) ) ;
Il motivo per cui è preferibile mantenere le due fasi separate è legato ad esigenze di ordine, standardizzazione e distinzione logica delle operazioni. Le due funzioni di registrazione (wp_register_script e wp_register_style) inoltre possono essere utilizzate in qualsiasi hook (un argomento che tratteremo in un prossimo articolo) e perciò in qualsiasi momento dell’esecuzione di WordPress, mentre le due funzioni per l’enqueuing (wp_enque_script e wp_enque_style) possono essere associate solo agli hook wp_enque_scripts e admin_enque_scripts (quest’ultimo per l’aggiunta dei file alle pagine di backend). Ad esempio, può essere utile registrare inizialmente gli script e i css e fare la richiesta dell’enqueuing in base a precise condizioni.
Aggiunta tramite add_action
Ora che sono chiare le due funzioni di registrazione e per l’enqueuing, dobbiamo passare al comando che indicherà a WordPress in quale punto esatto o circostanza procedere con l’aggiunta dei file in questione. Per farlo dovremo modificare il file functions.php.
Nota: Ovviamente le funzioni definite valgono anche nel caso in cui volessimo aggiungere script in un plugin o altri file del tema (sia esso un tema esistente che stiamo modificando o uno che stiamo creando ex-novo). Per la modifica di un tema esistente di cui non si conosce bene la struttura o per chi sta provando queste funzioni per le prime volte, sarà sufficiente eseguire questi passaggi aggiungendo il codice in fondo a functions.php.
Aggiungiamo le due funzioni di wp_register e wp_enque all’interno di una funzione, con un nome di nostra scelta, ad esempio:
function aggiungi_css_e_js () {
wp_register_script( ‘responsive_sub_menu’, ‘/js/responsive_sub_menu.js’, array = (‘responsive_menu’, ‘responsive_page’ )
wp_enque_script(‘responsive_sub_menu’);
}
Chiamiamo la funzione tramite add_action, definendo così anche dove e in quali circostanze vogliamo che i files vengano aggiunti. Ad esempio:
add_action ( ‘wp_enqueue_scripts’, ‘aggiungi_css_e_js ‘ , 10 );
Vediamo brevemente anche gli argomenti della funzione add_action:
- Il primo argomento, nell’esempio wp_enque_scripts, serve a indicare dove dovrà essere eseguita la nostra funzione per l’aggiunta degli script (ovvero ‘aggiungi_css_e_js’). Lasciando il valore wp_enqueue_scripts la funzione verrà eseguita in ogni pagina visitabile del sito, ovvero il front end. Per quanto riguarda le pagine di amministrazione (o back end) possiamo utilizzare il valore admin_enque_scripts. Determinati plugin richiedono l’aggiunta di javascript o fogli di stile proprio per modificare l’interfaccia di WordPress nelle pagine che li interessano (vi sarà capitato di vedere pagine di plugin con una grafica personalizzata rispetto a quella standard di WordPress). Ulteriore opzione è utilizzare il valore login_enqueue_scripts per aggiungere files solamente nella pagina di login. In generale la funzione add_action può essere utilizzata in moltissime situazioni, e sarà argomento di una prossima trattazione.
- Il secondo argomento, come apparirà ovvio è il nome della funzione da eseguire. Sarà sufficiente utilizzare lo stesso che abbiamo scelto nella sua definizione, sotto forma di stringa e quindi incluso tra virgolette (in questo caso ‘aggiungi_css_e_js’).
- Il terzo argomento, nell’esempio il numero 10, è la priorità. Si tratta di un argomento opzionale e deve essere un numero intero che stabilisce l’ordine con cui vogliamo che la funzione venga eseguita. Minore il numero, prima avverrà l’esecuzione. Questo parametro è necessario se, ad esempio, dovessimo usare add_action in due punti diversi del codice per aggiungere diversi gruppi di file javascript e css. Nell’esecuzione finale del codice l’ordine di aggiunta sarà determinato da questo valore, di cui è opportuno tenere conto nel caso in cui i javascript siano in rapporto di dipendenza reciproca. Il valore di default è 10. Due funzioni con la stessa priorità saranno eseguite nell’ordine esatto con cui sono state aggiunte all’azione selezionata da add_action, ovvero ‘wp_enqueue_scripts’ o ‘admin_enqueue_scripts’.
(Due funzioni con la stessa priorità saranno eseguite nell’ordine esatto con cui sono state aggiunte all’azione selezionata da add_action, ovvero ‘wp_enqueue_scripts’ o ‘admin_enqueue_scripts’.)
Terminata l’aggiunta della funzione add_action potremo aprire le pagine del nostro sito che la interessano, visualizzare il codice sorgente e controllare l’inclusione dei nostri file.
Nota: Per i css l’id del link corrisponderà (di solito) all’handler selezionato:
<link rel='stylesheet' id='responsive_menu' href='' type='text/css'media='all'>