Eine Einführung in Stimulus.js

Das Web bewegt sich ziemlich schnell und es ist schwierig, einen Ansatz für Ihr Frontend auszuwählen, der sich in einem Jahr als sinnvoll anfühlt. Meine größte Angst als Entwickler ist es, ein Projekt aufzugreifen, das seit einiger Zeit nicht mehr bearbeitet wurde, und die Dokumentation für den verwendeten Ansatz entweder nicht vorhanden oder nicht leicht online zu finden.

Vor ungefähr einem Jahr habe ich angefangen, Stimulus zu verwenden, und ich war wirklich glücklich über den Code, den ich verschickte. Es ist eine ~ 30-kb-Bibliothek , die kleine wiederverwendbare JavaScript-Sprünge in Ihrer App fördert, die so organisiert sind, dass sie kleine Hinweise in Ihrem zugänglichen HTML hinterlassen, wo das JavaScript zu finden ist, mit dem sie verbunden ist. Es macht das Verständnis, wie ein Stück JavaScript mit Ihrer Seite interagiert, fast so, als würde man Pseudocode lesen.

Stimulus wurde vom Team von Basecamp entwickelt – sie haben kürzlich den HEY -E-Mail-Dienst veröffentlicht – um bei der Wartung des JavaScripts zu helfen, das sie für ihre Webanwendungen schreiben. In der Vergangenheit war Basecamp ziemlich gut darin, seine Open-Source-Projekte zu pflegen, daher bin ich ziemlich zuversichtlich, dass Stimulus gründlich getestet wurde und für die nächsten Jahre gepflegt wird.

Stimulus hat es mir ermöglicht, Anwendungen so zu erstellen, dass sie sich wiederverwendbar und zugänglich anfühlen. Obwohl ich nicht glaube, dass Stimulus das Web übernehmen wird, wie es React und Vue getan haben, denke ich, dass es sich lohnt, es zu lernen.

Terminologie

Wie alle Frameworks hat Stimulus bevorzugte Begriffe zur Beschreibung bestimmter Dinge. Glücklicherweise (und einer der Hauptgründe, warum ich Stimulus mag), gibt es nur zwei, die Sie kennen müssen:

• Regler
  Dies bezieht sich auf Instanzen von JavaScript-Klassen, die die Bausteine ​​Ihrer Anwendung sind. Man kann mit Sicherheit sagen, dass wir, wenn wir über Stimulus-Controller sprechen, über JavaScript-Klassen sprechen.
• Kennung
  Dies ist der Name, den wir verwenden, um auf unseren Controller in unserem HTML-Code zu verweisen, indem wir ein Datenattribut verwenden, das Stimulus-Codebasen gemeinsam ist.
  

Lassen Sie uns in Stimulus springen!

In den folgenden Beispielen werde ich Code verwenden, den Sie in den Browser einfügen können, um sofort über die über unpkg.com verteilte Bibliothek loszulegen. Später werde ich den Webpack-Ansatz behandeln, der sehr empfohlen wird, da er eine verbesserte Organisation Ihres Codes ermöglicht und der im Stimulus-Handbuch verwendete Ansatz ist.

Die Boilerplatte

Sobald Sie den Kern des obigen Ausschnitts verstanden haben, verfügen Sie über das nötige Wissen, um ein Projekt aufzunehmen, das Stimulus verwendet.

Ziemlich toll, oder? Lassen Sie uns in das springen, was alles tut!

application.start

Diese Zeile weist Stimulus an, die Listener zur Seite hinzuzufügen. Wenn Sie es nur einmal oben auf Ihrer Seite aufrufen, bevor Sie Stimulus-Code hinzufügen, gibt es eine Instanz des Haupt-Stimulus-Controllers zurück, der das Methodenregister enthält register das verwendet wird, um Stimulus über die Klassen zu informieren, die Sie verbinden möchten dazu.

Controller

Das data-controller Attribut verbindet unser HTML-Element mit einer Instanz unserer JavaScript-Klasse. In diesem Fall haben wir den Bezeichner „counter“ verwendet, um eine Instanz der JavaScript-Klasse CounterController mit unserem div -Element zu verknüpfen. Wir haben Stimulus über die Verbindung zwischen dieser Kennung und dem Controller über die Methode „ application.register “ informiert.

Stimulus überwacht Ihre Seite kontinuierlich darauf, ob Elemente mit diesem Attribut hinzugefügt oder entfernt werden. Wenn der Seite ein neues HTML-Element mit einem data-controller Attribut hinzugefügt wird, initialisiert es eine neue Instanz der relevanten Controller-Klasse und verbindet dann das HTML-Element. Wenn Sie dieses Element von der Seite entfernen, ruft es die Methode disconnect für die Controller-Klasse auf.

