Transformer les blocs et définir des raccourcis Markdown

Dans l’éditeur, il est possible de transformer un bloc en un autre bloc, similaire dans les informations qu’il affiche. On va tirer parti de ce mécanisme dans notre propres blocs sur mesure et on va même voir comment déclarer des raccourcis à base de markdown pour insérer nos blocs plus rapidement.

Sommaire du cours

Transformations bloc à bloc
Insérer des blocs via des raccourcis Markdown
Aller plus loin avec les transformations

Lorsque vos utilisateurs écrivent dans l’éditeur, il se peut qu’à un moment, ils se disent « Tiens, j’aurais pu utiliser tel bloc à la place de celui-ci ».

Alors afin de leur éviter de supprimer le bloc et d’en recréer un, Gutenberg propose de transformer certains blocs en d’autres blocs.

Ainsi, le contenu déjà écrit sera conservé et on n’aura pas besoin de commencer à zéro.

Le menu permettant de transformer un bloc en un autre. Ici, on peut transformer le paragraphe en titre, liste, ou citation par exemple. — On peut transformer un simple paragraphe en titre, liste, citation…

Dans cet exemple, on voit qu’on peut transformer le paragraphe en cliquant sur la première icône de la Toolbar.

C’est un mécanisme qui peut s’avérer pratique et qui aide à l’amélioration de l’expérience utilisateur de l’éditeur.

Dans ce cours, on va voir comment déclarer des transformations pour nos blocs sur-mesure, pour transformer un bloc natif en notre bloc, et inversement. Et vous allez voir que c’est hyper facile !

On va également voir comment créer des raccourcis de type Markdown pour insérer des blocs dans le contenu à partir de raccourcis textuels.

Transformations bloc à bloc

On va commencer par voir comment transformer un bloc présent dans l’éditeur en un autre bloc aux attributs similaires.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Celui que l’on va étudier dans ce cours est très simple :

Le bloc que l'on va transformer, avec un fond jaune et une zone de texte administrable. — Un bloc simple avec un seul attribut et un RichText

C’est un bloc avec un fond uni, et une zone RichText à l’intérieur. Rien de plus.

Pour ceux qui ont accès à la formule premium de la formation, on va étudier l’exemple /src/16-transforms/ de mon plugin.

Lorsque l’on regarde le fichier block.json, on peut observer un seul attribut description sous forme de string dont le sélecteur est un paragraphe :

JSON

/src/16-transforms/block.json

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "capitainewp/transforms",
	"version": "1.0",
	"title": "Transforms",
	"category": "capitainewp",
	"icon": "update",
	"description": "Un bloc qui se transforme en un autre.",
	"attributes": {
		"description": {
			"type": "string",
			"source": "html",
			"selector": "p"
		}
	},
	"example": {
		"attributes": {
			"description": "<p>Je suis un bloc transformable.</p>"
		}
	},
	"textdomain": "capitainewp-blocks",
	"editorScript": "file:./index.js",
	"editorStyle": "file:./index.css",
	"style": "file:./style-index.css"
}

Et dans edit.js, on a un simple <RichText /> pour piloter cette valeur. Un bloc classique comme le premier qu’on a réalisé dans cette formation au final.

JSX

/src/16-transforms/edit.js

import { __ } from "@wordpress/i18n";
import { useBlockProps, RichText } from "@wordpress/block-editor";

import "./editor.scss";

export default function Edit(props) {
	const { attributes, setAttributes } = props;
	const { description } = attributes;

	return (
		<div {…useBlockProps()}>
			<RichText
				tagName="p"
				placeholder={__("Your text", "capitainewp-blocks")}
				value={description}
				onChange={(description) => setAttributes({ description })}
			/>
		</div>
	);
}

L’avantage de n’avoir qu’un seul attribut, c’est que ce sera plus simple pour le transformer en d’autres blocs.

Déclarer des transformations de bloc

Maintenant, pour déclarer des transformations, il faudra aller dans le fichier index.js.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Pour cela, on va ajouter une propriété transforms à la suite de edit et save.

JSX

/src/16-transforms/index.js

import { registerBlockType } from "@wordpress/blocks";

import "./style.scss";

