Comment créer des blocs personnalisés Gutenberg (block editor) dans WordPress

Juil 17, 2020 | wordPress | 0 commentaire

Ajouter un bloc personnalisé à l'éditeur de bloc Gutenberg de wordPress

On va voir comment créer un bloc personnalisé dans le nouvel éditeur de blocs Gutenberg de WordPress. Il s’agira d’ajouter un paragraphe dont on pourra changer le contenu.

La création d’un bloc dans WordPress (au moment de l’écriture) se fait via JavaScript (pas PHP) à l’aide d’une fonction appelée registerBlockType(). Le fichier JavaScript est chargé en PHP avec le hook enqueue_block_editor_assets.

La fonction registerBlockType() se trouve à l’intérieur de la bibliothèque wp.blocks, qui contient des fonctions utiles pour la création de blocs, ainsi que les principaux blocs WordPress eux-mêmes. WordPress rend cette fonction accessible en tant que variable globale dans l’objet window.wp sous la forme wp.blocks.registerBlockType().

registerBlockType() : Nom et Paramètres de réglages

La fonction registerBlockType() prend deux paramètres : le nom et les paramètres (settings).

  • Le nom : Les noms de bloc doivent contenir un préfixe d’espace de noms, inclure uniquement des caractères alphanumériques en minuscules ou des tirets et commencer par une lettre. Exemple: my-plugin/my-custom-block. En gros, on commence par une chaîne en caractères minuscules et des tirets si nécessaire, il doit y avoir un slash (/), et une autre chaîne. Voir la source.
  • settings [Object] – Le paramètre settings est un objet avec plusieurs propriétés prédéfinies dont certaines doivent être attribuées pour que le bloc fonctionne.

Le paramètre Settings de registerBlockType() :

L’objet settings de registerBlockType() possède sept propriétés qui incluent à la fois des métadonnées sur le bloc ainsi que des méthodes contrôlant l’interface utilisateur et les fonctionnalités du bloc dans l’éditeur et sur le frontend.

  • title [string] – Le titre donne un nom au bloc. Il peut être traduit en utilisant wp.i18n .__().
  • category [string] – La catégorie détermine dans quelle rubrique se trouvera le bloc. Les options sont common, formatting, layout, widgets et embed.
  • icon [Dashicon|Element] – L’icone representera graphiquement le bloc. On peut utiliser les noms de classes WP Dashicons ou utiliser un icon personnalisé en SVG.
  • keywords [Array] – keyword fournit jusqu’à trois mots clés/phrases additionnels pour rechercher le bloc. Limité à 3.
  • attributes [Object] – Les attributs indiquent quels contenus dynamiques sont utilisés dans le bloc. Plusieurs attributs existent selon les types de données utilisées. Les paramètres d’attribut sont facultatifs si votre bloc n’utilise aucune donnée dynamique. Ces données sont ensuite accessibles par props.attributes.name. Référence.
  • edit [function] – Indique ce qui sera affiché dans la zone du bloc dans l’éditeur. Cette fonction doit retourner un élément React valide en utilisant wp.element.createElement() ou JSX. Cette fonction peut accepter des données dynamiques en paramètre props de la fonction.
  • save [function] – C’est une fonction qui indique le contenu qui sera sauvegardé et affiché sur le frontend. Cette fonction doit retourner un élément React valide en utilisant wp.element.createElement() ou JSX. Cette fonction peut accepter des données dynamiques en paramètre props de la fonction.

Charger le fichier JavaScript

Dans functions.php ou dans un plugin, on charge le fichier Javascript qui créera le block personnalisé.

1
2
3
4
5
6
7
8
9
10
add_action('enqueue_block_editor_assets', 'xbs_loadMyBlock');
 
function xbs_loadMyBlock() {
  wp_enqueue_script(
    'test-block',                                 // Handle id
    plugin_dir_url(__FILE__) . 'test-block.js',   // Block JavaScript URL
    ['wp-blocks','wp-i18n', 'wp-element'],        // Dépendances
    true                                          // Version
  );
}

