Uma introdução ao Stimulus.js

A web se move muito rápido e escolher uma abordagem para o seu frontend que pareça sensato em um ano é complicado. Meu maior medo como desenvolvedor é pegar um projeto que não foi tocado por um tempo, e encontrar a documentação para qualquer abordagem que eles usaram é inexistente ou não é facilmente encontrada online.

Cerca de um ano atrás, comecei a usar o Stimulus e me senti muito feliz com o código que estava enviando. É uma biblioteca de aproximadamente 30kb que encoraja pequenas quantidades reutilizáveis ​​de JavaScript dentro de seu aplicativo, organizada de tal forma que deixa pequenas dicas em seu HTML acessível sobre onde encontrar o JavaScript ao qual está conectado. Isso torna a compreensão de como um pedaço de JavaScript irá interagir com sua página quase como ler pseudocódigo.

O Stimulus foi criado pela equipe da Basecamp - eles lançaram recentemente o serviço de e-mail HEY - para ajudar a manter o JavaScript que eles escrevem para seus aplicativos da web. Historicamente, o Basecamp tem sido muito bom em manter seus projetos de código aberto, então me sinto bastante confiante de que o Stimulus foi testado minuciosamente e será mantido nos próximos anos.

O estímulo me permitiu criar aplicativos de uma maneira que parece reutilizável e acessível. Embora eu não ache que o Stimulus dominará a web como o React e o Vue, acho que é uma ferramenta que vale a pena aprender.

Terminologia

Como todos os frameworks, o Stimulus tem termos preferidos para descrever certas coisas. Felizmente (e uma das principais razões pelas quais passei a gostar do Stimulus), existem apenas dois que você precisa conhecer:

• Controlador
  Isso se refere a instâncias de classes JavaScript que são os blocos de construção do seu aplicativo. É seguro dizer que quando falamos de Controladores de Estímulo, estamos falando de classes JavaScript.
• Identificador
  Este é o nome que usaremos para referenciar nosso controlador em nosso HTML usando um atributo de dados que é comum às bases de código do Stimulus.
  

Vamos pular no estímulo!

Nos exemplos a seguir, vou usar o código que você pode colocar no navegador para começar imediatamente por meio da biblioteca distribuída via unpkg.com. Mais tarde, abordarei a abordagem do webpack, que é altamente recomendada, pois permite uma melhor organização do seu código e é a abordagem usada no Manual de estímulos.

A Caldeira

Depois de entender a essência do trecho acima, você terá o conhecimento para se sentir confortável em escolher um projeto que use o Stimulus.

Muito incrível, certo? Vamos pular para o que tudo está fazendo!

application.start

Esta linha diz ao Stimulus para adicionar os ouvintes à página. Se você chamá-lo apenas uma vez no topo da sua página antes de adicionar qualquer código de estímulo, ele retornará uma instância do controlador de estímulo principal que inclui o register de método usado para informar ao estímulo sobre as classes que você gostaria de conectar para isso.

Controladores

O atributo data-controller conecta nosso elemento HTML a uma instância de nossa classe JavaScript. Nesse caso, usamos o identificador “counter” para conectar uma instância da classe JavaScript CounterController ao nosso elemento div . Contamos ao Stimulus sobre a conexão entre este identificador e o controlador através do método application.register .

O estímulo monitorará continuamente sua página para quando elementos com esse atributo forem adicionados e removidos. Quando um novo pedaço de HTML é adicionado à página com um atributo data-controller , ele inicializa uma nova instância da classe de controlador relevante e, em seguida, conecta o elemento HTML. Se você remover esse elemento da página, ele chamará o método de disconnect na classe do controlador.

Ações

O estímulo usa uma data-action atributo de dados para definir claramente qual função do controlador será executada. Usando a sintaxe event->controller#function qualquer pessoa lendo o HTML poderá ver o que ele faz. Isso é especialmente útil, pois reduz o risco de código inesperado de outros arquivos, facilitando a navegação na base de código. Quando vi pela primeira vez a abordagem que o Stimulus encoraja, parecia quase como ler pseudocódigo.

No exemplo acima, quando o botão dispara o evento “click”, ele será passado para a função addOne dentro do nosso controller “counter”.

Alvos

Os destinos são uma maneira de definir explicitamente quais elementos estarão disponíveis para seu controlador. Historicamente, usei uma mistura de ID, nomes de classes CSS e atributos de dados para conseguir isso, então ter um único “Esta é a maneira de fazer” que é tão explícito torna o código muito mais consistente.

Isso requer definir seus nomes de destino dentro de sua classe de controlador por meio da função targets e adicionar o nome a um elemento por meio do data-target .

