Une introduction à Stimulus.js

Le Web évolue assez rapidement et il est délicat de choisir une approche pour votre interface qui se sentira sensée dans un an. Ma plus grande crainte en tant que développeur est de reprendre un projet qui n'a pas été touché depuis un certain temps et de trouver la documentation pour l'approche qu'ils ont utilisée soit inexistante ou difficile à trouver en ligne.

Il y a environ un an, j'ai commencé à utiliser Stimulus et je me suis senti vraiment heureux du code que j'envoyais. Il s'agit d'une bibliothèque d'environ 30 Ko qui encourage les petites gouttes réutilisables de JavaScript dans votre application, organisées de manière à laisser de petites indications dans votre code HTML accessible pour savoir où trouver le JavaScript auquel il est connecté. Cela permet de comprendre comment un morceau de JavaScript interagira avec votre page presque comme lire du pseudocode.

Stimulus a été créé par l'équipe de Basecamp - ils ont récemment lancé le service de messagerie HEY - pour aider à maintenir le JavaScript qu'ils écrivent pour leurs applications Web. Historiquement, Basecamp a été assez bon pour maintenir ses projets open source, donc je suis tout à fait convaincu que Stimulus a été testé de manière approfondie et sera maintenu pendant les prochaines années.

Stimulus m'a permis de créer des applications d'une manière qui semble réutilisable et accessible. Bien que je ne pense pas que Stimulus prendra le contrôle du Web comme React et Vue, je pense que c'est un outil intéressant à apprendre.

Terminologie

Comme tous les frameworks, Stimulus a des termes préférés pour décrire certaines choses. Heureusement (et l'une des principales raisons pour lesquelles j'aime Stimulus), il n'y en a que deux que vous devez connaître :

• Manette
  Il s'agit d'instances de classes JavaScript qui sont les blocs de construction de votre application. Il est prudent de dire que lorsque nous parlons de contrôleurs de stimulation, nous parlons de classes JavaScript.
• Identifiant
  C'est le nom que nous utiliserons pour référencer notre contrôleur dans notre code HTML à l'aide d'un attribut de données commun aux bases de code Stimulus.
  

Sautons dans Stimulus !

Dans les quelques exemples suivants, je vais utiliser du code que vous pouvez déposer dans le navigateur pour démarrer immédiatement via la bibliothèque distribuée via unpkg.com. Plus tard, je couvrirai l'approche webpack qui est fortement encouragée car elle permet une meilleure organisation de votre code et est l'approche utilisée dans le manuel Stimulus.

Le passe-partout

Une fois que vous aurez compris l'essentiel de l'extrait ci-dessus, vous aurez les connaissances nécessaires pour vous sentir à l'aise de choisir un projet qui utilise Stimulus.

Assez génial, non? Passons à ce que tout fait !

application.start

Cette ligne indique à Stimulus d'ajouter les auditeurs à la page. Si vous l'appelez une seule fois en haut de votre page avant d'ajouter un code Stimulus, il renverra une instance du contrôleur Stimulus principal qui inclut le register de méthode utilisé pour indiquer à Stimulus les classes que vous souhaitez connecter. à elle.

Contrôleurs

L'attribut data-controller connecte notre élément HTML à une instance de notre classe JavaScript. Dans ce cas, nous avons utilisé l'identifiant "counter" pour connecter une instance de la classe JavaScript CounterController à notre élément div . Nous avons informé Stimulus de la connexion entre cet identifiant et le contrôleur via la méthode application.register .

Stimulus surveillera en permanence votre page pour savoir quand des éléments avec cet attribut sont ajoutés et supprimés. Lorsqu'un nouveau morceau de HTML est ajouté à la page avec un attribut data-controller , il initialise une nouvelle instance de la classe de contrôleur appropriée, puis connecte l'élément HTML. Si vous supprimez cet élément de la page, il appellera la méthode disconnect sur la classe contrôleur.

Actions

