Intégrer et exploiter dans Magento 2 un plugin jQuery tiers dont le code source est structuré selon le pattern AMD
Pour illustrer cette partie, nous allons intégrer dans Magento 2 le plugin jQuery Slick Carousel, dont le code source est structuré selon le pattern AMD.
Remarque: l’intégration du plugin jQuery tiers va se faire dans un thème. Si vous comptez utiliser le plugin en question sur un projet multi-sites/multi-thèmes ou sur plusieurs projets, une meilleure stratégie consisterait à intégrer ce premier dans un nouveau module MyVendor_Slick qu’on placerait dans app/code/MyVendor/Slick
.
Cette démarche n’est pas décrite ici, mais mériterait d’être envisagée en fonction de vos besoins.
Récupération du plugin sous Git et copie dans l’arborescence du thème
Récupérer la source minifiée du plugin Slick sous Git (tag v1.8.1 dans mon exemple, mais vous pouvez vérifier si il existe un tag plus récent) et copier-coller le fichier dans votre thème, au chemin suivant: app/design/frontend/MyVendor/mytheme/web/js/vendor/slick/slick.min.js
.
Déclaration du plugin en tant que module via RequireJS
Dans le fichier app/design/frontend/MyVendor/mytheme/requirejs-config.js
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
|
var config = { // Paths defines associations from library name (used to include the library, // for example when using "define") and the library file path. paths: { 'slick': 'js/vendor/slick/slick.min }, // Shim: when you're loading your dependencies, requirejs loads them all // concurrently. You need to set up a shim to tell requirejs that the library // (e.g. a jQuery plugin) depends on another already being loaded (e.g. depends // on jQuery). shim: { 'slick': { deps: ['jquery'] } } }; |
Création d’un fichier d’initialisation d’une instance du plugin
Dans votre thème, créer le fichier app/design/frontend/MyVendor/mytheme/web/js/init-slick.js
qui va servir à appeller et à initialiser une instance du plugin javascript Slick et vous donnera accès à toutes les options de l’API originale:
|
define(['jquery','slick'], function($) { return function(config, element) { $(element).slick(config); }; }); |
Petite subtilité: ajouter une configuration spécifique par défaut à toutes les instances de votre plugin
Dans l’exemple ci-dessous, le fichier app/design/frontend/MyVendor/mytheme/web/js/init-slick.js
est agrémenté d’un objet defaults
qui surcharge (via les settings proposés de base par le plugin Slick Carousel prevArrow
et nextArrow
) l’aspect graphique des chevrons « slide précédent/slide suivant ».
L’intérêt d’ajouter une configuration spécifique par défaut à toutes les instances de votre plugin réside, pour l’exemple du Carousel, dans le fait qui si la charte graphique de votre projet prévoit les mêmes chevrons spés pour tous les sliders du site, vous allez pouvoir tous les initialiser sans avoir besoin de re-préciser à chaque fois que vous voulez surcharger les pictos fournis de base par ceux de votre charte.
Vous pouvez, bien entendu, les re-surcharger et utiliser d’autres options du plugin à la demande pour chaque nouveau Carousel que vous allez mettre en place.
|
define(['jquery','slick'], function($) { return function(config, element) { let defaults = { prevArrow: '<button type="button" class="btn-round slick-prev"><svg viewBox="0 0 100 100" class="icon icon-arrow-back-chevron"><use xlink:href="#icon-arrow-back-chevron"></use></svg></button>', nextArrow: '<button type="button" class="btn-round slick-next"><svg viewBox="0 0 100 100" class="icon icon-arrow-forward-chevron"><use xlink:href="#icon-arrow-forward-chevron"></use></svg></button>' }; $(element).slick($.extend(defaults, config)); }; }); |
Appeler et initialiser une instance du plugin sur un élément du DOM
Cette page de la documentation officielle vous expliquera comment appeler et initialiser une instance du plugin sur un élément du DOM dans Magento 2.
Elle aborde notamment la manière de procéder depuis un fichier template PHTML, depuis un fichier JS et comment exécuter data-amge-init
et x-magento-init
dans un cas où le DOM se met à jour dynamiquement.
Dans ce billet, je vais me contenter d’illustrer un exemple de notation déclarative avec x-magento-init
depuis un fichier PHTML.
Exemple de notation déclarative avec x-magento-init
depuis un fichier PHTML
Ici, j’initialise simplement mon module Slick sur l’élément du DOM qui porte l’ID home-slider
. Le carousel va s’afficher soit avec les options de base fournies par le plugin Slick, soit avec les options de base fournies par le plugin Slick ET des pictos chevrons surchargés par ma configuration par défaut si j’en ai défini une.
|
<div id="home-slider"> <div><a href="#">Slide one</a></div> <div><a href="#">Slide two</a></div> <div><a href="#">Slide three</a></div> <div><a href="#">Slide four</a></div> <div><a href="#">Slide five</a></div> <div><a href="#">Slide six</a></div> </div> <script type="text/x-magento-init"> { "#home-slider": { "js/init-slick": {} } } </script> |
Même exemple avec ajout d’options
Ici, je choisis de paramétrer mon carousel afin qu’il affiche 4 slides à la fois et qu’on scrolle d’une slide à chaque fois qu’on active les boutons prev/next ou tout autre mode de navigation fourni par le plugin. Les options slidesToShow
et slidesToScroll
sont fournies par le plugin Slick et exploitables immédiatement grâce à la magie d’AMD, de RequireJs et de Magento.
|
<script type="text/x-magento-init"> { "#home-slider": { "js/init-slick": { "slidesToShow": "4", // # of slides to show at a time "slidesToScroll": "1" // # of slides to scroll at a time } } } </script> |
Ressources en ligne: