Nel capitolo dedicato al file functions.php, si è visto come aggiungere funzionalità ad un tema offrendo un'introduzione a filtri e azioni di WordPress; questi possono essere assimilati agli event listener di JavaScript, rimangono in attesa di un evento, che in questo caso corrisponde ad un momento preciso del caricamento del core di WordPress. Al verificarsi dell'evento action hook e filter hook eseguono una o più funzioni di callback.
Seppur condividendo la definizione di hook, filtri e azioni sono strutturalmente diversi. Le azioni permettono di eseguire una funzione al verificarsi di un evento (il caricamento dei widget o il momento in cui un post viene memorizzato nel database); i filtri invece permettono di intercettare e modificare l'output delle funzioni del core, prima che questo venga mandato al client per la generazione della pagina (ad esempio, modificare il contenuto di un post nel database, prima che questo venga inviato al browser).
Le azioni (action hooks)
Come anticipato, le azioni permettono di agganciare una data funzione di callback ad uno specifico evento: ciò significa che, in un momento preciso dell'esecuzione del core, WordPress invocherà automaticamente la funzione. Sono due le precisazioni importanti da fare al riguardo:
- un'azione può essere utilizzata più volte, in modo tale che allo stesso evento vengano agganciate più funzioni di callback;
- la scelta dell'evento, il momento in cui deve essere eseguita la funzione, non è arbitraria: determinate azioni devono essere eseguite in momenti precisi onde evitare errori di esecuzione del codice.
La funzione di utilizzo più comune è add_action() che aggancia una funzione ad un'azione, ossia invoca la funzione al verificarsi dell'evento associato all'azione.
add_action( 'action-hook-name', 'my-custom-function', $priority, $vars );action-hook-name è il nome dell'azione; my-custom-function è il nome della funzione di callback; $priority è la priorità di esecuzione della funzione in una scala da 1 a 10 (valore predefinito 10); $vars è un intero che indica il numero di argomenti accettati dalla funzione (di default 1).
Invio automatico di email
Nel tema Seventyone si è fatto ricorso ad azioni che eseguissero specifiche funzioni di callback. Qui si presenterà un esempio non inserito nel codice del tema per una dimostrazione del funzionamento degli hook.
Come inviare automaticamente un'email all'autore di un post nel momento in cui questo viene approvato dall'amministratore del sito? L'action hook da utilizzare è publish_post, agganciato alla funzione mycallback_notify_new_post:
add_action( 'publish_post', 'mycallback_notify_new_post' );publish_post individua il passaggio di stato del post da non pubblicato (bozza o sospeso) a pubblicato. Ogni volta che il post viene pubblicato o ri-pubblicato viene eseguita l'azione e invocata la funzione di callback:
function mycallback_notify_new_post( $post_ID ){
global $post;
$post_permalink = get_permalink( $post_ID );
$author_id = $post->post_author;
$author_email = get_the_author_meta( 'user_email', $author_id );
$author_name = get_the_author_meta( 'display_name', $author_id );
$to[] = sprintf( '%s <%s>', $author_name, $author_email );
$subject = __( 'Hei! Your post has been published', 'seventyone' );
$message = sprintf( __( 'Hi %s!', 'seventyone' ), $author_name ) . "\r\n" .
__( 'Your post is now online', 'seventyone' ) . "\r\n" .
sprintf( __( 'You can view it here: %s', 'seventyone' ), $url ) . '.';
$headers[] = 'From: Yourname <you@yourdomain.com>';
$headers[] = 'Reply-To: you@yourdomain.com';
wp_mail( $to, $subject, $message, $headers ) );
}La funzione recupera dal database id, email e nome dell'autore; assegna i valori delle variabili $to, $subject e $headers; invia l'email tramite wp_mail.
I filtri (filter hooks)
Anche i filtri, come le azioni, permettono di intervenire in momenti precisi dell'esecuzione del core e mandare in esecuzione una funzione di callback. A differenza delle azioni essi vanno utilizzati per modificare una parte del codice HTML generato prima che questo venga inviato al client o archiviato nel database. Ad esempio si può modificare il contenuto di un post, grazie al filtro the_content, oppure il titolo, con the_title, o il riassunto (the_excerpt) prima che questi vengano visualizzati. Un filter hook viene attivato in modo molto simile alle azioni:
add_filter( 'filter-hook-name', 'my-custom-function', $priority, $vars );La funzione di callback dovrà sempre restituire il valore della variabile ricevuta come argomento. I dati presenti nel database non vengono modificati ma filtrati prima dell'invio al client.
Filtrare il contenuto dei post
Si supponga ora di voler filtrare il contenuto dei post aggiungendo un collegamento ipertestuale alla parola "WordPress" ad ogni sua occorrenza. Per prima cosa si aggiunga il filtro come segue:
add_filter( 'the_content', 'mycallback_customize_content' );Quindi si definisca la funzione di callback:
function mycallback_customize_content( $content ){
return str_replace( 'WordPress', '<a href="http://wordpress.org/">WordPress</a>', $content );
}str_replace/( sostituirà ogni occorrenza della parola WordPress all'interno della stringa $content con il link a "wordpress.org". Il nuovo contenuto andrà restituito in output.
Filtri e azioni personalizzate
Oltre ai numerosissimi hook disponibili, WordPress permette di crearne di nuovi. Aggiungere hook alle funzionalità di un tema consente di creare estensioni personalizzate, aggiungendo codice custom senza dover modificare il sorgente del tema stesso, con enormi vantaggi sia per la diffusione del tema che per l'ulteriore sviluppo. Per creare un nuovo action hook WordPress fornisce la funzione do_action, mentre per un nuovo filtro si dispone di apply_filters(). La differenza tra le due funzioni è che apply_filters() deve restituire un valore.
Si supponga di voler creare un action hook per il proprio tema. L'azione dovrà essere eseguita in un momento preciso del caricamento del tema. Ad esempio, nel momento in cui viene caricato il footer della pagina. Si apra, quindi, il template footer.php del tema Seventyone e si modifichi il codice come segue:
<?php wp_footer(); ?>
<?php seventyone_footer(); ?>
</body>
</html>Si noterà che è stata invocata la funzione seventyone_footer() subito dopo wp_footer(). Ora si apra il file functions.php e si definisca la funzione come segue:
function seventyone_footer() {
do_action( 'seventyone_footer' );
}è possibile agganciare una qualsiasi funzione all'action hook appena creato esattamente come con le funzioni del core:
add_action( 'seventyone_footer', 'my_custom_callback' );
function my_custom_callback(){
echo 'Say hello!';
}Si ricarichi la pagina. Se non sono stati commessi errori, esattamente prima della chiusura del tag <body> verrà stampata la stringa Say hello!.