Créer un bloc Gutenberg personnalisé – Partie 9 : Blocs dynamiques et rendu PHP

Jusqu’à présent, nous avons rendu la sortie du bloc en Javascript. Cependant, avec un contenu dynamique comme des publications récentes ou l’affichage d’une publication, nous devons rendre la sortie du bloc en PHP. Dans cet article, nous allons apprendre comment et pourquoi.

Pourquoi devons-nous gérer les blocs dynamiques différemment ?

Certains exemples sont évidents; un bloc qui affiche les derniers messages d’une catégorie est dynamique car les messages changeront au fil du temps. Vous ne choisissez pas les publications dans le bloc ; à la place, vous aurez probablement des paramètres pour choisir la catégorie, les informations à afficher pour chaque publication, le nombre de publications, le nombre de colonnes, etc. Chaque fois que WordPress charge un article avec ce bloc, il doit interroger WordPress à ce moment-là pour les articles les plus récents. L’affichage du même message le mois suivant peut donner des résultats différents, même si le message avec le bloc lui-même n’a pas été mis à jour.

Mais la nécessité de blocs dynamiques n’est parfois pas si évidente. Vous pouvez imaginer qu’un bloc de publication en vedette dans lequel vous choisissez une publication spécifique pour l’afficher n’est pas nécessairement dynamique. Mais cela pourrait être – et devrait être. N’oubliez pas que le message sélectionné peut mettre à jour son titre, son extrait ou son image à tout moment – et cela doit être reflété dans les blocs qui présentent ce message.

Afin de créer un bloc non dynamique pour afficher une seule publication, vous devrez enregistrer l’ID de la publication, son URL, l’URL de l’image en vedette, la chaîne d’extrait ou tout ce dont vous avez besoin pour prévisualiser la publication, dans les attributs du bloc. Et c’est là que réside le problème. Si vous mettez à jour l’image en vedette de la publication sélectionnée, la publication avec le bloc de publication en vedette ne mettra pas automatiquement à jour ses attributs. Il restera enregistré avec l’ancienne URL de l’image sélectionnée. Ce n’est que lorsque vous modifiez la publication avec le bloc et que vous vous assurez qu’il réenregistre les attributs avec les informations mises à jour que le bloc affichera les informations mises à jour correctes.

Ainsi, chaque fois que nous traitons avec du contenu dynamique – publications, catégories ou tout ce qui peut changer avec le temps – nous traitons avec des blocs dynamiques. Et pour les blocs dynamiques, nous devons utiliser PHP – code côté serveur – pour rendre notre bloc afin de nous assurer qu’il récupérera des informations mises à jour à chaque rendu.

La nature modifiée des blocs dynamiques dans l’éditeur

Lorsque vous commencez à développer des blocs dynamiques, la nature de votre bloc dans l’éditeur change. La fonction de votre bloc editdoit souvent être également dynamique. Par exemple, pour un bloc de publication en vedette, vous devrez récupérer les publications parmi lesquelles choisir, ou pour un bloc de nouvelles les plus récentes, vous devrez récupérer une liste de catégories parmi lesquelles l’utilisateur pourra choisir.

Il est tout à fait possible de demander des informations à WordPress depuis l’éditeur en effectuant des requêtes AJAX – soit en utilisant des packages et des composants, soit en les exécutant manuellement avec l’ API WordPress REST. Quelle que soit la méthode choisie, votre bloc doit gérer le flux d’entrée asynchrone – le délai d’attente d’une réponse.

Il existe plusieurs méthodes et modèles pour créer un bloc dynamique pour Gutenberg. Le plus souvent, vous utiliserez un modèle React appelé composants d’ordre supérieur dans lequel WordPress fournit de nombreuses fonctions et composants.

Nous verrons comment récupérer des messages et comment récupérer des catégories dans notre bloc dans la prochaine partie du didacticiel. Pour l’instant, nous devons apprendre à faire en sorte que PHP rende notre bloc.

Préparer notre bloc pour le rendu PHP

La partie principale que nous devons faire en Javascript est de rendre la savefonction du bloc return null. Vous pouvez conserver la sortie d’origine, mais une fois que nous disons à WordPress d’utiliser PHP pour rendre le bloc, cela sera ignoré. Pour qu’il soit clair pour nous et pour les autres que la sortie du bloc n’est pas gérée en Javascript, nous allons changer la savefonction.

N’oubliez pas que la modification de la fonction de sauvegarde entraînera la rupture de tous les blocs existants. Ajoutez à nouveau le bloc. Le bloc devrait fonctionner comme avant ; avec les paramètres et la mise à jour des attributs. Il ne sortira plus rien en frontend. Le bloc de commentaires sera là, stockant tous les attributs dans JSON, mais aucun code HTML visible n’est rendu.