On édite ensuite le fichier JavaScript test-block.js.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
( function( wp ) {
   const el = wp.element.createElement;
   const __ = wp.i18n.__;
   const textdomain = 'textdomain';
 
   const iconEl = 'universal-access-alt';
 
   wp.blocks.registerBlockType( 'block/test', {
      title: __( 'My Block', textdomain ),
 
      category: 'common',
      icon: iconEl,
 
      // Remove to make block editable in HTML mode.
      supportHTML: false,
 
      edit: function( props ) {
         return el(
            'p',
            { className: props.className },
            __( 'Replace with your content!', textdomain )
         );
      },
 
      save: function() {
         return el(
            'p',
            {},
            __( 'Replace with your content!', textdomain )
         );
      }
   } );
} )( window.wp );

On recharge l’éditeur et l’on voit apparaître, en appuyant sur nouveau bloc, l’icone dashicons ‘universal-access-alt’ et le titre ‘My Block’ dans la section ‘common’ des blocs.

Ajout de bloc personnalisé, block editor

On peut personnaliser l’icone représentant le bloc en définissant un svg et un path dans iconEl :

1
const iconEl = el( 'svg', { width: 20, height: 20, viewBox: '0 0 512 512' }, el('path', { d: "m236 7c-63 6-114 30-157 72-38 39-62 87-71 142-2 16-2 54 0 70 9 56 33 103 71 142 39 38 87 62 142 71 16 2 54 2 70 0 56-9 103-33 142-71 38-39 62-86 71-142 2-16 2-54 0-70-9-55-33-103-71-142-39-38-87-62-141-70-10-2-48-3-56-2z m-62 129c18 3 32 9 37 16 1 1 10 31 20 65 10 34 19 67 21 71l3 9 16-33c22-45 46-96 58-123 3-7 5-7 20-7 20 0 41 4 51 11 8 5 9 8 9 28 0 14 3 110 5 168 0 17 0 20-1 23-3 4-8 5-20 5-24-2-43-9-48-20-1-2-1-15-1-69 0-36 0-69-1-74l0-9-8 15c-4 9-14 31-23 49-21 45-28 60-37 83-11 25-10 25-26 24-20 0-38-5-46-14-4-3-4-5-12-33-18-66-34-123-35-121-1 3-12 87-18 139-2 13-3 25-3 26-1 2-5 4-9 4-1 0-6-1-9-2-8-2-15-8-18-14-2-6-2-13 15-113 5-36 11-73 13-83 1-10 3-18 4-20 0-1 3-2 5-2 2-1 4-1 5-2 1 0 25 1 33 3z" } ) );

Le path est déterminé à l’aide d’un générateur de police d’icones telle que Fontastic. Ne pas oublier l’attribut viewBox, sinon cela rique de ne pas marcher.

Icone SVG de bloc personnalisé, Gutenberg Block Editor

Le code utilisé pour les fonctions edit et save est du code wp React Element. Si l’on veut utiliser du JSX, il faut au préalable compilé le code JavaScript, ce qui fera l’objet d’un nouvel article. Pour transformer facilement du code JSX en React.createElement ou wp.element.createElement, on peut utiliser le compilateur Babel en ligne.

Par exemple, si l’on veut insérer un bloc du type :

<pre><code>Replace with your content</code></pre>

Babel Compiler

On insère le code suivant pour les fonctions edit et save :

1
2
3
4
5
6
7
8
9
10
11
edit: function( props ) {
   return el(
      "pre",
      { className: props.className },
      el(
         "code",
         null,
         __( 'Replace with your content!', textdomain )
      )
   );
},

Et hop, on peut ajouter un bloc personnalisé à l’Editeur de blocs Gutenberg de WordPress.

Soumettre un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables.