Le basi dello sviluppo di un plugin di Wordpress

Tutti conoscono l’utilità e la versatilità di Wordpress e la maniera migliore per personalizzare ed utilizzare a proprio piacimento questo strumento è creare dei plugin. Sviluppare un plugin non è difficile e permette di avere del codice che non va ad interferire con il comportamento di Wordpress stesso e contemporaneamente si crea del codice pacchettizzato e facilmente trasportabile in un’altra installazione di Wordpress.

Vediamo in questo breve tutorial la creazione di un plugin, il più minimale possibile e che abbia dentro tutti gli elementi base di un plugin più articolato, cioè:

  • utilizzo del database per la configurazione dei parametri del plugin;
  • schermata di configurazione amministrazione;
  • interazione con il sito pubblico;
  • utilizzo di risorse css/js;
  • codice comune contenente informazioni sul plugin.

Questa breve guida vuole essere solo un’introduzione allo sviluppo dei plugin di Wordpress toccando la maggior parte degli argomenti di base per farsi un’idea di partenza ed evitare di scontrarsi con le difficoltà iniziali che possono insorgere.

Ci sono tanti modi per strutturare un plugin, partire da un framework esistente o modificare un plugin già esistente, in questo caso ho voluto essere il più semplice possibile e ridurre ogni tipo di strutturazione non necessaria.

Innanzitutto questo è il repository con il codice se volete andare a vederne il codice completo.

Vediamo la struttura dei file:

.
├── admin-layout.php
├── content.php
├── static
│   └── style.css
└── timed-popup.php

I file principali sono:

  • admin-layout.php, è il file php che viene visualizzato all’interno dell’admin di Wordpress, la schermata di configurazione del plugin nel wp-admin;
  • content.php, è il file php contentente il codice che va a modificare il sito pubblico Wordpress;
  • timed-popup.php, è il file php principale, nominato con lo stesso nome del nostro plugin per evitare conflitti con altri plugin al momento dell’installazione; il file contiene il codice comune e le informazioni sul plugin. In un plugin ancora più minimale è possibile anche avere solo questo file.

Andiamo a descrivere ognuno di questi file in dettaglio per capire come funziona il plugin e vederlo in azione.

Il file principale (timed-popup.php)

Come potete vedere la prima parte del file consiste in un commento strutturato in maniera particolare contenente diverse informazioni che verranno lette da Wordpress e mostrate all’utente nell’admin.

Una lista completa di queste meta-informazioni è disponibile nella documentazione di Wordpress.

Viene aggiunto un controllo subito dopo che termina l’esecuzione del codice se la costante speciale WPINC non è definita, se non è definita ciò sta a significare che il il file php è stato chiamato direttamente.

Subito dopo è possibile definire delle costanti che possono essere riutilizzate all’interno del plugin, contententi versione e directory del plugin.

La funzione plugin_dir_url restituisce l’URL assoluto del plugin ed è comoda per recuperare velocemente l’url da mostrare delle risorse statiche che verranno utilizzate nel nostro plugin.

Andiamo a registrare le funzioni di attivazione e deattivazione del plugin, che vengono eseguite al momento di installazione e disinstallazione; è buona regola pulire il database ed altri eventuali dati non più utili al momento della disinstallazione.

La funzione register_activation_hook registra la nostra funzione activate_timed_popup per l’hook di attivazione e register_deactivation_hook registra la nostra funzione deactivate_timed_popup per l’hook di disattivazione.

Un hook nel contesto di Wordpress è una funzione che viene chiamata in un determinato momento durante l’esecuzione di Wordpress; è proprio questo meccanismo che permette agli sviluppatori di scrivere dei plugin per Wordpress. Per esempio in questo caso eseguiamo del codice personalizzato, cioè il “comportamento” del nostro plugin al momento della installazione e disinstallazione del plugin.

