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 [test] mai echo 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 contenuto [shortcode attributo="valore"]

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 bar $foo $bar

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

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

Quindi definiamo il nostro metodo come prioritario nel filtro su the_content wpautop

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.