import metadata from "./block.json";
import Edit from "./edit";
import save from "./save";
import transforms from "./transforms";

registerBlockType(metadata.name, {
	edit: Edit,
	save,
	transforms: {
        from: [
            { … },
        ],
        to: [
            { … },
        ],
    },
});

À l’intérieur, on va y assigner un objet avec une structure bien précise :

from : permettra de transformer d’autres blocs en celui-ci ;
to : permet cette fois de transformer ce bloc en d’autres blocs.

On peut donc faire des transformations dans les deux sens, ce qui peut s’avérer très pratique puisqu’on n’a pas accès au code des blocs natifs.

On observe que from et to sont des listes [] qui permettent de définir plusieurs transformations depuis plusieurs blocs et vers plusieurs autres blocs.

Afin d’être plus malins, je vous propose que l’on créé un fichier dédié aux transformations, et que l’on importe ensuite de cette manière :

JSX

/src/16-transforms/index.js

import { registerBlockType } from "@wordpress/blocks";

import "./style.scss";

import metadata from "./block.json";
import Edit from "./edit";
import save from "./save";
import transforms from "./transforms"; // Import du fichier

registerBlockType(metadata.name, {
	edit: Edit,
	save,
	transforms, // Équivalent de « transforms: transform »
});

Ensuite, on créé un fichier transforms.js dans lequel on déclare une constante contenant l’objet, que l’on exporte ensuite.

JSX

/src/16-transforms/transforms.js

import { createBlock } from "@wordpress/blocks";

const transforms = {
	from: [
        { … },
	],
	to: [
        { … },
	],
};

export default transforms;

Rappelez-vous que c’est toujours une bonne idée de découper vos composants, comme on l’a vu dans le cours sur la refactorisation et l’optimisation de notre code.

Maintenant, on va voir ce qu’il faut mettre dans from et to pour faire fonctionner nos transformations !

Transformer depuis un autre bloc

On va commencer par déclarer une transformation depuis un autre bloc (le paragraphe par exemple) vers notre bloc.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Pour cela, on va se positionner dans le from de notre objet transforms.

JSX

/src/16-transforms/transforms.js

import { createBlock } from "@wordpress/blocks";

const transforms = {
	from: [
		{
			type: "block",
			blocks: ["core/paragraph", "core/heading"],
			transform: ({ content }) => {
				return createBlock("capitainewp/transforms", {
					description: content,
				});
			},
		},
	],
	to: […],
};

export default transforms;

Ici j’ai déclaré une seule transformation, depuis le paragraphe vers mon bloc.

La magie opère dans la propriété transform, à laquelle on attache une fonction anonyme. Celle-ci renvoie les attributs du bloc à transformer.

Le paragraphe fournit plusieurs attributs : align, content, direction, dropCap, placeholder.

D’ailleurs, pour connaître les attributs d’un bloc, consultez la liste complète des blocs natifs et leurs attributs dans la documentation WordPress.

Dans notre cas, c’est surtout l’attribut content qui va nous intéresser.

À l’intérieur de la fonction, on va utiliser la fonction createBlock() de WordPress pour créer un bloc. WordPress s’occupe ensuite automatiquement de supprimer le bloc actuel.

JSX

import { createBlock } from "@wordpress/blocks";

return createBlock("capitainewp/transforms", {
    description: content,
});

Dans cette fonction, on indique tout d’abord le nom du bloc que l’on veut créer, ici on indique notre bloc, puis en second paramètre un objet contenant les attributs de notre bloc. On assigne le content du paragraphe à la description de notre bloc.

On doit définir également deux autres propriétés :

type : pour indiquer qu’on fait une transformation bloc à bloc ;
blocks : pour lister le ou les blocs depuis lesquels on active la transformation.

JSX

from: [
    {
        type: "block",
        blocks: ["core/paragraph", "core/heading"],
        transform: ({ content }) => {
            return createBlock("capitainewp/transforms", {
                description: content,
            });
        },
    },
],

On verra à la fin du cours les autres types de transformations possibles, et vous allez voir qu’il y a des choses très intéressantes !

Vous pouvez tout à fait indiquer plusieurs blocs d’origine, mais faites attention à ce qu’ils aient des attributs en commun. Par exemple, le paragraphe et le titre ont tous deux un attribut content.

