Templating

Alpine propose une poignée de directives utiles pour manipuler le DOM d'une page web.

Voyons ici quelques directives de templating de base, mais n'oubliez pas de parcourir les directives disponibles dans la barre latérale pour en obtenir la liste exhaustive.

Contenu textuel

Alpine facilite le contrôle du contenu textuel d'un élément avec la directive x-text.

<div x-data="{ title: 'Démarrage' }">
    <h1 x-text="title"></h1>
</div>

Alpine définit maintenant le contenu textuel du <h1> avec la valeur de title (« Démarrage »). Quand title change, le contenu du <h1> change aussi.

Comme toutes les directives d'Alpine, vous pouvez utiliser n'importe quelle expression JavaScript. Par exemple :

<span x-text="1 + 2"></span>

Le <span> contiendra maintenant la somme de « 1 » et « 2 ».

→ En savoir plus sur x-text

Afficher et masquer des éléments

Afficher ou masquer des éléments est un besoin courant dans les pages et applications web. Menus déroulants, fenêtres modales, boîtes de dialogue, « voir plus », etc. en sont de bons exemples.

Alpine propose les directives x-show et x-if pour cela.

x-show

Voici un composant d'affichage/masquage simple utilisant x-show.

<div x-data="{ open: false }">
    <button @click="open = ! open">Déplier</button>

    <div x-show="open">
        Contenu...
    </div>
</div>

Le <div> contenant le contenu est maintenant affiché ou masqué selon la valeur de open.

En coulisses, Alpine ajoute la propriété CSS display: none; à l'élément lorsqu'il doit être masqué.

→ En savoir plus sur x-show

Cela convient dans la plupart des cas, mais parfois vous voudrez ajouter et retirer complètement l'élément du DOM. C'est le rôle de x-if.

x-if

Voici le même exemple que précédemment, mais avec x-if à la place de x-show.

<div x-data="{ open: false }">
    <button @click="open = ! open">Déplier</button>

    <template x-if="open">
        <div>
            Contenu...
        </div>
    </template>
</div>

Notez que x-if doit être déclaré sur une balise <template>. Ainsi, Alpine peut s'appuyer sur le comportement existant de l'élément <template> du navigateur et l'utiliser comme source du <div> à ajouter à la page ou à retirer.

Lorsque open est vrai, Alpine ajoute le <div> à la suite de la balise <template>, et le retire lorsque open est faux.

→ En savoir plus sur x-if

Afficher et masquer avec des transitions

Alpine permet de passer en douceur de l'état « affiché » à l'état « masqué » avec la directive x-transition.

Remarque : x-transition ne fonctionne qu'avec x-show, pas avec x-if.

Voici à nouveau l'exemple simple, mais cette fois avec des transitions :

<div x-data="{ open: false }">
    <button @click="open = ! open">Déplier</button>

    <div x-show="open" x-transition>
        Contenu...
    </div>
</div>

Concentrons-nous sur la partie du template qui gère les transitions :

<div x-show="open" x-transition>

x-transition seule applique des transitions par défaut raisonnables (fondu et zoom) à l'affichage/masquage.

Il y a deux façons de personnaliser ces transitions :

• Les assistants de transition
• Les classes CSS de transition

Voyons chacune de ces approches :

Assistants de transition

Supposons que vous vouliez allonger la durée de la transition : vous pouvez la préciser manuellement avec le modificateur .duration, comme ceci :

<div x-show="open" x-transition.duration.500ms>

La transition durera maintenant 500 millisecondes.

Si vous voulez des valeurs différentes pour l'entrée et la sortie, vous pouvez utiliser x-transition:enter et x-transition:leave :

<div
    x-show="open"
    x-transition:enter.duration.500ms
    x-transition:leave.duration.1000ms
>

Vous pouvez en outre ajouter .opacity ou .scale pour ne faire transitionner que cette propriété. Par exemple :

<div x-show="open" x-transition.opacity>

→ En savoir plus sur les assistants de transition

Classes de transition

Si vous avez besoin d'un contrôle plus fin sur les transitions de votre application, vous pouvez appliquer des classes CSS précises à chaque phase de la transition avec la syntaxe suivante (cet exemple utilise Tailwind CSS) :

<div
    x-show="open"
    x-transition:enter="transition ease-out duration-300"
    x-transition:enter-start="opacity-0 transform scale-90"
    x-transition:enter-end="opacity-100 transform scale-100"
    x-transition:leave="transition ease-in duration-300"
    x-transition:leave-start="opacity-100 transform scale-100"
    x-transition:leave-end="opacity-0 transform scale-90"
>...</div>

→ En savoir plus sur les classes de transition

Lier des attributs

Vous pouvez ajouter des attributs HTML comme class, style, disabled, etc. aux éléments avec la directive x-bind.

Voici un exemple d'attribut class lié dynamiquement :

<button
    x-data="{ red: false }"
    x-bind:class="red ? 'bg-red' : ''"
    @click="red = ! red"
>
    Basculer le rouge
</button>

Par raccourci, vous pouvez omettre x-bind et utiliser directement la syntaxe abrégée : :

<button ... :class="red ? 'bg-red' : ''">

Activer ou désactiver des classes selon les données d'Alpine est un besoin courant. Voici un exemple utilisant la syntaxe objet de liaison de class d'Alpine (note : cette syntaxe n'est disponible que pour les attributs class) :

<div x-data="{ open: true }">
    <span :class="{ 'hidden': ! open }">...</span>
</div>

La classe hidden sera maintenant ajoutée à l'élément si open est faux, et retirée si open est vrai.

Parcourir des éléments en boucle

Alpine permet de répéter des parties de votre template à partir de données JavaScript avec la directive x-for. Voici un exemple simple :

<div x-data="{ statuses: ['open', 'closed', 'archived'] }">
    <template x-for="status in statuses">
        <div x-text="status"></div>
    </template>
</div>

Comme x-if, x-for doit être appliqué à une balise <template>. En interne, Alpine ajoute le contenu de la balise <template> à chaque itération de la boucle.

Comme vous le voyez, la nouvelle variable status est disponible dans la portée des templates itérés.

→ En savoir plus sur x-for

HTML interne

Alpine facilite le contrôle du contenu HTML d'un élément avec la directive x-html.

<div x-data="{ title: '<h1>Démarrage</h1>' }">
    <div x-html="title"></div>
</div>

Alpine définit maintenant le contenu du <div> avec l'élément <h1>Démarrage</h1>. Quand title change, le contenu change aussi.

Remarque : ⚠️ N'utilisez cette directive que sur du contenu de confiance, jamais sur du contenu fourni par un utilisateur. ⚠️ Afficher dynamiquement du HTML provenant de tiers peut facilement mener à des failles XSS.

→ En savoir plus sur x-html

Traduction française de la documentation officielle d'Alpine.js (licence MIT) – https://alpinejs.dev