Depois de configurar essas duas peças, seu elemento estará disponível em seu controlador. Neste caso, configurei o alvo com o nome “output” e ele pode ser acessado por this.outputTarget dentro das funções do nosso controller.

Destinos duplicados

Se você tiver vários alvos com o mesmo nome, você pode acessá-los usando a versão plural do método alvo, neste caso quando eu chamo this.outputTargets , ele retornará um array contendo minhas duas divs com o atributo data-target="hello.output" .

Tipos de eventos

Você ouve qualquer um dos eventos que normalmente poderia anexar por meio do método JavaScript addEventListener. Assim, por exemplo, você pode ouvir quando um botão é clicado, um formulário é enviado ou uma entrada é alterada.

Para ouvir eventos de window ou document (como redimensionamento ou o usuário ficar offline), você precisará anexar “@window” ou “@document” ao tipo de event (por exemplo, resize@window->console#logEvent chamará a função logEvent ) no controlador do console quando a janela é redimensionada.

Existe uma maneira abreviada de anexar eventos comuns, onde você pode omitir o tipo de evento e tem uma ação padrão para o tipo de elemento. No entanto, desencorajo fortemente o uso da abreviação de evento, pois aumenta a quantidade de suposições que alguém menos familiarizado com o estímulo precisa fazer sobre seu código.

Usa vários controladores no mesmo elemento

Muitas vezes você pode querer quebrar duas partes da lógica em classes separadas, mas fazer com que elas apareçam próximas uma da outra dentro do HTML. O estímulo permite que você conecte elementos a várias classes colocando referências a ambas no seu HTML.

No exemplo acima, configurei um objeto basket que se preocupa apenas em contar o número total de itens na cesta, mas também adicionei um objeto child que mostra a quantidade de sacolas por item.

Passando dados para seu objeto

O estímulo fornece os métodos this.data.get e this.data.set dentro da classe do controlador, isso permitirá que você altere os atributos de dados que estão dentro do mesmo namespace que o identificador. Com isso quero dizer que se você quiser passar dados para o seu controlador de estímulo a partir do seu HTML, basta adicionar um atributo como data-[identifier]-a-variable ao seu elemento HTML.

Ao chamar this.data.set , ele atualizará o valor em seu HTML para que você possa ver a alteração do valor ao inspecionar o elemento usando as ferramentas de desenvolvimento do navegador.

Usar atributos de dados com namespace é uma maneira muito boa de ajudar a deixar bem claro qual atributo de dados é para qual pedaço de código.

Inicializar, Conectado, Desconectado

À medida que seu aplicativo cresce, você provavelmente precisará se conectar a 'eventos de ciclo de vida' para definir padrões, buscar dados ou lidar com comunicação em tempo real. Stimulus tem três métodos embutidos que são chamados ao longo do ciclo de vida de uma classe de estímulo.

Quando Stimulus vê um elemento com um atributo data-controller correspondente, ele criará uma nova versão do seu controlador e chamará a função de initialize . Isso geralmente será executado quando você carregar a página pela primeira vez, mas também será executado se você anexar um novo HTML à sua página (por exemplo, via AJAX) contendo uma referência ao seu controlador. Ele não será executado quando você mover um elemento para uma nova posição em seu DOM.

Depois que uma classe for inicializada, o Stimulus a conectará ao elemento HTML e chamará a função connect . Ele também chamará connect se você mover um elemento dentro do seu DOM. Portanto, se você pegar um elemento, removê-lo de um elemento e anexá-lo em outro lugar, notará que apenas connect será chamado.

A função de disconnect será executada quando você remover um elemento da sua página, então, por exemplo, se você substituir o corpo do seu HTML, você pode derrubar qualquer código que precise ser executado novamente se o elemento não estiver no mesma posição. Por exemplo, se você tivesse um editor WYSIWYG sofisticado que adiciona muito HTML extra a um elemento, você poderia revertê-lo ao seu estado original quando a disconnect fosse chamada.

Herdar Funcionalidade

Ocasionalmente, você pode querer compartilhar um pouco de funcionalidade comum entre seus controladores de estímulos. A coisa legal sobre o Stimulus é que (sob o capô) você está conectando classes JavaScript um tanto simples a elementos HTML, então o compartilhamento de funcionalidades deve parecer familiar.

Neste exemplo, configurei uma classe pai chamada ParentController , que é estendida por uma classe filha chamada ChildController . Isso me permitiu herdar métodos do ParentController para não ter que duplicar o código dentro do meu ChildController .

Usando na produção

Eu demonstrei alguns exemplos bastante independentes de como usar o Estímulo acima, o que deve lhe dar uma amostra do que você pode alcançar. Eu também pensei que deveria tocar em como eu o uso na produção e como isso funcionou para mim.

Webpack

Se você estiver usando o Webpack, terá um prazer! O Stimulus foi totalmente feito para ser usado com o Webpack. A documentação deles tem até um lindo kit inicial para o Webpack. Ele permitirá que você divida seus controladores em arquivos separados e o Stimulus decidirá o nome correto a ser usado como identificador.

Você não precisa usar o webpack se quiser usar o Stimulus, mas ele limpa bastante a experiência. Pessoalmente, Stimulus foi a biblioteca que me ajudou a me apresentar ao Webpack e realmente sentir o valor que ele oferecia.

Convenções de nome de arquivo

Mencionei na introdução deste artigo que gostei de usar o Stimulus porque parecia organizado. Isso realmente se torna aparente quando você o combina com o Webpack, que permite o carregamento automático e o registro de controladores.

Depois de configurar o Stimulus no Webpack, ele o encorajará a nomear seus arquivos como [identifier]_controller.js , onde o identificador é o que você passará para o atributo data-controller HTML.

À medida que seu projeto cresce, você também pode querer mover seus controladores de estímulos para subpastas. De uma maneira mágica, o Stimulus converterá sublinhados em traços e as barras em dois traços, que se tornarão seu identificador. Assim, por exemplo, o nome de arquivo chat/conversation_item_controller.js terá o identificador chat--conversation-item .

Mantendo menos JavaScript

Uma das minhas citações favoritas é “O melhor código é nenhum código”, tento aplicar essa abordagem em todos os meus projetos.

Os navegadores da Web estão evoluindo muito, estou bastante convencido de que a maioria das coisas que preciso para escrever JavaScript hoje será padronizada e incorporada ao navegador nos próximos 5 anos. Um bom exemplo disso é o elemento de detalhes, quando comecei no desenvolvimento era super comum ter que codificar manualmente essa funcionalidade usando jQuery.

Como resultado disso, se eu puder escrever HTML acessível com uma pitada de JavaScript para atender às minhas necessidades, com a mentalidade de "Isso funciona hoje, mas em 5 anos eu quero substituir isso facilmente", ficarei feliz desenvolvedor. Isso é muito mais viável quando você escreveu menos código para começar, ao qual o Stimulus se presta.

HTML primeiro, depois JavaScript

Um aspecto que eu realmente gosto na abordagem que o Stimulus incentiva, é que eu posso me concentrar em enviar HTML para meus usuários, que é então aprimorado um pouco com JavaScript.

Sempre fui fã de usar os primeiros milissegundos da atenção de um usuário para obter o que tenho para compartilhar com eles – na frente deles. Então se preocupe em configurar a camada de interação enquanto o usuário pode começar a processar o que está vendo.

Além disso, se o JavaScript falhar por qualquer motivo, o usuário ainda poderá ver o conteúdo e interagir com ele sem JavaScript. Por exemplo, em vez de um formulário ser enviado via AJAX, ele será enviado por meio de uma solicitação de formulário tradicional que recarrega a página.

Conclusão

Eu amo construir sites que precisam apenas de pequenas pitadas de JavaScript sustentável para melhorar a experiência do usuário, às vezes é bom apenas construir algo que pareça mais simples. Ter algo leve é ​​ótimo, eu realmente amo que, sem muita carga cognitiva, é bem claro como organizar seus arquivos e configurar pequenas migalhas de pão que indicam como o JavaScript será executado com um pedaço de HTML.

Gostei muito de trabalhar com o Stimulus. Não há muito para isso, então a curva de aprendizado é bastante suave. Sinto-me bastante confiante de que, se eu passar meu código para outra pessoa, eles serão desenvolvedores felizes. Eu recomendo dar uma chance, mesmo que seja apenas por pura curiosidade.

O elefante na sala é como ele se compara a React e Vue, mas na minha opinião, eles são ferramentas diferentes para um requisito diferente. No meu caso, muitas vezes estou renderizando HTML do meu servidor e estou adicionando um pouco de JavaScript para melhorar a experiência. Se eu estivesse fazendo algo mais complexo, consideraria uma abordagem diferente (ou adiaria os requisitos para ajudar a manter meu código simples).

Leitura adicional

• Página inicial do estímulo
  Eles têm um manual fantástico que aborda os conceitos que descrevi acima com muito mais profundidade.
• Repositório GitHub de estímulo
  Eu aprendi muito sobre como o Stimulus funciona explorando seu código.
• Folha de dicas de estímulo
  O manual resumido em uma única página.
• Fórum de estímulo
  Ver outras pessoas trabalhando com o Stimulus me fez sentir como se estivesse sendo usado na natureza.