Essayez maintenant d’insérer un paragraphe et un titre dans une publication. Dans le menu de transformation, notre bloc « Transform » devrait apparaître.

On peut transformer un paragraphe ou un titre en notre bloc, qui apparaît bien dans la liste des transformations disponibles. — La transformation vers notre bloc custom est disponible

Au clic, le contenu est bien récupéré et notre bloc custom apparaît à la place.

Transformer vers un autre bloc

Cette fois, on va faire le contraire : on va donner la possibilité de transformer notre bloc custom en un autre bloc, par exemple un paragraphe ou un titre.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Pour cela, on va aller maintenant du côté de to de notre objet transforms, et comme vous pouvez le constater, l’approche est très similaire à from :

JSX

/src/16-transforms/transforms.js

import { createBlock } from "@wordpress/blocks";

const transforms = {
	from: [ … ],
	to: [
		{
			type: "block",
			blocks: ["core/paragraph", "core/heading"],
			transform: ({ description }) => {
				return createBlock("core/paragraph", {
					content: description,
				});
			},
        },
		{
			type: "block",
			blocks: ["core/title"],
			transform: ({ description }) => {
				return createBlock("core/title", {
					content: description,
				});
			},
		},
	],
};

export default transforms;

Cette fois, je suis obligé de le faire en 2 fois : une transformation vers le paragraphe, et une autre vers le titre.

Mais sinon le principe reste le même : on récupère cette fois la description de notre bloc custom, que l’on assigne à l’attribut content des 2 autres blocs.

Essayez cette fois d’insérer notre bloc custom, et transformez-le en un titre ou un paragraphe. Si tout s’est bien passé, vous devriez retrouver votre contenu dans le nouveau bloc.

Et voilà, on a nos transformations dans les 2 sens ! Simple et efficace.

Insérer des blocs via des raccourcis Markdown

On a vu commencer transformer un bloc en un autre, mais savez-vous qu’il est possible de créer un bloc à partir d’un raccourci de texte ?

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Raccourci sur la touche Entrée

Grâce au type enter, on va pouvoir indiquer que lorsqu’on écrit dans l’éditeur un certain texte, puis qu’on appuie sur la touche « Entrée », le raccourci va se transformer en un bloc :

JSX

transforms = {
    from: [
        {
            type: 'enter',
            regExp: /^-{3,}$/,
            transform: () => createBlock( 'core/separator' ),
        },
    ],
};

Pour cela, on doit utiliser la propriété regExp qui nous permet d’écrire une expression régulière.

Dans cet exemple, lorsqu’on écrit 3 tirets dans l’éditeur, et que l’on appuie sur Entrée, le bloc de séparateur sera automatiquement créé.

C’est d’ailleurs déjà le cas nativement dans WordPress !

Raccourci sur la touche Espace

Il existe aussi le type prefix qui fait à peu près la même chose, mais cette fois lorsqu’on tape un caractère suivi de la touche « Espace ».

JSX

transforms: {
    from: [
        {
            type: 'prefix',
            prefix: '?',
            transform( content ) {
                return createBlock("capitainewp/le-saviez-vous", {
                    content: "",
                });
            },
        },
    ];
}

Dans ce cas, lorsque vous commencez une ligne par ? puis « Espace », Mon bloc « Le saviez-vous ? » sera automatiquement créé.

Le saviez-vous ?

La différence entre les deux exemples, c’est que lorsqu’on appuie sur « Entrée », on insère le bloc et on passe au suivant. Ce qui est adapté pour le séparateur. Avec la technique du préfixe, on insère le bloc et on reste dessus, pour éditer son contenu.

C’est également ce principe qui est utilisé par WordPress pour appliquer les règles de markdown, comme ## qui génère un titre de niveau 2 ou un tiret - qui génère une liste à puces.

Raccourci sur le glisser-déposer

Lorsque vous glissez un média dans l’éditeur, WordPress le transforme directement en bloc correspondant :

Si c’est une image, le bloc « Image » est automatiquement créé ;
Si c’est un document, le bloc « Fichier » est créé ;
Si c’est un son, c’est le bloc « Audio » qui est créé.

Bonne nouvelle, vous allez pouvoir utiliser cette logique pour effectuer vos propres transformations de fichiers :

