Comment accéder et analyser les blocs Gutenberg avec PHP

Dans cet article, nous verrons comment analyser les blocs Gutenberg d’un article et extraire des blocs spécifiques pour créer autre chose. Nous examinerons les fonctions PHP de WordPress pour l’analyse, l’extraction et le rendu des blocs choisis.

L’un des avantages du nouvel éditeur Gutenberg dans WordPress est des données plus structurées pour le contenu des publications. Autrefois, tout était stocké au format HTML et il n’y avait aucun moyen d’extraire des éléments de contenu spécifiques sans quelques expressions régulières très complexes. Mais avec Gutenberg, chaque élément de contenu, qu’il s’agisse d’un paragraphe, d’un titre, d’une image, d’une vidéo, d’un bouton ou d’une colonne contenant d’autres blocs, est stocké avec des informations qui nous indiquent ce qu’est cet élément de contenu.

Avec les fonctions WordPress intégrées, il est très facile de récupérer tous les blocs du contenu d’un article dans un tableau avec toutes leurs informations. Cela ouvre de nombreuses fonctionnalités utiles pour les développeurs de thèmes. Juste pour mentionner quelques idées :

• Générez dynamiquement une table des matières en allant chercher toutes les rubriques (tutoriel ci-dessous).
• Récupérez toutes les vidéos, images ou citations utilisées dans tous les messages pour les rassembler et les répertorier toutes sur une autre page.
• Extrayez le premier paragraphe d’un message et utilisez-le comme extrait dans les archives (tutoriel ci-dessous).
• Obtenez un aperçu de l’utilisation de blocs spécifiques et de leur position. Par exemple, supposons que vous ayez un bloc d’annonces personnalisé et que vous ayez besoin de savoir à quelle fréquence il est utilisé dans vos publications et à quelle distance du contenu ils apparaissent.
• Affichez les blocs d’une publication, mais excluez des types de blocs spécifiques.
• Vérifiez si le contenu d’un article commence par une vidéo et utilisez cette vidéo au lieu de l’image en vedette dans les archives.
• Si vous utilisez un bloc personnalisé qui contient des spécifications techniques sur les produits, vous pouvez facilement créer une page qui affiche et compare les spécifications techniques entre les publications de produits.
• Rassemblez dynamiquement toutes les images uniques utilisées dans un article et générez-en une galerie à la fin ou ailleurs.

Allons droit au but !

Analyser les blocs d’un article

