Vuoi capire come funzionano le REST API di WordPress? Provaci con un semplice tutorial!

Le REST API di WordPress consentono di accedere, attraverso delle richieste http, ai dati di un database WordPress in formato JSON. È possibile ottenere i dati relativi a post, categorie, pagine, utenti, tag, tassonomie, commenti, media e post types.

Se già confuso? Proviamo con un esempio.

Apri un’altra finestra del browser e digita il seguente indirizzo: https://www.alessandrocosta.pro/wp-json/wp/v2/posts. Il browser ti restituirà i dati dei 10 articoli più recenti del mio sito, in formato JSON. Poichè il browser non è in grado di visualizzare i dati JSON in un formato facilmente leggibile dagli esseri umani, ti suggerisco di scaricare l’applicazione Postman ed utilizzarla per continuare questo tutorial. Nella schermata principale di Postman, accanto alla voce GET, incolla l’indirizzo che ti ho fatto scrivere prima e clicca su send.

immagine della schermata dell'applicazione Postman

Adesso la situazione è molto più chiara! Se hai un minimo di dimestichezza con JSON, puoi facilmente notare dieci oggetti contenenti i dati degli ultimi post, tra cui l’Id, la data di pubblicazione, il titolo e molto altro.

Facciamo qualche altra prova, supponiamo che ti occorrano i dati di un articolo in particolare, contrassegnato dall’Id n. 698. Per ottenerli basta inserire questo indirizzo:

https://www.alessandrocosta.pro/wp-json/wp/v2/posts/698

ed otterrai i dati del singolo articolo 698.
Oppure ti servono tutti i post appartenenti alla categoria con id n. 1? Semplice, basta digitare

https://www.alessandrocosta.pro/wp-json/wp/v2/posts?categories=1

Quello che voglio dire è che tutti i dati che fino ad oggi hai ottenuto attraverso delle query in linguaggio php (la classe WP_Query ti ricorda qualcosa?), adesso puoi ottenerli tramite delle semplici richieste http. Questo significa che possiamo creare dei siti basati su WordPress ma che utilizzano linguaggi di programmazione diversi dal php, che fino ad oggi è stato la base di questo CMS. Per darti un’idea, adesso procederemo con un piccolo tutorial che ti consentirà di visualizzare gli articoli correlati ai post, cioè quelli appartenenti alla medesima categoria del post visualizzato sullo schermo, utilizzando le rest api. In altre parole, i post che vedremo sullo schermo non saranno generati con codice php, ma con javascript!

Tutorial: visualizzare gli articoli correlati grazie alle REST Api

Lo scopo di questo tutorial è quello di visualizzare alla fine di ciascun post gli articoli correlati al post medesimo.

I passi da seguire per raggiungere il nostro obiettivo sono i seguenti:

  • creare un div contenitore al cui interno andremo ad inserire i post correlati;
  • ricavare i dati necessari per il funzionamento delle funzioni javascript. Otterremo questi dati tramite alcune funzioni WordPress e li trasferiremo al file javascript;
  • Utilizzare jQuery e ajax per caricare i dati dei post correlati e visualizzarli sulla pagina.

Per fare questo ho predisposto un tema child del tema twentysixteen, che puoi scaricare da qui.

Il tema originale evidenzia alla fine di ciascun post una sezione navigazione per muoversi tra i post precedenti e successivi. Con questo tutorial aggiungeremo gli articoli correlati appena al di sotto della suddetta navigazione. Per capire meglio cosa intendo dire puoi dare un’occhiata alle immagini che seguono, che evidenziano la differenza tra il tema originale ed il tema child.

il layout originale del tema twentysixteen
il tema child incude i link ai post correlati

Il tema comprende i seguenti file:

  • il file style.css, che contiene soltanto alcune righe css per rendere visivamente apprezzabile il risultato finale, sulle quali non ci soffermeremo;
  • il file functions.php che contiene alcune istruzioni necessarie al funzionamento delle istruzioni javascript;
  • il file single.php, che modifica leggermente il layout del singolo post del tema genitore;
  • il file rest.js, contenuto all’interno della cartella js, che contiene le istruzioni javascript necessarie al caricamento dei post correlati.

Iniziamo con l’esaminare il file single.php. Rispetto all’originale del tema Twentysixteen, differisce soltanto per queste due righe di codice, inserite subito dopo la funzione the_post_navigation()

<div id='related' class="post-navigation"></div>
<div id='placeholder'></div>

Il div #related è quello che andrà a contenere i post correlati, mentre il div #placeholder è un elemento segnaposto che ha il solo scopo di determinare il momento in cui fare apparire i post correlati. In altre parole, il caricamento dei nuovi post avverrà soltanto quando il div #placeholder sarà visibile sullo schermo.

