Azioni e Filtri in Wordpress: Quali sono le Differenze?

() translation by (you can also view the original English article)

Azioni e filtri sono una parte fondamentale delle varie WordPress APIs. Senza di loro si potrebbero fare molte meno modifiche nei nostri temi e (soprattutto) nei nostri plugin.

Ma a volte può essere facile confonderli, soprattutto nei casi in cui WordPress ha un un'azione e un filtro con lo stesso nome.

In questo articolo definiremo azioni e filtri, vedremo le differenze tra di loro e ti mostrerò come come usarli nei tuoi temi e plugin. Ti darò anche alcuni esempi di quando è possibile utilizzare ciascuno.

Quando stai aggiungendo azioni e filtri al codice (o se ci stai agganciando funzioni), è utile capire come azioni e filtri sono chiamati da WordPress, cosa succede e in quale ordine. Non tratterò questo nel dettaglio, come invece fa questo altro tutorial.

Definizioni e Differenze

Iniziamo con alcune definizioni. Definirò azioni, filtri e anche le funzioni, così si può vedere la differenza tra tutti loro.

Funzioni

Le funzioni sono la prima cosa con la quale la maggior parte delle persone lavora quando stanno imparando lo sviluppo di WordPress. Se hai aggiunto codice al file functions.php del tema avrai sicuramente scritto una funzione.

Le funzioni specificano come qualcosa accadrà. Tu scrivi una funzione per eseguire query sui dati, per visualizzare del contenuto o per eseguire molte altre attività. Puoi chiamare (eseguire) funzioni nei files del template del tuo tema, oppure puoi agganciarle a filtri o azioni. Le funzioni possono anche includere "template tag" come tag condizionali, che servono per specificare quando si deve applicare la funzione.

Ti mostrerò i diversi modi di eseguire le funzioni più avanti in questo articolo.

Azioni

Le azioni vengono attivate quando qualcosa si svolge, come per esempio il caricamento di una pagina, il log-in di un utente o un'azione personalizzata che si definisce nel tuo tema o plugin.

È possibile aggiungere la propria azione mediante la funzione do_action(), che illustrerò brevemente. Tutte le funzioni che si agganciano a questa azione verranno eseguita in quel punto del codice.

Filtri

I filtri, controllano come succede qualcosa o cambiano qualcosa che è in uscita. Puoi usare un filtro per l'output dei metadati in uno specifico formato, per sovrascrivere l'output del testo dal vostro plugin, o per evitare che qualcosa venga visualizzato.

Puoi aggiungere filtri nel codice utilizzando la funzione apply_filters(), che illustrerò brevemente. Come la parola «applica» indica, è possibile applicare filtri al codice esistente, considerando che un'azione che si crea utilizzando do_action() è vuota fino a quando vi si collegano le funzioni.

Usare Funzioni, Azioni e Filtri

Diamo un'occhiata ad alcuni esempi che dimostrano come si utilizza ciascuna delle funzioni, azioni e filtri. In primo luogo utilizzeremo funzioni direttamente nel codice senza associarle a un gancio.

Chiamare Funzioni Direttamente

Ecco un esempio di una funzione che viene chiamata direttamente in un template file . Nei siti dei miei clienti aggiungo un colophon nel footer, che include le informazioni di copyright. Questa è la funzione:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() { ?>
    <section class="colophon" role="contentinfo">
  	<small class="copyright left">
			<?php echo compass_copyright(); ?>
			<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
			<?php bloginfo( 'name' ); ?>
			</a>
		</small><!-- #copyright -->

		<small class="credits right">
				Powered by <a href="https://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->
	<?php }
}

Questa funzione è inseribile, come uso fare io, in un tema genitore. Se serve creare una funzione con lo stesso nome nel mio tema figlio, questa sovrascriverà la precedente funzione. Notare come la funzione include un'altra funzione, compass_colophon(), chiamandola direttamente nel codice.

Questa funzione è nel file functions.php del mio tema genitore. Posso chiamarla direttamente nel file footer.php del mio tema, in questo modo:

1	compass_colophon();

Questo genera il codice della funzione nel punto nel mio tema nel quale la richiamo. È anche possibile passare parametri per le funzioni, che vengono poi utilizzati all'interno della funzione.

Come dimostrerò tra poco, questa funzione potrebbe anche essere agganciata a un'azione o un filtro.

Agganciare Funzioni alle Azioni

Anziché chiamare direttamente tale funzione avremo più flessibilità se la collego a un gancio.

Creare Azioni

Invece di chiamare la funzione compass_colophon() nel mio footer, posso aggiungere un'azione in quel punto nel file footer.php, aggiungendo questo:

1	do_action( 'compass_in_footer' );