Cependant; si l’un de vos attributs utilise la sourcepropriété, vous devez le modifier. Ceci n’est pas pris en charge avec les blocs rendus avec PHP car ils sont analysés directement à partir de la sortie de la sauvegarde – sur laquelle nous revenons maintenant null. Nous utilisons source sur le deuxième RichTextde notre bloc – pour le paragraphe. À ce stade, l’éditeur n’enregistrera pas du tout ce que vous y mettez RichText.

Donc, si vous utilisez toujours sourcel’ myRichTextattribut, nous devons supprimer les propriétés sourceet selectorpour nous assurer que les attributs seront stockés et non analysés à partir de la savefonction :

attributes: {
    ...
    myRichText: {
        type: 'string',
    },
    ...

Après cela, notre bloc est prêt pour le rendu en PHP. On peut laisser les fichiers Javascript (n’oubliez pas de le compiler) et le reste se fait en PHP.

Rendre des blocs en PHP

Afin de dire à WordPress de rendre la sortie du bloc en PHP, nous ajoutons un nouvel argument à la fonction register_block_type(). Nous devons ajouter la clé render_callbackau tableau avec une valeur de la fonction qu’elle doit exécuter.

La fonction de rendu PHP

Définissons la fonction awp_myfirstblock_renderplus bas functions.php(ou là où vous avez mis votre code PHP). Notre fonction obtiendra deux paramètres ; nous les appellerons $attret $content.

function awp_myfirstblock_render($attr, $content) {
    // return the block's output here
}

Le paramètre $attrsera un tableau associatif avec tous les attributs enregistrés. Le deuxième paramètre, $content, est pour les blocs à l’intérieur de notre bloc. Ceci n’est pertinent que pour les blocs qui prennent en charge les blocs imbriqués – ce que font, par exemple, les colonnes ou la couverture.

La fonction ne devrait jamais echorien sortir. Toutes les sorties doivent être renvoyées, vous devez donc créer une chaîne et la renvoyer à la fin.

Une chose importante à retenir à propos des attributs est que seuls les attributs enregistrés apparaîtront dans le premier paramètre de la fonction. Si un attribut n’a jamais été réellement modifié et enregistré – c’est-à-dire qu’il s’appuie simplement sur son default, l’attribut ne sera pas du tout inclus pour notre fonction PHP.

Vous devez gérer ce problème en vérifiant toujours if (isset($attr['...']))ou de la manière préférable : définir les attributs dans notre register_block_type()appel. Nous pouvons fournir une autre clé, attributeset définir sa valeur sur un tableau avec tous les attributs que nous souhaitons extraire de notre bloc. La structure doit être identique à celle que vous avez définie en Javascript, mais au lieu d’un objet Javascript, vous en avez besoin dans un tableau PHP. Cela peut être un peu fastidieux de redéfinir les mêmes attributs, mais avec un éditeur de code intelligent, il devrait être assez rapide de le copier-coller et de le modifier sur plusieurs lignes dans PHP.

Ajout des attributs pour notre fonction de rendu

Ajoutons le nouvel attributesélément register_block_type()et collons exactement les mêmes attributs que nous avons définis dans notre fichier Javascript :

Gardez à l’esprit que si vous définissez a defaultpour tous les attributs, le $attrparamètre de votre fonction doit toujours contenir tous les attributs. Par exemple, l’attribut textAlignmentci-dessus n’existera que dans $attrs’il a été modifié – et vous devrez vérifier isset($attr['textAlignment']).

Malheureusement, pour le moment, il y a deux choses que vous ne comprendrez pas avec PHP block render. L’un est l’ classNameaccessoire – vous devez donc créer vous-même la classe d’emballage (si vous le souhaitez). L’autre est la supportpropriété d’alignement des blocs. Pour le moment, WordPress ne prend pas en charge cette propriété dans les blocs dynamiques. Nous n’obtiendrons pas la valeur de l’alignement de bloc choisi à moins de le changer en attribut et de le gérer manuellement en Javascript.

Quant à la sortie HTML de la fonction, cela dépend entièrement de vous !

Demande de rendu PHP depuis l’éditeur interne

Il est possible de demander le rendu PHP de notre bloc dans l’éditeur. Ceci est utile si vous souhaitez pouvoir prévisualiser la sortie du bloc dans l’éditeur. Nous pouvons le faire avec un composant appelé ServerSideRenderdepuis le wp.editorpackage.

En tant qu’accessoires ServerSideRender, vous devez définir tous les attributs que vous souhaitez transmettre. Au minimum, vous devez fournir le nom du bloc au prop block, afin que WordPress sache quelle méthode de rendu rechercher. Ceci est disponible pour vous dans props.namela editfonction. Vous devez également fournir tous les attributs dont vous avez besoin dans le prop attributes. Si vous le souhaitez, vous pouvez également ajouter ici des variables personnalisées en dehors des attributs. Gardez simplement à l’esprit que cela ne fonctionnera que pour l’éditeur interne, et non pour l’interface.

Vous ne pouvez pas utiliser ServerSideRenderdans la fonction du bloc save. Votre savefonction doit toujours retourner null.

Mettons en œuvre ServerSideRenderdans notre bloc pour le voir en pratique.

Utilisation de ServerSideRender pour le mode aperçu/édition de bloc

Si vous avez suivi l’étape précédente où nous avons créé un basculeur de mode aperçu/édition pour notre bloc, nous pouvons maintenant l’utiliser ServerSideRenderpour afficher l’aperçu du bloc à partir de PHP lorsque nous passons en mode aperçu.

Il faut d’abord se rappeler de déstructurer ServerSideRenderen haut :

const { ServerSideRender } = wp.editor;

Si vous vous souvenez de l’étape précédente, nous avons utilisé les composants Disabledet/ou Placeholderpour conserver l’aperçu. Le problème avec l’utilisation Placeholderest que nous obtenons un style indésirable appliqué à notre sortie. Remplaçons Placeholderpar ServerSideRender. Vous pouvez choisir de conserver le Disabledcomposant, pour vous assurer qu’aucun de ses contenus ne sera cliquable ou déplaçable.

Au niveau du code pour rendre le bloc lorsque l’attribut editModeest faux, nous faisons :

Maintenant, notre bouton personnalisé dans la barre d’outils affichera la sortie de PHP lorsque nous passerons en mode aperçu. La sortie doit être identique lors de la visualisation du message en frontend. C’est une bonne habitude pour s’assurer que la sortie est identique dans l’éditeur et le frontend.

Exemple : bloc dynamique affichant une publication sélectionnée

La sortie de votre fonction de rendu PHP peut être n’importe quoi et vous avez un accès complet à toutes les fonctions de WordPress. Supposons un bloc où un ID de publication sera enregistré dans un attribut. Dans la render_callbackfonction PHP, vous pouvez interroger la publication à partir de l’ID et afficher ses informations. La procédure à suivre devrait être assez explicite, mais voici un exemple rapide.

NB: Dans cet exemple, nous allons simplement ajouter une entrée de texte à l’éditeur pour saisir manuellement un identifiant de publication. Ce n’est pas une solution très intuitive et conviviale pour sélectionner un message – mais c’est ce que nous apprendrons à l’étape suivante. L’accent est mis ici sur la partie PHP du rendu du message sélectionné.

Ajoutons un attribut selectedPostIdde type numéro :

attributes: {
    selectedPostId: {
        type: 'number'
    }
}

Et quelque part dans la fonction de notre bloc, editnous ajoutons un TextControlcomposant. Il peut être où vous voulez – à l’intérieur du bloc ou dans l’inspecteur.

Notez que je prends des précautions supplémentaires pour m’assurer que l’entrée enregistre correctement l’attribut sous forme de nombre en le convertissant en entier avec parseInt(). Même si nous définissons le type prop typesur numberafin de rendre une entrée numérique, la valeur modifiée est toujours interprétée comme une chaîne. WordPress n’enregistrera pas votre attribut s’il est au mauvais format.

N’oubliez pas d’ajouter le nouvel attribut à votre ServerSideRendercomposant si vous en avez un :

La partie PHP

Cela aurait dû prendre en charge la partie Javascript. Passons à PHP. Nous devons d’abord ajouter le nouvel attribut selectedPostIdau attributestableau dans register_block_type():

Dans la render_callbackfonction, nous pouvons maintenant accéder à l’ID de publication avec $attr['selectedPostId']. Nous pouvons avec cela effectuer un simple get_post()et sortir les données du poste; son lien et son titre :

Il s’agit d’un exemple très basique destiné à servir de tremplin pour vous permettre d’écrire du code plus avancé et personnalisé.

Maintenant que nous savons comment gérer le rendu des blocs dynamiques, la prochaine étape consiste à apprendre à rendre également la partie éditeur plus intuitive. Dans l’étape suivante, nous nous concentrerons sur la façon d’interroger les publications à partir de l’éditeur de blocs et de fournir à l’utilisateur un meilleur moyen de sélectionner une publication.