Stimulus utilise un attribut data-action pour définir clairement quelle fonction du contrôleur sera exécutée. En utilisant la syntaxe event->controller#function toute personne lisant le code HTML pourra voir ce qu'il fait. Ceci est particulièrement utile car cela réduit le risque de code inattendu provenant d'autres fichiers, ce qui facilite la navigation dans la base de code. Quand j'ai vu pour la première fois l'approche encouragée par Stimulus, j'avais presque l'impression de lire du pseudocode.

Dans l'exemple ci-dessus, lorsque le bouton déclenche l'événement "click", il sera transmis à la fonction addOne dans notre contrôleur "counter".

Cibles

Les cibles sont un moyen de définir explicitement quels éléments seront disponibles pour votre contrôleur. Historiquement, j'ai utilisé un mélange d'ID, de noms de classes CSS et d'attributs de données pour y parvenir, donc avoir un seul "C'est la façon de le faire" qui est si explicite rend le code beaucoup plus cohérent.

Cela nécessite de définir vos noms de targets dans votre classe de contrôleur via la fonction target et d'ajouter le nom à un élément via le data-target .

Une fois que vous avez configuré ces deux pièces, votre élément sera disponible dans votre contrôleur. Dans ce cas, j'ai configuré la cible avec le nom "output" et elle est accessible par this.outputTarget dans les fonctions de notre contrôleur.

Cibles en double

Si vous avez plusieurs cibles portant le même nom, vous pouvez y accéder en utilisant la version plurielle de la méthode cible, dans ce cas, lorsque j'appelle this.outputTargets , il renverra un tableau contenant mes deux divs avec l'attribut data-target="hello.output" .

Types d'événements

Vous écoutez tous les événements que vous seriez généralement en mesure d'attacher via la méthode JavaScript addEventListener. Ainsi, par exemple, vous pouvez écouter quand un bouton est cliqué, un formulaire est soumis ou une entrée est modifiée.

