Comme le disent ses créateurs, Stimulus est un framework JavaScript aux ambitions modestes, qui ne cherche pas à prendre le pas sur l'ensemble de votre frontend, mais à ajouter au HTML juste ce qu'il faut de comportement pour le faire briller.
Je sais ce que vous pensez... Un autre JavaScript cadre ? Il y en a déjà tellement ! Vous avez raison, mais celui-ci a attiré mon attention car il a été créé par Basecamp. Vous connaissez probablement cette société, qui est à l'origine de la création de Ruby on Rails. Ils ont également créé Turbolinks, et je le mentionne parce que Stimulus s'y associe parfaitement. Cela vaut donc peut-être la peine d'essayer Stimulus ?
Comment cela fonctionne-t-il ?
Stimulus fonctionne en surveillant la page, en attendant que la contrôleur de données pour qu'il apparaisse. L'attribut contrôleur de données connecte et déconnecte les contrôleurs de Stimulus. Le principe est simple : tout comme la classe est un lien entre HTML et CSS, contrôleur de données est une passerelle entre HTML et JavaScript. Stimulus ajoute également la fonction données-action qui décrit comment les événements de la page doivent déclencher les méthodes du contrôleur, et l'attribut données-cible qui permet de trouver des éléments dans le champ d'application du contrôleur.
Installation facile
Si votre application Rails utilise une gem webpacker, vous pouvez installer Stimulus avec une simple commande car la gem webpacker fournit une tâche pour l'installation de Stimulus. Exécutez simplement la commande suivante dans le répertoire racine de votre application Rails :
rails webpacker:install:stimulus
Cela ajoute la stimulation à package.json et crée les deux fichiers suivants : app/javascript/controllers/index.js :
import { Application } from "stimulus"
import { definitionsFromContext } from "stimulus/webpack-helpers"
const application = Application.start()
const context = require.context("controllers", true, /_controller.js$/)
application.load(definitionsFromContext(context))
Vous pouvez voir que l'aide require.context de webpack est appelée. Il a ensuite transmis le contexte résultant à la méthode Application#load. Cela signifie que notre application recherche des fichiers nommés[identifiant]_controller.js dans le app/javascript/contrôleurs/ où l'identifiant correspond à l'identifiant du contrôleur de données dans votre HTML. C'est exactement l'endroit où nous devons placer les contrôleurs Stimulus.
L'application/javascript/controllers/hello_controller.js est également générée. Il s'agit d'un exemple de contrôleur avec lequel nous pouvons jouer.
Utilisation de base
Ok, nous avons donc le hello_controller.js créé avec le fichier suivant code:
import { Controller } from "stimulus"
export default class extends Controller {
static targets = ["output"]
connect() {
this.outputTarget.textContent = 'Hello, Stimulus!'
}
}
Mais, comme vous le savez, nous ne verrons aucun effet si nous ne faisons pas le lien entre HTML et JavaScript. Ajoutons un peu de code à votre vue HTML. Vous pouvez le mettre où vous voulez :
<div data-controller="hello">
<p data-target="hello.output"> </p>
</div>
Et vous savez quoi ? C'est tout ! Si vous rechargez votre page et que vous voyez "Hello, Stimulus !" sur votre page, cela signifie que la connexion fonctionne correctement. C'est simple, non ?
D'accord, mais ce n'est qu'un simple affichage de texte. Pouvons-nous avoir de l'action ? Oui, c'est possible ! Comme je l'ai déjà mentionné, il y a aussi la fonction données-action attribut. Modifions ensuite notre vue HTML :
<div data-controller="hello">
<p><input type="number" data-target="hello.days"><br><button data-action="click->hello#calculate">Calculer</button></p>
</div>
Et le contrôleur de stimulus app/javascript/controllers/hello_controller.js:
import { Controller } from "stimulus"
export default class extends Controller {
static targets = ["output", "days"]
connect() {
this.outputTarget.textContent = "Depuis combien de temps êtes-vous en quarantaine ?
}
calculate() {
const element = this.daysTarget
const days = element.value
const lockdownDays = 14
let daysLeft = lockdownDays - days
if (daysLeft < 1) {
alert('Vous êtes libre!')
}
else {
alert(`Combien de jours vous devez rester en quarantaine : ${daysLeft}`)
}
}
}
Nous avons ici une application très simple qui calcule combien de temps nous devons rester en quarantaine. Nous avons réussi à le faire en utilisant l'attribut data-action en HTML.
Vous pouvez voir que nous avons également ajouté "jours" à la liste des cibles dans le code JavaScript. Lorsque nous faisons cela, Stimulus crée automatiquement un fichier this.daysTarget qui renvoie le premier élément cible correspondant.
Que faut-il encore savoir ?
Rappels
Vous avez probablement remarqué qu'il existe un connecter() dans les deux exemples. Celle-ci concerne les rappels intégrés. Vous devriez tous les connaître, ainsi que leur cycle de vie, alors les voici :
initialiserLe contrôleur ne peut être utilisé qu'une seule fois, lors de sa première instanciation,
relierLe contrôleur est connecté au DOM à tout moment,
se déconnecterLe contrôleur est déconnecté du DOM à chaque fois que le contrôleur est déconnecté du DOM.
Descripteur d'action
Les données-action valeur click->hello#calculer est appelé descripteur d'action. Ce descripteur indique que
cliquer est le nom de l'événement,Bonjour est l'identifiant du contrôleur,calculer est le nom de la méthode.
Objectifs
Comme pour les actions, Stimulus a un descripteur de cible. Le descripteur bonjour.jours indique que : Bonjour est l'identifiant du contrôleur,
jours est le nom de la cible.
Dans l'exemple précédent, j'ai mentionné que Stimulus crée le this.daysTarget lorsqu'il y a "jours" dans la liste des cibles. Vous devez également savoir que d'autres propriétés peuvent être créées. Par rapport à l'exemple, vous pouvez avoir :
this.daysTarget qui évalue jusqu'à la première cible dans le champ d'application du contrôleur. S'il n'y a pas de cible, la propriété signale une erreur,
this.daysTargets évalue jusqu'à un tableau de toutes les cibles sources dans le champ d'application du contrôleur,
this.hasDaysTarget retourne true s'il y a une cible ou false s'il n'y en a pas.
Comme vous pouvez le voir, Stimulus est simple et peut facilement être ajouté à votre application. Il gagne en popularité dans la communauté RdR et je n'en suis pas surpris. En tant que développeur Ruby, j'aime beaucoup travailler avec Stimulus. Alors que diriez-vous de l'essayer ?
En savoir plus :