Nota: esistono due tipi di hooks in Wordpress: actions e filters.

  • I filters sono hook che vengono eseguiti da Wordpress e che vengono utilizzati per ricevere dei dati in input ed eventualmente restituire un valore modificato o per modificare un stato globale.
  • Le actions sono sempre hook chiamati da Wordpress ma che hanno semplicemente il compito di eseguire del codice in un determinato momento; un esempio di actions sono proprio le funzioni che stiamo considerando in questo momento.

In ogni caso ecco una lista di tutte le actions disponibili e di tutti i filters disponibili.

Ora normalmente actions e filters vengono registrati rispettivamente con le funzioni add_action e add_filter, utilizzate in questa maniera:

Dove example_action e example_filter sono le actions e filters predefiniti di Wordpress a cui agganciare le nostre funzioni.

Mentre register_activation_hook e register_deactivation_hook sono delle funzioni wrapper di comodo che aiutano a registrare i nostri hook attivazione e disattivazione, in ogni caso sarebbe stato possibile utilizzare add_action al posto di queste due funzioni.

Ora aggiungiamo la voce di menu del nostro plugin all’admin di Wordpress. Con la funzione add_theme_page è possibile aggiungere la voce di menu direttamente all’interno del sotto-menu Appearance di Wordpress, diversamente avremmo potuto utilizzare add_menu_page per aggiungere la voce direttamente nel menu principale.

In ordine le voci della funzione sono:

  • il testo che Wordpress mostrerà per notificare l’utente della pagina corrente quando il menu è selezionato;
  • il testo da mostrare nel menu;
  • manage_options è il nome di una capability cioè il nome di uno dei permessi standard disponibili agli utenti che accedono all’admin di Wordpress. Se un utente non ha la disponibilità di questa capability non potra accedere al plugin tramite questa voce di menu;
  • lo slug cioè l’identificativo della voce all’interno di questo menu;

Nota: la funzione __ serve per tradurre una stringa tramite i file .po, rimando al sito per ulteriori chiarimenti su questo concetto.

La funzione che aggiunge la voce di menu, cioè la nostra timed_popup_admin_menu che a sua volta chiama add_theme_page, viene chiamata quando l’action admin_menu viene chiamata da Wordpress.

Per questo motivo utilizziamo add_action.

Ora tramite l’action wp_enqueue_scripts aggiungiamo le risorse css/js, quindi quando Wordpress chiama l’action wp_enqueue_scripts significa che ha bisogno di ottenere dal plugin le risorse css/js da aggiungere alla pagina pubblica. Le aggiungiamo con wp_enqueue_style per quanto riguarda i css e wp_enqueue_script per i js. Gli argomenti di queste funzioni in ordine:

  • una stringa identificativa univoca della risorsa che utilizzerà Wordpress;
  • l’url della risorsa, in questo caso costruita aggiungendo l’url assoluto del plugin recuperato prima.

Ora registriamo l’action wp_footer che viene chiamata al momento della chiusura del body dell’html.

Al momento dell’esecuzione di questa action quindi il nostro plugin esegue il require della nostra pagina content.php, cioè aggiunge la nostra personalizzazione alla grafica pubblica del sito web.

Il plugin esegue require però solo quando sono valide alcune condizioni che vado a prendere dalle configurazioni nel db, configurazioni che recupero tramite la funzione get_option. Il valore recuperato viene deserializzato, cioè da una rappresentazione a stringa recupero una struttura dati PHP, un array in questo caso. Rimando alla funzione unserialize sul sito di PHP, essendo unserialize una funzione nativa di PHP.

La voce di menu del plugin nell’admin
La voce di menu del plugin nell’admin

La grafica dell’admin (admin-layout.php)

Da qui in poi la spiegazione tocca solo gli argomenti che riguardano concetti di Wordpress direttamente; la logica del codice è legata al funzionamento di questo particolare plugin, potete prenderla come un punto di partenza per strutturare le parti personalizzabili del vostro plugin.