Pour écouter les événements de la window ou document (tels que le redimensionnement ou la déconnexion de l'utilisateur), vous devez ajouter « @window » ou « @document » au type d' event (par exemple, resize@window->console#logEvent appellera la fonction logEvent ) sur le contrôleur de la console lorsque la fenêtre est redimensionnée.

Il existe un raccourci pour attacher des événements communs, où vous pouvez omettre le type d'événement et il a une action par défaut pour le type d'élément. Cependant, je déconseille fortement d'utiliser le raccourci d'événement, car cela augmente le nombre d'hypothèses qu'une personne moins familière avec Stimulus doit faire à propos de votre code.

Utilise plusieurs contrôleurs dans le même élément

Très souvent, vous souhaiterez peut-être diviser deux éléments de logique en classes distinctes, mais les faire apparaître proches l'un de l'autre dans le code HTML. Stimulus vous permet de connecter des éléments à plusieurs classes en plaçant des références aux deux dans votre code HTML.

Dans l'exemple ci-dessus, j'ai configuré un objet basket qui se préoccupe uniquement de compter le nombre total d'articles dans le panier, mais j'ai également ajouté un objet child qui affiche le nombre de sacs par article.

Transmission de données à votre objet

Stimulus fournit les méthodes this.data.get et this.data.set dans la classe du contrôleur, cela vous permettra de modifier les attributs de données qui se trouvent dans le même espace de noms que l'identifiant. Je veux dire par là que si vous souhaitez transmettre des données à votre contrôleur de stimulus à partir de votre HTML, ajoutez simplement un attribut comme data-[identifier]-a-variable à votre élément HTML.

Lors de l'appel this.data.set , il mettra à jour la valeur dans votre code HTML afin que vous puissiez voir la valeur changer lorsque vous inspectez l'élément à l'aide des outils de développement de votre navigateur.

L'utilisation d'attributs de données à espace de noms est un très bon moyen de rendre très clair quel attribut de données correspond à quel morceau de code.

Initialiser, Connecté, Déconnecté

Au fur et à mesure que votre application se développe, vous devrez probablement vous connecter à des "événements de cycle de vie" pour définir des valeurs par défaut, récupérer des données ou gérer une communication en temps réel. Stimulus a trois méthodes intégrées qui sont appelées tout au long du cycle de vie d'une classe Stimulus.

Lorsque Stimulus voit un élément avec un attribut data-controller correspondant, il crée une nouvelle version de votre contrôleur et appelle la fonction d' initialize . Cela s'exécutera souvent lorsque vous chargez la page pour la première fois, mais sera également exécuté si vous deviez ajouter un nouveau code HTML à votre page (par exemple via AJAX) contenant une référence à votre contrôleur. Il ne fonctionnera pas lorsque vous déplacerez un élément vers une nouvelle position dans votre DOM.

Une fois qu'une classe a été initialisée, Stimulus la connectera à l'élément HTML et appellera la fonction de connect . Il appellera également connect si vous deviez déplacer un élément dans votre DOM. Donc, si vous deviez prendre un élément, le supprimer d'un élément, puis l'ajouter ailleurs, vous remarquerez que seul connect sera appelé.

La fonction de disconnect sera exécutée lorsque vous supprimerez un élément de votre page, donc par exemple, si vous deviez remplacer le corps de votre code HTML, vous pourriez supprimer tout code qui pourrait avoir besoin d'être réexécuté si l'élément n'est pas dans le Même position. Par exemple, si vous aviez un éditeur WYSIWYG sophistiqué qui ajoute beaucoup de code HTML supplémentaire à un élément, vous pouvez le rétablir dans son état d'origine lorsque la disconnect a été appelée.

Fonctionnalité héritée

À l'occasion, vous voudrez peut-être partager une petite fonctionnalité commune entre vos contrôleurs Stimulus. Ce qui est cool avec Stimulus, c'est que (sous le capot) vous connectez des classes JavaScript quelque peu vanillées à des éléments HTML, donc la fonctionnalité de partage devrait vous sembler familière.

Dans cet exemple, j'ai configuré une classe parent nommée ParentController , qui est ensuite étendue par une classe enfant nommée ChildController . Cela m'a permis d'hériter des méthodes du ParentController afin de ne pas avoir à dupliquer le code dans mon ChildController .

Utilisation en production

J'ai montré ci-dessus quelques exemples assez autonomes d'utilisation de Stimulus, ce qui devrait vous donner un avant-goût de ce que vous pouvez réaliser. J'ai aussi pensé que je devrais parler de la façon dont je l'utilise en production et de la façon dont cela a fonctionné pour moi.

Webpack

Si vous utilisez Webpack, vous allez vous régaler ! Stimulus a été entièrement conçu pour être utilisé avec Webpack. Leur documentation contient même un joli kit de démarrage pour Webpack. Cela vous permettra de diviser vos contrôleurs en fichiers séparés et Stimulus décidera du nom correct à utiliser comme identifiant.

Vous n'êtes pas obligé d'utiliser Webpack si vous souhaitez utiliser Stimulus, mais cela simplifie énormément l'expérience. Personnellement, Stimulus était la bibliothèque qui m'a aidé à me présenter à Webpack et à vraiment ressentir la valeur qu'il offrait.

Conventions de nom de fichier

J'ai mentionné dans l'introduction de cet article que j'aimais utiliser Stimulus car il se sentait organisé. Cela devient vraiment évident lorsque vous le combinez avec Webpack, qui permet le chargement et l'enregistrement automatiques des contrôleurs.

Une fois que vous avez configuré Stimulus dans Webpack, cela vous encouragera à nommer vos fichiers comme [identifier]_controller.js , où l'identifiant est ce que vous passerez dans votre attribut data-controller HTML.

Au fur et à mesure que votre projet grandit, vous pouvez également déplacer vos contrôleurs Stimulus dans des sous-dossiers. De manière magique, Stimulus convertira les traits de soulignement en tirets et les barres obliques de dossier en deux tirets, qui deviendront alors votre identifiant. Ainsi, par exemple, le nom de fichier chat/conversation_item_controller.js aura l'identifiant chat--conversation-item .

Maintenir moins de JavaScript

L'une de mes citations préférées est "Le meilleur code est pas de code du tout", j'essaie d'appliquer cette approche à tous mes projets.

Les navigateurs Web évoluent beaucoup, je suis assez convaincu que la plupart des choses dont j'ai besoin pour écrire du JavaScript aujourd'hui deviendront standardisées et intégrées au navigateur dans les 5 prochaines années. Un bon exemple de cela est l'élément de détails, lorsque j'ai commencé le développement, il était très courant de devoir coder manuellement cette fonctionnalité à la main à l'aide de jQuery.

En conséquence, si je peux écrire du HTML accessible avec une pincée de JavaScript pour répondre à mes besoins, avec l'état d'esprit de "Cela fait le travail aujourd'hui, mais dans 5 ans, je veux le remplacer facilement", je serai un heureux développeur. Ceci est beaucoup plus réalisable lorsque vous avez écrit moins de code pour commencer, ce à quoi Stimulus se prête.

HTML d'abord, puis JavaScript

Un aspect que j'aime beaucoup dans l'approche encouragée par Stimulus, c'est que je peux me concentrer sur l'envoi de code HTML à mes utilisateurs, qui est ensuite un peu agrémenté de JavaScript.

J'ai toujours aimé utiliser les premières millisecondes de l'attention d'un utilisateur pour obtenir ce que j'ai à partager avec lui, devant lui. Ensuite, s'inquiéter de la configuration de la couche d'interaction pendant que l'utilisateur peut commencer à traiter ce qu'il voit.

De plus, si JavaScript devait échouer pour une raison quelconque, l'utilisateur peut toujours voir le contenu et interagir avec lui sans JavaScript. Par exemple, au lieu d'un formulaire soumis via AJAX, il sera soumis via une demande de formulaire traditionnelle qui recharge la page.

Conclusion

J'adore créer des sites qui n'ont besoin que de petites touches de JavaScript maintenable pour améliorer l'expérience utilisateur, parfois c'est bien de créer quelque chose qui semble plus simple. Avoir quelque chose de léger est génial, j'aime vraiment le fait que sans trop de charge cognitive, il est assez clair comment organiser vos fichiers et configurer de petits fils d'Ariane qui indiquent comment le JavaScript fonctionnera avec un morceau de HTML.

J'ai vraiment aimé travailler avec Stimulus. Il n'y a pas grand-chose à faire, donc la courbe d'apprentissage est assez douce. Je suis assez confiant que si je devais passer mon code à quelqu'un d'autre, ils seraient des développeurs heureux. Je vous conseille vivement de l'essayer, même si c'est juste par pure curiosité.

L'éléphant dans la pièce est de savoir comment cela se compare-t-il à React et Vue, mais dans mon esprit, ce sont des outils différents pour une exigence différente. Dans mon cas, je rends souvent du HTML à partir de mon serveur et j'ajoute un peu de JavaScript pour améliorer l'expérience. Si je faisais quelque chose de plus complexe, j'envisagerais une approche différente (ou repousserais les exigences pour aider à garder mon code simple).

Lectures complémentaires

• Page d'accueil de stimulation
  Ils ont un manuel fantastique qui approfondit beaucoup plus les concepts que j'ai décrits ci-dessus.
• Référentiel GitHub Stimulus
  J'ai tellement appris sur le fonctionnement de Stimulus en explorant leur code.
• Feuille de triche de stimulation
  Le manuel résumé sur une seule page.
• Forum de relance
  Voir d'autres personnes travailler avec Stimulus m'a donné l'impression qu'il est utilisé à l'état sauvage.