Integrare i plugin con i temi di WordPress

I plugin di WordPress non sono concepiti per essere delle "isole", cioè entità a sé stanti. In WordPress un plugin deve poter interagire con i temi in uso nell'installazione. In questo capitolo vedremo appunto alcuni modi per far si che i nostri plugin si integrino con il tema corrente.

Creare delle API per i temi

Il celebre plugin multilingua WPML a prima vista potrebbe sembrare come un'implementazione monolitica che lascia ben poco spazio all'interazione con il codice esterno dei temi.

In realtà questo plugin, come altri, dispone di API specifiche che permettono agli autori di temi di poter interagire con esso, ad esempio creando un selettore di lingua personalizzato o ottenendo la traduzione di alcune stringhe.

Se osserviamo la pagina dedicata alle API di WPML noteremo che tali interfacce sono state implementate usando due tecniche già utilizzate da WordPress, ossia:

1. action personalizzate;
2. funzioni globali;
3. costanti.

WPML adotta lo stesso approccio di WordPress nella gestione del codice: l'OOP viene usato per gestire tramite classi il funzionamento core del plugin ma non deve essere direttamente invocato nei temi. Al contrario i temi dovranno utilizzare le API pubbliche, ossia le action e le funzioni globali.

Vediamo ora come implementare le nostre API partendo dalle basi, ossia dalle funzioni.

Le funzioni

Le funzioni possono avere o non avere argomenti. Usare funzioni senza argomenti può avere senso se stiamo inserendo del contenuto che non necessita di essere modificato, ma se vogliamo permettere agli autori di temi di gestire il nostro codice con maggiore facilità, allora creare funzioni con argomenti è la scelta consigliata.

Ipotizziamo di avere implementato un plugin che gestisce degli slideshow tramite custom post type e tassonomie. Nella nostra classe core avremo:

class My_Slideshow {
    //...
    public function render( $slideshow ) {
        $args = array(
            'post_type' => 'slides',
            'slideshow' => $slideshow,
            'posts_per_page' => -1
        );
        $loop = new WP_Query( $args );
        if( $loop->have_posts() ) {
           // Crea lo slideshow
        }
     }
}
$mySlideshow = new My_Slideshow();

Possiamo creare una funzione specifica globale che, dato lo slug di una tassonomia, visualizzi uno slideshow specifico nel tema:

function my_slideshow_show( $slideshow ) {
    global $mySlideshow;
    echo $mySlideshow->render( $slideshow );
}

Quindi un autore potrà usare la nostra funzione nel modo seguente all'interno del suo tema:

if( is_home() || is_front_page() ):
    my_slideshow_show( 'main' );
endif;

Quella che abbiamo appena creato è una funzione che agisce direttamente sul tema modificandolo. Possiamo anche creare funzioni che restituiscano un valore impostato nel plugin, ad esempio attraverso le sue opzioni o i suoi custom field (funzioni getter):

function my_slideshow_get_animation_type() {
    $type = get_option( 'my_slideshow_animation_type' );
    return $type;
}

In questo caso l'autore del tema potrà usare il valore restituito per gestire alcune scelte a livello di codice CSS o JavaScript:

$anim_type = my_slideshow_get_animation_type();
if( $anim_type == 'fade' ):
    // Codice
else:
    // Codice
endif;

Le costanti

Il nostro plugin può anche operare tenendo presente le preferenze espresse dall'autore del tema sotto forma di costanti PHP definite nel file functions.php del tema. Dato che le costanti PHP sono immutabili e non possono essere ridefinite, pena un "errore fatale", dobbiamo prima verificare che l'autore del tema le abbia dichiarate:

if( defined( 'MY_SLIDESHOW_NO_PLUGIN_CSS' ) ) {
    if( MY_SLIDESHOW_NO_PLUGIN_CSS ) {
        // Non carichiamo i nostri stili CSS
    } else {
       // Carichiamo i nostri stili CSS
    }
} else {
    // Default
}

In questo caso se la costante MY_SLIDESHOW_NO_PLUGIN_CSS è stata impostata su true non andremo a caricare i nostri stili CSS ma lasceremo all'autore il compito di definire il layout dello slideshow.

Le action

Alla base delle action personalizzate ci sono due funzioni di WordPress:

1. add_action();
2. do_action().

Leggendo la documentazione appare chiaro il motivo per cui abbiamo affrontato le funzioni come primo argomento di questo capitolo: le action personalizzate non sono altro che funzioni che vengono registrate in WordPress tramite add_action() e che poi possono essere eseguite nei temi con la funzione do_action().

Ritornando all'esempio della nostra funzione che visualizza uno slideshow, possiamo quindi ridefinirla come action:

add_action( 'slideshow_show', 'my_slideshow_show', 10, 2 );

La funzione accetta come sappiamo un argomento che però verrà delegato alla funzione do_action():

if( is_home() || is_front_page() ):
    do_action( 'slideshow_show', 'main' );
endif;

In questo modo l'autore del tema ha a disposizione uno strumento ancora più flessibile per interagire con il nostro plugin.