Comment créer un module Divi : Image Overlay

7 Mar 2018

EDIT 18/09/2018 : Mise à jour suite à la refonte du code source de Divi (v3.1) et compatibilité partielle avec le Visual Builder.

Salut à tous,

Nous avons déjà vu comment modifier des modules Divi avec la récupération des alt text en bibliothèque. Aujourd’hui, nous allons créer un module de toute pièce. Enfin presque ; je suis plutôt du genre à recycler !

Pour l’exemple, j’ai choisi d’implanter un module qui reprend le principe du module Image, mais qui permet en plus de superposer un texte sur l’image, avec un fond de couleur, au survol de la souris ou en permanence. Ce qu’on appelle communément un « overlay ». Ce mécanisme est d’ailleurs tellement commun qu’Elegant Themes n’a pas jugé bon de l’intégrer dans Divi en natif 😉 Ce n’est que le 147e grief que j’ai contre eux, ne vous inquiétez pas, je râle tout le temps.

En fait ce sujet m’est assez cher car je trouve que c’est une grosse faiblesse de Divi. On peut approximativement combler le manque en utilisant un module Texte avec une image de fond, mais cela implique que l’image sera rognée sur les bords en fonction de la mise en page, et de plus on n’aura pas l’effet « hover » (le survol à la souris) à notre disposition, à moins de le paramétrer en CSS ou d’utiliser un bouton. Pas très adapté, en somme !

Bref, le module conserve les propriétés classiques « lien » et « visionneuse » du module original. Il permet en outre de styliser le texte (titre et contenu) avec les réglages adaptés (police, taille, couleur, ombre, niveau de titre, etc.). Résultat :

Un texte en superposition sur une photo

La technique est « relativement » simple si on connait un peu HTML, CSS et PHP, et si on aime bien farfouiller le code. Il faut surtout accepter, et ça a été le plus dur pour moi, de découvrir le côté sombre de Divi : son code obscur sans aucun commentaire, avec des noms de variables qui ne correspondent pas exactement à leur rôle, des éléments dupliqués, du rafistolage, etc.  Codeurs sensibles, s’abstenir.Depuis Divi 3.1, celui-ci a d’ailleurs été nettement amélioré par Elegant Themes, même s’il reste encore du boulot.

Deux stratégies : thème enfant ou plugin

Il y a deux façons d’envisager l’ajout d’un nouveau module dans Divi ; modification d’un thème enfant ou ajout d’une extension. Ces deux techniques sont très équivalentes, on l’a vu avec le plugin alt text.

J’ai choisi ici la solution du plugin car elle est plus souple pour vous sans être plus compliquée pour moi. Vous pourrez ainsi installer le module Image Overlay en un clic après l’avoir téléchargé à la fin de cet article 🙂

Approche globale pour ajouter un module à Divi

Pour créer mon nouveau module, bien entendu je ne suis pas parti de zéro avec un éditeur de texte et trois litres de café… Je me suis d’abord demandé comment étaient implémentés les modules dans Divi, afin de reproduire le mécanisme par analogie (comprendre « copier-coller » !), et surtout je me suis penché sur les modules existants qui pouvaient me fournir ce dont j’avais besoin. On ne va pas réinventer la roue !

La création du module

Les modules Divi sont en fait des « objets » PHP, définis par des « classes objet ». Je ne vais pas rentrer dans les détails, ni même vous introduire la notion de « langage objet », car ce n’est pas le propos de ce tuto. Vous devez juste savoir qu’un objet module dans Divi permet de spécifier :

  • l’interface de réglage de l’objet dans le constructeur de page (back-end ou front-end avec le Visual Builder),
  • toutes les variables à mémoriser lors de la sauvegarde de l’objet dans un shortcode (que ce soit sur une page ou en bibliothèque),
  • la génération du code HTML associé au module dans la page récupérée par votre navigateur (le « rendering » du shortcode).

Et que pour ajouter un module dans Divi, il faut :

  • déclarer la classe objet associée (en procédant par analogie avec les autres) ;
  • l’instancier, pour pouvoir concrètement manipuler l’objet en mémoire (builder ou front-end) ;
  • initialiser le shortcode (un « mot-clé » avec pleins de paramètres, sauvegardé par le builder, qui sera remplacé par le code HTML en front-end) correspondant à l’instance du module ;
  • ajouter un peu de code CSS associé au module dans le fichier style.css de Divi.

Remarque : Si la suite de mots « instancier une classe objet » ne vous évoque rien, à part peut-être une envie de partir en courant, c’est normal. C’est un concept abstrait fondamental dans la programmation orientée objet (la POO, quoi !). Mais ne vous inquiétez pas, on s’en servira très peu ici, et vous pourrez comprendre ce qui se passe sans en avoir aucune notion.

Fonctionnalités à implanter

Par chance, tout ce dont nous avons besoin pour notre module existe déjà dans les modules originaux Divi (je n’ai quand même pas choisi au hasard…).

En effet, le module Image fournit bien sûr toute l’infrastructure nécessaire à notre module et la majorité des options et mécanismes dont nous avons besoin :

  • l’image elle-même,
  • l’overlay avec l’icône au survol de la souris pour les liens et le zoom (qui nous apporte la superposition, trop bien !),
  • le mécanisme de lien,
  • la visionneuse,
  • les réglages de base commun à tous les modules (espacement, ombres, etc.),
  • les réglages avancés également communs.

Pour spécifier le texte à superposer, j’ai ensuite tout simplement décortiqué le module Blurb pour récupérer le paramétrage du titre et du contenu 😉

Et enfin pour afficher l’overlay, j’ai adapté le mécanisme de l’objet Image et injecté le texte dans le code généré.

L’implantation d’un nouveau module en détails

J’explique ci-après mon cheminement pour arriver au code final. Je vous invite à le consulter si vous désirez voir les changements concrets, car c’était trop fastidieux d’intégrer proprement chaque élément de code supprimé/modifié/ajouté dans cet article.

Au départ, le module Image

Ayant décidé de récupérer le module Image pour en faire une base départ, j’ai copié le contenu du fichier Image.php dans un nouveau fichier divi-image-overlay.php qui me servira au final de « plugin ».

J’ai ensuite remplacé dans le nouveau fichier toutes les références au module Image par leur équivalent avec le nouveau module :

  • la classe objet ET_Builder_Module_Image devient ET_Builder_Module_Image_Overlay ;
  • le nom du module « Image » devient « Image Overlay » ;
  • la classe de l’objet dans le code généré « et_pb_image » devient « et_pb_imageoverlay » ;
  • et surement d’autres (j’aurais dû écrire le tuto sur le moment…).

A ce stade, mon fichier n’est pas encore utilisable, mais il contient la définition d’un nouveau module « Image Overlay », au fonctionnement exactement identique au module Image.

Instanciation du nouveau module

Avant de continuer à développer le module, je voulais tout de suite savoir si je partais dans la bonne direction, donc j’ai voulu le tester. Pour cela, il fallait :

  • instancier le module comme tous les autres,
  • déclarer le shortcode associé,
  • intégrer le mécanisme dans un plugin.

Pour les deux premiers point, j’ai procédé par analogie avec les autres modules (déclaration de la classe et création de l’instance par appel à new).

Pour le second, j’ai ajouté un entête de type « extension » au fichier, et j’ai encapsulé tout le reste dans une fonction que j’injecte dans Divi après l’initialisation du builder, pour être sûr que tous le nécessaire au code du module a déjà bien été mis en place.

Une fois zippé et installé sur une installation WordPress avec Divi, le plugin est bien fonctionnel :

Le Divi builder en back-end

Ajustements CSS

Après avoir un peu testé le module, je me suis rendu compte que des problèmes apparaissaient au niveau de son affichage sur une page… C’était dû au CSS standard du module Image qui n’était pas appliqué au nouveau module. Effectivement, la classe et_pb_imageoverlay n’est pas affectée par le CSS ciblé par et_pb_image.

J’ai donc dû injecter le CSS de base manquant dans le fichier style.css, via la fonction ET_Builder_Element::set_style(), qui permet d’écrire le CSS dans le fichier au moment de l’instanciation du module.

Très pratique pour ne pas avoir à modifier le fichier style.css directement ou inclure un fichier supplémentaire dans le plugin. Mais un peu moins propre, je l’avoue… je me suis laissé emporter par la philo Divi, il faut croire !

Suppression des éléments inutiles

Une fois le module opérationnel, j’ai continué par une phase de nettoyage pour supprimer ce qui concernait l’affichage de l’icône :

  • variables associées à l’icône (type et couleur),
  • affichage icône si lien ou visionneuse,
  • choix de l’icône dans l’onglet « style » du module, rubrique « superposition ».