JSX

transforms: {
    from: [
        {
            type: 'files',
            isMatch: ( files ) => files.length === 1,
            priority: 5, // Priorité forte
            transform: ( files ) => {
                const file = files[ 0 ];
                const blobURL = createBlobURL( file );
                return createBlock( 'capitainewp/custom-file', {
                    href: blobURL,
                    fileName: file.name,
                    textLinkHref: blobURL,
                } );
            },
        },
    ];
}

Si vous faites un bloc pour afficher un type de fichier déjà pris en charge (comme un document) mais que vous voulez que ce soit votre bloc custom qui soit intégré au lieu du bloc « Fichier » habituel, vous pouvez jouer sur la propriété priority, en indiquant un chiffre inférieur à 10 (qui est la valeur par défaut).

Ici, la fonction createBlobURL() permet d’obtenir les informations du fichier téléchargé comme son URL.

Pas mal non ?

Conseil

Ces raccourcis peuvent mine de rien vous faire gagner énormément de temps lors de la rédaction de contenus, surtout pour les rédacteurs chevronnés. N’hésitez pas à en créer plein pour les aider !

Aller plus loin avec les transformations

Avant d’en terminer avec ce cours, je vous invite à aller faire un tour sur la documentation WordPress des transformations. On va y découvrir quelques petites astuces intéressantes.

verrouillé Vidéo premium

Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?

Choisir une formule

Récupérer les blocs enfants (InnerBlocks) lors des transformations

Si vous voulez ajouter des transformations sur des blocs contenant des enfants via le composant <InnerBlocks />, c’est très simple :

JSX

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'capitainewp/block-with-innerblocks' ],
            transform: ( attributes, innerBlocks ) => {
                return createBlock(
                    'capitainewp/other-block-with-innerblocks',
                    attributes,
                    innerBlocks // C'est ici !
                );
            },
        },
    ],
},

Les blocs enfants sont envoyés automatiquement en second paramètre de la fonction rattachée à transforms.

De cette manière, on peut ensuite les transmettre au bloc que l’on crée via le troisième paramètre de la fonction createBlock(), qui sert à définir les blocs enfants justement.

Transformation multi-blocs

Vous pouvez pousser le bouchon encore plus loin en transformant d’un coup plusieurs blocs sélectionnés grâce à la propriété isMultiBlock passée à true :

JSX

const transforms = {
  from: [
    {
      type: "block",
      blocks: ["core/paragraph"],
      isMultiBlock: true,
      transform: (attributes) => {
          
		// Combiner tous les paragraphes sélectionnés en un bloc
        const combinedContent = attributes
          .map((item) => item.content)
          .join('\n\n');
          
        return createBlock("capitainewp/transforms", {
          description: combinedContent,
        });
      },
    }
  ],
}

Dans ce cas, attributes devient une liste [] des attributs de chaque bloc sélectionné, et on récupère chaque contenu pour en faire un contenu unique combiné et enfin retourner notre bloc custom.

Conditions de transformation plus poussées

Enfin, vous allez pouvoir effectuer des vérifications supplémentaires avant de lancer une transformation grâce à la propriété isMatch :

JSX

const transforms = {
    from: [
        {
            type: "block",
            blocks: ["core/list"],
            isMatch: ({ values }) => {
                // Transforme les listes de plus 3 éléments uniquement
                return values && values.length >= 3;
            },
            transform: ({ values }) => {
                // Fusion des éléments
                const formattedContent = values
                    .map(item => `• ${item.content}`)
                    .join('\n');
                
                return createBlock("capitainewp/transforms", {
                    description: formattedContent,
                });
            },
        },
    ],
}

Dans cet exemple, je transforme une liste qui possède au minimum 4 éléments. La transformation ne sera pas possible s’il y en a moins.

Les transformations sont faciles à mettre en place et vont améliorer quelque peu l’expérience utilisateur globale de l’éditeur. N’hésitez pas à les mettre en place sur chacun de vos blocs sur mesure !

Dans le prochain cours, on va voir ce qu’il se passe lorsqu’on change le HTML enregistré dans un bloc, et comment gérer la dépréciation des blocs dans le temps et éviter le HTML invalide.