La funzione do_action() ha un parametro obbligatorio, che è il nome dell'azione. È anche possibile aggiungere argomenti.

Agganciare Funzioni con Azioni

Così ora, invece di chiamare la mia funzione colophon, devo collegarla alla mia nuova azione. Nel mio file functions.php, aggiungo questo con la mia funzione:

1	add_action( 'compass_in_footer', 'compass_colophon' );

Questo aggancia la mia funzione all'azione compass_in_footer, che significa che il codice all'interno della funzione verrà eseguito nel punto del codice in cui è stata messa l'azione. Il primo parametro è il nome dell'azione, e il secondo è il nome della mia funzione.

Un vantaggio di fare in questo modo è la possibilità di collegare più di una funzione per la stessa azione, ed è possibile impostare la priorità così da essere lanciate nell'ordine desiderato.

Quindi diciamo che ho un'altra funzione che voglio agganciare al mio hook di compass_in_footer, chiamato compass_smallprint(), che contiene alcune più piccola stampe:

if ( ! function_exists( compass_smallprint() ) ) {
    function compass_smallprint() {
		// contents of function here
	}
}
add_action( 'compass_in_footer', 'compass_smallprint', 20 );

Puoi vedere qui che ho aggiunto un terzo parametro alla funzione add_action(), che è la priorità. La priorità predefinita è 10, e verrà applicata se si lascia vuoto questo parametro. Quindi siccome non ho fissato una priorità per la mia funzione compass_colophon(), l'impostazione di 20 della funzione compass_smallprint() farà in modo che quella funzione venga eseguita dopo la funzione compass_colophon().

Sganciare funzioni dalle azioni

A volte si desidera interrompere una funzione in esecuzione, ma non è possibile perché non è collegabile. Se la funzione è stata agganciata ad una azione è possibile farlo utilizzando la funzione remove_action().

Quindi vuoi impedire l'esecuzione della mia funzione compass_smallprint(), bisogna sganciarla dall'azione compass_in_footer in questo modo:

1	remove_action( 'compass_in_footer', 'compass_smallprint', 20 );

La funzione remove_action() dispone di tre parametri: il nome dell'azione, il nome della funzione e la priorità con cui la funzione era originariamente collegata all'azione. È necessario includere la priorità per farla funzionare.

Puoi sganciare tutte le funzioni da un'azione se si desidera impedirene l'esecuzione. Presta attenzione quando fai questo, potrebbero esserci funzioni di cui non sei consapevole agganciate alla tua azione.

Per fare questo, usa la funzione remove_all_actions():

1	remove_all_actions( 'compass_in_footer' );

Aggiungendo il numero della priorità come secondo parametro si rimuovono solo le funzioni che sono collegate a quell'azione con la priorità che hai specificato, offre un maggiore controllo.

Agganciare Funzioni ai Filtri

Esiste anche la possibilità di agganciare le funzioni ai filtri. Si esegue questa operazione quando si desidera modificare o sostituire il codice esistente. Quando si crea il filtro (utilizzando la funzione apply_filters()), si avvolge questa nel codice del tema o plugin, che viene poi alterata da qualsiasi filtro agganciato.

Questo può essere utile se si desidera sovrascrivere un'impostazione predefinita del tema o di un plugin, o se si sta creando un tema genitore che può avere elementi sovrascritti da un tema figlio.

Creare Filtri

La funzione apply_filters() ha tre parametri: il nome del filtro, il valore che si desidera filtrare (cioè il valore predefinito) e variabili facoltative che si passano poi alle funzioni collegate al filtro.

È possibile aggiungere un filtro nei file di template del tema o all'interno di una funzione che è collegata tramite un'azione. Diamo un'occhiata ad entrambe le opzioni.

Torniamo alla mia funzione compass_colophon(), convertiamo questa in un filtro aggiungendo il contenuto al file footer. php all'interno della funzione apply_filters()come segue:

echo apply_filters( 'compass_colophon', '
    <section class="colophon" role="contentinfo">
		<small class="copyright left">
			<?php echo compass_copyright(); ?>
			<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
			<?php bloginfo( 'name' ); ?>
			</a>
		</small><!-- #copyright -->

		<small class="credits right">
				Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->'
);

Questo genera il codice che ho impostato come secondo parametro della funzione apply_filters().

Tuttavia, preferisco non aggiungere questo direttamente al file del template del tema, così aggiungo il filtro alla funzione tramite un'azione.