Pour cela, j’ai recherché dans le code du nouveau fichier les occurrences des variables PHP overlay_icon_color et hover_icon, et supprimé les variables et tous les réglages associés dans la méthode init(), ainsi que tout le code généré dans la méthode render().

Affichage de l’overlay au survol ou en permanence

J’ai ensuite décorrélé le type de l’image (lien/visionneuse) et l’affichage de l’overlay, et remplacé dans l’onglet « style » du module la bascule permettant d’utiliser un overlay par une bascule permettant de l’afficher en permanence plutôt qu’uniquement au hover.

Pour ce faire, j’ai remplacé la variable use_overlay par une nouvelle variable always_visible associée à la bascule, et ajouté la classe « always-visible » dans le code généré si l’overlay doit être affiché en permanence, avec le CSS associé.

Ainsi, quel que soit le type de l’image (lien, visionneuse, ou image simple), on peut afficher l’overlay au survol de la souris ou en permanence.

J’ai bien entendu conservé le choix de la couleur de l’overlay.

Puis le texte du Blurb

Pour le titre et le contenu de l’overlay, je me suis naturellement tourné vers le Blurb, qui propose titre et contenu. Il a juste fallu isoler les parties du code associées à ces deux éléments et les intégrer dans le nouveau module :

  • champs « titre » et « contenu » dans l’onglet « contenu » du module,
  • bascule « couleur du texte » dans l’onglet « style » (pour gérer les fonds clairs/sombres),
  • tous les réglages de style associés au titre dans la rubrique « titre texte »,
  • et de même pour le contenu dans la rubrique « corps texte »,
  • CSS personnalisé pour titre et contenu dans l’onglet « avancé ».

Récapitulatif des nouveaux réglages

Onglet « contenu » :

Divi builder image overlay contenu

Onglet « style » :

Divi builder image overlay style

Onglet « avancé » :

Divi builder image overlay avancé

Et enfin le code généré

Dans le code HTML généré pour le nouveau module (rappel du shortcode par la méthode render), j’ai ajouté à l’overlay existant un div contenant titre et contenu, qui me permet de centrer facilement tout le texte sur l’image.

Il est bien sûr toujours possible d’aligner le texte comme on le souhaite (gauche, centre, droite, justifié), mais le bloc texte sera toujours centré sur l’image, horizontalement et verticalement (voir exemple en haut de page).

Au final, voici le module Divi Image Overlay observé à la loupe de l’inspecteur :

Code html du module Image Overlay

Compatibilité avec le Visual Builder

La compatibilité du plugin avec le VB est en mode ‘partial’, ce qui veut dire que le rendu est effectué via la fonction render() utilisée en front-end, et non pas via React comme les modules natifs de Divi ou les modules externes en mode compatibilité ‘on’.

Concrètement, l’affichage n’est donc pas aussi réactif car il faut recharger le module à chaque modification dans les paramètres, mais c’est suffisant pour apprécier le rendu et faire quelques réglages (attention, quelques bugs cependant quand on le chahute un peu trop, mais c’est indépendant de ma volonté).

Peut-être une compatibilité totale dans une prochaine mise à jour…

Télécharger l’extension Divi Image Overlay

Vous pouvez télécharger le plugin pour l’installer et l’utiliser, ou simplement pour consulter son code source 😉 J’ai essayé de commenter clairement les modifications que j’ai effectuées par rapport à l’objet Image et celles inspirées du Blurb.

Disclaimer : J’ai mis à jour et testé le module avec la version 3.15 de Divi, et il ne sera pas forcément maintenu.

 

Télécharger Divi Image Overlay 2.0

 

Conclusion

L’ajout d’un module dans Divi n’est donc pas « très » complexe, pour peu que l’on soit un tantinet codeur.

Ceci dit, le module Image Overlay est un exemple basique. Je l’ai choisi car j’avais à ma disposition dans Divi tous les éléments nécessaires, et parce qu’il y avait peu de choses à modifier par rapport au module Image existant. Pour un module plus complexe, j’y réfléchirais à deux fois avant de me lancer, car :

  • le code de Divi est crado et n’est pas commenté, donc il faut un certain temps pour le prendre en main ;
  • la création d’un plugin nécessite de le maintenir, car les mises à jour de Divi risquent fortement de l’impacter un jour ou l’autre.

A bientôt et n’hésitez pas à me faire part de vos réalisations !