Un'introduzione a Stimulus.js

Il web si muove abbastanza velocemente e scegliere un approccio per il tuo frontend che sembrerà ragionevole tra un anno è complicato. La mia più grande paura come sviluppatore è raccogliere un progetto che non è stato toccato per un po 'e trovare la documentazione per qualsiasi approccio utilizzato è inesistente o non è facilmente reperibile online.

Circa un anno fa, ho iniziato a utilizzare Stimulus e mi sono sentito davvero felice del codice che stavo spedendo. È una libreria di circa 30kb che incoraggia piccole porzioni riutilizzabili di JavaScript all'interno della tua app, organizzata in modo tale da lasciare piccoli suggerimenti nel tuo HTML accessibile su dove trovare il JavaScript a cui è connesso. Fa capire come un pezzo di JavaScript interagirà con la tua pagina quasi come leggere uno pseudocodice.

Stimulus è stato creato dal team di Basecamp - hanno recentemente rilasciato il servizio di posta elettronica HEY - per aiutare a mantenere il JavaScript che scrivono per le loro applicazioni web. Storicamente, Basecamp è stato abbastanza bravo nel mantenere i propri progetti open source, quindi sono abbastanza fiducioso che Stimulus sia stato testato a fondo e verrà mantenuto per i prossimi anni.

Stimulus mi ha permesso di creare applicazioni in un modo che sia riutilizzabile e accessibile. Anche se non penso che Stimulus prenderà il controllo del web come hanno fatto React e Vue, penso che sia uno strumento utile da imparare.

Terminologia

Come tutti i framework, Stimulus ha termini preferiti per descrivere determinate cose. Fortunatamente (e uno dei motivi principali per cui ho iniziato ad apprezzare Stimulus), ce ne sono solo due che devi sapere:

• Controllore
  Questo si riferisce a istanze di classi JavaScript che sono gli elementi costitutivi della tua applicazione. È sicuro dire che quando parliamo di controller di stimolo, stiamo parlando di classi JavaScript.
• Identificatore
  Questo è il nome che useremo per fare riferimento al nostro controller nel nostro HTML utilizzando un attributo di dati comune alle basi di codice Stimulus.
  

Facciamo un salto nello stimolo!

Nei seguenti esempi, utilizzerò il codice che puoi inserire nel browser per iniziare subito tramite la libreria distribuita tramite unpkg.com. Più avanti tratterò l'approccio webpack che è altamente incoraggiato in quanto consente una migliore organizzazione del codice ed è l'approccio utilizzato nel Manuale di stimolo.

La caldaia

Una volta compreso l'essenza del frammento di cui sopra, avrai le conoscenze per sentirti a tuo agio nel raccogliere un progetto che utilizza Stimulus.

Abbastanza fantastico, vero? Entriamo in quello che sta facendo tutto!

application.start

Questa riga dice a Stimulus di aggiungere gli ascoltatori alla pagina. Se lo chiami solo una volta nella parte superiore della pagina prima di aggiungere qualsiasi codice Stimulus, restituirà un'istanza del controller Stimulus principale che include il register del metodo utilizzato per comunicare a Stimulus le classi che desideri connettere ad esso.

Controllori

L'attributo data-controller collega il nostro elemento HTML a un'istanza della nostra classe JavaScript. In questo caso, abbiamo utilizzato l'identificatore "counter" per collegare un'istanza della classe JavaScript CounterController al nostro elemento div . Abbiamo parlato a Stimulus della connessione tra questo identificatore e il controller tramite il metodo application.register .

Stimulus monitorerà continuamente la tua pagina per quando gli elementi con questo attributo vengono aggiunti e rimossi. Quando un nuovo pezzo di HTML viene aggiunto alla pagina con un attributo data-controller , inizializzerà una nuova istanza della classe controller pertinente, quindi connetterà l'elemento HTML. Se rimuovi quell'elemento dalla pagina, chiamerà il metodo di disconnect sulla classe controller.

Azioni

Stimulus utilizza un attributo data-action per definire chiaramente quale funzione del controller verrà eseguita. Usando la sintassi event->controller#function chiunque legga l'HTML sarà in grado di vedere cosa fa. Ciò è particolarmente utile in quanto riduce il rischio di codice imprevisto da altri file, semplificando la navigazione nella codebase. Quando ho visto per la prima volta l'approccio incoraggiato da Stimulus, mi è sembrato quasi di leggere uno pseudocodice.

Nell'esempio sopra, quando il pulsante attiva l'evento "clic", verrà passato alla funzione addOne all'interno del nostro controller "contatore".

Obiettivi

I target sono un modo per definire in modo esplicito quali elementi saranno disponibili per il controller. Storicamente ho usato un mix di ID, nomi di classi CSS e attributi di dati per raggiungere questo obiettivo, quindi avere un unico "Questo è il modo per farlo" che è così esplicito rende il codice molto più coerente.

Ciò richiede la definizione dei nomi di destinazione all'interno della classe del controller tramite la funzione targets e l'aggiunta del nome a un elemento tramite data-target .

