Introduction au framework Javascript Stimulus

Si vous développez des applications web, vous utilisez (ou connaissez) certainement des frameworks Javascript tels que Vue, React ou encore Angular. Ils prennent en charge l’ensemble de la partie front-end d’une application par le biais de composants à intégrer dans les templates HTML.

Sur certains projets, il n’est pas forcément pertinent de charger un framework Javascript pour seulement quelques fonctionnalités qui pourraient être développées à la main. C’est là que Stimulus entre en scène !

Qu’est-ce que Stimulus ?

Stimulus est un framework Javascript léger et performant (environ 30ko), qui a pour but de mettre en valeur des sites qui pourraient très bien fonctionner sans Javascript. Contrairement aux autres frameworks existants, il n’a pas pour ambition de prendre en charge l’intégralité du rendu de votre HTML. Il permet simplement de créer du code Javascript réutilisable facilement pour ajouter de l’interactivité à votre application web. C’est un peu comme la cerise sur le gâteau, qui va vous permettre de rendre un site plus vivant et provoquer un effet « waouh ! », sans avoir à charger un framework plus lourd ou même tout simplement jQuery.

Nous avons découvert Stimulus il y a quelques mois en initiant un nouveau projet Symfony pour un client, dans lequel il n’y avait pas énormément de travail à réaliser côté front-end en terme de rendu. L’idée de base était de ne pas avoir à charger jQuery pour réaliser les quelques fonctions à mettre en place pour créer des animations, car là encore, cela serait revenu à charger une bibliothèque qui n’aurait été que très peu utilisée et qui aurait joué sur les performances du site.

Ce qui nous séduits avec Stimulus, c’est la simplicité avec laquelle il a été mis en place sur le projet (grâce à sa configuration facile avec Webpack) mais également la rapidité avec laquelle il a été pris en main. Il permet de construire du code réutilisable avec une maintenabilité facilitée.

Comment ça marche ?

Comme nous l’expliquions plus haut, Stimulus a pour objectif d’améliorer le rendu d'un code HTML déjà existant. Il connecte des objets JavaScript (controllers) aux éléments d'une page via des annotations dans le HTML (data-attributs). Lorsque Stimulus détecte un attribut sur un élément HTML, il fait le lien avec la classe correspondante, crée une nouvelle instance de cette classe et la connecte à l’élément concerné.

Une fois l’installation faite sur votre projet, voyons comment Stimulus fonctionne concrètement. Pour commencer, nous allons créer un template HTML (ou Twig), dans lequel nous ajouterons un bouton qui réalisera une action simple au clic.


        <!doctype html>
<html lang="fr">
<head>
    <meta charset="utf-8">
    <title>Titre de la page</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>

<div>
    <button>Cliquez ici !</button>
</div>

</body>
</html>

Ensuite, nous créons un controller (dans notre cas alerting_controller) qui nous permettra de gérer les différentes fonctions associées à ce bouton dans le dossier controllers de notre projet.


        import { Controller } from "stimulus"

export default class extends Controller {
}

Pour que ce controller soit chargé dans notre fichier HTML, plus besoin de créer une balise <script> avec le lien vers notre fichier Javascript avant la fermeture du body ! Il suffit tout simplement d’appeler l’identifiant de ce controller via une annotation data-controller dans notre fichier HTML et le tour est joué. Pratique non ?


        <div data-controller="alerting">
    <button>Cliquez ici !</button>
</div>

Mais comment savoir si le controller est bien chargé sur la page ? Découvrez-le tout de suite grâce aux lifecycle callbacks.

Les lifecycle callbacks

Stimulus gère déjà plusieurs méthodes appelées « lifecycle callbacks », qui sont appelées à chaque fois qu’un controller se connecte, ou se déconnecte ou est initialisé dans d’un élément :

connect : à chaque fois que le controller se connecte au DOM.
disconnect : à chaque fois que le controller se déconnecte du DOM.
initialize : une seule fois, lorsque le controller est initialisé.

Ajoutons un peu de code Javascript dans notre controller afin d'afficher une alerte avec un message lorsqu'il est connecté.


        import { Controller } from "stimulus"

export default class extends Controller {
    connect() {
        alert("Le controller est bien chargé !");
    }
}

Pour en savoir plus sur ces méthodes, n’hésitez pas à consulter la documentation officielle de Stimulus qui est très bien construite. Rechargez votre page et vous verrez apparaître une alerte contenant le message ci-dessus. Il est maintenant temps de voir comment ajouter une action directement sur notre bouton.

