Share
Le nouvel éditeur WordPress (nom de code Gutenberg) doit sortir dans la version 5.0. C’est le moment idéal pour le maîtriser avant d’atteindre le noyau WordPress. Dans cette série, je vous montre comment utiliser l'API Block et créer vos propres blocs de contenu que vous pouvez utiliser pour créer vos publications et vos pages..
Dans le post précédent, nous avons vu comment utiliser le créer-guten-block boîte à outils pour créer un plugin contenant un exemple de bloc prêt à être utilisé. Nous pouvons facilement étendre cela au besoin, mais c'est une bonne idée de savoir comment créer un bloc à partir de zéro pour bien comprendre tous les aspects du développement de blocs de Gutenberg..
Dans ce post, nous allons créer un deuxième bloc dans notre mon bloc personnalisé plugin pour afficher une image aléatoire du service Web PlaceIMG. Vous pourrez également personnaliser le bloc en sélectionnant la catégorie d'image à partir d'un contrôle de sélection déroulant..
Mais d'abord, nous allons apprendre comment les scripts et les styles de bloc sont mis en file d'attente avant de passer à la tâche primordiale. registerBlockType () fonction essentielle pour la création de blocs à Gutenberg.
Pour ajouter le code JavaScript et CSS requis par nos blocs, nous pouvons utiliser deux nouveaux points d'ancrage WordPress fournis par Gutenberg:
Accentsconagua
enqueue_block_editor_assetsenqueue_block_assetsCelles-ci ne sont disponibles que si le plug-in Gutenberg est actif et fonctionnent de manière similaire aux points d'ancrage WordPress standard pour les scripts de mise en file d'attente. Cependant, ils sont spécifiquement conçus pour travailler avec des blocs de Gutenberg.
le enqueue_block_editor_assets hook ajoute des scripts et des styles à l'éditeur admin uniquement. Cela le rend idéal pour mettre en file d'attente JavaScript pour enregistrer des blocs et CSS pour styliser les éléments de l'interface utilisateur pour les paramètres de bloc.
Pour la sortie de bloc, cependant, vous voudrez que vos blocs affichent le même rendu dans l'éditeur, comme ils le font la plupart du temps. En utilisant enqueue_block_assets facilite les choses car les styles sont automatiquement ajoutés à l'éditeur et au frontal. Vous pouvez également utiliser ce crochet pour charger du JavaScript si nécessaire.
Mais vous vous demandez peut-être comment mettre en file d'attente les scripts et les styles seulement sur le devant. Il n'y a pas de hook WordPress pour vous permettre de le faire directement, mais vous pouvez contourner cela en ajoutant une instruction conditionnelle à l'intérieur du enqueue_block_assets fonction de rappel automatique.
add_action ('enqueue_block_assets', 'scripts load_front_end'); function load_front_end scripts () if (! is_admin () // met en file d'attente uniquement les scripts et les styles iciPour mettre réellement en file d'attente les scripts et les styles à l'aide de ces deux nouveaux points d'ancrage, vous pouvez utiliser la norme wp_enqueue_style () et wp_enqueue_scripts () fonctionne comme vous le feriez normalement.
Cependant, vous devez vous assurer que vous utilisez les dépendances de script correctes. Pour les scripts de mise en file d'attente sur l'éditeur, vous pouvez utiliser les dépendances suivantes:
tableau ('wp-blocks', 'wp-i18n', 'wp-element', 'wp-components') tableau ('wp-edit-blocks') Et lors de la mise en file d'attente de styles pour l'éditeur et le front-end, vous pouvez utiliser cette dépendance:
tableau ('wp-blocks')Une chose à noter ici est que les fichiers réels mis en file d'attente par notre mon bloc personnalisé plugin sont les compilé versions de JavaScript et CSS et non les fichiers contenant le code source JSX et Sass.
C’est juste quelque chose à garder à l’esprit lors de la mise en file d'attente manuelle des fichiers. Si vous essayez de mettre en file d'attente du code source brut comprenant React, ES6 + ou Sass, vous rencontrerez de nombreuses erreurs..
C’est pourquoi il est utile d’utiliser une boîte à outils telle que créer-guten-block car il traite et met automatiquement les scripts en file d'attente pour vous!
Pour créer un nouveau bloc, nous devons l'enregistrer auprès de Gutenberg en appelant registerBlockType () et en passant le nom du bloc plus un objet de configuration. Cet objet a pas mal de propriétés qui nécessitent une explication correcte.
Tout d’abord, regardons le nom du bloc. Ceci est le premier paramètre et est une chaîne composée de deux parties, un espace de noms et le nom du bloc lui-même, séparés par une barre oblique..
Par exemple:
registerBlockType ('espace de noms de blocs / nom de bloc', // objet de configuration);Si vous enregistrez plusieurs blocs dans un plugin, vous pouvez utiliser le même espace de noms pour organiser tous vos blocs. L'espace de noms doit cependant être unique pour votre plug-in, ce qui permet d'éviter les conflits de noms. Cela peut arriver si un bloc du même nom a déjà été enregistré via un autre plugin.
La deuxième registerBlockType () paramètre est un objet de paramétrage et nécessite la spécification d’un certain nombre de propriétés:
Titre (chaîne): affiché dans l'éditeur en tant que libellé de bloc interrogeablela description (chaîne facultative): décrit le but d'un blocicône (élément facultatif Dashicon ou JSX): icône associée à un blocCatégorie (chaîne): où le bloc apparaît dans le Ajouter des blocs dialoguemots clés (tableau facultatif): jusqu'à trois mots clés utilisés dans les recherches par blocsles attributs (objet facultatif): gère les données de bloc dynamiquesmodifier (fonction): une fonction qui renvoie le balisage à rendre dans l'éditeurenregistrer (fonction): une fonction qui retourne le balisage sur le front-enduseOnce (booléen optionnel): empêche le bloc d'être ajouté plus d'une foisles soutiens (objet facultatif): définit les fonctionnalités prises en charge par blocsEn supposant que nous utilisions JSX pour le développement de blocs, voici un exemple. registerBlockType () call pourrait ressembler à un bloc très simple:
registerBlockType ('my-unique-namespace / ultimate-block', titre: __ ('Le meilleur bloc jamais', 'domaine'), icône: 'wordpress', catégorie: 'commun', mots clés: [__ ('exemple ',' domaine '), __ (' Gutenberg ',' domaine '), __ (' bloc ',' domaine ')], éditez: () => Bienvenue dans l'éditeur Gutenberg!
, enregistrer: () => Comment je regarde sur le devant?
);Remarquez comment nous n’avons pas inclus d’entrée pour le la description, les attributs, useOnce, et les soutiens Propriétés? Tous les champs facultatifs (et non pertinents pour votre bloc) peuvent être omis en toute sécurité. Par exemple, comme ce bloc n’impliquait aucune donnée dynamique, nous n’avons pas à nous soucier de spécifier des attributs..
Couvrons maintenant le registerBlockType () Propriétés de l'objet de configuration plus en détail un par un.
Lors de l'insertion ou de la recherche d'un bloc dans l'éditeur, le titre sera affiché dans la liste des blocs disponibles..
Il est également affiché dans la fenêtre de l'inspecteur de blocs, avec la description du bloc si elle est définie. Si l'inspecteur de bloc n'est pas visible, vous pouvez utiliser l'icône représentant un engrenage dans le coin supérieur droit de l'éditeur Gutenberg pour activer / désactiver la visibilité..
Les champs titre et description doivent idéalement être entourés de fonctions i18n pour permettre la traduction dans d'autres langues..
Cinq catégories de blocs sont actuellement disponibles:
communmise en formedispositionwidgetsintégrerCelles-ci déterminent la section de la catégorie où votre bloc est répertorié à l'intérieur du Ajouter un bloc la fenêtre.
le Des blocs onglet contient Blocs Communs, Mise en forme, Éléments de mise en page, et Widgets catégories, tandis que le Incorporés la catégorie a son propre onglet.
Les catégories sont actuellement définies dans Gutenberg, mais cela pourrait être modifié à l'avenir. Cela serait utile, par exemple, si vous développiez plusieurs blocs dans un même plug-in et que vous souhaitiez tous qu'ils soient répertoriés dans une catégorie commune afin que les utilisateurs puissent les localiser plus facilement..
Par défaut, votre bloc se voit attribuer le bouclier Dashicon, mais vous pouvez le remplacer en spécifiant un Dashicon personnalisé dans le champ. icône champ.
Chaque Dashicon est préfixé par dashicons- suivi d'une chaîne unique. Par exemple, l’icône engrenage porte le nom dashicons-admin-generic. Pour l'utiliser comme une icône de bloc, supprimez simplement le dashicons- préfixe pour qu'il soit reconnu, par exemple. icône: 'admin-generic'.
Cependant, vous n'êtes pas limité à l'utilisation de Dashicons en tant que propriété icon. La fonction accepte également un élément JSX, ce qui signifie que vous pouvez utiliser n’importe quelle image ou élément SVG comme icône de bloc..
Assurez-vous simplement de garder la taille de l'icône cohérente avec les autres icônes de bloc, qui est de 20 x 20 pixels par défaut.
Choisissez jusqu'à trois mots clés traduisibles pour que votre bloc se démarque lorsque les utilisateurs le recherchent. Il est préférable de choisir des mots clés étroitement liés aux fonctionnalités de votre bloc pour obtenir de meilleurs résultats..
mots clés: [__ ('recherche', 'domaine'), __ ('pour', 'domaine'), __ ('moi', 'domaine'),]Vous pouvez même déclarer le nom de votre société et / ou du plug-in en tant que mots-clés. Ainsi, si vous avez plusieurs blocs, les utilisateurs peuvent commencer à saisir le nom de votre société et tous vos blocs apparaîtront dans les résultats de la recherche..
Bien que l’ajout de mots-clés soit une option, c’est un excellent moyen de faciliter la recherche des blocs par les utilisateurs..
Les attributs aident à gérer les données dynamiques dans un bloc. Cette propriété est facultative car vous n'en avez pas besoin pour les blocs très simples qui génèrent du contenu statique..
Toutefois, si votre bloc traite des données susceptibles de changer (telles que le contenu d'une zone de texte modifiable) ou si vous avez besoin de stocker des paramètres de bloc, utilisez des attributs..
Les attributs fonctionnent en stockant des données de bloc dynamiques dans le contenu de la publication sauvegardé dans la base de données ou dans la publication méta. Dans ce tutoriel, nous utiliserons uniquement des attributs qui stockent des données avec le contenu de la publication..
Pour récupérer les données d'attributs stockées dans le contenu de publication, nous devons spécifier leur emplacement dans le balisage. Nous pouvons le faire en spécifiant un sélecteur CSS qui pointe vers les données d'attribut.
Par exemple, si notre bloc contient une balise d'ancrage, nous pouvons utiliser sa Titre champ comme notre attribut comme suit:
attributs: linktitle: source: 'attribut', sélecteur: 'a', attribut: 'titre'
Ici, le nom de l'attribut est lien titre, qui est une chaîne arbitraire et peut être tout ce que vous voulez.
Par exemple, nous pourrions utiliser cet attribut pour stocker le titre du lien. cela a été entré via une zone de texte dans les paramètres de bloc. Cela rend le champ de titre dynamique et vous permet de changer sa valeur dans l'éditeur..
Lorsque la publication est enregistrée, la valeur de l'attribut est insérée dans les liens. Titre champ. De même, lorsque l’éditeur est chargé, la valeur de Titre La balise est extraite du contenu et insérée dans le lien titre attribut.
Il y a plus de façons d'utiliser la source pour déterminer comment le contenu du bloc est stocké ou récupéré via des attributs. Par exemple, vous pouvez utiliser le 'texte' source pour extraire le texte intérieur d'un élément de paragraphe.
attributs: paragraphe: source: 'texte', sélecteur: 'p'
Vous pouvez également utiliser le les enfants source pour extraire tous les nœuds enfants d'un élément dans un tableau et le stocker dans un attribut.
attributs: contenu éditable: source: 'enfants', sélecteur: '.parent'
Ceci sélectionne l'élément avec la classe .parent et stocke tous les nœuds enfants dans le contenu éditable attribut.
Si vous ne spécifiez pas de source, la valeur de l'attribut est enregistrée dans les commentaires HTML dans le cadre du balisage de publication lors de son enregistrement dans la base de données. Ces commentaires sont supprimés avant que le message ne soit rendu au début..
Nous verrons un exemple spécifique de ce type d'attribut lorsque nous commencerons à implémenter notre bloc d'image aléatoire plus tard dans ce tutoriel..
Les attributs peuvent prendre un peu de temps pour s'y habituer, alors ne vous inquiétez pas si vous ne les comprenez pas bien du premier coup. Je vous recommande de consulter la section sur les attributs du manuel de Gutenberg pour plus de détails et d'exemples..
le modifier function contrôle la manière dont votre bloc apparaît dans l'interface de l'éditeur. Les données dynamiques sont transmises à chaque bloc en tant que les accessoires, y compris tous les attributs personnalisés qui ont été définis.
C'est une pratique courante d'ajouter className = props.className à l'élément de bloc principal pour générer une classe CSS spécifique à votre bloc. WordPress ne l'ajoute pas pour vous dans l'éditeur, il doit donc être ajouté manuellement pour chaque bloc si vous souhaitez l'inclure..
En utilisant props.className Cette pratique standard est recommandée car elle permet de personnaliser les styles CSS pour chaque bloc. Le format de la classe CSS générée est .wp-block- espace de noms - nom. Comme vous pouvez le constater, ceci est basé sur l'espace de nom / nom de bloc et le rend idéal pour être utilisé comme identifiant de bloc unique..
La fonction d’édition vous oblige à renvoyer un balisage valide via le rendre() méthode, qui est ensuite utilisée pour rendre votre bloc dans l'éditeur.
Semblable à la modifier une fonction, enregistrer affiche une représentation visuelle de votre bloc mais au début. Il reçoit également des données de bloc dynamiques (si définies) via des accessoires.
Une différence principale est que props.className n'est pas disponible à l'intérieur enregistrer, mais ce n'est pas un problème car il est inséré automatiquement par Gutenberg.
le les soutiens La propriété accepte un objet de valeur booléenne pour déterminer si votre bloc prend en charge certaines fonctionnalités essentielles..
Les propriétés d'objet disponibles que vous pouvez définir sont les suivantes.
ancre (false par défaut): permet de lier directement à un bloc spécifiquecustomClassName (true): ajoute un champ dans l'inspecteur de blocs pour définir une nom du cours pour le bloc nom du cours (true): ajoute un nom du cours à l'élément racine du bloc en fonction du nom du blochtml (true): permet de modifier directement le marquage du blocuseOnce PropriétéC'est une propriété utile qui vous permet d'empêcher qu'un bloc soit ajouté plusieurs fois à une page. Un exemple de ceci est le noyau Plus block, qui ne peut pas être ajouté à une page s'il est déjà présent.
Comme vous pouvez le voir, une fois le Plus Si un bloc a été ajouté, l’icône du bloc est grisée et ne peut pas être sélectionnée. le useOnce la propriété est définie sur faux par défaut.
Il est temps maintenant d'utiliser les connaissances acquises jusqu'à présent pour mettre en œuvre un exemple concret de bloc qui fait quelque chose de plus intéressant que de simplement produire du contenu statique..
Nous allons construire un bloc pour générer une image aléatoire obtenue via une requête externe sur le site Web PlaceIMG, qui renvoie une image aléatoire. En outre, vous serez en mesure de sélectionner la catégorie d’image renvoyée via un contrôle déroulant de sélection..
Pour plus de commodité, nous ajouterons notre nouveau bloc au même mon bloc personnalisé plugin, plutôt que de créer un tout nouveau plugin. Le code du bloc par défaut est situé à l'intérieur du / src / block dossier, alors ajoutez un autre dossier à l'intérieur / src appelé image aléatoire et ajoutez trois nouveaux fichiers:
Alternativement, vous pouvez copier le / src / block dossier et renommez-le si vous ne voulez pas tout taper à la main. Assurez-vous cependant de renommer block.js à index.js dans le nouveau dossier de bloc.
Nous utilisons index.js pour le nom de fichier du bloc principal car cela nous permet de simplifier la déclaration d'importation à l'intérieur blocks.js. Au lieu d’avoir à inclure le chemin et le nom de fichier complet du bloc, nous pouvons simplement spécifier le chemin du dossier du bloc, et importation cherchera automatiquement un index.js fichier.
S'ouvrir /src/blocks.js et ajoutez une référence à notre nouveau bloc en haut du fichier, directement sous l'instruction d'importation existante.
importer './random-image';
À l'intérieur /src/random-image/index.js, ajoutez le code suivant pour lancer notre nouveau bloc.
// Importer CSS. import './style.scss'; import './editor.scss'; const __ = wp.i18n; const registerBlockType, query = wp.blocks; registerBlockType ('cgb / block-random-image', title: __ ('Image aléatoire'), icône: 'format-image', catégorie: 'commun', mots-clés: [__ ('random'), __ (' image ')], edit: function (props) return ( Bloc d'images aléatoires (éditeur)
) , save: function (props) return ( Bloc d'image aléatoire (front end)
) );Ceci définit la structure de notre bloc et est assez similaire au code de bloc standard généré par le créer-guten-block boîte à outils.
Nous commençons par importer l'éditeur et les feuilles de style front-end, puis nous extrairons certaines fonctions couramment utilisées. wp.i18n et wp.blocks en variables locales.
À l'intérieur registerBlockType (), des valeurs ont été entrées pour le Titre, icône, Catégorie, et mots clés propriétés, tandis que le modifier et enregistrer fonctions actuellement juste sortir du contenu statique.
Ajouter le bloc d'image aléatoire à une nouvelle page pour voir la sortie générée jusqu'à présent.
Assurez-vous que vous surveillez toujours les fichiers pour connaître les modifications afin que tout code source de bloc (JSX, ES6 +, Sass, etc.) soit transpilé en JavaScript et CSS valides. Si vous ne regardez pas les fichiers pour les modifications, ouvrez une fenêtre de ligne de commande à l'intérieur du mon bloc personnalisé dossier racine du plugin et entrez npm start.
Vous vous demandez peut-être pourquoi nous n'avons pas eu besoin d'ajouter de code PHP pour mettre en file d'attente des scripts de bloc supplémentaires. Les scripts de bloc pour la mon bloc personnalisé bloc sont mis en file d'attente via init.php, mais nous n'avons pas besoin de mettre en file d'attente les scripts spécifiquement pour notre nouveau bloc, car cela est pris en charge pour nous par créer-guten-block.
Tant que nous importons notre fichier de bloc principal dans src / blocks.js (comme nous l'avons fait ci-dessus), nous n'avons pas besoin de faire de travail supplémentaire. Tous les codes JSX, ES6 + et Sass seront automatiquement compilés dans les fichiers suivants:
Ces fichiers contiennent les codes JavaScript et CSS de tous les blocs. Par conséquent, un seul ensemble de fichiers doit être mis en file d'attente, quel que soit le nombre de blocs créés.!
Nous sommes maintenant prêts à ajouter un peu d'interactivité à notre bloc et nous pouvons le faire en ajoutant d'abord un attribut pour stocker la catégorie d'image..
attributs: catégorie: type: 'chaîne', par défaut: 'nature'
Cela crée un attribut appelé Catégorie, qui stocke une chaîne avec une valeur par défaut de 'la nature'. Nous n'avons pas spécifié d'emplacement dans le balisage pour stocker et récupérer la valeur de l'attribut. Par conséquent, des commentaires HTML spéciaux seront utilisés. C'est le comportement par défaut si vous omettez une source d'attribut.
Nous avons besoin d'un moyen de changer la catégorie d'image, ce que nous pouvons faire via un contrôle déroulant de sélection. Mettre à jour le modifier fonction à la suivante:
edit: function (props) const attributs: category, setAttributes = props; function setCategory (event) const sélectionné = event.target.querySelector ('option: vérifié'); setAttributes (category: selected.value); event.preventDefault (); revenir ( La catégorie actuelle est: category ) Voici à quoi cela ressemblera:
Ceci est assez différent de la précédente statique modifier fonction, alors passons en revue les changements.
Nous avons d’abord ajouté un contrôle déroulant de sélection avec plusieurs choix correspondant aux catégories d’images disponibles sur le site PlaceIMG..
Lorsque la valeur de la liste déroulante change, le setCategory fonction est appelée, qui trouve la catégorie actuellement sélectionnée et appelle à son tour le setAttributes une fonction. Il s’agit d’une fonction essentielle de Gutenberg qui met à jour correctement la valeur d’un attribut. Il est recommandé de ne mettre à jour qu'un attribut à l'aide de cette fonction..
Maintenant, chaque fois qu’une nouvelle catégorie est sélectionnée, la valeur de l’attribut est mise à jour et est renvoyée dans la mémoire. modifier fonction, qui met à jour le message de sortie.
Nous devons compléter une dernière étape pour que l'image aléatoire s'affiche. Nous devons créer un composant simple qui prendra dans la catégorie actuelle et produira un
La demande que nous devons faire à PlaceIMG est de la forme: https://placeimg.com/[width]/[height]/[category]
Nous allons garder la largeur et la hauteur fixes pour le moment, il ne reste donc qu'à ajouter la catégorie actuelle à la fin de l'URL de la demande. Par exemple, si la catégorie était 'la nature' alors l'URL de la demande complète serait: https://placeimg.com/320/220/nature.
Ajouter un Image aléatoire composant ci-dessus registerBlockType ():
function RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; revenir;
Pour l'utiliser, ajoutez-le simplement dans la fonction d'édition et supprimez le message de sortie statique. Pendant que nous y sommes, faites la même chose pour la fonction de sauvegarde.
Le plein index.js Le fichier devrait maintenant ressembler à ceci:
// Importer CSS. import './style.scss'; import './editor.scss'; const __ = wp.i18n; const registerBlockType, query = wp.blocks; function RandomImage (category) const src = 'https://placeimg.com/320/220/' + category; revenir) , enregistrer: fonction (props) const attributs: catégorie = props; revenir (
Enfin (pour le moment), ajoutez les styles suivants à editor.scss ajouter une bordure colorée autour de l'image.
.wp-block-cgb-block-random-image select padding: 2px; marge: 7px 0 5px 2px; border-radius: 3px;
Vous aurez également besoin de certains styles dans style.css.
.wp-block-cgb-block-random-image background: # f3e88e; couleur: #fff; bordure: solide 2px # ead9a6; border-radius: 10px; rembourrage: 5px; width: -webkit-fit-content; largeur: -moz-fit-content; largeur: fit-content; img border-radius: hériter; bordure: 1px en pointillé # caac69; affichage: grille;
Chaque fois que la page est actualisée dans l'éditeur ou sur le front-end, une nouvelle image aléatoire sera affichée.
Si la même image est affichée à plusieurs reprises, vous pouvez effectuer une actualisation brutale pour empêcher la diffusion de l'image à partir du cache de votre navigateur..
Dans ce tutoriel, nous avons couvert pas mal de terrain. Si vous avez fait tout le chemin alors donnez-vous une tape bien méritée dans le dos! Le développement de blocs de Gutenberg peut être très amusant, mais il est vraiment difficile de saisir chaque concept dès la première exposition..
En cours de route, nous avons appris à mettre en file d'attente les scripts et les styles de blocs et avons couvert la registerBlockType () fonction en profondeur.
Nous avons ensuite mis en pratique la théorie et créé un bloc personnalisé pour afficher une image aléatoire d'une catégorie spécifique à l'aide du service Web PlaceIMG..
Dans la dernière et dernière partie de cette série de didacticiels, nous ajouterons davantage de fonctionnalités à notre bloc d'images aléatoires via le panneau de configuration de l'inspecteur de blocs..
Si vous suivez ce didacticiel et que vous souhaitez simplement expérimenter le code sans tout saisir, vous pourrez télécharger la version finale. mon bloc personnalisé plugin dans le prochain tutoriel.