Una volta che hai impostato questi due pezzi, il tuo elemento sarà disponibile nel tuo controller. In questo caso, ho impostato il target con il nome "output" e può essere acceduto da this.outputTarget all'interno delle funzioni nel nostro controller.

Obiettivi duplicati

Se hai più target con lo stesso nome, puoi accedervi usando la versione plurale del metodo target, in questo caso quando chiamo this.outputTargets , restituirà un array contenente entrambi i miei div con l'attributo data-target="hello.output" .

Tipi di eventi

Ascolti tutti gli eventi che potresti comunemente allegare tramite il metodo JavaScript addEventListener. Quindi, ad esempio, potresti ascoltare quando viene fatto clic su un pulsante, viene inviato un modulo o viene modificato un input.

Per ascoltare gli eventi della window o document (come il ridimensionamento o l'uscita dell'utente offline), dovrai aggiungere "@window" o "@document" al tipo di event (ad es. resize@window->console#logEvent chiamerà la funzione logEvent ) sul controller della console quando la finestra viene ridimensionata.

C'è un modo abbreviato per allegare eventi comuni, in cui puoi omettere il tipo di evento e ha un'azione predefinita per il tipo di elemento. Tuttavia, sconsiglio vivamente l'uso della scorciatoia dell'evento, poiché aumenta la quantità di ipotesi che qualcuno che ha meno familiarità con Stimulus deve fare sul tuo codice.

Utilizza più controller nello stesso elemento

Molto spesso potresti voler suddividere due parti di logica in classi separate, ma farle apparire vicine l'una all'altra all'interno dell'HTML. Stimulus ti consente di connettere elementi a più classi inserendo riferimenti a entrambi all'interno del tuo HTML.

Nell'esempio sopra, ho impostato un oggetto basket che si occupa solo di contare il numero totale di articoli nel cestino, ma ho anche aggiunto un oggetto child che mostra la quantità di bagagli per articolo.

Passare i dati al tuo oggetto

Stimulus fornisce i metodi this.data.get e this.data.set all'interno della classe controller, ciò consentirà di modificare gli attributi dei dati che si trovano all'interno dello stesso spazio dei nomi dell'identificatore. Con questo intendo se vuoi passare i dati al tuo controller di stimolo dal tuo HTML, aggiungi semplicemente un attributo come data-[identifier]-a-variable al tuo elemento HTML.

Quando si chiama this.data.set , aggiornerà il valore nell'HTML in modo da poter vedere la modifica del valore quando si ispeziona l'elemento utilizzando gli strumenti di sviluppo del browser.

L'uso di attributi di dati con spazio dei nomi è un modo davvero carino per aiutare a chiarire quale attributo di dati è per quale pezzo di codice.

Inizializza, connesso, disconnesso

Man mano che la tua applicazione cresce, probabilmente dovrai collegarti agli "eventi del ciclo di vita" per impostare i valori predefiniti, recuperare i dati o gestire la comunicazione in tempo reale. Stimulus ha tre metodi integrati che vengono chiamati durante il ciclo di vita di una classe Stimulus.

Quando Stimulus vede un elemento con un attributo data-controller corrispondente, creerà una nuova versione del controller e chiamerà la funzione di initialize . Questo verrà spesso eseguito quando carichi la pagina per la prima volta, ma verrà eseguito anche se dovessi aggiungere un nuovo HTML alla tua pagina (ad esempio tramite AJAX) contenente un riferimento al tuo controller. Non verrà eseguito quando sposti un elemento in una nuova posizione all'interno del tuo DOM.

Dopo che una classe è stata inizializzata, Stimulus la collegherà all'elemento HTML e chiamerà la funzione di connect . Chiamerà anche connect se dovessi spostare un elemento all'interno del tuo DOM. Quindi, se dovessi prendere un elemento, rimuoverlo da un elemento, quindi aggiungerlo da qualche altra parte, noterai che verrà chiamato solo connect .

La funzione di disconnect verrà eseguita quando rimuovi un elemento dalla tua pagina, quindi, ad esempio, se dovessi sostituire il corpo del tuo HTML, potresti eliminare qualsiasi codice che potrebbe dover essere rieseguito se l'elemento non è nel stessa posizione. Ad esempio, se si dispone di un elaborato editor WYSIWYG che aggiunge molto HTML extra a un elemento, è possibile ripristinarlo al suo stato originale quando è stata chiamata la disconnect .

Funzionalità ereditaria

A volte, potresti voler condividere una piccola funzionalità comune tra i tuoi controller Stimulus. La cosa interessante di Stimulus è che (sotto il cofano) stai collegando classi JavaScript in qualche modo vanigliate a elementi HTML, quindi la funzionalità di condivisione dovrebbe sembrare familiare.

In questo esempio, ho impostato una classe padre denominata ParentController , che viene quindi estesa da una classe figlio denominata ChildController . Questo mi ha permesso di ereditare i metodi da ParentController in modo da non dover duplicare il codice all'interno del mio ChildController .

Usandolo in produzione

Ho mostrato alcuni esempi abbastanza autonomi su come usare Stimulus sopra, che dovrebbero darti un assaggio di ciò che puoi ottenere. Ho anche pensato di dover toccare con mano come lo uso nella produzione e come ha funzionato per me.

Pacchetto Web

Se stai usando Webpack, sei pronto per una sorpresa! Stimulus è stato creato per essere utilizzato con Webpack. La loro documentazione ha anche un delizioso kit di base per Webpack. Ti consentirà di suddividere i controller in file separati e Stimulus deciderà il nome corretto da utilizzare come identificatore.

Non è necessario utilizzare webpack se si desidera utilizzare Stimulus, ma ripulisce un po' l'esperienza. Personalmente, Stimulus è stata la libreria che mi ha aiutato a farmi conoscere Webpack ea sentire davvero il valore che offriva.

Convenzioni sui nomi dei file

Ho menzionato nell'introduzione di questo articolo che mi è piaciuto usare Stimulus perché sembrava organizzato. Questo diventa davvero evidente quando lo si combina con Webpack, che consente il caricamento e la registrazione automatici dei controller.

Dopo aver impostato Stimulus in Webpack, ti ​​incoraggerà a nominare i tuoi file come [identifier]_controller.js , dove l'identificatore è ciò che passerai nell'attributo del controller data-controller HTML.

Man mano che il tuo progetto cresce, potresti anche voler spostare i tuoi controller Stimulus in sottocartelle. In modo magico, Stimulus converte i trattini bassi in trattini e le barre in avanti della cartella in due trattini, che diventeranno quindi il tuo identificatore. Quindi, ad esempio, il nome del file chat/conversation_item_controller.js avrà l'identificatore chat--conversation-item .

Mantenere meno JavaScript

Una delle mie citazioni preferite è "The Best Code is No Code At All", cerco di applicare questo approccio a tutti i miei progetti.

I browser Web si stanno evolvendo molto, sono abbastanza convinto che la maggior parte delle cose di cui ho bisogno per scrivere JavaScript oggi diventeranno standardizzate e integrate nel browser entro i prossimi 5 anni. Un buon esempio di ciò è l'elemento dettagli, quando ho iniziato lo sviluppo era super comune dover codificare manualmente quella funzionalità a mano usando jQuery.

Di conseguenza, se riesco a scrivere HTML accessibile con una spolverata di JavaScript per soddisfare le mie esigenze, con la mentalità di "Questo fa il lavoro oggi, ma tra 5 anni voglio sostituirlo facilmente" sarò felice sviluppatore. Questo è molto più realizzabile quando hai scritto meno codice per cominciare, cosa a cui Stimulus si presta.

Prima HTML, poi JavaScript

Un aspetto che mi piace molto dell'approccio incoraggiato da Stimulus è che posso concentrarmi sull'invio di codice HTML ai miei utenti, che viene poi ravvivato un po' con JavaScript.

Sono sempre stato un fan dell'utilizzo dei primi millisecondi dell'attenzione di un utente per ottenere ciò che ho da condividere con loro, davanti a loro. Quindi preoccuparsi di impostare il livello di interazione mentre l'utente può iniziare a elaborare ciò che sta vedendo.

Inoltre, se il JavaScript dovesse fallire per qualsiasi motivo, l'utente può comunque vedere il contenuto e interagire con esso senza JavaScript. Ad esempio, invece di inviare un modulo tramite AJAX, verrà inviato tramite una richiesta di modulo tradizionale che ricarica la pagina.

Conclusione

Adoro creare siti che necessitano solo di piccole quantità di JavaScript gestibile per migliorare l'esperienza dell'utente, a volte è bello creare qualcosa che sembri più semplice. Avere qualcosa di leggero è fantastico, mi piace davvero che senza troppo carico cognitivo sia abbastanza chiaro come organizzare i tuoi file e impostare piccole briciole di pane che suggeriscono come verrà eseguito JavaScript con un pezzo di HTML.

Mi è piaciuto molto lavorare con Stimulus. Non c'è molto da fare, quindi la curva di apprendimento è abbastanza delicata. Sono abbastanza sicuro che se dovessi passare il mio codice a qualcun altro, sarebbero sviluppatori felici. Consiglio vivamente di provarlo, anche se è solo per pura curiosità.

L'elefante nella stanza è come si accumula rispetto a artisti del calibro di React e Vue, ma nella mia mente sono strumenti diversi per un'esigenza diversa. Nel mio caso, eseguo spesso il rendering di HTML dal mio server e aggiungo un po' di JavaScript per migliorare l'esperienza. Se stessi facendo qualcosa di più complesso, prenderei in considerazione un approccio diverso (o respingerei i requisiti per mantenere il mio codice semplice).

Ulteriori letture

• Pagina iniziale di stimolo
  Hanno un fantastico manuale che approfondisce i concetti che ho delineato sopra in modo molto più approfondito.
• Repository GitHub di stimolo
  Ho imparato così tanto su come funziona Stimulus esplorando il loro codice.
• Cheatsheet dello stimolo
  Il manuale riassunto in un'unica pagina.
• Forum degli stimoli
  Vedere altre persone che lavorano con Stimulus mi ha fatto davvero sentire come se fosse usato in natura.