Una introducción a Stimulus.js

La web se mueve bastante rápido y elegir un enfoque para su interfaz que se sienta sensato dentro de un año es complicado. Mi mayor temor como desarrollador es tomar un proyecto que no se ha tocado por un tiempo y encontrar la documentación para cualquier enfoque que usaron no existe o no se encuentra fácilmente en línea.

Hace aproximadamente un año, comencé a usar Stimulus y me sentí muy feliz con el código que estaba enviando. Es una biblioteca de ~30kb que fomenta pequeñas chispas reutilizables de JavaScript dentro de su aplicación, organizada de tal manera que deja pequeñas pistas en su HTML accesible sobre dónde encontrar el JavaScript al que está conectado. Hace que comprender cómo una pieza de JavaScript interactuará con su página es casi como leer un pseudocódigo.

Stimulus fue creado por el equipo de Basecamp (recientemente lanzaron el servicio de correo electrónico HEY ) para ayudar a mantener el JavaScript que escriben para sus aplicaciones web. Históricamente, Basecamp ha sido bastante bueno en el mantenimiento de sus proyectos de código abierto, por lo que estoy bastante seguro de que Stimulus se ha probado a fondo y se mantendrá durante los próximos años.

Stimulus me ha permitido crear aplicaciones de una manera que se siente reutilizable y accesible. Si bien no creo que Stimulus se haga cargo de la web como lo han hecho React y Vue, creo que es una herramienta que vale la pena aprender.

Terminología

Como todos los marcos, Stimulus tiene términos preferidos para describir ciertas cosas. Afortunadamente (y una de las razones principales por las que me ha gustado Stimulus), solo hay dos que debes conocer:

• Controlador
  Esto se refiere a instancias de clases de JavaScript que son los componentes básicos de su aplicación. Es seguro decir que cuando hablamos de controladores de estímulo, estamos hablando de clases de JavaScript.
• identificador
  Este es el nombre que usaremos para hacer referencia a nuestro controlador en nuestro HTML usando un atributo de datos que es común a las bases de código de Stimulus.
  

¡Saltamos al estímulo!

En los siguientes ejemplos, usaré un código que puede colocar en el navegador para comenzar de inmediato a través de la biblioteca distribuida a través de unpkg.com. Más adelante, cubriré el enfoque del paquete web, que es muy recomendable ya que permite una mejor organización de su código y es el enfoque utilizado en el Manual de estímulo.

el repetitivo

Una vez que comprenda la esencia del fragmento anterior, tendrá el conocimiento para sentirse cómodo al elegir un proyecto que use Stimulus.

Bastante impresionante, ¿verdad? ¡Pasemos a lo que todo está haciendo!

application.start

Esta línea le dice a Stimulus que agregue los oyentes a la página. Si lo llama solo una vez en la parte superior de su página antes de agregar cualquier código de Stimulus, devolverá una instancia del controlador principal de Stimulus que incluye el register de método que se usa para informar a Stimulus sobre las clases que le gustaría conectar. lo.

Controladores

El atributo data-controller conecta nuestro elemento HTML a una instancia de nuestra clase de JavaScript. En este caso, usamos el identificador "contador" para conectar una instancia de la clase JavaScript CounterController a nuestro elemento div . Le contamos a Stimulus sobre la conexión entre este identificador y el controlador a través del método application.register .

Stimulus monitoreará continuamente su página para ver cuándo se agregan y eliminan elementos con este atributo. Cuando se agrega una nueva pieza de HTML a la página con un atributo data-controller , inicializará una nueva instancia de la clase de controlador relevante y luego conectará el elemento HTML. Si elimina ese elemento de la página, llamará al método de disconnect en la clase del controlador.

Comportamiento

Stimulus utiliza una data-action para definir claramente qué función del controlador se ejecutará. Usando la sintaxis event->controller#function cualquiera que lea el HTML podrá ver lo que hace. Esto es especialmente útil ya que reduce el riesgo de código inesperado de otros archivos, lo que facilita la navegación por el código base. Cuando vi por primera vez el enfoque que fomenta Stimulus, me sentí casi como leer un pseudocódigo.

En el ejemplo anterior, cuando el botón activa el evento "clic", se pasará a la función addOne dentro de nuestro controlador "contador".

Objetivos

Los objetivos son una forma de definir explícitamente qué elementos estarán disponibles para su controlador. Históricamente, he usado una combinación de ID, nombres de clase CSS y atributos de datos para lograr esto, por lo que tener un solo "Esta es la manera de hacerlo" que es tan explícito hace que el código sea mucho más consistente.

Esto requiere definir sus nombres de destino dentro de su clase de controlador a través de la función de targets y agregar el nombre a un elemento a través del data-target .

