Come accedere e analizzare i blocchi di Gutenberg con PHP

In questo post vedremo come analizzare i blocchi Gutenberg di un post ed estrarre blocchi specifici per creare qualcos’altro. Esamineremo le funzioni PHP di WordPress per l’analisi, l’estrazione e il rendering dei blocchi scelti.

Uno dei vantaggi del nuovo editor Gutenberg in WordPress sono dati più strutturati per i contenuti dei post. In passato tutto era archiviato come HTML e non c’era modo di estrarre contenuti specifici senza alcune espressioni regolari molto complesse. Ma con Gutenberg ogni contenuto, sia esso un paragrafo, un’intestazione, un’immagine, un video, un pulsante o una colonna che contiene altri blocchi al suo interno, viene archiviato con informazioni che ci dicono qual è questo contenuto.

Con le funzioni integrate di WordPress è molto facile recuperare tutti i blocchi nel contenuto di un post in un array con tutte le loro informazioni. Questo apre un sacco di funzioni utili per gli sviluppatori di temi. Solo per citare alcune idee:

• Genera dinamicamente un sommario recuperando tutte le intestazioni (tutorial di seguito).
• Recupera tutti i video, le immagini o le citazioni utilizzati in tutti i post per raccoglierli ed elencarli tutti in un’altra pagina.
• Estrai il primo paragrafo di un post e usalo come estratto negli archivi (tutorial sotto).
• Ottieni una panoramica dell’uso di blocchi specifici e della loro posizione. Ad esempio, supponiamo che tu abbia un Blocco annunci personalizzato e devi sapere con quale frequenza viene utilizzato nei tuoi post e fino a che punto appaiono nel contenuto.
• Visualizza i blocchi di un post ma escludi tipi di blocchi specifici.
• Controlla se il contenuto di un post inizia con un video e usa quel video invece dell’immagine in primo piano negli archivi.
• Se utilizzi un blocco personalizzato che contiene le specifiche tecniche sui prodotti, puoi facilmente creare una pagina che visualizza e confronta le specifiche tecniche tra i post dei prodotti.
• Raccogli dinamicamente tutte le singole immagini utilizzate in un post e genera una galleria di esse alla fine o altrove.

Diamoci dentro!

Analizza i blocchi di un post

