Tra i tanti motivi che rendono WordPress un punto di riferimento tra i CMS vi è anche il fatto che contiene un ampio elenco di API per l’esecuzione di operazioni comuni in un sito.

Per esempio, alcune di queste favoriscono l’interazione con il database, mentre altre permettono di creare delle immagini responsive.

È però questo solo piccolo esempio: frugando un po’ in rete si troverà infatti un’API pronta a fare praticamente tutto quello che ti serve.

Ecco dunque che, nella nostra guida odierna, abbiamo voluto fare il punto su questo tema. Scopriamo insieme di che si tratta e come sfruttare al meglio questa caratteristica!

Cos’è l’API Dashboard Widgets

Per entrare con la giusta consapevolezza all’interno di questo ambito di analisi, iniziamo con il definire l’API Dashboard Widgets come una serie di funzioni che consentono di aggiungere, rimuovere e modificare i widget che appaiono nella Dashboard di WordPress.

Si tratta di un servizio piuttosto utile se si desidera un modo diretto di interagire con gli utenti, sia per mostrare loro informazioni che per consentire loro di eseguire azioni specifiche.

Proviamo a fare un esempio di widget personalizzati prendendo come riferimento il plugin Jetpack, che aggiunge un widget che mostra le statistiche del sito e i post e le pagine più importanti.

Il plugin Seriously Simple Stats per Seriously Simple Podcasting mostra invece le statistiche degli episodi e include anche un widget per il feed RSS di Castos news, la società che possiede e sviluppa il Seriously Simple Podcasting.

Gli esempi sono naturalmente infiniti. Ai nostri fini, però, ora ci interessa capire come utilizzarla.

logo wordpress

Come utilizzare l’API Dashboard Widgets

Dalla versione 2.7 di WordPress in poi, l’API Dashboard Widgets rende molto semplice l’aggiunta di nuovi widget alla dashboard di amministrazione di WordPress.

La funzione principale da conoscere è la funzione wp_add_dashboard_widget(), che accetta una serie di parametri:

  • $widget_id – un ID univoco per il widget, utilizzato anche come attributo id nell’output HTML del widget;
  • $widget_name – il nome del widget;
  • $callback – la funzione che sarà richiamata per produrre il contenuto del widget.

Inoltre, ci sono alcuni parametri opzionali che si possono specificare ulteriormente, come:

  • $control_callback – una funzione opzionale che sarà chiamata per emettere i controlli che configurano i dati per il widget e per elaborare i dati inviati dai controlli;
  • $callback_args – un array opzionale di argomenti che saranno passati alla funzione di callback;
  • $context – una stringa opzionale che definisce la colonna in cui il widget sarà mostrato. Il valore predefinito è “normal”, ma si può optare anche per “side”, “column3” e “column4”;
  • $priority – una stringa opzionale che definisce la priorità del widget all’interno del contesto. L’impostazione predefinita è “core”, ma altre opzioni includono “default”, “high” e “low”.

Per capire come funziona, costruiamo un esempio di widget per la dashboard di WordPress.

Creare un widget per la dashboard di WordPress

Per iniziare, creiamo una nuova cartella di plugin e un file PHP di plugin nella cartella wp-content/plugins. Per questo esempio, la chiameremo wp-learn-dashboard-widgets.

Affinché questo plugin venga riconosciuto come plugin di WordPress, è necessario aggiungere un’intestazione del plugin, con almeno un valore per il nome del plugin.

Come per la maggior parte delle API di WordPress, si inizierà agganciandosi a un’azione. In questo caso, si utilizza l’azione wp_dashboard_setup, che viene attivata quando la dashboard viene inizializzata. È qui che si aggiungerà il nostro widget.

add_action( ‘wp_dashboard_setup’, ‘wp_learn_dashboard_widget’ );

function wp_learn_dashboard_widget(){

wp_add_dashboard_widget(

‘wp_learn_dashboard_widget’,

‘Learn WordPress Dashboard Widget’,

‘wp_learn_dashboard_widget_callback’

);

}

function wp_learn_dashboard_widget_callback(){

echo ‘<p>Hello, World!</p>’;

}

Se si aggiunge questo codice al file vuoto del plugin, si attiva il plugin e si carica la dashboard, si vedrà il widget in fondo alla prima colonna della dashboard.

Naturalmente, si può godere di molta flessibilità con la funzione di richiamo del contenuto, a patto che trasmetta un HTML valido. Prova per esempio ad aggiungere un elenco dei post più recenti al widget, utilizzando la funzione wp_get_recent_posts().

function wp_learn_dashboard_widget_callback(){

$args = array(

‘numberposts’ => 5,

‘post_status’ => ‘publish’

);

$recent_posts = wp_get_recent_posts( $args );

echo ‘<ul>’;

foreach( $recent_posts as $recent ){

echo ‘<li><a href=”‘ . get_permalink( $recent[‘ID’] ) . ‘”>’ . $recent[‘post_title’] . ‘</a></li>’;

}

echo ‘</ul>’;

}

Come aggiungere un controllo al widget

È anche possibile aggiungere alcuni controlli per configurare il widget. Supponiamo di voler controllare quanti post vengono visualizzati. Per farlo, configurare la funzione di callback del controllo. Aggiungiamo così una funzione chiamata wp_learn_dashboard_widget_control() per elaborare i dati.

function wp_learn_dashboard_widget_control(){

echo ‘<label>Enter number of posts to display</label>’;

echo ‘<input type=”text” name=”wp_learn_dashboard_widget_numberposts”/>’;

}

Quando si aggiorna la dashboard, apparentemente potrebbe sembrare che non accada nulla. Tuttavia, se si passa il mouse sul widget, si vedrà apparire un nuovo link con la dicitura “Configura”. Facendo clic su questo link, si visualizzerà il modulo appena creato.

A questo punto è necessario aggiornare il callback del controllo per elaborare i dati inviati dal modulo. Per salvare i dati, utilizza la funzione update_option(), che memorizzerà il valore nella tabella delle opzioni.

function wp_learn_dashboard_widget_control_callback(){

if (isset($_POST[‘wp_learn_dashboard_widget_numberposts’])){

update_option( ‘wp_learn_dashboard_widget_numberposts’, sanitize_text_field( $_POST[‘wp_learn_dashboard_widget_numberposts’] ) );

}

$number_posts = get_option( ‘wp_learn_dashboard_widget_numberposts’, 5 );

echo ‘<label>Enter number of posts to display</label>’;

echo ‘<input type=”text” name=”wp_learn_dashboard_widget_numberposts” value=’.$number_posts.’ />’;

}

Quindi, sarà necessario tornare alla funzione di callback del contenuto e aggiornare l’array $args per utilizzare il valore appena salvato. Per recuperare il valore, si può usare la funzione get_option().

function wp_learn_dashboard_widget_callback(){

$numberposts = get_option( ‘wp_learn_dashboard_widget_numberposts’, 5 );

$args = array(

‘numberposts’ => $numberposts,

‘post_status’ => ‘publish’

);

$recent_posts = wp_get_recent_posts( $args );

echo ‘<ul>’;

foreach( $recent_posts as $recent ){

echo ‘<li><a href=”‘ . get_permalink( $recent[‘ID’] ) . ‘”>’ . $recent[‘post_title’] . ‘</a></li>’;

}

echo ‘</ul>’;

}

Per saperne ancora di più, vai sul sito developer.wordpress.org e poi nella sezione delle API Widgets.