Creare una classe per gestire gli shortcode di WordPress

In questo articolo proseguiremo il discorso su WordPress e l'OOP illustrando il modo con cui creare una classe che gestisca gli shortcode.

Cosa sono gli shortcode

Partiamo dalle basi. Uno shortcode in WordPress (solitamente nella forma [shortcode] non è altro che una macro con cui possiamo inserire nei post e nelle pagine dei frammenti di codice HTML. WordPress individua lo shortcode nel contenuto e lo espande utilizzando la funzione associata al suo nome tramite la funzione del core add_shortcode(). Gli shortcode sono in genere creati da temi o plugin, quando rimuovete un tema o un plugin che ha generato lo shortcode, quest'ultimo viene mostrato non espanso nella sua forma letterale, ossia come [shortcode], infatti gli shortcode vengono sempre salvati in modo letterale nel database, soltanto l'engine di WordPress può espanderli.

Nella sua forma più semplice la registrazione di uno shortcode avviene come segue:

function my_shortcode() {
  $html = '<p>Test.</p>';
  return $html;
}
add_shortcode( 'test', 'my_shortcode' );

Inserendo questo codice nel file functions.php o in un plugin creerete lo shortcode [test] che restituirà la stringa HTML specificata. La cosa fondamentale da capire nel funzionamento degli shortcode è che non dovete mai usare l'operatore echo ma sempre restituire l'output tramite return. Se volete forzare l'esecuzione di uno shortcode nel vostro tema, ossia al di fuori del contenuto dei post o delle pagine, potete usare la funzione do_shortcode():

do_shortcode( 'test' );

Solitamente gli shortcode non sono abilitati nei widget, potrete comunque abilitarli utilizzando il filtro widget_text:

add_filter( 'widget_text', 'do_shortcode' );

Abbiamo sinora visto gli shortcode nella loro forma essenziale, ma gli shortcode possono accettare attributi e contenuto. Gli attributi, nella forma [shortcode attributo="valore"], servono ad inserire delle variabili impostate dall'utente per modificare il comportamento dello shortcode, essi vengono definiti in questo modo:

function my_shortcode( $atts ) {
  extract( shortcode_atts( array(
    'foo' => '',
    'bar' => ''
  ), $atts ) );
$html = '<p class="' . $foo . '" title="' . $bar . '">Test</p>';
return $html;
}
add_shortcode( 'test', 'my_shortcode' );

foo e bar sono i nomi dei nostri attributi che vengono estratti come variabili, ossia come $foo e $bar. Quello che facciamo usando l'array associativo è semplicemente dichiarare dei valori predefiniti nel caso in cui l'utente non ne specifichi nessuno.

Ma gli shortcode possono accettare anche del contenuto, nel qual caso vengono scritti usando una notazione simile ai tag HTML, ossia:

[test]Contenuto[/test]

Data la sintassi peculiare usata da WordPress, che si basa sull'ordine degli argomenti delle funzioni PHP, uno shortcode con contenuto viene definito in questo modo:

function my_shortcode( $atts, $content = null ) {
  $html = '<p>' . $content . '</p>';
  return $html;
}
add_shortcode( 'test', 'my_shortcode' );

Per una panoramica completa sulle API degli shortcode, consultate la documentazione ufficiale di WordPress.

Definire la classe

Paradossalmente il compito più difficile di questa classe non è quello di creare shortcode, quanto piuttosto quello di fare in modo che l'output degli shortcode risulti corretto. Fin dalle origini WordPress ha utilizzato il filtro wpautop per richiamare e gestire la funzione che gestisce la formattazione del contenuto. WordPress è un CMS orientato al blogging. Molti blogger copiano ed incollano testo nell'editor visuale utilizzando semplicemente il tasto Invio per aggiungere la spaziatura verticale.

WordPress interpreta i ritorni a capo in due modi:

1. come paragrafi (elementi p);
2. come interruzioni di riga (elementi br).

Dato che gli shortcode vengono per lo più inseriti nei post e nelle pagine, sono purtroppo comuni due situazioni note:

1. La marcatura degli shortcode viene racchiusa in elementi p.
2. All'interno del contenuto degli shortcode vi sono dei ritorni a capo in eccesso.

Definiamo intanto la nostra classe:

class My_Shortcodes {
  public function __construct() {
    // qui useremo add_shortcode()
  }
}

$myShortcodes = new My_Shortcodes();

Come routine di filtraggio possiamo seguire la soluzione utilizzata nell'articolo Remove Automatic Paragraphs In Shortcodes. In pratica definiamo il seguente metodo:

public function shortcodeUnAutoP( $pee ) {
  // codice dell'articolo
}

Quindi definiamo il nostro metodo come prioritario nel filtro su the_content rimuovendo al contempo il filtro wpautop originale:

public function __construct() {
  remove_filter( 'the_content', 'wpautop' );
  add_filter( 'the_content', 'wpautop' , 99);
  add_filter( 'the_content', array( &$this, 'shortcodeUnAutoP' ), 100 );
}

Il filtro originale ha una priorità pari a 99, ma il nostro filtro ha una priorità pari a 100, quindi verrà eseguito per ultimo scavalcando il filtro originale. Una volta risolto il problema dell'output, possiamo definire i nostri shortcode con facilità:

public function createVimeoVideo( $atts ) {
  extract( shortcode_atts( array(
    'id' => '',
    'width' => '',
    'height' => ''
  ), $atts ) );

$html = '<iframe src="http://player.vimeo.com/video/' . $id . '" width="' . $width . '" height="' . $height . '"></iframe>';
  return $html;
}

E quindi nel costruttore scriveremo:

add_shortcode( 'my-vimeo', array( &$this, 'createVimeoVideo' ) );

Conclusioni

Il problema principale nella creazione degli shortcode è un problema di formattazione del suo output, una volta risolto tale problema, il meccanismo di creazione degli shortcode diviene molto semplice da capire e da implementare.