Una vez que haya configurado esas dos piezas, su elemento estará disponible en su controlador. En este caso, configuré el destino con el nombre "salida" y se puede acceder a él mediante this.outputTarget dentro de las funciones de nuestro controlador.

Objetivos duplicados

Si tiene varios objetivos con el mismo nombre, puede acceder a ellos usando la versión plural del método de destino, en este caso, cuando llamo this.outputTargets , devolverá una matriz que contiene mis dos divs con el atributo data-target="hello.output" .

Tipos de eventos

Escucha cualquiera de los eventos que normalmente podría adjuntar a través del método de JavaScript addEventListener. Entonces, por ejemplo, podría escuchar cuando se hace clic en un botón, se envía un formulario o se cambia una entrada.

Para escuchar eventos de window o document (como cambiar el tamaño o que el usuario se desconecte), deberá agregar "@window" o "@document" al tipo de event (por ejemplo resize@window->console#logEvent llamará la función logEvent ) en el controlador de la console cuando se cambia el tamaño de la ventana.

Hay una forma abreviada de adjuntar eventos comunes, donde puede omitir el tipo de evento y tiene una acción predeterminada para el tipo de elemento. Sin embargo, desaconsejo encarecidamente el uso de la abreviatura de evento, ya que aumenta la cantidad de suposiciones que alguien que está menos familiarizado con Stimulus debe hacer sobre su código.

Utiliza múltiples controladores en el mismo elemento

Muy a menudo, es posible que desee dividir dos piezas de lógica en clases separadas, pero hacer que aparezcan cerca una de la otra dentro del HTML. Stimulus le permite conectar elementos a múltiples clases colocando referencias a ambos dentro de su HTML.

En el ejemplo anterior, configuré un objeto de basket que solo se ocupa de contar la cantidad total de artículos en la canasta, pero también agregué un objeto child que muestra la cantidad de bolsas por artículo.

Pasar datos a su objeto

Stimulus proporciona los métodos this.data.get y this.data.set dentro de la clase del controlador, esto le permitirá cambiar los atributos de datos que están dentro del mismo espacio de nombres que el identificador. Con esto quiero decir que si desea pasar datos a su controlador de estímulo desde su HTML, simplemente agregue un atributo como data-[identifier]-a-variable a su elemento HTML.

Al llamar a this.data.set , actualizará el valor en su HTML para que pueda ver el cambio de valor cuando inspeccione el elemento usando las herramientas de desarrollo de su navegador.

El uso de atributos de datos con espacio de nombres es una manera muy buena de ayudar a dejar muy claro qué atributo de datos es para qué fragmento de código.

Inicializar, Conectado, Desconectado

A medida que crezca su aplicación, probablemente necesitará conectarse a "eventos de ciclo de vida" para establecer valores predeterminados, obtener datos o manejar la comunicación en tiempo real. Stimulus tiene tres métodos integrados que se llaman a lo largo del ciclo de vida de una clase de Stimulus.

Cuando Stimulus ve un elemento con un atributo data-controller coincidente, creará una nueva versión de su controlador y llamará a la función de initialize . Esto a menudo se ejecutará cuando cargue la página por primera vez, pero también se ejecutará si agregara un nuevo HTML a su página (por ejemplo, a través de AJAX) que contenga una referencia a su controlador. No se ejecutará cuando mueva un elemento a una nueva posición dentro de su DOM.

Después de inicializar una clase, Stimulus la conectará al elemento HTML y llamará a la función de connect . También llamará a connect si tuviera que mover un elemento dentro de su DOM. Entonces, si tuviera que tomar un elemento, eliminarlo de un elemento y luego agregarlo en otro lugar, notará que solo se llamará a connect .

La función de disconnect se ejecutará cuando elimine un elemento de su página, por lo que, por ejemplo, si tuviera que reemplazar el cuerpo de su HTML, podría eliminar cualquier código que deba volver a ejecutarse si el elemento no está en el misma posición. Por ejemplo, si tuviera un elegante editor WYSIWYG que agrega mucho HTML adicional a un elemento, podría revertirlo a su estado original cuando se llamó a la disconnect .

Herencia de funcionalidad

En ocasiones, es posible que desee compartir una pequeña funcionalidad común entre sus controladores Stimulus. Lo bueno de Stimulus es que (debajo del capó) está conectando clases de JavaScript un tanto vanidosas a elementos HTML, por lo que compartir la funcionalidad debería resultarle familiar.

En este ejemplo, configuré una clase principal llamada ParentController , que luego se amplía con una clase secundaria llamada ChildController . Esto me permitió heredar métodos de ParentController para no tener que duplicar el código dentro de mi ChildController .

Usándolo en producción

Mostré algunos ejemplos bastante independientes de cómo usar Stimulus arriba, lo que debería darle una idea de lo que puede lograr. También pensé que debería mencionar cómo lo uso en producción y cómo me ha funcionado.

paquete web

Si está utilizando Webpack, ¡le espera una sorpresa! Stimulus se hizo totalmente para usarse con Webpack. Su documentación incluso tiene un hermoso kit de inicio para Webpack. Le permitirá dividir sus controladores en archivos separados y Stimulus decidirá el nombre correcto para usar como identificador.

No tienes que usar webpack si quieres usar Stimulus, pero limpia mucho la experiencia. Personalmente, Stimulus fue la biblioteca que me ayudó a presentarme a Webpack y a sentir realmente el valor que ofrecía.

Convenciones de nombre de archivo

Mencioné en la introducción de este artículo que disfruté usando Stimulus porque se sentía organizado. Esto realmente se vuelve evidente cuando lo combina con Webpack, que permite la carga automática y el registro de controladores.

Una vez que haya configurado Stimulus en Webpack, lo alentará a nombrar sus archivos como [identifier]_controller.js , donde el identificador es lo que pasará a su atributo data-controller HTML.

A medida que crece su proyecto, es posible que también desee mover sus controladores Stimulus a subcarpetas. De una manera mágica, Stimulus convertirá los guiones bajos en guiones y las barras diagonales de la carpeta en dos guiones, que luego se convertirán en su identificador. Entonces, por ejemplo, el nombre de archivo chat/conversation_item_controller.js tendrá el identificador chat--conversation-item .

Mantener menos JavaScript

Una de mis citas favoritas es "El mejor código es ningún código". Trato de aplicar este enfoque a todos mis proyectos.

Los navegadores web están evolucionando mucho, estoy bastante convencido de que la mayoría de las cosas que necesito para escribir JavaScript hoy se estandarizarán y se integrarán en el navegador dentro de los próximos 5 años. Un buen ejemplo de esto es el elemento de detalles, cuando comencé con el desarrollo era muy común tener que codificar manualmente esa funcionalidad usando jQuery.

Como resultado de esto, si puedo escribir HTML accesible con una pizca de JavaScript para satisfacer mis necesidades, con la mentalidad de "Esto funciona hoy, pero en 5 años quiero reemplazarlo fácilmente", seré un feliz desarrollador. Esto es mucho más factible cuando ha escrito menos código para empezar, a lo que se presta Stimulus.

Primero HTML, luego JavaScript

Un aspecto que realmente me gusta del enfoque que fomenta Stimulus es que puedo concentrarme en enviar HTML por cable a mis usuarios, que luego se anima un poco con JavaScript.

Siempre he sido fanático de usar los primeros milisegundos de la atención de un usuario para obtener lo que tengo que compartir con ellos, frente a ellos. Luego, preocuparse por configurar la capa de interacción mientras el usuario puede comenzar a procesar lo que está viendo.

Además, si JavaScript fallara por cualquier motivo, el usuario aún puede ver el contenido e interactuar con él sin JavaScript. Por ejemplo, en lugar de enviar un formulario a través de AJAX, se enviará a través de una solicitud de formulario tradicional que recarga la página.

Conclusión

Me encanta crear sitios que solo necesitan pequeñas cantidades de JavaScript mantenible para mejorar la experiencia del usuario, a veces es bueno simplemente crear algo que se sienta más simple. Tener algo liviano es excelente, realmente me encanta que, sin demasiada carga cognitiva, es bastante claro cómo organizar sus archivos y configurar pequeñas migas de pan que insinúan cómo se ejecutará JavaScript con una pieza de HTML.

He disfrutado mucho trabajar con Stimulus. No hay demasiado, por lo que la curva de aprendizaje es bastante suave. Estoy bastante seguro de que si tuviera que pasar mi código a otra persona, serían desarrolladores felices. Recomiendo encarecidamente darle una oportunidad, aunque sea por pura curiosidad.

El elefante en la habitación es cómo se compara en comparación con React y Vue, pero en mi opinión, son herramientas diferentes para un requisito diferente. En mi caso, a menudo renderizo HTML desde mi servidor y agrego un poco de JavaScript para mejorar la experiencia. Si estuviera haciendo algo más complejo, consideraría un enfoque diferente (o retrocedería en los requisitos para ayudar a que mi código siguiera siendo simple).

Otras lecturas

• Página de inicio de estímulo
  Tienen un manual fantástico que profundiza mucho más en los conceptos que he esbozado anteriormente.
• Repositorio GitHub de estímulo
  Aprendí mucho sobre cómo funciona Stimulus al explorar su código.
• Hoja de trucos de estímulo
  El manual resumido en una sola página.
• Foro de estímulo
  Ver a otras personas trabajando con Stimulus me ha hecho sentir realmente como si se estuviera utilizando en la naturaleza.