Pour analyser les blocs, nous utilisons la fonction WordPress [parse_blocks](https://developer.wordpress.org/reference/functions/parse_blocks/)(). En tant que paramètre, vous devez fournir une chaîne du contenu d’un article. Si vous êtes dans une boucle ou avez accès à un objet de publication, fournissez simplement $post->post_contentcomme paramètre à la fonction.

Le retour de parse_blocks()est un tableau où chaque élément du tableau est un bloc. Pour chaque élément de bloc, vous disposez d’informations telles que le type de bloc (clé ‘ blockName‘), les attributs de bloc (clé ‘ attrs‘), les blocs internes pour les blocs imbriqués tels que les colonnes (clé ‘ innerBlocks‘) et deux éléments pour le contenu réel du bloc (clés ‘ innerHTML‘ et ‘ innerContent‘). L’élément innerHTMLest une chaîne de contenu HTML, alors qu’il innerContents’agit d’un tableau de chaînes HTML.

Et c’est tout! Faites une boucle dans le tableau renvoyé à partir de parse_blocks()pour faire votre travail. Nous examinerons plus d’exemples de code plus loin dans cet article.

Une note sur les messages classiques (non Gutenberg)

Vous travaillez peut-être sur un site WordPress plus ancien qui a créé des publications avant la mise à niveau vers Gutenberg (ou utilisé un plugin Désactiver Gutenberg). Dans ce cas, ces publications n’auront pas de contenu de publication structuré, mais l’intégralité du contenu de la publication se trouvera dans un bloc "Éditeur classique".

Le tableau renvoyé par la fonction parse_blocks()renverra sur ce type de messages un élément de tableau de bloc avec blockNamela valeur null. Le contenu HTML complet de la publication se trouve dans la innerHTMLchaîne de cet élément.

Nous pouvons supposer en toute sécurité que si le retour d’un article sur parse_blocks()a un élément et que blockNamec’est null, nous avons affaire à un article "pré-Gutenberg". Sinon blockName, sera toujours peuplé. C’est une bonne vérification à garder à l’esprit lorsque vous écrivez du code pour analyser les blocs de publications et que vous souhaitez gérer du contenu WordPress plus ancien.

Rendre un bloc

WordPress propose également une fonction pour rendre un bloc spécifique avec [render_block](https://developer.wordpress.org/reference/functions/render_block/)(). En tant que paramètre, vous devez fournir un tableau pour un bloc, tout comme l’un de ceux renvoyés parse_blocks()ci-dessus. La fonction renvoie une chaîne de code HTML rendu que vous pouvez simplement répercuter directement.

Le code ci-dessus rendra tous les blocs de la publication, comme il le ferait normalement lors du rendu du contenu de la publication. La partie amusante survient lorsque nous commençons à ajouter du code pour exclure ou inclure des blocs spécifiques qui nous intéressent.

Par exemple, le code ci-dessous n’imprimera que les blocs de paragraphes de l’article :

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

Et cela rendra tous les blocs, mais exclura tous les blocs de shortcode :

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

Bloquer les noms

Lors de l’analyse des blocs d’un article, vous devrez probablement vérifier le type de bloc. Ils sont assez simples à deviner. Par exemple, un bloc Paragraphe est, vous l’aurez deviné, paragraph. Cependant, gardez à l’esprit que tous les blocs Gutenberg dans WordPress sont précédés d’un espace de noms. Pour les blocs de base WordPress (par défaut), ils sont tous préfixés par " core/". L’exception sont les blocs Embed qui sont préfixés par " core-embed/". Ainsi, par exemple, un bloc de paragraphe aura le nom du bloc core/paragraph.

Pour éviter les devinettes, voici un aperçu des blocs par défaut fournis par WordPress (au moment d’écrire ceci) :

Blocs communs

• Paragraphe:core/paragraph
• Image:core/image
• Titre:core/heading
• Galerie:core/gallery
• Liste:core/list
• Devis:core/quote
• L’audio:core/audio
• Couverture:core/cover
• Dossier:core/file
• Vidéo:core/video

Mise en page

• Préformaté :core/preformatted
• Code:core/code
• Classique : core/freeform
  (mais pour les messages non Gutenberg, ce sera null, voir la note sur les messages non Gutenberg)
• HTML personnalisé :core/html
• Pullquote :core/pullquote
• Table:core/table
• Verset:core/verse

Disposition

• Bouton:core/button
• Colonnes:core/columns
• Suite:core/more
• Saut de page:core/nextpage
• Séparateur:core/separator
• Entretoise :core/spacer
• Médias et texte :core/media-text

Widget

• Petit code:core/shortcode
• Les archives:core/archives
• Catégories :core/categories
• Derniers Commentaires:core/latest-omments
• Derniers articles :core/latest-posts

Intègre

• Intégrer :core/embed

• Twitter:core-embed/twitter

• Youtube:core-embed/youtube

• Facebook:core-embed/facebook

• Instagram :core-embed/instagram

• WordPress :core-embed/wordpress

• Sound Cloud :core-embed/soundcloud

• Spotify :core-embed/spotify

• Flickr :core-embed/flickr

• Viméo :core-embed/vimeo

• Animoto :core-embed/animoto

• Nuage vers le haut :core-embed/cloudup

• Signal de foule :core-embed/crowdsignal

• Daily motion :core-embed/dailymotion

• Hulu :core-embed/hulu

• Imgur :core-embed/imgur

• Publier:core-embed/issuu

• Lanceur :core-embed/kickstarter

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

• Mix cloud :core-embed/mixcloud

• Reddit :core-embed/reddit

• ReverbNation :core-embed/reverbnation

• Capture d’écran :core-embed/screencast

• Script :core-embed/scribd

• Slideshare :core-embed/slideshare

• SmugMug :core-embed/smugmug

• Plate-forme de haut-parleur :core-embed/speaker

• TED :core-embed/ted

• Tumblr :core-embed/tumblr

• VidéoPress :core-embed/videopress

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

• Kindle d’Amazon:core-embed/amazon-kindle

Exemple de code : Récupérer le premier paragraphe d’un message sous forme d’extrait

Un article bien rédigé devrait commencer par un paragraphe qui présente le sujet de l’article et inciter les gens à continuer à lire. Ceux-ci sont parfaits pour être utilisés comme extraits au lieu de compter sur la fonction d’extrait automatique de WordPress !

Il s’agit d’une fonction que vous pouvez ajouter à votre thème et functions.phpqui renverra le premier paragraphe d’un article. Si aucun article n’a été fourni, il fera référence à l’objet de publication global. Il accepte également les messages non Gutenberg en renvoyant l’extrait WordPress réel pour ceux-ci.

Après l’ parse_blocks()appel de la fonction, nous vérifions si la publication contient ou non des données de bloc invalides (la publication a été créée avant Gutenberg) et renvoyons un extrait de publication si tel est le cas. Sinon, nous parcourons les blocs de l’article, trouvons le premier bloc de paragraphe et renvoyons son innerHTML. À la toute fin, nous renvoyons une chaîne avec (ceci est facultatif) un <div>autour.

Pour utiliser cette fonction, il suffit d’appeler :

echo awp_get_excerpt();

En supposant que l’appel de fonction est placé quelque part, il y a un objet global $post, par exemple à l’intérieur d’une boucle. Si vous souhaitez spécifier un post, fournissez l’objet post comme paramètre à l’appel de fonction :

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

Exemple : Créer une table des matières à partir des titres d’un article

Vous pouvez générer automatiquement et dynamiquement une table des matières basée sur les blocs d’en-tête d’un article. Le processus est assez simple; analyser les blocs de la publication et trouver tous les blocs de type core/heading. Mais nous pouvons aller plus loin et incorporer des niveaux ; par exemple mettre h3comme sous-titre sous h2et ainsi de suite.

Un bloc d’en-tête contient des informations sur son niveau dans l’élément de tableau d’attributs (clé ‘ attrs‘). À l’intérieur du attrstableau, ce serait un élément de tableau avec la clé ‘ level‘ et un entier signifiant le niveau. A h3aurait ‘ level‘ la valeur de 3, a h4aurait ‘ level‘ de 4, et ainsi de suite.

Cependant, notez que attrspour les en-têtes, les blocs peuvent être vides! Cela se produit lorsque l’auteur n’a pas modifié le type de titre par rapport aux valeurs par défaut dans les paramètres du bloc. Pour contourner cela, nous devons faire quelques hypothèses. Comme les en-têtes par défaut seront h2(sauf si vous avez changé cela dans votre thème). Nous pouvons donc supposer que si un bloc d’en-tête n’a pas d’attribut de niveau, c’est un h2. Sinon, nous obtenons les informations de niveau à partir des attributs.

Si vous êtes vraiment prêt à relever le défi, je vous invite à améliorer le code ci-dessous. Le problème de la génération d’une liste structurée appropriée olest que nous ne pouvons pas contrôler la façon dont l’auteur structure ses titres. Ils pourraient très bien devenir fous et commencer par un h4titre et passer directement à un h2titre juste après. Et du coup ils mélangent un h1au milieu. Ma solution consiste donc à générer une liste plate olet à fournir les informations de niveau dans les classes de l’élément de liste. Ensuite, avec un CSS intelligent, vous pouvez indenter les éléments de la liste en conséquence avec un rembourrage à gauche.

Le code

Voici la fonction table des matières :

La fonction commence par gérer la publication et analyser ses blocs. En ligne, #9nous accueillons les messages non Gutenberg. La fonction continue de parcourir tous les blocs et chaque fois qu’elle trouve un bloc d’en-tête, elle est ajoutée à notre $headingstableau. Nous utilisons [wp_strip_all_tags](https://developer.wordpress.org/reference/functions/wp_strip_all_tags/)()pour supprimer les balises HTML des titres. Nous ajoutons également les informations de niveau à notre tableau, où la valeur par défaut est définie sur 2si les attributs sont vides.

Après la boucle de bloc, le $headingstableau doit contenir tous les titres du message, dans l’ordre. Nous pouvons alors simplement générer une chaîne HTML et afficher son contenu. Comme mentionné, je génère un nom de classe sur chaque élément avec des informations sur le niveau du titre afin que nous puissions créer l’illusion d’une liste structurée avec CSS.

Comme avec la fonction d’extrait ci-dessus, nous pouvons appeler cette fonction lorsque nous sommes à l’intérieur de la boucle comme ceci :

echo awp_table_of_contents();

Ou si nous sommes en dehors de la boucle ou si nous voulons spécifier un message ;

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

Cela générera une liste ressemblant à ceci :

Conclusion

Comme nous l’avons vu avec le contenu de publication riche et structuré rendu possible avec Gutenberg, nous pouvons très facilement trouver et extraire des parties spécifiques du contenu des publications. Reportez-vous à la liste d’exemples que j’ai mentionnés au début de l’article. Il n’y a pas de limites à ce que vous pouvez faire en tant que développeur de thème. Cela dépend simplement de ce dont votre thème ou votre site WordPress a besoin (ou de ce qui serait tout simplement cool).