Les actions

Les actions gèrent les événements DOM depuis le controller. En d’autres termes elles permettent de connecter une méthode, un élément et un événement DOM. Chaque élément peut prendre en compte plusieurs actions. Nous verrons un peu plus tard comment appeler deux actions sur un même élément.

D’abord, modifiions un peu la méthode créée précédemment dans notre controller, afin de pouvoir l’appeler en la combinant à une action particulière comme l’événement « clic ».


        import { Controller } from "stimulus"

export default class extends Controller {
    userAlert() {
        alert("Vous avez cliqué sur le bouton !");
    }
}

Pour appeler une action particulière sur un élément, il suffit encore une fois de lui attribuer une annotation, cette fois-ci data-action. Cet attribut prend en compte trois options :

le nom de l’événement à écouter (dans notre cas l'événement click)
l’identifiant du controller à charger (en l'occurence alerting)
le nom de la méthode à invoquer (ici userAlert)


        <div data-controller="alerting">
    <button data-action="click->alerting#userAlert">Cliquez ici !</button>
</div>

Rechargez à nouveau votre page, cliquez sur le bouton et l’alerte devrait apparaître à l’écran ! Si vous aviez besoin d’appeler plusieurs actions sur le même élément, il vous suffit de les mettre les unes à la suite des autres dans l’attribut data-action, en les séparant d’un espace.


        <div data-controller="alerting">
    <button data-action="click->alerting#userAlert focus->alerting#changeColor">Cliquez ici !</button>
</div>

Les targets

Parfois, on a besoin de cibler un élément précis, on utilise alors l’attribut target.


        <div data-controller="alerting">
    <p data-alerting-target="text">Mon paragraphe</p>
    <button data-action="click->alerting#userAlert">Cliquez ici !</button>
</div>

Pour appeler cet élément du côté du controller, on y ajoute une variable statique qui correspond à l’élément précédemment déclaré dans le HTML.


        import { Controller } from "stimulus"

export default class extends Controller {
    static targets = [ "text" ]
    // …
}

Si on a besoin de cibler plusieurs éléments, il suffit de les appeler un par un dans le tableau consacré à nos targets. Pour chaque target définie, Stimulus crée les propriétés suivantes, qui peuvent être utilisées dans les différentes méthodes et actions :

this.[name]Target : cible le premier élément portant cet attribut.
this.[name]Targets : un tableau contenant tous les éléments portant cet attribut.
this.has[name]Target : un booléen permettant de savoir s’il y a ou pas des targets dans un document.

Les valeurs

Dans certains cas, on peut également avoir besoin de travailler avec des valeurs, passées depuis le HTML vers le Javascript. Par exemple, on pourrait avoir besoin de récupérer une date passée en tant qu'attribut depuis le HTML, afin d'y opérer des calculs en Javascript et d'en ressortir de nouvelles valeurs à insérer dynamiquement sur le site. Encore une fois, Stimulus gère ce type d'attribut, qui peut ensuite être appelé dans le controller.


        <div data-controller="alerting" data-alerting-date-value="2021-02-25T00:00:00">
    <button data-action="click->alerting#userAlert">Cliquez ici !</button>
</div>

Pour ajouter une valeur à un élément, il faudra simplement déclarer un attribut data composé du nom du controller alerting associé au nom de notre valeur date et finissant par value.

Pour récupérer cette valeur dans le controller, on opèrera de la façon suivante :


        import { Controller } from "stimulus"

export default class extends Controller {
    static values = {date: String}

    connect() {
        alert(this.dateValue);
    }
}

Cette fois-ci, si vous rechargez votre page vous verrez apparaître une alerte contenant la date que vous aviez renseigné dans votre HTML !

Vous avez pu le constater par vous-même, Stimulus offre un certain confort lorsque l'on a besoin de développer une application web et que l'on souhaite y intégrer quelques fonctionnalités / animations, sans avoir à charger obligatoirement des librairies externes pouvant réduire ses performances. Tout est fait pour vous permettre d’avoir un code Javascript bien organisé, clair et réutilisable facilement à différents endroits de l'application.

Nous vous avons donné un aperçu simple et rapide de ce que peut faire Stimulus, à vous maintenant de l’intégrer à vos projets et de découvrir toutes ses capacités !