Adesso occupiamoci del file functions.php, aprilo e troverai soltanto due funzioni:

//funzione per ottenere l'id della categoria del post
function restApiTut_get_category_id() {
    
    $category = get_the_category();
    $category_id = $category[0]->term_id;
    return $category_id;
}

add_action('wp_enqueue_scripts', 'restApiTut_scripts');
function restApitut_scripts(){
   
    if(is_single()){
         // Includiamo il file javascript    
        wp_enqueue_script('restApiTut-js', get_theme_file_uri('js/rest.js'), array('jquery'), '0.1', true);
        
        // Trasferiamo i dati al file Javascript    
        wp_localize_script('restApiTut-js', 'postdata',
            array(
                'rest_url' => rest_url('/wp/v2/'),
                'category_id' => restApiTut_get_category_id(),
            ));
    }
   
}

 

Il file functions.php ha lo scopo di ottenere dei dati da WordPress con  il consueto linguaggio php e trasferire tali dati al file javascript che utilizzaremo in questo tutorial. Questo perchè ci sono dei dati che javascript non può ricavare da solo, come ad esempio l’url del nostro sito, per cui dobbiamo prima ottenerli attraverso il linguaggio php.

La prima funzione all’interno del file, restApiTut_get_category_id(), ha lo scopo di ottenere l’id della prima categoria alla quale appartiene il singolo post visualizzato sullo schermo.  Tale categoria viene assegnata alla variabile $category_id, che utilizzaremo tra poco. L’altra funzione del file, restApiTut_scripts(), contiene innanzitutto le istruzioni per caricare il file rest.js con la classica istruzione wp_enqueue_script. Inoltre troviamo un’altra istruzione, meno conosciuta della precedente, wp_localize_script(), che ha lo scopo di comunicare alcuni dati  al file javascript rest.js. I dati in questione sono inseriti all’interno di un array contenente due elementi:

 

array(
      'rest_url' => rest_url('/wp/v2/'),
      'category_id' => restApiTut_get_category_id(),
));

Nella variabile rest_url memorizziamo l’url del nostro sito, mentre nella variabile category_id memorizziamo l’id della categoria del singolo articolo che abbiamo ricavato attraverso la funzione restApiTut_get_category_id(), come detto sopra.

Il codice javascript necessario per utilizzare i dati forniti dalle REST API

Apriamo adesso il file rest.js e vediamo che come le prime righe di codice servono appunto ad assegnare alle variabili i dati che abbiamo appena trasferito con il file functions.php

 

var rest_url = postdata.rest_url;
var category_id = postdata.category_id;

Creiamo inoltre una variabile myCounter alla quale assegniamo il valore 1, che utilizzeremo successivamente per incrementare la paginazione.
Creiamo adesso la prima funzione javascript, category_post_starter(), che ha lo scopo di impostare il momento in cui la pagina comincerà a visualizzare gli articoli correlati. Dobbiamo fare in modo che tali articoli vengano visualizzati soltanto quando l’utente arriva alla fine della pagina, ed il div#placeholder venga visualizzato sullo schermo.

function category_post_starter() {
        
        var $placeholder = $('#placeholder');
        var starter_position = $placeholder.offset().top + 100 - $(window).outerHeight();
    
        $(window).scroll(function(event){
            
            if(starter_position > $(window).scrollTop()){
                return;    
            }
            get_category_post();
            
            $(this).off(event);
        })
        
}

category_post_starter();

Esaminiamo nel dettaglio la funzione: assegniamo alla variabile $placeholder il div #placeholder che abbiamo aggiunto al file single.php, come abbiamo visto sopra.
Assegniamo alla variabile starter_position la differenza tra la posizione del div#placeholder (aumentato di 100 pixel) e la dimensione dell’altezza dell’elemento window.
Dopodichè, ogni volta che la pagina scrolla verso il basso, diciamo al browser di verificare se il div #placeholder è visibile o meno sullo schermo, facendo un confronto tra il valore di starter_position e il valore restituito dalla funzione scrollTop dell’elemento window: Se il valore di starter position è maggiore di quest’ultimo, cioè se il div #placeholder è più in basso rispetto alla porzione di schermo attualmente visibile, fermiamo la funzione con l’istruzione return; se invece il valore è minore, cioè se il div#placeholder è visibile sullo schermo, chiamiamo la funzione get_category_post(). L’ultima istruzione $(this).off(event) serve a terminare l’evento ed evitare che la funzione get_category_post venga richiamata altre volte. A questo punto chiamiamo per la prima volta la funzione category_post_starter() appena dichiarata.

Occupiamoci adesso della funzione get_category_post(), appena invocata dalla funzione category_post_starter()

