Utilizzo di filtri personalizzati con codici brevi

Una volta compresa l’ API Shortcode e come funzionano i filtri, è facile implementarli in WordPress.

E quando sei in grado di combinare i due, puoi fare molto di più del solito rispetto a quando funzionano indipendentemente l’uno dall’altro.

In particolare, puoi filtrare i dati che si trovano nel risultato dello shortcode e questo può essere particolarmente utile per altri sviluppatori. Se hai familiarità con l’implementazione di filtri personalizzati, farlo nel contesto di un codice breve non è molto diverso.

Ma se non hai mai utilizzato né l’API shortcode né la funzionalità prima, è comunque facile da fare.

Filtri personalizzati con codici brevi

Per questo post, useremo un esempio relativamente artificioso. Cioè, lo shortcode risulterà in qualcosa di statico. Il motivo è che semplifica la dimostrazione in un post e l’implementazione nel codice.

Lo Shortcode

Per implementare uno shortcode, hai bisogno di due cose:

1. un nome personalizzato per lo shortcode,
2. una funzione che viene utilizzata per inserire informazioni ovunque venga utilizzato lo shortcode.

<?php

namespace Acme;

add_shortcode('a_simple_example', __NAMESPACE__. 'aSimpleExample');
/**
 * Replaces [a_simple_example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 */
function aSimpleExample()
{
  return 'This is the result of an example shortcode.';
}

Nota nel codice sopra; Ho preceduto la funzione con. __NAMESPACE__Questo perché la funzione risiede all’interno di uno spazio dei nomi personalizzato (che puoi vedere nella parte superiore del file).

Senza questo prefisso, la funzione non verrà chiamata. Se si sceglie di non utilizzare gli spazi dei nomi, è possibile rinunciare sia al prefisso che alle barre iniziali del nome della funzione.

Tieni presente che rivisiteremo questa funzione non appena avremo il filtro in posizione.

Il filtro

L’aggiunta di un filtro personalizzato è simile all’aggiunta di uno shortcode. Hai bisogno:

1. un nome di filtro personalizzato,
2. una funzione che viene utilizzata per filtrare le informazioni in entrata (e i filtri dovrebbero generalmente accettare almeno un parametro che è, ovviamente, i dati da filtrare):

Per essere coerenti con l’esempio sopra, diciamo che vogliamo solo sostituire alcune parole nello shortcode :

<?php

namespace Acme;

add_filter('custom_shortcode_example', __NAMESPACE__. 'aSimpleShortcodeFilter');
/**
 * Replaces [a simple example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 *
 * @param string $input the input to filter.
 *
 * @return string       the result of the filter running on the input
 */
function aSimpleShortcodeFilter(string $input): string
{
  return str_ireplace(
    'an example shortcode.',
    'a filtered shortcode',
    $input
  );
}

Questo sostituirà il contenuto di:

Questo è il risultato di uno shortcode di esempio.

Per:

Questo è il risultato di uno shortcode filtrato.

Ma dobbiamo ancora legarli insieme.

Rivisitazione dello Shortcode

Per associare le due funzioni insieme, dobbiamo assicurarci che la funzione per lo shortcode applichi il filtro al valore che restituisce.

Fortunatamente, implementarlo è semplice soprattutto perché abbiamo tutto ciò di cui abbiamo bisogno:

<?php

namespace Acme;

add_shortcode('a_simple_example', __NAMESPACE__. 'aSimpleExample');
/**
 * Replaces [a_simple_example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 */
function aSimpleExample()
{
  return apply_filters('custom_shortcode_example', 'This is the result of an example shortcode.');
}

In un esempio più concreto, consiglio sempre di verificare che il risultato del parametro non sia vuoto, che contenga la stringa che sto cercando o qualcosa di simile.

Cioè, mi piace spesso aprire con una clausola di guardia. Se il test fallisce, restituisco semplicemente il valore in entrata; in caso contrario, filtrerò i dati e restituirò qualunque sia il risultato di tale operazione.