Le composant import de média - Formation Gutenberg - Capitaine WP

Formation « Créer des blocs avec Gutenberg »

Le composant import de média

Lecture :7 minutes •0

Le composant d’import de média fait appel à la bibliothèque de médias de WordPress et permet d’importer des photos, vidéos, fichiers et les afficher dans vos blocs. Il est très simple à mettre en place.

On peut s’imaginer que l’import d’un média dans un bloc est un calvaire. Eh bien détrompez-vous car c’est plutôt simple !

Bon, ce bloc que j’ai fait n’est pas très différent du bloc Image par défaut fournit avec WordPress en terme de fonctionnalités, mais vous pourrez ensuite l’adapter comme vous le souhaitez.

Utiliser le composant MediaUpload

Pour cet exemple on va regarder le bloc src/10-media.

Quand on appelle le bloc la première fois, une zone apparait :

Bloc choix d'une image
Le bloc invite l’utilisateur à choisir une image

En cliquant sur le bouton on ouvre la médiathèque WordPress :

La médiathèque de WordPress
Le composant permet d’ouvrir la médiathèque de WordPress

La médiathèque est codée en Backbone.js (car dans le coeur de WP depuis très longtemps) et reste indépendante de React, mais comme on peut le voir rien ne l’empêche de bien communiquer avec Gutenberg.

Une fois l’image choisie, elle apparait dans l’éditeur, accompagnée dun bouton « supprimer » quand le bloc est actif :

L'image affichée dans le bloc image
L’image choisie est affichée

Et maintenant on va analyser le code pour faire tout cela.

Les attributs et leurs fonctions

On va commencer avec les attributs ! On en déclare 3 : l’ID de l’image, son URL et sa description alternative.

JSX
src/11-media/index.js

En soit l’identifiant ne sert qu’à indiquer à la bibliothèque de média quelle et l’image qu’on a choisi afin qu’elle soit affichée en bleu dans la liste d’images de la bibliothèque lorsque l’on change d’image. Sinon il n’a pas d’autre utilité pour notre bloc.

Il est stocké dans le commentaire de définition du bloc <!-- wp:capitainewp/media {"pictureID":69} -->

Concernant l’URL et la description, ce sont des attributs de la balise <img>, respectivement src et alt.

J’ai crée 2 fonctions, l’une pour définir les attributs de l’image une fois que l’utilisateur en a choisi une dans la bibliothèque de médias, et une autre pour la retirer.

J’ai ajouté un console.log(picture) dans onSelectImage() afin que l’on puisse voir toutes les informations qui nous sont retournées.

Et on peut dire que l’on est gâtés ! On a le droit à plein de données, dont notamment les différentes tailles d’image :

résultat du console.log
Les données de l’image retournées par la médiathèque

Du coup, on pourrait préférer sélectionner une taille intermédiaire, car mon image provient de Unsplash et fait plus 5000px de large, pas terrible donc pour le temps de chargement de ma page.

JS

Mieux ! Et si on veut aller plus loin on pourrait utiliser le srcset HTML5 pour définir plusieurs sources de tailles intermédiaires, mais on a un peu la flemme, n’est-ce pas ?

On pourrait également tester le type mime avec picture.mime, mais on a déjà restreint en amont le choix du type de fichier dans le composant <MediaUpload /> avec l’attribut allowedTypes={ [ 'image' ] }.

Pour supprimer l’image c’est simple, il suffit d’assigner la valeur null à mes attributs pour effacer leurs valeurs.

Comme on peut le voir ensuite dans le code, je teste en premier lieu la présence d’un ID d’image : si il n’est pas défini, j’affiche l’import de média, et s’il est défini j’affiche l’image et le bouton de retrait. En simplifiant :

JSX

On aurait pu écrire l’inverse en fait, mais je pars du principe que l’on commence toujours par le cas par défaut, quand il n’y a pas encore d’image définie.

Le composant MediaUpload

On va regarder maintenant plus en détails ce composant qui nous permet d’invoquer la bibliothèque de média.

Voici son code :

JSX
src/11-media/edit.js

Il ne faut pas oublier de charger les composants en début de fichier, ils appartiennent à @wordpress/block-editor.

On va ensuite brancher notre fonction onSelectImage sur l’événement onSelect.  On peut ensuite définir le type de fichier désiré, ici des images seulement.

On pourrait tout à fait utiliser l’import de média pour récupérer l’url d’un fichier et le stocker dans un champ <TextControl> tout simple.

La value permet d’indiquer l’image actuellement choisie grâce à pictureID. Comme je le disais plus haut cette valeur ne sert au final qu’à ça.

Ensuite les choses deviennent intéressantes, on a un attribut render qui nous permet d’appeler une fonction et du HTML.

C’est ici que l’on va pouvoir mettre le markup pour donner une apparence personnalisée à mon import de média.

Alors pourquoi ne pas tout simplement mettre mon HTML entre les balises <MediaUpload /> comme le permet habituellement React ? Comme cela par exemple :

HTML

