In the previous blog post, we learned how to create a simple progress bar with Hotwire Turbo and broadcast updates to the frontend. But sometimes, simple solutions aren't enough. It's time to get familiar with another part of Hotwire: Stimulus! In this article, I'll demonstrate using Stimulus to handle more complex frontend logic.
The problem of async updates
Displaying the progress of synchronous data updates is straightforward with Hotwire Turbo. But a more real-life scenario considers asynchronous changes on the backend. In the context of our dummy jokes application, we can introduce more than one job that downloads jokes. When the number of jokes to fetch is more than 25, the process is split into more jobs.
Unfortunately, it causes some issues:
Architecture
Before we go to the code, let's revise the implementation plan. We can summarize the previous architecture with a simple graph: updating the data on the server results in an immediate broadcast and update of the frontend page.
The new architecture must handle async updates. We can't update the HTML directly from the background jobs because of overriding. We need to introduce a "mediator" between broadcasted updates and displaying them on the frontend. Time to use Stimulus. The plan is to:
broadcast updates from jobs
intercept the 'Append new joke' action in the Stimulus controller
apply frontend updates with JavaScript. We will update the progress bar (and other elements) and then execute default behavior (add new joke elements) as before.
The code
The provided code snippets highlight the most significant changes.
Check out a complete solution in this repository.
Update the job/service in your Ruby on Rails application: make just one broadcast that amends new jokes.
# app/services/fetch_jokes_service.rbclassFetchJokesServicedefperform(missing_jokes_count)jokes=[]missing_jokes_count.timesdo|num|# logic for fetching/creating jokes same as before# (...)add_joke_card(joke)endtrueend# now this is the only broadcast from the servicedefadd_joke_card(joke)Turbo::StreamsChannel.broadcast_append_to([jokes_request,"jokes"],target: "jokes_grid",partial: "jokes/joke",locals: {joke: joke})end# rest of service code# (..)end
Prepare HTML page to work with Stimulus:
on the parent div define the controller name: data-controller="progress-bar"
define targets following Stimulus convention, eg. data-progress-bar-target="jokesGrid" is translated into jokesGridTarget inside a controller
add attributes with input values needed for controller, eg: data-progress-bar-limit-value="<%= @jokes_request.amount %>".
Add the most important part: Stimulus controller. Lots of stuff happening here:
define values and targets corresponding to HTML page elements
add a new EventListener hook to override rendering turbo stream event: make additional updates on the page and then execute the default behavior. The same approach we would use for adding custom actions to the Stimulus controller.
configure functions to run when a new joke is added: update count, update the progress bar.
Huge thanks to Cezary Kłos, who proposed this solution!
In conclusion, the responsibility for displaying updates shifts from the backend to the frontend. The backend only signals a change, but the Stimulus controller decides what and how to display. The new solution uses JavaScript and is far more flexible than before.
Summary
Hotwire Turbo is perfect for transmitting backend updates to the frontend. But for more complex use cases, we need to use another element of Hotwire: Stimulus. The presented solution is an example of manipulating DOM elements with minimal JavaScript. Hopefully, it inspires you in your Hotwire journey!