Metto in alto la parte di logica php di inserimento e recupero dei dati dal database e in basso la parte html della pagina.

Recupero le configurazioni da $_POST.

Dato che $timed_popup_text contiene html e verrà mostrato in un editor wysiwyg è necessario eseguire alcuni filtri sull’input:

  • addslashes aggiunge lo slash alle virgolette;
  • wp_filter_post_kses pulisce l’html in input eliminando html non valido;
  • stripslashes rimuove gli slash dalle virgolette;
  • wpautop funzione opzionale che converte i tag <p> al posto dei tag <br>.

Ora salviamo le configurazioni nel database con update_option con argomenti:

  • nome della configurazione;
  • stringa di configurazione che abbiamo trasformato da array php a stringa con serialize e poi la ritrasformeremo con unserialize.

Recuperiamo la configurazione indipendentemente che sia stata appena salvata in db o meno.

Popolo delle variabili di configurazione.

<div class="wrap">

    <h1><?php _e('Timed popup settings'); ?></h1>
    <p>
        <?php _e('Customize the data to display your timed popup.'); ?>
    </p>

    <form id="timed_popup-admin-form" method="post" action="">

        <table class="form-table">
            <tbody>
                <tr>
                    <th scope="row"><?php _e( 'Popup active' ); ?></th>
                    <td> 
                        <label >
                            <input name="timed_popup_active" type="checkbox" id="users_can_register" <?php echo $timed_popup_active ? 'checked' : ''; ?>>
                            <?php _e( 'Check to enable' ); ?>
                        </label>
                    </fieldset></td>
                </tr>                
                <tr>
                    <th scope="row"><?php _e( 'Display delay in seconds' ); ?></th>
                    <td>
                        <input name="timed_popup_time" type="text" value="<?php echo $timed_popup_time; ?>" class="regular-text" /><br>
                    </td>
                </tr>
                <tr>
                    <th scope="row"><?php _e( 'Text content' ); ?></th>
                    <td>

E mostro una grafica di configurazione dell’admin di Wordpress, i nomi di classi e la struttura sono standard e permettono di avere una grafica uniforme al resto dell’admin.

La funzione _e stampa la stringa tradotta, ancora una volta rimando al sito di Wordpress per quanto riguarda le traduzioni dei plugin.

                        <?php wp_editor( $timed_popup_text, 'timed_popup_text' ); ?>
                    </td>
                </tr>
                <tr>
                    <tr>
                        <td colspan="2">
                            <button class="button button-primary" id="timed_popup-admin-save" type="submit"><?php _e( 'Save', 'timed_popup' ); ?></button>
                        </td>
                    </tr>
                </tbody>
            </table>

        </form>


    </div>

La funzione wp_editor mostra l’editor wysiwyg di default dell’installazione di Wordpress con argomenti:

  • html da visulizzare;
  • id html dell’editor.
La schermata di amministrazione del plugin
La schermata di amministrazione del plugin

La grafica sul sito (content.php)

L’ultima parte è semplice e consiste in codice javascript che mostra un popup con grafica data dal css incluso nel template corrente di Wordpress (vedi wp_enqueue_scripts sopra).

<div class="timed-popup-modal-body">
    <?php echo isset($timed_popup_option['timed_popup_text']) ? $timed_popup_option['timed_popup_text'] : ''; ?>
</div>

Mostro il testo del popup, la variabile $timed_popup_option è stata dichiarata al momento del require di questo file (il content.php) quando è stata eseguita l’action wp_footer (vedi sopra).

<script type="text/javascript">
setTimeout(function(){
    modal.style.display = "block";
},<?php echo isset($timed_popup_option['timed_popup_time']) ? $timed_popup_option['timed_popup_time'] : '0'; ?>*1000);
</script>

Sempre con questa variabile eseguo del codice javascript che mostra il popup.

Il plugin in azione
Il plugin in azione