Per analizzare i blocchi utilizziamo la funzione WordPress [parse_blocks](https://developer.wordpress.org/reference/functions/parse_blocks/)(). Come parametro devi fornire una stringa del contenuto di un post. Se sei all’interno di un loop o hai accesso a un oggetto post, fornisci semplicemente $post->post_contentcome parametro alla funzione.

Il ritorno da parse_blocks()è un array in cui ogni elemento dell’array è un blocco. Per ogni elemento del blocco hai informazioni come il tipo di blocco (tasto ‘ blockName‘), gli attributi del blocco (tasto ‘ attrs‘), i blocchi interni per i blocchi nidificati come Colonne (tasto ‘ innerBlocks‘) e due elementi per il contenuto effettivo del blocco (chiavi ‘ innerHTML‘ e ‘ innerContent‘). L’elemento innerHTMLè una stringa di contenuto HTML, mentre innerContentè un array di stringhe HTML.

E questo è tutto! Passa attraverso l’array restituito da parse_blocks()per fare le tue cose. Vedremo altri esempi di codice di questo più in basso in questo post.

Una nota sui post classici (non Gutenberg).

Potresti lavorare su un vecchio sito WordPress che ha creato post prima di eseguire l’aggiornamento a Gutenberg (o utilizzato un plugin Disable Gutenberg). In questo caso questi post non avranno un contenuto strutturato, ma l’intero contenuto del post è all’interno di un blocco "Editor classico".

L’array restituito dalla funzione parse_blocks()su questo tipo di post restituirà un elemento dell’array di blocchi con blockNameset to null. Il contenuto HTML completo del post è all’interno della innerHTMLstringa di questo elemento.

Possiamo tranquillamente presumere che se il ritorno di un post parse_blocks()ha un elemento ed blockNameè null, abbiamo a che fare con un post "pre-Gutenberg". Altrimenti blockNamesarà sempre popolato. Questo è un buon controllo da tenere a mente quando si scrive il codice per analizzare i blocchi dei post e si desidera gestire i contenuti WordPress meno recenti.

Rendi un blocco

WordPress offre anche una funzione per eseguire il rendering di un blocco specifico con [render_block](https://developer.wordpress.org/reference/functions/render_block/)(). Come parametro è necessario fornire un array per un blocco, proprio come uno di quelli restituiti parse_blocks()dall’alto. La funzione restituisce una stringa di HTML renderizzato che puoi semplicemente richiamare direttamente.

Il codice sopra visualizzerà tutti i blocchi del post, proprio come farebbe normalmente durante il rendering del contenuto del post. La parte divertente arriva quando iniziamo ad aggiungere codice per escludere o includere blocchi specifici che ci interessano.

Ad esempio, il codice seguente stamperà solo i blocchi di paragrafo del post:

foreach ($blocks as $block) {
    if ($block['blockName'] == 'core/paragraph') {
        echo render_block($block);
    }
}

E questo renderà tutti i blocchi, ma escluderà tutti i blocchi shortcode:

foreach ($blocks as $block) {
    if ($block['blockName'] != 'core/shortcode') {
        echo render_block($block);
    }
}

Blocca i nomi

Quando analizzi i blocchi di un post, molto probabilmente dovrai controllare il tipo di blocco. Sono abbastanza semplici da indovinare. Ad esempio, un blocco di paragrafo è, hai indovinato, paragraph. Tuttavia, tieni presente che tutti i blocchi Gutenberg in WordPress sono preceduti da uno spazio dei nomi. Per i blocchi principali di WordPress (predefiniti), sono tutti preceduti da " core/". L’eccezione sono i blocchi Embed che sono preceduti da ” core-embed/“. Quindi, ad esempio, un blocco di paragrafo avrà il nome del blocco core/paragraph.

Per evitare ipotesi selvagge, ecco una panoramica dei blocchi predefiniti forniti da WordPress (al momento della stesura di questo):

Blocchi comuni

• Paragrafo:core/paragraph
• Immagine:core/image
• Intestazione:core/heading
• Galleria:core/gallery
• Elenco:core/list
• Citazione:core/quote
• Audio:core/audio
• Coperchio:core/cover
• File:core/file
• Video:core/video

Formattazione

• Preformattato:core/preformatted
• Codice:core/code
• Classico: core/freeform
  (ma per i post non Gutenberg sarà null, vedi la nota sui post non Gutenberg)
• HTML personalizzato:core/html
• Citazione:core/pullquote
• Tavolo:core/table
• Versetto:core/verse

Disposizione

• Pulsante:core/button
• Colonne:core/columns
• Di più:core/more
• Interruzione di pagina:core/nextpage
• Separatore:core/separator
• Distanziatore:core/spacer
• Media e testo:core/media-text

Widget

• Codice corto:core/shortcode
• Archivi:core/archives
• Categorie:core/categories
• Ultimi commenti:core/latest-omments
• Ultimi post:core/latest-posts

Incorpora

• Incorporare:core/embed

• Twitter:core-embed/twitter

• Youtube:core-embed/youtube

• Facebook:core-embed/facebook

• Instagram:core-embed/instagram

• WordPress:core-embed/wordpress

• SoundCloud:core-embed/soundcloud

• Spotify:core-embed/spotify

• Flickr:core-embed/flickr

• Vimeo:core-embed/vimeo

• Animato:core-embed/animoto

• Cloudup:core-embed/cloudup

• Segnale di massa:core-embed/crowdsignal

• Movimento quotidiano:core-embed/dailymotion

• Hulu:core-embed/hulu

• Imgur:core-embed/imgur

• Problema:core-embed/issuu

• Kickstarter:core-embed/kickstarter

• Meetup.com:core-embed/meetup-com

• Mixcloud:core-embed/mixcloud

• Reddit:core-embed/reddit

• ReverbNation:core-embed/reverbnation

• Screencast:core-embed/screencast

• Scribd:core-embed/scribd

• Condivisione diapositive:core-embed/slideshare

• Tazza compiaciuta:core-embed/smugmug

• Piattaforma degli altoparlanti:core-embed/speaker

• TED:core-embed/ted

• Tumblr:core-embed/tumblr

• Videostampa:core-embed/videopress

• wordpress.tv:core-embed/wordpress-tv

• Amazon Kindle:core-embed/amazon-kindle

Esempio di codice: recupera il primo paragrafo di un post come estratto

Un post ben scritto dovrebbe iniziare con un paragrafo che introduca di cosa tratta il post e inviti le persone a continuare a leggere. Questi sono perfetti da usare come estratti invece di fare affidamento sulla funzione di estratto automatico in WordPress!

Questa è una funzione che puoi aggiungere al tuo tema functions.phpche restituirà il primo paragrafo di un post. Se non è stato fornito alcun post, farà riferimento all’oggetto post globale. Accoglie anche post non Gutenberg restituendo l’effettivo estratto di WordPress per quelli.

Dopo la parse_blocks()chiamata della funzione controlliamo se il post ha o meno dati di blocco non validi (il post è stato creato prima di Gutenberg) e restituiamo un estratto del post in tal caso. Altrimenti andiamo in rassegna i blocchi del post, troviamo il primo blocco di paragrafo e restituiamo il suo innerHTML. Alla fine restituiamo una stringa con (questo è facoltativo) a <div>attorno ad essa.

Per utilizzare questa funzione è sufficiente chiamare:

echo awp_get_excerpt();

Supponendo che la chiamata di funzione sia collocata da qualche parte c’è un $postoggetto globale, ad esempio all’interno di un ciclo. Se vuoi specificare un post, fornisci l’oggetto post come parametro per la chiamata di funzione:

$post_id = 1;
$post = get_post($post_id);
echo awp_get_excerpt($post);

Esempio: crea un sommario dalle intestazioni di un post

Puoi generare automaticamente e dinamicamente un sommario basato sui blocchi di intestazione di un post. Il processo è abbastanza semplice; analizza i blocchi del post e trova tutti i blocchi di tipo core/heading. Ma possiamo fare un ulteriore passo avanti e incorporare i livelli; es. mettendo h3come sottotitolo sotto h2e così via.

Un blocco di intestazione contiene informazioni sul suo livello nell’elemento dell’array di attributi (tasto ‘ attrs‘). All’interno attrsdell’array sarebbe un elemento dell’array con la chiave ‘ level‘ e un numero intero che indica il livello. A h3avrebbe ‘ level‘ valore di 3, a h4avrebbe ‘ level‘ di 4, e così via.

Tuttavia, tieni presente che attrsper i blocchi di intestazione possono essere vuoti! Ciò accade quando l’autore non ha modificato il tipo di intestazione lontano dai valori predefiniti nelle impostazioni del blocco. Per aggirare questo problema, dobbiamo fare alcune ipotesi. Come saranno i titoli predefiniti h2(a meno che tu non lo abbia modificato nel tuo tema). Quindi possiamo presumere che se un blocco di intestazione non ha un attributo di livello, è un h2. Altrimenti otteniamo le informazioni sul livello dagli attributi.

Se sei davvero all’altezza della sfida, ti invito a migliorare il codice qui sotto. Il problema della generazione di un elenco strutturato adeguato olè che non possiamo controllare come l’autore struttura i propri titoli. Potrebbero benissimo impazzire e iniziare con h4un’intestazione e passare direttamente a h2un’intestazione subito dopo. E all’improvviso si mescolano a h1nel mezzo. La mia soluzione prevede quindi la generazione di un olelenco semplice e la fornitura delle informazioni di livello nelle classi dell’elemento dell’elenco. Quindi con alcuni CSS intelligenti puoi indentare gli elementi dell’elenco di conseguenza con un po’ di riempimento sinistro.

Il codice

Ecco la funzione del sommario:

La funzione inizia con la gestione del post e l’analisi dei suoi blocchi. In linea #9accogliamo posti non Gutenberg. La funzione continua a scorrere tutti i blocchi e ogni volta che trova un blocco di intestazione viene aggiunto al nostro $headingsarray. Usiamo [wp_strip_all_tags](https://developer.wordpress.org/reference/functions/wp_strip_all_tags/)()per rimuovere i tag HTML dai titoli. Aggiungiamo anche le informazioni sul livello al nostro array, dove il valore predefinito è impostato su 2se gli attributi sono vuoti.

Dopo il ciclo del blocco, l’ $headingsarray dovrebbe contenere tutte le intestazioni del post, in ordine. Possiamo quindi semplicemente generare una stringa HTML e visualizzarne il contenuto. Come accennato, genero un nome di classe su ogni elemento con informazioni sul livello dell’intestazione in modo da poter creare l’illusione di un elenco strutturato con CSS.

Come con la funzione excerpt sopra, possiamo chiamare questa funzione quando siamo all’interno del ciclo in questo modo:

echo awp_table_of_contents();

Oppure se siamo fuori dal ciclo o vogliamo specificare un post;

$post_id = 1;
$post = get_post($post_id);
echo awp_table_of_contents($post);

Questo genererà un elenco simile a questo:

Conclusione

Come abbiamo visto con i contenuti ricchi strutturati dei post resi possibili con Gutenberg, possiamo trovare ed estrarre molto facilmente parti specifiche del contenuto dei post. Fare riferimento all’elenco di esempi che ho citato all’inizio del post. Non ci sono limiti a ciò che tu come sviluppatore di temi puoi fare. Dipende solo da ciò di cui il tuo tema o sito WordPress ha bisogno (o da cosa sarebbe semplicemente fantastico).