Quindi aggiungo l'azione compass_in_footer al mio file footer.php utilizzando la funzione do_action() come dimostrato in precedenza, e quindi creo una funzione nel mio file functions.php che è collegato a tale azione e contiene un filtro:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() {
    echo apply_filters( 'compass_colophon_filter', '
		<section class="colophon" role="contentinfo">
			<small class="copyright left">
				<?php echo compass_copyright(); ?>
				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
				<?php bloginfo( 'name' ); ?>
				</a>
			</small><!-- #copyright -->
	
			<small class="credits right">
					Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
				</a>
			</small><!-- #credits -->
		</section><!--#colophon-->'
	);
}
add_action( 'compass_in_footer', 'compass_colophon' );

Questo significa che ora posso sovrascrivere il contenuto di default in uno dei tre modi:

creando una nuova funzione chiamata compass_colophon() nel mio tema figlio, che sovrascrive la funzione del mio tema genitore
sganciando la funzione compass_colophon() dall'azione compass_in_footere scrivendo una nuova funzione che attaccherò a questa
creando una nuova funzione che aggancia filtro compass_colophon_filter, e che sostituisce il valore nella mia funzioneapply_filters()

Nella vita reale non c'è bisogno di avere tutte queste opzioni, è più probabile applicare i filtri nel contenuto della tua funzione.

Così ho potuto creare due filtri, uno per la sezione copyright e un altro per i crediti:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() {
    
	echo '<section class="colophon" role="contentinfo">';
		
		echo apply_filters( 'compass_copyright_filter', '
			<small class="copyright left">
				<?php echo compass_copyright(); ?>
				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
				<?php bloginfo( 'name' ); ?>
				</a>
			</small><!-- #copyright -->'
		);
		
		echo apply_filters( 'compass_copyright_filter', '
			<small class="credits right">
					Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
				</a>
			</small><!-- #credits -->'
		);
	echo '</section><!--#colophon-->';
}
add_action( 'compass_in_footer', 'compass_colophon' );

Quindi io potrei sovrascrivere tutta la mia funzione compass_colophon sganciandola, o scrivendone una nuova nel mio tema figlio, o potrei creare una funzione agganciata filtro compass_copyright_filter o compass_credits_filter, e sovrascrivere ogni elemento singolarmente.

Agganciare Funzioni ai Filtri

Per agganciare una funzione a un filtro, si utilizza la funzione add_filter(), che dispone di due parametri: il nome del filtro e il nome della funzione.

Quindi, per modificare i crediti, dovrei scrivere questa funzione:

function new_credits() { ?>
    <small class="credits right">
		Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://rachelmccollin.co.uk">Rachel McCollin</a>.
			</a>
	</small><!-- #credits -->
<?php }
add_filter( 'compass_credits_filter', 'new_credits' );

Questa sostituisce il valore impostato nel mio filtro originale compass_credits_filter con il contenuto della mia funzione new_credits(), ma tutto il resto nella funzione compass_colophon() rimane lo stesso.

È inoltre possibile specificare la priorità quando agganciamo funzioni ai filtri, esattamente nello stesso modo come per le azioni. Le funzioni con una priorità più bassa verranno eseguite per prime.

Sganciare Funzioni dai Filtri

Come per le azioni, puoi rimuovere le funzioni anche dai filtri. Si esegue questa operazione utilizzando la funzione remove_filter(), che dispone di tre parametri: il nome del filtro, il nome della funzione e la priorità, che è obbligatoria se è già stata impostata quando la funzione era originariamente collegata al filtro.

Per rimuovere la mia funzione new_credits(), userò questo:

1	remove_filter( 'compass_credits_filter', 'new_credits' );

Il codice ripristina il valore specificato nella mia originale funzioneapply_filters(). Così, se voglio rimuovere la funzione new_credits() e non voglio far apparire nulla al suo posto, devo aggiungere una nuova funzione. Sgancio la prima funzione e aggancio la mia nuova funzione in questo modo:

function no_credits() {
    return;
}
remove_filter( 'compass_credits_filter', 'new_credits' );
add_filter( 'compass_credits_filter', 'no_credits' );

Riepilogo

Capire la differenza tra azioni e filtri ed essere in grado di utilizzare efficacemente entrambi darà una spinta al tuo sviluppo di temi e plugin. Infatti, senza l'utilizzo di ganci (azioni e filtri) di almeno un tipo, non è possibile scrivere plugin, l'unico modo in cui il codice del tuo plugin viene attivato è tramite azioni o filtri ai quali è collegato.

Questa guida mostra come aggiungere le stesse funzionalità utilizzando una funzione, un'azione e uno o più filtri, insieme a tecniche per la rimozione delle funzioni e consigli su quando ogni tecnica è più utile.

Così come è possibile agganciare funzioni ad azioni e filtri che si creano, è possibile collegare funzioni alle azioni e ai filtri forniti da WordPress, ad esempio l'azione wp_head o il filtro body_class.