Aktionen

Stimulus verwendet ein Datenattribut data-action , um klar zu definieren, welche Funktion des Controllers ausgeführt wird. Mit der Syntax event->controller#function kann jeder, der das HTML liest, sehen, was es tut. Dies ist besonders nützlich, da es das Risiko von unerwartetem Code aus anderen Dateien verringert und die Navigation in der Codebasis erleichtert. Als ich zum ersten Mal den Ansatz sah, den Stimulus fördert, fühlte es sich fast so an, als würde man Pseudocode lesen.

Wenn im obigen Beispiel die Schaltfläche das „Klick“-Ereignis auslöst, wird es an die addOne Funktion innerhalb unseres „Zähler“-Controllers weitergeleitet.

Ziele

Ziele sind eine Möglichkeit, explizit zu definieren, welche Elemente für Ihren Controller verfügbar sein werden. In der Vergangenheit habe ich eine Mischung aus ID, CSS-Klassennamen und Datenattributen verwendet, um dies zu erreichen. Wenn Sie also ein einziges „So wird es gemacht“ haben, das so eindeutig ist, wird der Code viel konsistenter.

Dazu müssen Sie Ihre Zielnamen innerhalb Ihrer Controller-Klasse über die data-target definieren und den Namen über das targets zu einem Element hinzufügen.

Sobald Sie diese beiden Teile eingerichtet haben, ist Ihr Element in Ihrem Controller verfügbar. In diesem Fall habe ich das Ziel mit dem Namen „output“ eingerichtet und es kann von this.outputTarget innerhalb der Funktionen in unserem Controller aufgerufen werden.

Doppelte Ziele

Wenn Sie mehrere Ziele mit demselben Namen haben, können Sie darauf zugreifen, indem Sie die Pluralversion der Zielmethode verwenden. Wenn ich in diesem Fall this.outputTargets , wird ein Array zurückgegeben, das meine beiden divs mit dem Attribut data-target="hello.output" enthält data-target="hello.output" .

Ereignistypen

Sie hören auf alle Ereignisse, die Sie normalerweise über die JavaScript-Methode addEventListener anhängen könnten. So könnten Sie beispielsweise darauf achten, wenn ein Button geklickt, ein Formular abgeschickt oder eine Eingabe geändert wird.