En fait tout simplement car via le render, on peut invoquer une fonction (anonyme) et surtout récupérer des propriétés du composant, comme la fonction open qui va nous permettre de lancer l’ouverture de la bibliothèque de médias.

C’est là qu’est toute la nuance au final. Donc bon, je vous accorde que ça fait un peu bizarre de mettre du markup directement dans un attribut mais bon, ce n’est pas la première bizarrerie React que l’on croise au final !

Information

Mais d’où vient cette méthode open que l’on a déclarée nulle part ? En fait c’est le composant MediaUpload qui nous la fournit via le render. On peut donc ensuite l’utiliser telle quelle sans souci !

A l’intérieur j’y ai placé un Placeholder et un Button.

Concernant le bouton, on peut définir plusieurs styles différents. Consultez la documentation du composant Button pour savoir quelles sont les possibilités offertes par celui-ci.

Pour ma part, j’ai utilisé les propriétés isSecondary et isLarge pour l’afficher en bleu et assez gros.

Le Placeholder est le composant utilisé par les composants image, galerie… Il consiste en une simple zone dans laquelle on peut mettre un titre, des instructions et des boutons à l’intérieur et qui occupe l’espace en attendant que l’utilisateur sélectionne une image.

Cette fois on remarque que l’on place bien le Markup à l’intérieur des balises <Placeholder> ici </Placeholder>.

À quoi sert le MediaUploadCheck ?

Ce composant qui englobe MediaUpload permet de vérifier que le rédacteur a bien les droits pour importer une image. Le cas échéant, il ne pourra pas importer d’images.

C’est le cas par exemple du rôle Contributeur. Je parle d’ailleurs des rôles et capacités de WordPress dans la formation Développeur de thèmes.

Quand l’image est définie

Et enfin, de l’autre côté du test, on affiche simplement l’image lorsqu’un ID est défini. On affiche également un bouton pour permettre de supprimer l’image via la fonction onRemoveImage, mais on ne l’affiche que lorsque le bloc est actif grâce à la propriété props.isSelected.

JSX
src/11-media/edit.js

Et voilà ! Vous avez un composant image fonctionnel sans difficulté. Vous allez pouvoir le personnaliser à volonté.

Études de cas

On va maintenant rapidement voir comment j’ai pu utiliser les médias lors de mes expériences sur mon extension Advanced Gutenberg Blocks.

Cas n°1 : le bloc Témoignage de Advanced Gutenberg Blocks

Voici mon bloc Témoignage (testimonial). Ici je n’utilise pas le <Placeholder /> de Gutenberg et j’opte pour ma propre mise en forme.

Voici le rendu de mon bloc :

bloc testimonial sans image
Avant de choisir une image
bloc testimonial avec image
Une fois l’image choisie

Une fois l’image choisie, il suffit de cliquer dessus pour la changer. La médiathèque s’ouvre alors pour permettre de faire une nouvelle sélection.

Si vous regardez le code sur mon répertoire Github, cette fois toute ma logique est à l’intérieur du composant <MediaUpload />.

Comme ce composant n’as pas d’apparence, je l’affiche tout le temps, et je teste si j’ai un ID à l’intérieur : si oui, j’affiche l’image ainsi que le bouton « supprimer » mais aussi un lien autour de l’image pour rouvrir la bibliothèque afin d’en choisir une autre. Pour cela je fais simplement appel à la méthode open, qui n’est disponible qu’à l’intérieur de ce composant.

Et tant qu’aucune image n’est définie, j’affiche simplement un placeholder maison.

Je pense que du coup cette approche est meilleure que la précédente en ce qui concerne la gestion de l’image.

JSX

Cas n°2 : le bloc Unsplash et Giphy de Advanced Gutenberg Blocks

Mon extension possède également 2 autres blocs d’images pour Unsplash et Giphy qui permettent de chercher une image ou un GIF sur les sites concernés.

Le bloc Unsplash en action

Mais cette fois, au lieu d’afficher directement l’image dans le bloc, je vais la télécharger dans la médiathèque et transformer le bloc en un bloc image natif de Gutenberg.

JSX
src/blocks/unsplash/search.js

Le code de ce bloc est assez complexe car il doit récupérer l’image, la télécharger dans la médiathèque et supprimer enfin le bloc actuel pour le remplacer par un bloc image, mais je vous ai isolé la fonction qui permet de le faire.

Conseil

En utilisant le bloc natif d’image de Gutenberg, vous vous assurez que le HTML généré prendra en compte les srcset pour le responsive, ce qui n’est pas le cas dans mon premier exemple.

Si vous souhaitez en apprendre davantage sur les srcset dans WordPress, je vous invite à consulter le cours correspondant dans la formation développeur de thèmes :

Les srcset et WordPress


Bref, comme vous avez pu le constater, dans l’ère Gutenberg l’import de média n’est qu’une formalité, grâce à React et à la manière dont on fait du JS moderne, sous forme de composants.

Dans le chapitre suivant on va voir des concepts plus avancés, mais toujours simples à utiliser. On va commencer par voir l’inspecteur afin d’ajouter des paramètres à nos blocs.

0

Questions, réponses et commentaires

Laisser un commentaire