function get_category_post() {
        
        var json_url = rest_url + 'posts?&categories=' + category_id + '&page=' + myCounter;
        
        $.ajax({
            dataType: 'json',
            url: json_url,
        })
        
        .done(function(myPosts) {
            list_post(myPosts);
            myCounter++;
        })
       
        .fail(function(){
            console.log('Connection error');
        })
        
        .always(function(){
            console.log('End ajax');
        });
        
    }

L’elemento fondamentale di questa funzione è la variabile json_url, alla quale assegniamo l’indirizzo http da richiedere tramite JSON. È questa la richiesta http che restituirà i dati (in formato JSON) che ci servono per visualizzare i post correlati. La richiesta http che assegniamo alla variabile json_url è formata da diverse componenti:

  • la variabile rest_url, ottenuta tramite la funzione restApiTut_scripts del file functions.php, che corrisponde a www.miosito.com/wp-json/wp/v2/
  • /posts? Sono i post del sito;
  • aggiungiamo la categoria dei post che ci interessa con &categories= e la category_id che abbiamo ricavato tramite la funzione restApiTut_scripts del file functions.php
  • &page= + myCounter, cioè la pagina, che attualmente è la n. 1 in quanto la variabile myCounter ha attualmente il valore 1.

Una volta impostata la richiesta http, possiamo creare la richiesta ajax, che ha come url la variabile json_url appena esaminata.

Se la richiesta ajax è andata a buon fine chiamiamo la funzione list_post(), il cui parametro è l’oggetto json restituito da ajax. Inoltre incrementiamo di una unità il valore della variabile myCounter, affinchè la prossima chiamata della funzione restituisca la pagina successiva della lista dei post. Infine impostiamo dei messaggi da visualizzare nella console javascript nel caso in cui la richiesta ajax non sia andata a buon fine, ed anche alla fine della chiamata ajax.

L’ultima funzione di cui dobbiamo occuparci è quella incaricata di creare il codice html necessario alla visualizzazione dei post correlati.

function list_post(postData) {
        
        // viene create la variabile htmlContent al quale viene assegnato un valore vuoto
        var htmlContent = '';
        
        
        for (var i = 0; i < postData.length; i++) {
            
            htmlContent += '
<div class="nav-next">';
            htmlContent += '<a href="' + postData[i].link + '">';
            htmlContent += '<span class="meta-nav">Related article</span>';
            htmlContent += '<span class="screen-reader-text">Related article:</span>';
            htmlContent += '<span class="post-title">' + postData[i].title.rendered + '</span></a></div>

';
        }
        
       $('#related').append(htmlContent);
        
       category_post_starter();
    }

Il parametro postData della funzione list_post è costituito dai post ottenuti con la chiamata ajax.
Dichiariamo la variabile htmlContent, alla quale assegniamo inizialmente una stringa vuota. Dopodichè creiamo un ciclo for che si ripeterà tante volte quanti sono i post restituiti da JSON. Per ogni post creiamo un div con un link al post ed il relativo titolo. Alla fine del ciclo for, inseriamo il contenuto della variabile htmlContent all’interno del div #related.
Alla fine della funzione sono stati creati i post relativi alla prima pagina della richiesta http. Dobbiamo verificare se ve ne siano di altri nelle pagine successive, perciò chiamiamo nuovamente la funzione category_post_starter() per ricominciare da capo. Poichè adesso il valore di myCounter è stato incrementato di una unità la nuova richiesta http non sarà identica alla prima ma richiederà la pagina successiva.

Quello che abbiamo visto in questo tutorial è solo la punta dell’iceberg, ci siamo limitati a richiamare alcuni dati, mentre con le REST API è possibile anche creare, modificare e cancellare i dati del database di WordPress ma di questo ci occuperemo in un prossimo articolo.

Se hai dubbi su quello di cui ti ho parlato oppure hai qualcosa da aggiungere scrivilo pure nei commenti!

2 commenti su “Vuoi capire come funzionano le REST API di WordPress? Provaci con un semplice tutorial!”

  • Fausto ha commentato il :

    Post veramente notevole, complimenti.
    Mi puoi fare altri esempi pratici in cui può essere davvero utile utilizzare REST API? Grazie

    • alessandro ha commentato il :

      Ciao Fausto, a mio parere le REST API possono essere davvero utili all’interno di web applications create con moderni framework javascript, come ad esempio Angular.js. Tutto il front-end dell’applicazione potrebbe essere gestito tramite Angular mentre il back-end potrebbe funzionare tramite il classico pannello di amministrazione di WordPress. Io stesso sto lavorando ad una cosa del genere e mi propongo di scrivere un articolo appena possibile!

    I commenti sono chiusi