Um window oder document abzuhören (z. B. die Größenänderung oder das Offlinegehen des Benutzers), müssen Sie „@window“ oder „@document“ an den event anhängen (z. B. resize@window->console#logEvent wird aufgerufen die Funktion logEvent ) auf dem console , wenn die Größe des Fensters geändert wird.

Es gibt eine Kurzform zum Anhängen allgemeiner Ereignisse, bei der Sie den Ereignistyp weglassen können und es eine Standardaktion für den Elementtyp gibt. Ich rate jedoch dringend davon ab, die Ereigniskürzel zu verwenden, da sie die Menge an Annahmen erhöht, die jemand, der mit Stimulus weniger vertraut ist, über Ihren Code machen muss.

Verwendet mehrere Controller im selben Element

Ziemlich oft möchten Sie vielleicht zwei Teile der Logik in getrennte Klassen aufteilen, sie aber innerhalb des HTML-Codes nahe beieinander erscheinen lassen. Stimulus ermöglicht es Ihnen, Elemente mit mehreren Klassen zu verbinden, indem Sie Verweise auf beide in Ihrem HTML platzieren.

Im obigen Beispiel habe ich ein basket eingerichtet, das sich nur mit dem Zählen der Gesamtzahl der Artikel im Korb befasst, aber auch ein child Objekt hinzugefügt, das die Anzahl der Taschen pro Artikel anzeigt.

Übergeben von Daten an Ihr Objekt

Stimulus stellt die Methoden this.data.get und this.data.set innerhalb der Controller-Klasse bereit, damit können Sie Datenattribute ändern, die sich im selben Namensraum wie der Bezeichner befinden. Damit meine ich, wenn Sie Daten aus Ihrem HTML an Ihren Stimulus-Controller weitergeben möchten, fügen Sie einfach ein Attribut wie data-[identifier]-a-variable zu Ihrem HTML-Element hinzu.

Beim Aufrufen this.data.set wird der Wert in Ihrem HTML aktualisiert, sodass Sie die Wertänderung sehen können, wenn Sie das Element mit Ihren Browser-Entwicklungstools untersuchen.

Die Verwendung von Namespace-Datenattributen ist eine wirklich gute Möglichkeit, um wirklich klar zu machen, welches Datenattribut für welchen Codeabschnitt bestimmt ist.

Initialisieren, Verbunden, Getrennt

Wenn Ihre Anwendung wächst, müssen Sie sich wahrscheinlich in „Lebenszyklusereignisse“ einklinken, um Standardwerte festzulegen, Daten abzurufen oder die Echtzeitkommunikation zu handhaben. Stimulus hat drei eingebaute Methoden, die während des gesamten Lebenszyklus einer Stimulus-Klasse aufgerufen werden.

Wenn Stimulus ein Element mit einem passenden data-controller Attribut sieht, erstellt es eine neue Version Ihres Controllers und ruft die initialize auf. Dies wird oft ausgeführt, wenn Sie die Seite zum ersten Mal laden, wird aber auch ausgeführt, wenn Sie Ihrer Seite neuen HTML-Code hinzufügen (z. B. über AJAX), der einen Verweis auf Ihren Controller enthält. Es wird nicht ausgeführt, wenn Sie ein Element an eine neue Position in Ihrem DOM verschieben.

Nachdem eine Klasse initialisiert wurde, verbindet Stimulus sie mit dem HTML-Element und ruft die connect -Funktion auf. Es wird auch connect aufgerufen, wenn Sie ein Element innerhalb Ihres DOM verschieben würden. Wenn Sie also ein Element nehmen, es von einem Element entfernen und es dann an einer anderen Stelle anhängen würden, würden Sie feststellen, dass nur connect aufgerufen wird.

Die Funktion zum disconnect wird ausgeführt, wenn Sie ein Element von Ihrer Seite entfernen. Wenn Sie also beispielsweise den Hauptteil Ihres HTML-Codes ersetzen, könnten Sie jeglichen Code herunterreißen, der möglicherweise erneut ausgeführt werden muss, wenn das Element nicht in der ist gleiche Position. Wenn Sie beispielsweise einen ausgefallenen WYSIWYG-Editor hatten, der einem Element viel zusätzliches HTML hinzufügt, könnten Sie es in seinen ursprünglichen Zustand zurückversetzen, wenn disconnect aufgerufen wird.

Vererbung von Funktionalität

Gelegentlich möchten Sie vielleicht eine kleine gemeinsame Funktionalität zwischen Ihren Stimulus-Controllern teilen. Das Coole an Stimulus ist, dass Sie (unter der Haube) etwas Vanilla-JavaScript-Klassen mit HTML-Elementen verbinden, daher sollte sich die Freigabefunktion vertraut anfühlen.

In diesem Beispiel richte ich eine übergeordnete Klasse namens ParentController ein, die dann um eine untergeordnete Klasse namens ChildController erweitert wird. Dadurch konnte ich Methoden vom ParentController erben, sodass ich den Code in meinem ChildController nicht duplizieren musste.

Verwendung in der Produktion

Ich habe oben einige ziemlich eigenständige Beispiele für die Verwendung von Stimulus demonstriert, die Ihnen einen Vorgeschmack darauf geben sollten, was Sie erreichen können. Ich dachte auch, ich sollte darauf eingehen, wie ich es in der Produktion verwende und wie es für mich funktioniert hat.

Webpaket

Wenn Sie Webpack verwenden, werden Sie sich freuen! Stimulus wurde vollständig für die Verwendung mit Webpack entwickelt. Ihre Dokumentation hat sogar ein schönes Starter-Kit für Webpack. Es ermöglicht Ihnen, Ihre Controller in separate Dateien aufzuteilen, und Stimulus entscheidet über den richtigen Namen, der als Kennung verwendet werden soll.

Sie müssen Webpack nicht verwenden, wenn Sie Stimulus verwenden möchten, aber es bereinigt die Erfahrung erheblich. Persönlich war Stimulus die Bibliothek, die mir geholfen hat, Webpack kennenzulernen und den Wert, den es bietet, wirklich zu spüren.

Konventionen für Dateinamen

Ich habe in der Einleitung dieses Artikels erwähnt, dass ich Stimulus gerne verwende, weil es sich organisiert anfühlt. Dies wird wirklich deutlich, wenn Sie es mit Webpack kombinieren, das das automatische Laden und Registrieren von Controllern ermöglicht.

Sobald Sie Stimulus in Webpack eingerichtet haben, werden Sie aufgefordert, Ihre Dateien wie [identifier]_controller.js zu benennen, wobei die Kennung das ist, was Sie an Ihr HTMLs data-controller Attribut übergeben.

Wenn Ihr Projekt wächst, möchten Sie vielleicht auch Ihre Stimulus-Controller in Unterordner verschieben. Auf magische Weise wandelt Stimulus Unterstriche in Bindestriche und Ordner-Schrägstriche in zwei Bindestriche um, die dann zu Ihrer Kennung werden. So hat beispielsweise der Dateiname chat/conversation_item_controller.js die Kennung chat--conversation-item .

Weniger JavaScript pflegen

Eines meiner Lieblingszitate ist „The Best Code is No Code At All“, ich versuche, diesen Ansatz auf alle meine Projekte anzuwenden.

Webbrowser entwickeln sich stark weiter, ich bin ziemlich überzeugt, dass die meisten Dinge, für die ich heute JavaScript schreiben muss, innerhalb der nächsten 5 Jahre standardisiert und in den Browser integriert werden. Ein gutes Beispiel dafür ist das Detailelement. Als ich mit der Entwicklung anfing, war es sehr üblich, diese Funktionalität manuell mit jQuery zu codieren.

Wenn ich daher barrierefreies HTML mit einer Prise JavaScript schreiben kann, um meine Anforderungen zu erfüllen, mit der Denkweise „Das reicht heute, aber in 5 Jahren möchte ich das einfach ersetzen“, bin ich glücklich Entwickler. Dies ist viel besser erreichbar, wenn Sie zunächst weniger Code geschrieben haben, wofür sich Stimulus eignet.

Erst HTML, dann JavaScript

Ein Aspekt, den ich an dem von Stimulus geförderten Ansatz wirklich mag, ist, dass ich mich darauf konzentrieren kann, HTML über die Leitung an meine Benutzer zu senden, das dann mit JavaScript ein wenig aufgepeppt wird.

Ich war schon immer ein Fan davon, die ersten paar Millisekunden der Aufmerksamkeit eines Benutzers zu nutzen, um das zu bekommen, was ich mit ihm zu teilen habe – vor ihm. Dann kümmern Sie sich um die Einrichtung der Interaktionsebene, während der Benutzer mit der Verarbeitung dessen beginnen kann, was er sieht.

Sollte das JavaScript aus irgendeinem Grund fehlschlagen, kann der Benutzer den Inhalt weiterhin sehen und ohne JavaScript damit interagieren. Beispielsweise wird ein Formular nicht über AJAX gesendet, sondern über eine herkömmliche Formularanforderung, die die Seite neu lädt.

Fazit

Ich liebe es, Websites zu erstellen, die nur kleine Spritzer von wartbarem JavaScript benötigen, um die Benutzererfahrung zu verbessern. Manchmal ist es schön, einfach etwas zu erstellen, das sich einfacher anfühlt. Etwas Leichtes zu haben ist großartig, ich liebe es wirklich, dass es ohne zu viel kognitive Belastung ziemlich klar ist, wie Sie Ihre Dateien organisieren und kleine Breadcrumbs einrichten, die darauf hinweisen, wie das JavaScript mit einem Stück HTML ausgeführt wird.

Ich habe es wirklich genossen, mit Stimulus zu arbeiten. Es ist nicht zu viel, also ist die Lernkurve ziemlich sanft. Ich bin ziemlich zuversichtlich, dass wenn ich meinen Code an jemand anderen weitergeben würde, sie glückliche Entwickler sein würden. Ich würde es sehr empfehlen, es auszuprobieren, auch wenn es nur aus reiner Neugier ist.

Der Elefant im Raum ist, wie es im Vergleich zu React und Vue abschneidet, aber meiner Meinung nach sind sie unterschiedliche Tools für unterschiedliche Anforderungen. In meinem Fall rendere ich oft HTML von meinem Server und füge ein wenig JavaScript hinzu, um das Erlebnis zu verbessern. Wenn ich etwas Komplexeres tun würde, würde ich einen anderen Ansatz in Betracht ziehen (oder die Anforderungen zurückdrängen, damit sich mein Code einfach anfühlt).

Weiterführende Lektüre

• Stimulus-Homepage
  Sie haben ein fantastisches Handbuch, das auf die Konzepte, die ich oben skizziert habe, noch viel mehr eingeht.
• Stimulus-GitHub-Repository
  Ich habe so viel darüber gelernt, wie Stimulus funktioniert, indem ich ihren Code untersucht habe.
• Stimulus-Cheatsheet
  Das Handbuch auf einer Seite zusammengefasst.
• Impulsforum
  Andere Leute zu sehen, die mit Stimulus arbeiten, hat mir wirklich das Gefühl gegeben, dass es in freier Wildbahn verwendet wird.