Exemple basic

Pour créer un composant Alpine.js, vous pouvez utiliser l'attribut x-data pour définir les données du composant.

L'élément HTML qui porte l'attribut x-data devient le composant Alpine.js

<div x-data="{ title: 'Titre composant Alpine JS' }">
    <h1 x-text="title"></h1>
</div>

Dans Magento

Dans Magento vous verez souvent l'écriture suivante :

Dans x-data on passe le nom d'une fonction qui renvoie un objet contenant la logique du composant.

<div x-data="myComponent">
    <h1 x-text="title"></h1>
    <button @click="changeTitle">Changer le titre</button>
</div>
<script>
    function myComponent() {
        return {
            title: 'Titre composant Alpine JS',
            changeTitle() {
                this.title = 'Nouveau titre';
            }
        };
    }
</script>

Avant / Après

Sur un Magento standard on pourrais écrire le code suivant :

<div class="my-component" data-mage-init='{"Vendor_Module/js/mon-composant":{"message":"Titre composant Require JS"}}'>
    <h1 id="title" class="my-component__title">Titre composant Alpine JS</h1>
    <button id="buttonChange" class="my-component__button">Changer le titre</button>
</div>

et dans le fichier Vendor_Module/web/js/mon-composant.js on aurais le code suivant :

define(['jquery'], function ($) {
    "use strict";
    return function (config, element) {
        $("#buttonChange").on("click", function () {)
            $("#title").text(config.message);
        });
    }
});

Mutualisation des composants

On vient de voir que le code est écrit directement dans le code HTML et non dans un fichier JavaScript séparé. Mais si vous voulez réutiliser le même code dans plusieurs endroits de votre site, vous pouvez créer un composant Alpine.js réutilisable.

Plusieurs modules utilisent la convention suivante pour séparer le code Javascript du templates.

Le javascript est écrit dans un fichier .phtml souvent nommé Vendor_theme/templates/pages/js/mon-fichier-de-js.phtml.

Et pour les traductions ?

Comme le code JavaScript est écrit directement dans le .phtml, vous pouvez utiliser la fonction __() de Magento pour traduire les chaînes de caractères.


<div x-data="myComponent">
    <h1 x-text="title"></h1>
    <button @click="changeTitle"><?= __('Changer le titre'); ?></button>
</div>
<script>
    function myComponent() {
        return {
            title: "<?= __('Titre composant Alpine JS'); ?>",
            changeTitle() {
                this.title = "<?= __('Nouveau titre'); ?>";
            }
        };
    }
</script>

Sinon vous pouvez également utiliser la fonction hyva.str() pour traduire les chaînes de caractères dans le code JavaScript.

hyva.str('Welcome %1', customer.firstName);

La petite boite à outlis bien pratique

Hyva met à disposition un objet hyva qui contient plusieurs fonctions utiles pour les développeurs comme par exemple :

Récupérer un cookie
Ecrire un cookie
Formater un prix
traduire une chaîne de caractères
etc.

Toutes les fonctions disponibles sont documentées dans la documentation Hyva.

Comment charger un fichier javascript ?

Comme nous l'avons vu précédemment, Alpine.js est intégré directement dans le HTML et requireJS n'est plus utiliser.

Il est toujours possible de charger un fichier JavaScript externe si nécessaire, mais il faut le faire de manière différente.

const script = document.createElement('script')
script.src = 'https://www.example.com/render-blocking-script.js';
script.type = 'text/javascript';
document.head.append(script);

Vous pouvez utiliser une autre technique pour charger un fichier externe et attendre son chargement avant de l'utiliser.


function loadJs(jsFileSrc) {
    return new Promise(resolve => {
        const script = document.createElement('script');
        script.type = 'text/javascript';
        script.src = jsFileSrc;
        script.async = true;
        script.onload = resolve;
        document.head.appendChild(script);
    })
}

loadJs('<?= $escaper->escapeJs($block->getViewFileUrl('Example_Module::js/library.js')) ?>').then(() => {
    console.log('Fichier JavaScript chargé avec succès');
    // Vous pouvez maintenant utiliser les fonctions du fichier JavaScript
});

Documentation Hyva