DEV Community: David Colby

User notifications with Rails, Noticed, and Hotwire

David Colby — Tue, 22 Mar 2022 02:36:31 +0000

A nearly-universal need in web applications is user notifications. An event happens in the application that the user cares about, and you inform the user of the event. A common example is in applications that have a commenting system — when a user mentions another user in a comment, the application notifies the mentioned user of that comment through email.

The channel(s) used to notify users of new important events depends on the application but the path very often includes an in-app notification widget that shows the user their latest notifications. Other common options include emails, text messages, Slack, and Discord.

Rails developers that need to add a notification system to their application often turn to Noticed. Noticed is a gem that makes it easy to add new, multi-channel notifications to Rails applications.

Today, we are going to take a look at how Noticed works by using Noticed to implement in-app user notifications. We will send those notifications to logged in users in real-time with Turbo Streams and, for extra fun, we will load user notifications inside of a Turbo Frame.

When we are finished, our application will work like this:

Before we begin, this tutorial assumes that you are comfortable building simple Ruby on Rails applications independently. No prior knowledge of Turbo or Noticed is required.

Let’s dive in!

Application setup

To follow along with this tutorial, start by cloning this repository from Github and then set it up:

cd user-notices
bin/setup

The starter repo contains a Rails 7 application with Turbo, Tailwind, and Devise ready to go. The starter repo uses Ruby 3.0.2, but everything in this tutorial will work fine with Ruby 2.7 and 3.1, if you prefer.

If you want to work from your own application instead of cloning the starter, you will need a Rails 7 application with Turbo installed and an authentication system built around a User model.

When you’re ready to start building, start the server and build Tailwind’s css with bin/dev.

Noticed setup

Our starter application comes with a Devise-powered user model and the root path set to the Dashboard#show action which just contains links to sign in or sign out for now. Before diving in to the code, create at least one user through the form at http://localhost:3000/users/sign_up so that you can login and test notifications later in this tutorial.

Eventually, our users will be able to create Messages for other users in the application. Each time a message is a created, a new Notification will be created, and the user the message is for will see that notification on their dashboard.

Before any of that can happen, we need to add Noticed to our application and scaffold a Message resource. Start by adding Noticed, from your terminal:

bundle add noticed
rails generate noticed:model
rails db:migrate

These commands are straight from the Noticed installation docs. If your Rails app is running, be sure to restart it after adding the Noticed gem to your Gemfile with bundle add.

Next, update app/models/user.rb to associate notifications with users:

class User < ApplicationRecord
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :validatable

  has_many :notifications, as: :recipient
end

Here, we added the notifications has_many association, as directed by the Noticed setup script.

Now our users can receive notifications, but we don’t have anything useful to notify them about. We will fix that by scaffolding a Message resource. From your terminal:

rails g scaffold message content:text user:references
rails db:migrate

Thanks to the magic of Rails, the scaffold generator gives us almost everything we need to start creating messages and associating them with users. Because we are using Tailwind via the tailwindcss-rails gem, the scaffold generator also includes some nice looking base styles too.

After the generator runs, update the User model again at app/models/user.rb:

class User < ApplicationRecord
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :validatable

  has_many :messages
  has_many :notifications, as: :recipient
end

Here, we added has_many :messages to set up the other side of the messages relationship.

For convenience, we can also add a link to the messages index page in app/views/dashboard/show.html.erb:

<div>
  <% if user_signed_in? %>
    Signed in as <%= current_user.email %>. <%= button_to "Sign out", destroy_user_session_path, method: :delete, class: "text-blue-500" %>
    <%= link_to "All messages", messages_path, class: "text-blue-500" %>
  <% else %>
    <%= link_to "Sign in", new_user_session_path, class: "text-blue-500" %>
  <% end %>
</div>

And then make a small adjustment to the messages form so we don’t have to memorize user ids:

<%= form_with(model: message, class: "contents") do |form| %>
  <% if message.errors.any? %>
    <div id="error_explanation" class="bg-red-50 text-red-500 px-3 py-2 font-medium rounded-lg mt-3">
      <h2><%= pluralize(message.errors.count, "error") %> prohibited this message from being saved:</h2>

      <ul>
        <% message.errors.each do |error| %>
          <li><%= error.full_message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>

  <div class="my-5">
    <%= form.label :content %>
    <%= form.text_area :content, rows: 4, class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 mt-2 w-full" %>
  </div>

  <div class="my-5">
    <%= form.label :user_id %>
    <%= form.select :user_id, options_for_select(User.all.pluck(:email, :id)), class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 mt-2 w-full" %>
  </div>

  <div class="inline">
    <%= form.submit class: "rounded-lg py-3 px-5 bg-blue-600 text-white inline-block font-medium cursor-pointer" %>
  </div>
<% end %>

With these changes in place, head to http://localhost:3000/messages and create a couple of messages to ensure that creating messages works as expected.

Now that we have Noticed installed and messages ready to go, next up we will send users notifications when a new message is created.

Message notifications

Our goal in this section is to create and display notifications to logged in users on the Dashboard#show page.

Step one is to add a new notification, using the the generator built-in to Noticed. From your terminal:

rails generate noticed:notification MessageNotification

This generator creates a new MessageNotification class at app/notifications/message_notification.rb. Head there next and make a few small updates:

class MessageNotification < Noticed::Base
  deliver_by :database

  param :message

  def message
    params[:message].content
  end

  def url
    message_path(params[:message])
  end
end

Here, deliver_by :database stores the newly created notification in the database, which will be important for Turbo Stream broadcasts later. If we wanted to send the notification by email too, we could add deliver_by :email, mailer: SomeMailer, as described in the Noticed docs.

param :message serializes the message object and stores it with the notification record in the database. We use that serialized message in the message and url methods. Serializing objects into params in this manner makes it easy to access records related to the notification without managing complex references — just dump the record(s) you need into params and profit.

We can now use our MessageNotification to send notifications to users when a new message is created. Next we need to put the MessageNotification class into use. Head to app/models/message.rb and update it:

class Message < ApplicationRecord
  has_noticed_notifications

  belongs_to :user

  after_create_commit :notify_user

  def notify_user
    MessageNotification.with(message: self).deliver_later(user)
  end
end

Each time a message is created (after_create_commit), notify_user runs and creates a new MessageNotification, serializing the message object and delivering the message to the message’s user. We also add has_noticed_notifications to ensure that when a message is destroyed, any related notifications are destroyed too.

With those small changes, we now have a database-backed notification system up and running. Neat!

We have notifications in the database now but there is no way for users to see those notifications anywhere, which is not very useful. Next up, we will create a Notifications controller to display notifications to users.

From your terminal, generate the controller and a partial to render each notification:

rails g controller Notifications index
touch app/views/notifications/_notification.html.erb

Head to config/routes.rb and add a notifications path helper:

Rails.application.routes.draw do
  resources :notifications, only: [:index]
  resources :messages
  devise_for :users
  get 'dashboard/show'
  root "dashboard#show"
end

Update the NotificationsController at app/controllers/notifications_controller.rb:

class NotificationsController < ApplicationController
  def index
    @notifications = Notification.where(recipient: current_user)
  end
end

Here, we scope notifications to the current_user, so users only see their own notifications when logged in to the application.

Update the new Notifications index view at app/views/notifications/index.html.erb:

<%= turbo_frame_tag "notifications" do %>
  <h1 class="font-bold text-4xl">Notifications</h1>
  <ul>
    <%= render @notifications %>
  </ul>
<% end %>

Note the turbo_frame_tag wrapping the list of notifications. Our plan is to render the list of notifications on the dashboard show page — we will use Turbo Frame’s eager-loading functionality to load the content of the notifications index page on the dashboard show page.

render @notifications relies on Rails’ collection rendering to render each notification. Before this will work, we need to fill in app/views/notifications/_notification.html.erb:

<li>
  <div>
    <p class="text-gray-700">
      <%= notification.to_notification.message %>
    </p>
    <div class="flex justify-between mt-1 text-gray-500 text-sm space-x-4">
      <p>
        Received on <%= notification.created_at.to_date %>
      </p>
      <p>
        Status: <%= notification.read? ? "Read" : "Unread" %>
      </p>
    </div>
  </div>
</li>

Here, we use to_notification from Noticed to access the message method we added in MessageNotification earlier, and use the built-in read? method from Noticed to check if the user has read the notification or not.

One last step here before users can see notifications on the dashboard. Head to app/views/dashboard/show.html.erb and update it to add an eager-loaded Turbo Frame for logged in users:

<div class="flex justify-between">
  <% if user_signed_in? %>
    <div>
      Signed in as <%= current_user.email %>. <%= button_to "Sign out", destroy_user_session_path, method: :delete, class: "text-blue-500" %>
      <%= link_to "All messages", messages_path, class: "text-blue-500" %>
    </div>
    <%= turbo_frame_tag "notifications", src: notifications_path %>
  <% else %>
    <%= link_to "Sign in", new_user_session_path, class: "text-blue-500" %>
  <% end %>
</div>

The turbo_frame_tag has an id of notifications, which matches the Turbo Frame rendered by Notifications#index. When Turbo eager-loads content for a Turbo Frame, it expects the url passed to src to return a response that includes a Turbo Frame with a matching id.

The sequence of events for our eager-loaded notifications index page is this:

A logged in user visits Dashboard#show
Dashboard#show is loaded
Turbo sees the turbo_frame_tag with an src attribute and initiates a new request to /notifications
Notifications#index returns HTML that includes a turbo_frame_tag that matches the tag that initiated the request
Turbo extracts the contents of the turbo_frame_tag and uses that content to replace the content of the existing Turbo Frame

At this point, logged in users can see their notifications on the dashboard. Test it out by logging in as a user and then creating a new messages for that user. Refresh the dashboard as that user and see that your notifications are listed on the dashboard:

While our users can see notifications, they don’t see those notifications in real-time — they have to manually refresh the dashboard before they see new notifications. Let’s wrap up this tutorial by making notifications real-time with Turbo Stream broadcasts.

Real-time notifications with Turbo Streams

Turbo model broadcasts, powered by turbo-rails, make it easy to send real-time updates to users with ActionCable. When we finish this section, each time a new notification is created, a Turbo Stream broadcast will be sent over an ActionCable channel that will automatically insert new notifications for a user into the user's dashboard notifications list.

To start, update app/models/notification.rb to trigger a Turbo Stream broadcast when a new notification is created:

class Notification < ApplicationRecord
  include Noticed::Model
  belongs_to :recipient, polymorphic: true

  after_create_commit :broadcast_to_recipient

  def broadcast_to_recipient
    broadcast_append_later_to(
      recipient,
      :notifications,
      target: 'notifications-list',
      partial: 'notifications/notification',
      locals: {
        notification: self
      }
    )
  end
end

Here, the broadcast_to_recipient method appends a new notification to the list of notifications. To ensure that only the user the notification is for receives the broadcast, we set the broadcast channel to recipient, :notifications, as described in the turbo-rails source.

The model update handles sending Turbo Stream broadcasts, but before the broadcast will be picked up by the front end we need to subscribe users to a Turbo Stream channel. We also must ensure the markup includes a notifications-list id (matching the target passed to broadcast_append_later_to) for the Turbo Stream to update.

Starting in app/views/notifications/index.html.erb, add the notifications-list id to the ul containing the list of notifications:

<%= turbo_frame_tag "notifications" do %>
  <h1 class="font-bold text-4xl">Notifications</h1>
  <ul id="notifications-list">
    <%= render @notifications %>
  </ul>
<% end %>

And then in app/views/dashboard/show.html.erb:

<div class="flex justify-between">
  <% if user_signed_in? %>
    <div>
      Signed in as <%= current_user.email %>. <%= button_to "Sign out", destroy_user_session_path, method: :delete, class: "text-blue-500" %>
      <%= link_to "All messages", messages_path, class: "text-blue-500" %>
    </div>
    <%= turbo_stream_from current_user, :notifications %>
    <%= turbo_frame_tag "notifications", src: notifications_path %>
  <% else %>
    <%= link_to "Sign in", new_user_session_path, class: "text-blue-500" %>
  <% end %>
</div>

Here, the turbo_stream_from helper from turbo-rails subscribes the user to a channel that matches the channel our model is broadcasting from. current_user, :notifications in the view == recipient, :notifications in the model).

When a user visits the dashboard, the turbo_stream_from helper opens an ActionCable subscription to the matching channel. Broadcasts to that channel are picked up by Turbo and used to update the page when new broadcasts are received. The scoping of the channel to the current_user ensures that users do not receive broadcasts intended for another user so that our new message notifications are only sent to the user the message is for.

With these changes in place, login as a user in one browser and head to the dashboard. Confirm the ActionCable channel subscription is created by checking the server logs for a line that looks like this:

Turbo::StreamsChannel is streaming from Z2lkOi8vdXNlci1ub3RpY2VzL1VzZXIvMQ:notifications

In another browser, head to the new messages form and create a message, setting the user on the form to the user that you are logged in as in the first browser. If all has gone well, the new notification will be added to the list instantly, with no page updates required.

Great work following along with this tutorial, that is all of the code for the day!

Wrapping up & further reading

Today we built a simple notification system with Rails and Noticed, and we used Turbo to display new notifications for users in real-time. Noticed is an extremely powerful gem that makes the work of building and expanding a multi-channel notification system in a Rails app much simpler, and the easy integration with Turbo Streams makes it a great match for any modern Rails application.

In our tutorial application, we displayed notifications as a static list of every notification the user has ever received, with no way to interact with them or remove them from the list. We also required users to be on their dashboard to see the new notification.

In a production application, we might expand our Notifications controller to include an update method that allows users to mark notifications as read and clear those notifications from the list.

We would would also likely build a notification indicator in the main navigation that is rendered on every page of our application with an icon indicating unread notifications (think the ubiquitous bell icon seen across thousands of web applications).

The neat thing about this tutorial’s approach is that the basic approach remains the same even for a more sophisticated implementation. Use Turbo Streams to broadcast new notifications to users and update the UI in real-time. Use built-in Noticed methods to act on notifications (like mark_as_read! to read a notification). Use a Turbo Frame to fetch notifications for a user and load those notifications into a section of a larger page.

For further learning on Noticed, Turbo Streams, and Turbo Frames:

Check out the GoRails tutorial on Noticed (Chris from GoRails wrote Noticed, thanks Chris!)
Read the simple but effective Noticed docs, starting in the repo’s readme and digging in to specific delivery methods as needed
Solidify Turbo concepts with my Turbo 101 article, and my Turbo Frames and Turbo Streams on Rails articles, for more on how to use Turbo with Rails

Finally, if you want to dig deeper into implementing notifications in a Rails application, a chapter of my book is dedicated to building a very light notification system from scratch, with inspiration from Noticed. In the book, we add real-time updates in a more realistic way, with the standard bell icon, pop-out notification list, and the ability to mark notifications as read with a click. The book is written in this same, step-by-step tutorial style, and covers building a modern Rails application from scratch with StimulusReflex, CableReady, Hotwire, and friends.

Building your own notification system is a great exercise if you want to use Noticed in a real production application later, since you will have a much greater understanding of, and appreciation for, what Noticed offers you.

That’s all for today. As always, thanks for reading!

Toggling view layouts with Kredis, Turbo Frames, and Rails

David Colby — Tue, 08 Mar 2022 02:31:25 +0000

Kredis is a new gem that makes it easier to work with Redis keys in Ruby on Rails. Kredis was added a suggested gem for new Rails applications starting with the release of Rails 7.0 in December of 2021 and is likely to become a larger force in the Rails world in the coming years.

From the documentation, Kredis “encapsulates higher-level types and data structures around a single key, so you can interact with them as coherent objects rather than isolated procedural commands”.

What this means for us is that we can use Kredis to make it easier to use Redis as a data store in our application. With Kredis, it is simple to use Redis to read and write complex data structures. Kredis’ integration with ActiveRecord allows us to work with Redis data alongside existing models.

Today we will use Kredis to power a card/list view toggle for a resource’s index page, persisting the user’s view preference across requests. This tutorial will offer a gentle introduction into how Kredis works while exploring how Kredis can help us implement a common real-world UX pattern.

We will also add a bit of Turbo functionality in the form of a Turbo Frame to wrap the list of items to make applying the user’s view preference a bit more efficient.

When we are finished, our application will work like this:

Before we begin, this tutorial is best suited for folks with experience building simple applications with Ruby on Rails. If you have never used Rails before, this tutorial will be difficult to follow. You do not need any prior experience with Turbo or Kredis to follow along with this tutorial.

As usual, you can find the complete code for this application on Github.

Let’s start building.

Application setup

To begin, create a new Rails 7 application from your terminal and scaffold up a Players resource, which we will use as the base for our Kredis-powered view toggle.

rails new kredis-players --css=tailwind
cd kredis-players
./bin/rails g scaffold Player name:string team:string
./bin/rails db:migrate

Note the inclusion of the css=tailwind option in the rails new command. We will use Tailwind to style our application so we can stay focused on building with Kredis instead of copy/pasting CSS.

Once the application is created and the Players resource is scaffolded, you can start up the server and build Tailwind’s CSS with bin/dev.

Because we are building a view toggle for the Players index page, you may also want to seed the database with a few players to save you some manual typing. Head to db/seeds.rb and update it:

10.times do |n|
  Player.create(name: "Player #{n}",  team: "Dallas Mavericks")
end

Then seed the database from your terminal:

Build the list and card views

Before introducing Kredis to the application, we will begin by building a list/card view toggle that allows users to swap between the two views by reading URL parameters directly in the view.

Since we used the Rails scaffold generator, we already have a simple list view for Players ready on the index page. Let’s start by updating the generated views to be a little easier to process.

Update app/views/players/_player.html.erb like this:

<li class="border border-gray-200 rounded">
  <div href="#" class="block hover:bg-gray-50">
    <div class="flex items-center px-4 py-4 sm:px-6">
      <div class="min-w-0 flex-1 flex items-center">
        <div class="min-w-0 flex-1 px-4 md:grid md:grid-cols-2 md:gap-4">
          <div>
            <p class="text-sm font-medium"><%= player.name %></p>
          </div>
          <div class="hidden md:block">
            <div>
              <p class="text-sm text-gray-900">
                <%= player.team %>
              </p>
            </div>
          </div>
        </div>
      </div>
      <div>
        <p>
          <%= link_to "View", player, class: "text-blue-700 hover:text-blue-500" %>
        </p>
      </div>
    </div>
  </div>
</li>

Just regular ERB and some Tailwind classes for styling. Now update app/views/players/index.html.erb:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Players</h1>
    <%= link_to 'New player', new_player_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <div id="players" class="min-w-full">
    <div>
      <ul role="list" class="space-y-4">
        <%= render @players %>
      </ul>
    </div>
  </div>
</div>

Again, just ERB and Tailwind, nothing fancy here.

Next we will add the card view, starting with a _card partial. Create the new partial from your terminal:

touch app/views/players/_card.html.erb

And then fill in the new _card partial:

<li class="col-span-1 flex shadow-sm rounded-md">
  <div class="flex-1 flex items-center justify-between border-t border-r border-b border-gray-200 bg-white rounded-r-md">
    <div class="flex-1 px-4 py-2 text-sm">
      <p class="text-gray-900 font-medium hover:text-gray-600"><%= player.name %></p>
      <p class="text-gray-500"><%= player.team %></p>
    </div>
    <div class="px-4 py-2">
      <p><%= link_to "View", player, class: "text-blue-700 hover:text-blue-500" %></p>
    </div>
  </div>
</li>

With the card partial created, we can now add a simple toggle to the Players index page to switch between the list view and the card view.

Head to app/views/players/index.html.erb and update it:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Players</h1>
    <%= link_to 'New player', new_player_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <div id="players" class="min-w-full mt-8">
    <% if params[:view] == "card" %>
      <div class="my-4">
        <%= link_to "List view", players_path(view: "list"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
      </div>
      <ul role="list" class="grid grid-cols-1 gap-5 sm:gap-6 sm:grid-cols-2 lg:grid-cols-4">
        <%= render @players %>
      </ul>
    <% else %>
      <div class="my-4">
        <%= link_to "Card view", players_path(view: "card"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
      </div>
        <ul role="list" class="space-y-4">
          <%= render collection: @players, partial: "players/card", as: :player %>
        </ul>
    <% end %>
  </div>
</div>

Here we add a messy but functional if statement that checks the value of params[:view]. When the view param equals card, we render the players as a grid of cards, otherwise the players are rendered as a list. Both of the view also have a link to toggle the index page to the opposite view, with link_to players_path(view: "list"/"card").

This “works” as a starting point. Head to http://localhost:3000/players and click the button to toggle between the views and the page layout changes. However, we can quickly see the limits of this params based approach:

Toggle the index page to from a list to cards
Click on the view link for any player
Click the “Back to players” link on the show page

Instead of the card layout, the Players index page switches back to the list view. What is happening here? The Players index view relies on the presence of a view URL parameter to determine which layout to display. Because params do not persist between requests, the layout of the Players index page will always fall back to the default list view when visiting /players without any URL parameters.

This is where Kredis comes in. Instead of using the url params to set the view of the Players index page, we can use Kredis to persist the user’s view preference between requests so that the index page retains the expected layout.

Let’s see how Kredis works.

Using Kredis to store preferences

Kredis is a suggested gem in Rails 7, which means it is included in the default Gemfile but it is commented out. To install Kredis, first uncomment it in the Gemfile:

- # gem "kredis"
+ gem "kredis"

Then from your terminal:

bundle install
./bin/rails kredis:install

Restart your Rails application after installing the Kredis gem and running the install task to avoid errors about Kredis being undefined.

At this point, you will also need a Redis server running in your development environment. If you do not already have Redis installed and running, Mac users will find this gist helpful. Linux users may find this guide helpful.

With Kredis installed and Redis running in our local environment, we can now use Kredis to store the user’s view preference instead of relying on the presence of URL parameters.

Head to app/controllers/players_controller.rb and update the index action:

def index
  @players = Player.all
  @user_preferences = Kredis.hash('preferences')
  @user_preferences.update(view: params[:view]) if params[:view].present?
end

Here we are using Kredis to fetch a preferences key from Redis, initializing it as a hash and setting the user_preferences instance variable to be a new instance of a Kredis Hash.

Then, when params[:view] is present in the request, we update the preferences hash to store the value of view. update here updates the preferences key in Redis along with updating the user_preferences instance variable.

Because @user_preferences is an instance of a Kredis Hash, we can treat it (mostly) like a regular hash, as demonstrated by a little bit of experimenting in the console:

irb(main):012:0> preferences = Kredis.hash('preferences')
=>
#<Kredis::Types::Hash:0x00007faed43f0f90
...
irb(main):013:0> preferences.keys
  Kredis Proxy (0.3ms)  HKEYS preferences
=> []
irb(main):014:0> preferences.update(view: 'card')
  Kredis Proxy (0.2ms)  HSET preferences [{:view=>"card"}]
=> 1
irb(main):015:0> preferences.keys
  Kredis Proxy (0.3ms)  HKEYS preferences
=> ["view"]
irb(main):016:0> preferences['view']
  Kredis Proxy (0.3ms)  HGET preferences ["view"]
=> "card"
irb(main):017:0> preferences.delete('view')
  Kredis Proxy (0.3ms)  HDEL preferences ["view"]
=> 1
irb(main):018:0> preferences.keys
  Kredis Proxy (0.2ms)  HKEYS preferences
=> []

To use our new persistent Kredis value instead of URL parameters when rendering the index page, head back to app/views/players/index.html.erb and replace the existing if block with the below:

<% if @user_preferences[:view] == "card" %>
  <div class="my-4">
    <%= link_to "List view", players_path(view: "list"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
  </div>
  <ul role="list" class="grid grid-cols-1 gap-5 sm:gap-6 sm:grid-cols-2 lg:grid-cols-4">
    <%= render @players, partial: "players/card", as: :player %>
  </ul>
<% else %>
  <div class="my-4">
    <%= link_to "Card view", players_path(view: "card"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
  </div>
  <ul role="list" class="space-y-4">
    <%= render @players %>
  </ul>
<% end %>

Here we updated the if condition to check @user_preferences instead of params to determine which layout to render.

With that change in place, head back to http://localhost:3000/players and toggle between the list and card views. If all has gone well, toggling should still work. Even better, if you click on a player and then click to return back to the players index page, your list view preference will be retained.

Neat!

Adding a Turbo Frame

Now that we do not need the URL parameter on every request, it also makes sense to think about what actually needs to be updated when the user toggles between the list and card views. The rest of the page will not change — only the list of players will.

Turbo Frames give us the tools to adjust the application to only update the players section of the page when the user toggles the view, making the application feel faster and more responsive to user input.

For our application, Turbo Frames also resolve a subtle problem that you might have encountered while testing Kredis.

Turbo Drive takes a snapshot of every page to speed up applications. In almost all circumstances, this caching is something we just get for free without needing to think about; however, in this case, caching our players index page creates some issues that we need to resolve.

The issue works like this:

Head to http://localhost:3000/players
Toggle the view from list to card
Click on the view link for a player
Click on the link to go back to the players index page
Notice that for a brief moment, the index page renders the list view before replacing it with the card view

This flash of content happens because Turbo Drive caches the index page before navigating from /players to /players?view=card. The next time you visit /players, Drive uses the original, list-view version of /players from the cache to "preview" the index page before updating it with the new, card-view version of the index page rendered from the server.

Turbo Frames resolve this issue because Turbo does not cache a page when navigation is scoped within a Turbo Frame. Turbo Drive’s snapshot caching only occurs when a full-page navigation occurs.

This means that with Turbo Frames users are free to toggle between list and card views on the players index page as often as they like — the content of the index page will not be cached until they navigate away from the index page entirely.

Because the content is not cached until the final navigation, the correct layout of the page gets cached and the "preview" displayed by Turbo on the next visit to the index page matches the final version, eliminating the flash of bad cached content.

Let’s see how this works in practice.

First, update app/views/players/index.html.erb to wrap the list of players in a Turbo Frame:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Players</h1>
    <%= link_to 'New player', new_player_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <%= turbo_frame_tag "players", class: "min-w-full mt-8" do %>
    <% if @user_preferences[:view] == "card" %>
      <div class="my-4">
        <%= link_to "List view", players_path(view: "list"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
      </div>
      <ul role="list" class="grid grid-cols-1 gap-5 sm:gap-6 sm:grid-cols-2 lg:grid-cols-4">
        <%= render @players, partial: "players/card", as: :player %>
      </ul>
    <% else %>
      <div class="my-4">
        <%= link_to "Card view", players_path(view: "card"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
      </div>
        <ul role="list" class="space-y-4">
          <%= render @players %>
        </ul>
    <% end %>
  <% end %>
</div>

Here we removed the “players” div and replaced that div with a <turbo-frame id="players", using the turbo-rails provided turbo_frame_tag helper method.

Now that the list of players is wrapped in a Turbo Frame, links inside of that frame will update the content of that frame instead of updating the entire page.

This means that when the user clicks on the view toggle links, Turbo will extract the content of the players Turbo Frame from the response and use that content to update the players frame while discarding the rest of the content. When a Turbo Frame request is initiated, Rails helpfully renders the response without a layout, saving a (very small amount of) work on the server.

Finish up adding Turbo Frame support by updating the links to view players in both the card and player partials like this:

<%= link_to "View", player, class: "text-blue-700 hover:text-blue-500", data: { turbo_frame: "_top" } %>

The addition of data-turbo-frame="_top" to links wrapped inside of a <turbo-frame> tells Turbo to perform a normal full-page navigation, instead of scoping the navigation within the frame. This ensures that going to players#show still works as expected.

After making these changes, head back to http://localhost:3000/players, toggle the view from list to card (or card to list) and then click to view a player, and finally click back out to the players index page. If all has gone well you will not see any flashing cached content.

Improving our Kredis usage

Our current implementation of Kredis will only work if our application has exactly one user. This is because we are using a static key, preferences, to set the players list layout.

In the real world, we will (hopefully!) have more than one user in our application. Each of our users should be able to store their own view preferences or our view toggle will not be a very useful feature! Let's wrap up this tutorial by looking at how we can use Kredis in ActiveRecord models to store user-specific preferences, making view toggling much more useful.

From your terminal, create a User model:

./bin/rails g model User session:string
./bin/rails db:migrate

And then update app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base
  helper_method :current_user

  def current_user    
    @current_user ||= User.find_or_create_by(session: session.id.to_s)
  end
end

We do not want to build out a whole user authentication system to learn more about Kredis, so here we are faking it by using session.id to find or create a new user in the database and then defining current_user as a helper_method available throughout our application.

In a real application, current_user would be a real, actual, logged in user, but our fake users will be good enough to demonstrate the key concept here.

Our goal is to be able to associate user preferences with a User using Kredis. Our first implementation of Kredis hardcoded a preferences key to store all preferences. Our new implementation will give each User their own unique key through Kredis’ integration with ActiveRecord.

Head to app/models/user.rb and update it like this:

class User < ApplicationRecord
  kredis_hash :preferences
end

This update means that all users will have a unique key/value pair that stores their preferences in Redis. We can access this attribute with user.preferences, which will return an instance of a Kredis::Hash, just like Kredis.hash('preferences') did in our controller.

To use this new preferences attribute, update the PlayersController#index action in app/controllers/players_controller.rb:

def index
  @players = Player.all
  current_user.preferences.update(view: params[:view]) if params[:view].present?
end

Here we use the same update method we used before, this time using current_user.preferences to access a unique hash for the current user.

Then update the players index view to reference the right hash:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Players</h1>
    <%= link_to 'New player', new_player_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <%= turbo_frame_tag "players", class: "min-w-full mt-8" do %>
    <% if current_user.preferences[:view] == "card" %>
      <div class="my-4">
        <%= link_to "List view", players_path(view: "list"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
      </div>
      <ul role="list" class="grid grid-cols-1 gap-5 sm:gap-6 sm:grid-cols-2 lg:grid-cols-4">
        <%= render @players, partial: "players/card", as: :player %>
      </ul>
    <% else %>
      <div class="my-4">
        <%= link_to "Card view", players_path(view: "card"), class: "bg-blue-800 px-4 py-2 text-white hover:bg-blue-600 rounded" %>
      </div>
        <ul role="list" class="space-y-4">
          <%= render @players %>
        </ul>
    <% end %>
  <% end %>
</div>

The if statement now checks current_user.preferences instead of @user_preferences.

To test out these changes, open two separate browsers, toggle the list/card view to different options in each window, and then refresh each window to see that each “user” has their own unique preferences.

With that last change, you have reached the end of this tutorial! Incredible work today.

Wrapping up

Today we learned a little about how to use Kredis to unlock more power from our Redis-enabled Ruby on Rails applications.

Kredis’ tight integration with ActiveRecord gives it a leg up on other tools that are often used to do this type of work — if you have used Rails for a while, you have probably stuffed view preferences, filter and search terms, and other information into the session to persist the information across page turns. Redis is a more resilient and more appropriate tool for storing this type of information, and Kredis makes it simple to use Redis for this type of work in Ruby on Rails applications.

While we used a hash for storing data, Kredis supports a variety of datatypes to suit your needs — explore the repo to see the full list of available types.

One of the more exciting aspects of Kredis is the tools that can be built on top of it — we can build our own simple functionality like the preference storage we created today, but other smart folks are building gems on top of Kredis to enable functionality like presence tracking for application resources or complex, multi-stage forms.

That’s all for today. As always, thanks for reading!

Turbo Rails 101: Building a todo app with Turbo

David Colby — Fri, 11 Feb 2022 17:11:42 +0000

When Rails 7 released in December, Turbo became a default component of all new Ruby on Rails applications. This was an exciting moment for Rails developers that want to use Rails full-stack — especially folks on small teams with limited resources to pour into building and maintaining a React or Vue frontend.

Along with that excitement has come a constant stream of developers trying to learn how Turbo works, and how to integrate it into their Rails applications successfully.

For many, that learning journey has included a lot of roadblocks — Turbo requires some changes to how you structure applications and the official documentation is not yet as detailed as it could be. The good news is, most folks hit the same roadblocks early on their journey, which means we can help folks faster by addressing the common points of confusion.

In particular, there is confusion about how to use Turbo Frames and Turbo Streams together, and confusion about how Turbo Streams work.

Today, we are going to build a simple todo list application, powered entirely by Turbo. While building, we will take a few detours to look more deeply at a few common Turbo behaviors, and we will directly address two of the most common misconceptions that I see from folks who are brand new to using Turbo in their Rails applications.

When we are finished, our application will work like this:

This tutorial is written for Rails developers who are brand new to Turbo. The content is very much Turbo 101 and may not be useful if you are already comfortable working with Turbo Frames and Turbo Streams. This article also assumes comfort with writing standard CRUD applications in Rails — if you are have never used Rails before, this is not the right place to start!

As usual, you can find the complete code for our demo application on Github.

Let’s start building!

Application setup

We will start with a brand new Rails 7 application which comes with Turbo out of the box.

Generate a new Rails application with Tailwind CSS for styling. From your terminal:

rails new turbo-todo --css=tailwind
cd turbo-todo

And then scaffold up a Todo resource. From your terminal again:

rails g scaffold Todo name:string status:integer

Update migration to set default value for status:

class CreateTodos < ActiveRecord::Migration[7.0]
  def change
    create_table :todos do |t|
      t.string :name
      t.integer :status, default: 0

      t.timestamps
    end
  end
end

Finally, create and migrate the database:

Create new todos with Turbo Streams

The Rails scaffold generator provides a fully functional implementation of todos out of the box. If you start up the Rails app and head to /todos you can create, edit, and delete todos to your heart’s content, but every request will initiate a full page turn. Not very exciting.

Our goal in this section is to update the existing todo scaffold to use Turbo Streams to insert newly created todos into the DOM without a full page turn or any custom JavaScript.

Start by replacing the content of the index view, app/views/todos/index.html.erb, with the following:

<div class="mx-auto w-1/2">
  <h2 class="text-2xl text-gray-900">
    Your todos
  </h2>
  <div class="w-full max-w-2xl bg-gray-100 py-8 px-4 border border-gray-200 rounded shadow-sm">
    <div class="py-2 px-4">
      <%= render "form", todo: Todo.new %>
    </div>
    <ul id="todos">
      <%= render @todos %>
    </ul>
  </div>
</div>

Here, we updated the page layout so it looks a little nicer and inserted the new todo form directly on to the page. Users will use this form to add new todos, and existing todos will be rendered in the <ul> below the form.

Note that the <ul> has an id of todos. Turbo Streams target elements in the DOM by id, and the todos id will be used to insert newly created todos into the DOM.

Update app/views/todos/_todo.html.erb to render each todo properly inside of the <ul>:

<li class="py-2 px-4 border-b border-gray-300">
  <%= todo.name %>
</li>

The form partial we render in the index view needs a few adjustments too. In app/views/todos/_form.html.erb:

<%= form_with(model: todo, id: "#{dom_id(todo)}_form") do |form| %>
  <% if todo.errors.any? %>
    <div id="error_explanation" class="bg-red-50 text-red-500 px-3 py-2 font-medium rounded-lg mt-3">
      <h2><%= pluralize(todo.errors.count, "error") %> prohibited this todo from being saved:</h2>

      <ul>
        <% todo.errors.each do |error| %>
          <li><%= error.full_message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>
  <div class="flex items-stretch flex-grow">
    <%= form.label :name, class: "sr-only" %>
    <%= form.text_field :name, class: "block w-full rounded-none rounded-l-md sm:text-sm border-gray-300", placeholder: "Add a new todo..." %>
    <%= form.submit class: "-ml-px relative px-4 py-2 border border-blue-600 text-sm font-medium rounded-r-md text-white bg-blue-600 hover:bg-blue-700" %>
  </div>
<% end %>

Note the addition of an id to the <form>, using the dom_id of the todo passed to the partial, which will be used to target Turbo Stream updates.

To use these new ids to update the DOM, we need to tell our controller to render a Turbo Stream when the form is submitted.

To do this, head to the TodosController and update the create action:

def create
  @todo = Todo.new(todo_params)

  respond_to do |format|
    if @todo.save
      format.turbo_stream
      format.html { redirect_to todo_url(@todo), notice: "Todo was successfully created." }
    else
      format.html { render :new, status: :unprocessable_entity }
    end
  end
end

The change here is the addition of format.turbo_stream to the happy path in the action. format.turbo_stream tells Rails that when a Turbo Stream request is sent to the create action, respond with a matching create.turbo_stream.erb file.

If you are a long-time Rails developer, this will feel very similar to responding with js.erb files in response to ajax requests.

In order for this to work, we need to create the create.turbo_stream.erb file, otherwise you will get an error about a missing template.

From your terminal:

touch app/views/todos/create.turbo_stream.erb

And then fill that new file in:

<%= turbo_stream.prepend "todos" do %>
  <%= render "todo", todo: @todo %>
<% end %>
<%= turbo_stream.replace "#{dom_id(Todo.new)}_form" do %>
  <%= render "form", todo: Todo.new %>
<% end %>

Our first look at a Turbo Stream! In create.turbo_stream.erb we render two <turbo-stream> elements.

The first prepends the newly created todo to the list of todos, targeting the <ul> with the id of todos. The second replaces the todo form with a fresh copy of the form, allowing us to clear the todo form after each successful submission.

At this point, you can start up your Rails application with bin/dev. Head to localhost:3000/todos, create a couple of todos and see that they automatically append to the list of todos. Magic.

Let’s pause here and review what is happening in a little more detail. Each time the user submits the new todo form, the request sent to the server includes an Accept header that identifies the request as a Turbo Stream request:

text/vnd.turbo-stream.html, text/html, application/xhtml+xml

Turbo sets this header automatically on all POST, PUT, PATCH, DELETE form submissions, with no intervention required from the developer.

turbo-rails registers a turbo_stream Mime type to enable responding to inbound Turbo Stream form submissions with turbo_stream content. We see this in action in the TodosController:

def create
  respond_to do |format|
    format.turbo_stream
  end
end

When calling format.turbo_stream without passing a block, Rails conventions expect that a file that matches the action and Mime type exists — in our case, create.turbo_stream.erb.

In create.turbo_stream.erb, we render <turbo-stream> elements using the turbo_stream helper. Rails renders the create.turbo_stream view to HTML and sends that HTML back to the frontend:

<turbo-stream action="prepend" target="todos">
  <template>
    <li class="py-2 px-4 border-b border-gray-300">
      A new todo
    </li>
  </template>
</turbo-stream>

<turbo-stream action="replace" target="new_todo_form">
  <template>
    <form id="new_todo_form" action="/todos" accept-charset="UTF-8" method="post"><input type="hidden" name="authenticity_token" value="TmpPYfxQOln1t3jmigbzZ49ciBWjivGEjp_nJUWJMeUJZSoeA8dvbkLeD6kLkmHZx-zc8kOzcqu69tWGYASlpQ" autocomplete="off" />
      <div class="flex items-stretch flex-grow">
        <label class="sr-only" for="todo_name">Name</label>
        <input class="block w-full rounded-none rounded-l-md sm:text-sm border-gray-300" placeholder="Add a new todo..." type="text" name="todo[name]" id="todo_name" />
        <input type="submit" name="commit" value="Create Todo" class="-ml-px relative px-4 py-2 border border-blue-600 text-sm font-medium rounded-r-md text-white bg-blue-600 hover:bg-blue-700" data-disable-with="Create Todo" />
      </div>
    </form>
  </template>
</turbo-stream>

Turbo extracts the Turbo Stream elements from the HTML and uses each element’s action and content to update the DOM.

Now we understand a bit about what is happening when our Turbo-powered from is submitted, which also gives us the knowledge to knock out a few common misconceptions about Turbo.

Turbo Streams can target any element, not just Turbo Frames

First, many new Turbo developers think that Turbo Streams can only target Turbo Frames. This misconception causes them to run into issues nesting their forms within an unnecessary Turbo Frame or to end up with invalid HTML by wrapping <tr> or <li> elements in <turbo-frame> elements.

Issues caused by this misconception come up almost daily on the Rails Internet and Turbo Streams can be very difficult to work with while laboring under this misconception. Although the documentation never links Turbo Frames and Turbo Streams in this way, the issue persists.

So, let’s get very clear here: Turbo Streams target elements in the DOM by id (or class, less commonly). Any element with an id can be targeted by a Turbo Stream, not just Turbo Frame elements.

Turbo Streams do not require WebSockets

Turbo Streams have gotten a lot of attention because they can be used with WebSockets to proactively send updates to many users at once outside of the standard request/response cycle.

With turbo-rails, developers can easily broadcast updates from models and background jobs to send <turbo-stream> snippets over WebSockets with ActionCable.

These types of WebSockets-powered Turbo Stream broadcasts are great — but as you saw in the TodosController, you can also just render Turbo Stream tags in response to a request from a browser. You can make great use of Turbo Streams without WebSockets.

Now that we have gotten way down into the weeds of Turbo Streams, let’s zoom back out a bit and take our first look at Turbo Frames.

Editing existing todos

Users will edit their todos by clicking on the name of the todo. When they click on the name, the edit form for that todo will render in place of the todo in the list, like this:

To build this functionality, we will use a Turbo Frame to scope navigation to the piece of the page we want to update. Start by updating the existing todo partial like this:

<li id="<%= "#{dom_id(todo)}_container" %>" class="py-2 px-4 border-b border-gray-300">
  <%= turbo_frame_tag dom_id(todo) do %>
    <%= link_to todo.name, edit_todo_path(todo) %>
  <% end %>
</li>

Here, we added a unique id to each <li>. Nested within the <li>, we added a <turbo-frame> using the turbo-rails provided turbo_frame_tag helper method.

Within the Turbo Frame is a link_to pointing to the edit action in the TodosController. Because the link is within the Turbo Frame, Turbo will expect the server to return a Turbo Frame with a matching id. Turbo will extract the matching Turbo Frame from the response HTML and use it to replace the original content of the frame.

In our case, that means when the user clicks on the todo’s name, edit.html.erb will render an edit form and that form will replace the link to the edit page.

Let’s see this in action. Update app/views/edit.html.erb:

<%= turbo_frame_tag dom_id(@todo) do %>
  <%= render "form", todo: @todo %>
<% end %>

The turbo_frame_tag has an id that matches the turbo_frame_tag in the todo partial.

With that change in place, refresh the todos index page and click on the name of a todo. If all has gone well, you will see that the edit form replaces that todo in the list. If you submit the form, you will see that you get redirected to the show page of the todo you edited — not quite there yet!

We will fix this issue with another Turbo Stream rendered from the server, this time for TodosController#update.

From your terminal:

touch app/views/todos/update.turbo_stream.erb

Update the new update.turbo_stream.erb view like this:

<%= turbo_stream.replace "#{dom_id(@todo)}_container" do %>
  <%= render "todo", todo: @todo %>
<% end %>

We are using a Turbo Stream replace action again. This time the Turbo Stream action replaces the content of the <li> wrapping the todo with the content of the todo partial. Because the edit form is replaced by the updated Todo, we do not need to reset the edit form like we did the new form in create.turbo_stream.erb.

Update the TodosController to respond to Turbo Stream requests:

def update
  respond_to do |format|
    if @todo.update(todo_params)
      format.turbo_stream
      format.html { redirect_to todo_url(@todo), notice: "Todo was successfully updated." }
      format.json { render :show, status: :ok, location: @todo }
    else
      format.html { render :edit, status: :unprocessable_entity }
      format.json { render json: @todo.errors, status: :unprocessable_entity }
    end
  end
end

Now when the edit form is submitted successfully the edit form is replaced with an updated version of the edited todo’s partial.

At this point, we can create and edit todos without a full page turn but you may have noticed that we are not using Turbo Streams to handle invalid form submissions. The else path in the create and update actions is missing a turbo_stream response. We will fix that in the next section.

Handling form errors

To demonstrate handling form errors, we need to first add a validation to the Todo model so that we can send invalid form submissions to the server. In app/models/todo.rb:

validates_presence_of :name

Form submissions with a blank name will fail to save, letting us test out error handling with Turbo Streams.

Head back to the TodosController and update the create and update actions:

def create
  @todo = Todo.new(todo_params)

  respond_to do |format|
    if @todo.save
      format.turbo_stream
      format.html { redirect_to todo_url(@todo), notice: "Todo was successfully created." }
    else
      format.turbo_stream { render turbo_stream: turbo_stream.replace("#{helpers.dom_id(@todo)}_form", partial: "form", locals: { todo: @todo }) }
      format.html { render :new, status: :unprocessable_entity }
    end
  end
end

def update
  respond_to do |format|
    if @todo.update(todo_params)
      format.turbo_stream
      format.html { redirect_to todo_url(@todo), notice: "Todo was successfully updated." }
      format.json { render :show, status: :ok, location: @todo }
    else
      format.turbo_stream { render turbo_stream: turbo_stream.replace("#{helpers.dom_id(@todo)}_form", partial: "form", locals: { todo: @todo }) }
      format.html { render :edit, status: :unprocessable_entity }
      format.json { render json: @todo.errors, status: :unprocessable_entity }
    end
  end
end

When the todo fails to save, we render a turbo_stream directly from the controller, replacing the content of the form with an updated version of the form so that errors are displayed to the user.

This method of rendering Turbo Streams inline in the controller is an alternative to creating views like create.turbo_stream.erb — either approach will work. In practice, it tends to be easier to manage complex Turbo Stream responses with dedicated views while rendering simple responses inline works fine for single stream responses.

Deleting todos

Next up, we will add the ability to delete todos without a page turn by using another Turbo Stream rendered from the controller.

Start by updating the todo partial to add a delete button:

<li id="<%= "#{dom_id(todo)}_container" %>" class="py-2 px-4 border-b border-gray-300">
  <%= turbo_frame_tag dom_id(todo) do %>
    <div class="flex justify-between items-center space-x-2">
      <%= link_to todo.name, edit_todo_path(todo) %>

      <%= button_to todo_path(todo), class: "bg-red-600 px-4 py-2 rounded hover:bg-red-700", method: :delete do %>
        <span class="sr-only">Delete</span>
        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-white" viewBox="0 0 20 20" fill="currentColor" title="Delete todo">
          <path fill-rule="evenodd" d="M9 2a1 1 0 00-.894.553L7.382 4H4a1 1 0 000 2v10a2 2 0 002 2h8a2 2 0 002-2V6a1 1 0 100-2h-3.382l-.724-1.447A1 1 0 0011 2H9zM7 8a1 1 0 012 0v6a1 1 0 11-2 0V8zm5-1a1 1 0 00-1 1v6a1 1 0 102 0V8a1 1 0 00-1-1z" clip-rule="evenodd" />
        </svg>
      <% end %>
    </div>
  <% end %>
</li>

Note the method: :delete on the button, which ensures the button hits the destroy action on the controller. The svg icon here is from Heroicons — feel free to just make the button say “Delete” if you like, that will work fine too.

In the TodosController, update the destroy action:

def destroy
  @todo.destroy

  respond_to do |format|
    format.turbo_stream { render turbo_stream: turbo_stream.remove("#{helpers.dom_id(@todo)}_container") }
    format.html { redirect_to todos_url, notice: "Todo was successfully destroyed." }
    format.json { head :no_content }
  end
end

This inline turbo_stream uses the Turbo Stream remove action to remove the target element from the DOM entirely.

Refresh the index page, click the delete button on a todo and see that the todo is removed from the DOM without a full page turn.

Mark todos as complete

A todo list is not very helpful if todos cannot be marked as complete. In this section, we will add a button to toggle todos complete and incomplete, relying as usual on Turbo Streams to update the DOM for us.

To begin, let’s define a simple status enum in the Todo model:

enum status: {
  incomplete: 0,
  complete: 1
}

Back to app/views/todos/_todo.html.erb:

<li id="<%= "#{dom_id(todo)}_container" %>" class="py-2 px-4 border-b border-gray-300">
  <%= turbo_frame_tag dom_id(todo) do %>
    <div class="flex justify-between items-center space-x-2">
      <%= link_to todo.name, edit_todo_path(todo), class: todo.complete? ? 'line-through' : '' %>

      <div class="flex justify-end space-x-3">
        <% if todo.complete? %>
          <%= button_to todo_path(todo, todo: { status: 'incomplete' }), class: "bg-green-600 px-4 py-2 rounded hover:bg-green-700", method: :patch do %>
            <span class="sr-only">Mark as incomplete</span>
            <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-white" viewBox="0 0 20 20" fill="currentColor">
              <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
            </svg>
          <% end %>
        <% else %>
          <%= button_to todo_path(todo, todo: { status: 'complete' }), class: "bg-gray-400 px-4 py-2 rounded hover:bg-green-700", method: :patch do %>
            <span class="sr-only">Mark as incomplete</span>
            <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-white" viewBox="0 0 20 20" fill="currentColor">
              <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
            </svg>
          <% end %>
        <% end %>

        <%= button_to todo_path(todo), class: "bg-red-600 px-4 py-2 rounded hover:bg-red-700", method: :delete do %>
          <span class="sr-only">Delete</span>
          <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-white" viewBox="0 0 20 20" fill="currentColor" title="Delete todo">
            <path fill-rule="evenodd" d="M9 2a1 1 0 00-.894.553L7.382 4H4a1 1 0 000 2v10a2 2 0 002 2h8a2 2 0 002-2V6a1 1 0 100-2h-3.382l-.724-1.447A1 1 0 0011 2H9zM7 8a1 1 0 012 0v6a1 1 0 11-2 0V8zm5-1a1 1 0 00-1 1v6a1 1 0 102 0V8a1 1 0 00-1-1z" clip-rule="evenodd" />
          </svg>
        <% end %>
      </div>
    </div>
  <% end %>
</li>

There’s a lot here, let’s cut through the noise to highlight the important functional pieces.

The todo edit link gets struck through when the todo is complete:

<%= link_to todo.name, edit_todo_path(todo), class: todo.complete? ? 'line-through' : '' %>

If the todo is complete, we render button_to to mark the todo as incomplete. Incomplete todos get a button_to to mark the todo as complete.

<% if todo.complete? %>
  <%= button_to todo_path(todo, todo: { status: 'incomplete' }), class: "bg-green-600 px-4 py-2 rounded hover:bg-green-700", method: :patch do %>
<% else %>
  <%= button_to todo_path(todo, todo: { status: 'complete' }), class: "bg-gray-400 px-4 py-2 rounded hover:bg-green-700", method: :patch do %>
<% end %>

In either case the patch request goes to TodosController#update as a Turbo Stream request, and the existing update.turbo_stream.erb view is rendered.

If this were a real application, we would pull these buttons out into helper methods or into a view component, but for our purposes, we can live with a messy partial.

Complete/incomplete todos in separate tabs

Now that users can mark todos as complete, it would be nice to not have to see completed todos all of the time. We will finish up our Turbo-powered todo application by adding a tabbed interface to the todos index page, allowing users to toggle between incomplete and complete todos.

Get started by adding simple filtering logic to the index action in the TodosController:

def index
  @todos = Todo.where(status: params[:status].presence || 'incomplete')
end

Then update app/views/todos/index.html.erb:

<div class="mx-auto w-1/2">
  <h2 class="text-2xl text-gray-900">
    Your todos
  </h2>
  <%= turbo_frame_tag "todos-container", class: "block max-w-2xl w-full bg-gray-100 py-8 px-4 border border-gray-200 rounded shadow-sm" do %>
    <div class="border-b border-gray-200 w-full">
      <ul class="flex space-x-2 justify-center">
        <li>
          <%= link_to "Incomplete",
            todos_path(status: "incomplete"),
            class: "inline-block py-4 px-4 text-sm font-medium text-center text-gray-500 border-b-2 border-transparent hover:text-gray-600 hover:border-gray-300" 
          %>
        <li>
          <%= link_to "Complete",
            todos_path(status: "complete"),
            class: "inline-block py-4 px-4 text-sm font-medium text-center text-gray-500 border-b-2 border-transparent hover:text-gray-600 hover:border-gray-300"
          %>
        </li>
    </ul>
    </div>
    <% unless params[:status] == "complete" %>
      <div class="py-2 px-4">
        <%= render "form", todo: Todo.new %>
      </div>
    <% end %>
    <ul id="todos">
      <%= render @todos %>
    </ul>
  <% end %>
</div>

The index view now wraps the todo content in a todos-container <turbo-frame>. As with the edit links for each individual todo, this Turbo Frame will scope navigation within the frame, allowing the list of Todos to be updated without changing the content on the rest of the page.

Inside of the new todos-container frame, we added links to view incomplete and complete todos. Logic to hide the new todo form when viewing complete todos was also added, since newly created todos are always incomplete.

Because the links to view incomplete and complete todos are within the todos-container Turbo Frame, each time those links are clicked, Turbo will replace the content of the todos-container with updated content from the server.

Conveniently, we do not need to change anything about the index action to render Turbo Frame content. Even though the entire page re-renders when the index action is called, Turbo will extract the todos-container frame from the response and discard the rest. If that small bit of inefficiency bothers you, it is possible to be more efficient.

With this change in place, we have a slight problem with the status toggle behavior. Right now, when the user marks a todo as complete, the todo is updated but it stays on the list. Instead, when a todo’s status is updated, we would like to remove it from the list.

Implementing this functionality will require adding a new, non-RESTful action to the TodosController. We will call this new action change_status. Start in the TodosController:

before_action :set_todo, only: %i[ show edit update destroy change_status ]

def change_status
  @todo.update(status: todo_params[:status])
  respond_to do |format|
    format.turbo_stream { render turbo_stream: turbo_stream.remove("#{helpers.dom_id(@todo)}_container") }
    format.html { redirect_to todos_path, notice: "Updated todo status." }
  end
end

Here, we updated the set_todo before_action to set the @todo instance variable when change_status is called and we defined change_status.

change_status updates the status of the given todo and then removes that that todo from the DOM. This will work for marking todos as complete and for marking them as incomplete — either way, we just target the id of the <li> and use a Turbo Stream remove action.

We added this new action because the update action we used in the first implementation of this feature use a replace Turbo Stream action, instead of removing the todo from the DOM. We could have hacked the update action to handle status changes differently or created a whole new TodoStatusChangesController for this, but there’s no reason to do that in our learning application.

Update config/routes.rb to add the new route to the application:

resources :todos do
  patch :change_status, on: :member
end

And finally, update the todo partial one last time to use the change_status_todo_path on the status toggle buttons:

<% if todo.complete? %>
  <%= button_to change_status_todo_path(todo, todo: { status: 'incomplete' }), class: "bg-green-600 px-4 py-2 rounded hover:bg-green-700", method: :patch do %>
    <span class="sr-only">Mark as incomplete</span>
    <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-white" viewBox="0 0 20 20" fill="currentColor">
      <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
    </svg>
  <% end %>
<% else %>
  <%= button_to change_status_todo_path(todo, todo: { status: 'complete' }), class: "bg-gray-400 px-4 py-2 rounded hover:bg-green-700", method: :patch do %>
    <span class="sr-only">Mark as complete</span>
    <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-white" viewBox="0 0 20 20" fill="currentColor">
      <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
    </svg>
  <% end %>
<% end %>

With that last change in place, you can refresh the page and see that todos are now grouped into tabs. Toggle the status on a few todos and see that they are removed from the list of todos. Change tabs and see that the todo list updates:

Our application is so small that there’s no real way to tell that changing tabs is only updating the content of the todos-container Turbo Frame, right? It could just be updating the whole page and we would never be able to tell. A quick way to test the Turbo Frame out (and to see why partial page updates can be so useful) is to add a dummy input to the page, outside of the todos-container frame:

Neat!

Degrading gracefully

Throughout this application, we use respond_to blocks to render responses to Turbo Stream requests. The nice thing about this approach is that we always have a format.html back up ready to go if a user does not have JavaScript enabled in their browser.

Because we constructed our application in this way, the application remains fully functional even when JavaScript is disabled. The partial page updates powered by Turbo give way to regular full page turns. Turbo applications, constructed thoughtfully, tend to rely less on JavaScript to function, making it easier to build applications that can gracefully fall back to normal, server rendered HTML and full page turns.

Depending on your application’s audience, this may not be a top priority, but Turbo-powered applications give you a solid base to build from if your application needs to serve JavaScript-free users.

Wrapping up

Today we built a Turbo-powered todo application, using Turbo Streams and Turbo Frames to make fast, efficient page updates in response to user actions.

This simple application served as a base to explore the basics of Turbo Streams and Turbo Frames and gave us a chance to debunk a few common misconceptions about Turbo Streams in the process.

As you move forward in your Turbo journey, remember that Turbo Streams are for responding to form submissions. Streams give you the tools to update one or many elements after a form submission. You can render Turbo Streams inline in a controller, or from views.

Turbo Frames are for scoping GET requests to a single piece of the page. Use Turbo Frames to add tabbed content to a page, to power search and filter interfaces, or for inline editing like we saw today. Turbo Frames always replace the entire content of the target frame, and only one frame can be updated per GET request.

If you need more sophisticated update behavior (like appending items) or you need to update multiple elements at once, you cannot (easily) use a Turbo Frame.

In this tutorial, we looked at basic use cases for Streams and Frames; however, we only just scratched the surface of what you can do with Turbo.

To continue learning, a thorough review of the Turbo reference documentation is a good starting point. In particular, familiarizing yourself with the events Turbo emits is important for more advanced use cases. Understanding Turbo Frame options is also important — functionality like eager and lazy loaded frames, breaking out of frames, and targeting frames from the outside all help unlock powerful Turbo Frame-powered experiences.

In addition to the Turbo documentation, you might find my more in-depth explorations of using Turbo Streams and Turbo Frames in Rails useful.

For a much deeper dive into building a real application with Turbo, Alexandre Ruban’s (in-progress) Hotrails course is a great resource.

That’s all for today. As always, thanks for reading!

Pagination and infinite scrolling with Rails and the Hotwire stack

David Colby — Fri, 04 Feb 2022 22:24:28 +0000

Nearly every web application will eventually need to add pagination to improve page load times and allow users to process information in a more consumable way — you don’t want to load 1,000 records in one request!

Today, we are going to use the Hotwire stack (Turbo and Stimulus) to implement pagination in a Ruby on Rails application. We will implement pagination in three different ways, to give ourselves a chance to explore Turbo Frames, Turbo Streams, and Stimulus.

This article was inspired by a conversation on the StimulusReflex discord and the great article by Dale Zak published as a result of that conversation.

In Dale’s article, a purpose-built Stimulus controller is used to respond to a GET request with a Turbo Stream template. After reading that article, I decided to explore another method for achieving the same result, which is what we will tackle today.

In the article, we will start with a simple Rails 7 application, build standard pagination with Pagy, and then layer on three different implementations of Turbo-powered pagination:

Pagination with Previous and Next page buttons
Manual “infinite scroll” with a load more button
Automatic infinite scroll

When we are finished, the infinite scroll version will look like this:

Before we begin, this article assumes that you are comfortable with Ruby on Rails and you have had a bit of exposure to Turbo and Stimulus. The techniques described in this article will work without Ruby on Rails, but the code will be easiest to follow if you are comfortable developing simple Ruby on Rails applications.

You can find the complete code for this tutorial on Github, and you can try out a “production” version of the application on Heroku.

Let’s get started!

Application setup

We will work from a new Rails 7 application, using importmap-rails to manage JavaScript and Tailwind for styling.

Create a new Rails 7 application from your terminal:

rails new turbo-pagination --css=tailwind
cd turbo-pagination

To demonstrate pagination, we will create a simple Widget resource. From your terminal again, use the built-in scaffold generator:

rails g scaffold Widget name:string
rails db:migrate

Because we are using Tailwind via the tailwindcss-rails gem, the scaffold generator applies some basic Tailwind styling to generated views, so we have nice looking Widget pages right out of the box.

In order to test pagination as we work, we will need some Widgets in the database. Open your rails console with rails c and add test data to the Widgets table:

50.times do |n|
  Widget.create(name: "Widget ##{n}")
end

Pagination the old fashioned way

We are going to start by implementing pagination with standard Rails techniques. Each time a user requests a new page, we will load the new page with a full page turn, no Turbo required. Once pagination is working with full-page turns, we will add in Turbo to enhance the experience.

In our application, we will use Pagy to implement pagination. Let’s install Pagy now, following along with the Pagy quick start guide.

From your terminal, add pagy to your Gemfile:

bundle add pagy

Add Pagy’s backend to app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base
  include Pagy::Backend
end

Add Pagy’s frontend helpers to app/helpers/application_helper.rb:

module ApplicationHelper
  include Pagy::Frontend
end

With Pagy installed and ready to use across the application, update app/controllers/widgets_controller.rb to paginate records on the index page:

def index
  @pagy, @widgets = pagy(Widget.all, items: 10)
end

And then finish up our traditional pagination implementation by adding a simple pager UI to app/views/widgets/index.html.erb:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Widgets</h1>
    <%= link_to 'New widget', new_widget_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <div id="widgets" class="min-w-full">
    <%= render @widgets %>
  </div>
  <div id="pager" class="min-w-full my-8 flex justify-between">
    <div>
      <% if @pagy.prev %>
        <%= link_to "< Previous page", widgets_path(page: @pagy.prev), class: "rounded py-3 px-5 bg-gray-600 text-white block hover:bg-gray-800" %>
      <% end %>
    </div>
    <div class="text-right">
      <% if @pagy.next %>
        <%= link_to "Next page >", widgets_path(page: @pagy.next), class: "rounded py-3 px-5 bg-gray-600 text-white block hover:bg-gray-800" %>
      <% end %>
    </div>
  </div>
</div>

Here, we added the pager div and its contents, with a next and previous page buttons that render when a page exists to navigate to. The prev and next methods used on the links are supplied by pagy.

With this change in place, boot up the rails application with bin/dev and head to http://localhost:3000/widgets and see that widgets are paginated at 10 items per page. Click the next and previous links to move between pages as desired. Notice that each time a paging button is clicked, a full page turn is initiated and the entire content of the page is replaced.

In the next section, we will adjust our paging functionality to update only the widgets list and the pagination buttons, instead of performing a full-page turn on each request.

Navigate pages with Turbo

In this section, we will use a Turbo Frame to update the content of the widgets area with the new page data. Turbo Frames allow us to scope navigation to specific part of the page instead of replacing the entire page with each request.

Scoped navigation with Turbo Frames speeds up requests and allows us to build UIs that feel modern and fast, while continuing to use server-rendered HTML for each request.

To begin, we will wrap the widgets list and the pagination controls in a Turbo Frame. In app/views/widgets/index.html.erb:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Widgets</h1>
    <%= link_to 'New widget', new_widget_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <%= turbo_frame_tag "widgets", class: "min-w-full" do %>
    <%= render @widgets %>
    <%= render "pager", pagy: @pagy %>
  <% end %>
</div>

Here, we replaced the widgets div with a turbo_frame_tag, and moved the pager into that Turbo Frame.

This change means that all link clicks within the widgets Turbo Frame will now expect to receive a matching turbo_frame response from the server. Turbo will then replace the content of that frame with the content supplied by the server, leaving the rest of the page content untouched.

Before this will work, we need to add the pager partial and move the pagination controls into that partial. We don’t technically need to use a partial to render the pagination controls, but it helps keep the index page readable.

From your terminal:

touch app/views/widgets/_pager.html.erb

And then move the paging controls into the new pager partial:

<div id="pager" class="min-w-full my-8 flex justify-between">
  <div>
    <% if pagy.prev %>
      <%= link_to(
        "< Previous page",
        widgets_path(page: pagy.prev),
        class: "rounded py-3 px-5 bg-gray-600 text-white block hover:bg-gray-800",
        data: {
          turbo_action: "advance"
        }
      ) %>
    <% end %>
  </div>
  <div class="text-right">
    <% if pagy.next %>
      <%= link_to(
        "Next page >",
        widgets_path(page: pagy.next),
        class: "rounded py-3 px-5 bg-gray-600 text-white block hover:bg-gray-800",
        data: {
          turbo_action: "advance"
        }
      ) %>
    <% end %>
  </div>
</div>

The content here is nearly identical to what was previously in the index page. The only change is the addition of a new data-turbo-action data attribute on each link.

By default, when navigating within a Turbo Frame, the page URL does not change. Normally, this is correct behavior navigation within a Turbo Frame, but in our case it is not.

When a user moves from page one to page two, they expect to be able to refresh the page and stay on page two and to be able to use the back button in their browser to get back to page one.

The advance value for the data-turbo-action attribute tells Turbo to update the current URL and insert the previous page URL into the browser’s history, retaining the intuitive forward, back, and refresh behavior users expect.

At this point, refresh /widgets and see that clicking the Previous and Next page buttons correctly updates the content of the widgets frame. When you do this, you will notice one issue — navigating between pages does not update the user’s scroll position. They have to manually scroll back up to the top of the list to see the results.

We can fix this issue by updating the widgets Turbo Frame in the widgets index view:

<%= turbo_frame_tag "widgets", class: "min-w-full", autoscroll: "true" do %>

The autoscroll attribute tells Turbo to scroll the frame into view when the frame is loaded, automatically scrolling us back up to the top of the frame when a new page is loaded.

Nice work so far! We now have standard pagination implemented, powered by Turbo Frames. In the next section, we’ll transition to a manual version of an infinite scroll experience.

Manual “infinite scroll”

The first version of “infinite scroll” in our application will replace the Next and Previous pagination controls with a single load more button. When the user clicks this button, we will fetch the next page of widgets from the server, append them to the existing list of widgets, and update the load more button to prepare to fetch the next set of records.

The major functional change is that instead of replacing the content of the widgets list with entirely new content, we need to keep the current widgets in the list and add the new widgets to the end of the list.

This change will introduce us to a limitation of Turbo Frames. Today, navigation within a Turbo Frame always replaces the entire content of the Frame with new content. There is no concept of appending content using Turbo Frames — its replace or nothing.

This means that to implement an infinite scroll experience, we need to reach for Turbo Streams. In contrast to Turbo Frames, which always replace the target content, Turbo Streams can replace, remove, append, and prepend content as desired.

Our goal is to use the pagination controls to retrieve new widgets from the server and then append those widgets to the existing list with Turbo Streams. When we are finished, our server will render turbo-stream elements as HTML, which Turbo will use to update the widgets list and the pagination controls without touching the rest of the page.

To complicate matters a bit, Turbo expects Turbo Streams to be used with non-GET requests (like form submissions). There is no built-in way to render a Turbo Stream in response to a GET request, like the requests generated by clicks on our pagination controls.

One way to work around this is described in Dale’s article. In it, a Stimulus controller and request.js are used to insert a Turbo Stream header into GET requests, getting Turbo to see the request as a Turbo Stream request despite not originating from a form submission.

The approach is Dale's article is a completely valid way to solve the problem and it works quite well. However, we are going to use a different method to reach the same destination. Our approach will use a not-obvious but built-in Turbo behavior to get a Turbo Stream response without modifying headers.

Whew. Let’s look at some code.

To start, we need an empty Turbo Frame. Update app/views/widgets/index.html.erb like this:

<div class="w-full">
  <% if notice.present? %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-500 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex justify-between items-center">
    <h1 class="font-bold text-4xl">Widgets</h1>
    <%= link_to 'New widget', new_widget_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  </div>

  <%= turbo_frame_tag "page_handler" %>
  <div id="widgets" class="min-w-full">
    <%= render @widgets %>
  </div>
  <%= render "pager", pagy: @pagy %>
</div>

Here, we added a page_handler Turbo Frame with no content inside and we removed the widgets Turbo Frame, which we no longer need.

This empty page_handler frame will be the messenger that sneaks our Turbo Stream content in from the server, no header modification required.

To see this in action, update the pager partial to remove the old pagination controls and replace them with a single load more link:

<div id="pager" class="min-w-full my-8 flex justify-center">
  <div>
    <% if pagy.next %>
      <%= link_to(
        "Load more widgets",
        widgets_path(page: pagy.next),
        class: "rounded py-3 px-5 bg-gray-600 text-white block hover:bg-gray-800",
        data: {
          turbo_frame: "page_handler"
        }
      ) %>
    <% end %>
  </div>
</div>

Notice that the load more link is targeting the page_handler Turbo Frame, informing Turbo that clicks on that link should replace the content of the page_handler frame, instead of navigating the entire page. Because the load more link is not nested within the page_handler frame, we need this attribute to target that frame.

Now we have pagination controls targeting an empty Turbo Frame, but clicking on the link will just re-render app/views/widgets/index.html.erb with an empty page_handler frame. That’s not very useful.

To make this work, we need to update our controller to enable turbo_frame variants, so that we can render different content from the index action in response to a Turbo Frame request.

In app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base
  include Pagy::Backend

  before_action :turbo_frame_request_variant

  private

  def turbo_frame_request_variant
    request.variant = :turbo_frame if turbo_frame_request?
  end
end

Here we are using a turbo-rails method, turbo_frame_request?, to identify inbound Turbo Frame requests. When the inbound request is a Turbo Frame, we tell our controller to respond with a turbo_frame variant instead of the normal html.erb content.

To see this in action, create the new Turbo Frame variant for the index action. From your terminal:

touch app/views/widgets/index.html+turbo_frame.erb

And then fill the new view in:

<%= turbo_frame_tag "page_handler" do %>
  <%= turbo_stream_action_tag(
    "append",
    target: "widgets",
    template: %(#{render @widgets}) 
  ) %>
  <%= turbo_stream_action_tag(
    "replace",
    target: "pager",
    template: %(#{render "pager", pagy: @pagy})
    ) %>
<% end %>

Here, we respond with a page_handler Turbo Frame because Turbo expects us to render content for that frame when the load more link is clicked.

Inside of that Turbo Frame is where the magic happens. We first render a Turbo Stream that appends the @widgets to the existing list of widgets (using the widgets id). Then we render another Turbo Stream to replace the content of the pager div with an updated version of the pager.

Now, when the user clicks the load more link, a Turbo Frame request is sent to the /widgets, Rails sees the index.html+turbo_frame.erb view and responds with the content of that view, rendered as plain HTML.

Turbo then sees the response on client-side, “replaces” the content of the page_handler Turbo Frame tag with the two turbo-stream elements, and then processes the actions defined in those turbo-streams. The end result is a new set of widgets appended to the list, and a load more button updated to fetch the next page of results.

See this in action by heading to the widgets index page and clicking the load more button. If all has gone well, each click of the load more button will append more widgets to the list and increment the page number each time.

Note that the Turbo Frame + Turbo Stream technique we used here was originally found on the Turbo discussion forums — the folks there figured it out, I’m just building on their great work.

Now we have a manual “infinite scroll” experience in place. Let’s finish this article by using Stimulus to fetch new widgets automatically as the user scrolls down the page.

Automatic infinite scroll

Our infinite scroll experience will be powered by a Stimulus controller and will rely on the IntersectionObserver API to fetch new widgets automatically as the user scrolls the page.

To make using the IntersectionObserver API easier, we will add the wonderful stimulus-use package to our application. This is not a requirement, but it does simplify the code a bit.

From your terminal:

bin/importmap pin stimulus-use

We also need a Stimulus controller to add the automatic fetch behavior to the DOM as the user scrolls. Again from your terminal, generate a new Stimulus controller:

rails g stimulus autoclick

Fill in the new Stimulus controller at app/javascript/controllers/autoclick_controller.js:

import { Controller } from "@hotwired/stimulus"
import { useIntersection } from 'stimulus-use'

export default class extends Controller {
  options = {
    threshold: 1
  }

  connect() {
    useIntersection(this, this.options)
  }

  appear(entry) {
    this.element.click()
  }
}

This controller pulls in the useIntersection from stimulus-use. The appear function is triggered when the element the controller is attached scrolls into view in a user’s browser. appear simply calls click() on the element the controller is attached to.

To use this controller, update the pager partial:

<div id="pager" class="min-w-full my-8 flex justify-center">
  <div>
    <% if pagy.next %>
      <%= link_to(
        "Load more widgets",
        widgets_path(page: pagy.next),
        class: "rounded py-3 px-5 bg-gray-600 text-white block hover:bg-gray-800",
        data: {
          turbo_frame: "page_handler",
          controller: "autoclick"
        }
      ) %>
    <% end %>
  </div>
</div>

Here, we added data-controller="autoclick" to the load more link. With this change in place, each time the load more link is scrolled into view, the Stimulus controller will programmatically click the load more link. Each time this occurs, a Turbo Frame request to the index action is fired to fetch and append the next set of widgets.

The autoclick controller we are using here was lightly adapted from Sean Doyle’s autoclick controller in his own implementation of infinite scrolling with Turbo.

Sean’s implementation of infinite scrolling presents yet another approach to working around the limits of Turbo Frames and is worth reviewing in full, if you are interested in more advanced Turbo use cases. In Sean’s work, the key thing to note is his use of the code from this Turbo draft PR which adds additional “actions” to Turbo Frames.

That's all for this tutorial, great work following along!

Wrapping up

Today we implemented multiple pagination styles in a Rails 7 application with Turbo Frames, Turbo Streams, and Stimulus. While building pagination, we got to see a couple of useful, more advanced uses of Turbo Frames in Rails:

Rendering Turbo Frame variants to respond with different content in response to Turbo Frame requests
Rendering Turbo Streams inside of empty Turbo Frame tags to use Turbo Streams in response to GET requests

These types of techniques dramatically expand the usefulness of Turbo without adding significant complexity to your code, and are helpful tools to add to your Turbo kit.

The very smart folks on the StimulusReflex discord inspired this article, and the excellent work done by Dale Zak and Sean Doyle served as a great foundation to build on.

This article is intended to serve as a supplement to their work, presenting alternative approaches to help expand the set of tools we have to work with in Turbo.

That’s all for today. As always, thanks for reading!

Real-time previews with Rails and StimulusReflex

David Colby — Fri, 04 Feb 2022 00:10:51 +0000

Today we are going to build a live, server-rendered, liquid-enabled markdown previewer with Ruby on Rails and StimulusReflex. It’ll be pretty neat.

Allowing users to preview their content before saving it is a common need in web applications — posts, products, emails. Any user-created content that gets turned into HTML can benefit from a preview function to help users check their work before they save it.

Our StimulusReflex-powered previewer will parse user-generated markdown on the server, insert dynamic content with liquid, and update the DOM in ~100ms, fast enough that the preview feels instant.

When our work is done, the end product will look like this:

If you’d like to try out the previewer in a production environment, you can try it out on Heroku. The demo application is hosted on Heroku’s free tier so expect a delay on the first page load!

Before diving in, this tutorial assumes a basic level of Rails knowledge. If you have never written Rails before, this tutorial may not be for you. You do not need any prior experience with Stimulus or StimulusReflex to follow along — in fact, this tutorial will be most useful to you if you are new to StimulusReflex and curious about how it can help you build great experiences faster.

Let’s get started!

Application setup

We are working from a base Rails 7 application with TailwindCSS and StimulusReflex installed. To follow along with this tutorial, start by cloning the starter repo so we can skip past the install steps and get to build the application. All of the code changes we will make in this tutorial can be found in this pull request.

Our application will allow users to create and edit Posts. As they modify a post, the preview display beside the post will update. Before we can preview posts, we’ll need a Post resource to work with, so let’s begin by scaffolding that resource up.

From your terminal:

rails g scaffold Post title:string body:text
rails db:migrate

After you scaffold the resource, start up the rails application and build CSS and JavaScript with bin/dev. Head to http://localhost:3000/posts and make sure that creating and editing posts works before moving on.

As a reminder, our end goal is a live, updated-as-you-type preview displayed beside the post form. We’ll construct the UI first. Create a new preview partial from your terminal:

touch app/views/posts/_preview.html.erb

Fill the new partial in with:

<div class="bg-gray-200 p-4 shadow-sm rounded-sm">
  <article class="prose">
    <h2 class="text-2xl font-bold"><%= post.title %></h2>
    <div>
      <%= post.body %>
    </div>
  </article>
</div>

Update app/views/posts/new.html.erb to render the preview partial beside the post form, like this:

<div class="mx-auto md:w-2/3 w-full">
  <div class="flex space-x-12">
    <div class="w-1/2">
      <%= render "form", post: @post %>
    </div>
    <div class="w-1/2">
      <%= render "preview", post: @post %>
    </div>
  </div>
</div>

Now update app/views/posts/edit.html.erb with the same content:

<div class="mx-auto md:w-2/3 w-full">
  <div class="flex space-x-12">
    <div class="w-1/2">
      <%= render "form", post: @post %>
    </div>
    <div class="w-1/2">
      <%= render "preview", post: @post %>
    </div>
  </div>
</div>

Here, we could have created a new partial with the content we added to new and edit, but it is not strictly necessary. Feel free to move this content to a partial if you prefer.

Now we have preview content displayed beside the post form, but the preview content is static — visit posts/new and see that the "preview" is just an empty gray box. Not very useful yet.

In the next section, we will create a StimulusReflex-enabled Stimulus controller to update the preview content as the user types, making the gray preview box a little more useful.

Adding a Stimulus controller

Our application will eventually rely on a server-side reflex to update the content of the preview partial that we created in the last section. However, before we do that, let’s build a purely client-side implementation of the preview function to ease into things.

From your terminal, use the stimulus_reflex generator:

rails g stimulus_reflex post
rails stimulus:manifest:update

After this generator runs, you will see that the generator created both a client-side Stimulus controller and a server-side reflex: app/javascript/controllers/post_controller.js and app/reflexes/post_reflex.rb.

On the client-side, StimulusReflex enhances vanilla Stimulus controllers. StimulusReflex-powered Stimulus controllers have all of the same functionality of a regular Stimulus controller, with extra functionality layered on top.

To demonstrate this, we are going to start by using the new Stimulus controller, post_controller.js to update the content of the post preview as the user types. We will not have any markdown formatting or liquid substitution, but the page will react to user input and we will get to see a few Stimulus concepts in action.

Head to app/javascript/controllers/post_controller.js and update it:

import ApplicationController from './application_controller'

export default class extends ApplicationController {
  static targets = [ "title", "body", "titlePreview", "bodyPreview" ]

  preview() {
    this.titlePreviewTarget.innerText = this.titleTarget.value
    this.bodyPreviewTarget.innerText = this.bodyTarget.value
  }
}

Here, we inherit from ApplicationController, the base StimulusReflex controller.

In the controller, we define targets that we will use to obtain an easy reference to the elements that we care about. We use these targets in the preview function. Each time preview is called, the titlePreview and bodyPreview elements are updated with the current value of titleTarget and bodyTarget, respectively.

For the most part, this is regular JavaScript. If we wanted to, we could remove the targets and instead select each element by an id, with something like document.getElementById('body-target'). Stimulus targets give us a more convenient method to access any number of elements by a name, but nothing magical is happening.

To use this new preview function, we need to connect the new PostController to the DOM and add target elements and actions to the preview and form partials.

In new.html.erb:

<div class="mx-auto md:w-2/3 w-full">
  <div class="flex space-x-12" data-controller="post">
    <div class="w-1/2">
      <%= render "form", post: @post %>
    </div>
    <div id="post-preview" class="w-1/2">
      <%= render "preview", post: @post %>
    </div>
  </div>
</div>

Here we added data-controller="post" to the div wrapping the form and preview partials.

To use a Stimulus controller, you must connect the controller to a DOM element with the data-controller attribute. Stimulus scopes controllers based on the DOM hierarchy — the element with the data-controller attribute and all of the children of that element will be within that controller’s scope. targets and actions for a controller must be within the scope to function.

This scoping mechanism allows developers to have multiple independent instances of the same controller present on the page at once, when needed.

Update the form partial next:

<%= form_with(model: post, class: "contents") do |form| %>
  <% if post.errors.any? %>
    <div id="error_explanation" class="bg-red-50 text-red-500 px-3 py-2 font-medium rounded-lg mt-3">
      <h2><%= pluralize(post.errors.count, "error") %> prohibited this post from being saved:</h2>

      <ul>
        <% post.errors.each do |error| %>
          <li><%= error.full_message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>

  <div class="my-5">
    <%= form.label :title %>
    <%= form.text_field(
      :title,
      class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 mt-2 w-full",
      data: {
        post_target: "title",
        action: "input->post#preview"
      } 
    ) %>
  </div>

  <div class="my-5">
    <%= form.label :body %>
    <%= form.text_area(
      :body,
      rows: 4,
      class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 mt-2 w-full",
      data: {
        post_target: "body",
        action: "input->post#preview"
      } 
    ) %>
  </div>

  <div class="inline">
    <%= form.submit class: "rounded-lg py-3 px-5 bg-blue-600 text-white inline-block font-medium cursor-pointer" %>
  </div>
<% end %>

The important updates here are on the two form inputs. On each, we added a data-post-target and a data-action attribute. The post-target attribute defines a target for the PostController, and the action attribute tells Stimulus to fire the PostController's preview function when an input event occurs on that input.

With this change in place, each time a user types a character in the title or body inputs, the PostController will run the preview function to update the titlePreview and bodyPreview elements.

This won’t work just yet though. Before it will, we need to set the titlePreview and bodyPreview targets. Head to app/views/posts/_preview.html.erb and update it:

<div class="bg-gray-200 p-4 shadow-sm rounded-sm">
  <article class="prose">
    <h2 class="text-2xl font-bold" data-post-target="titlePreview"><%= post.title %></h2>
    <div data-post-target="bodyPreview">
      <%= post.body %>
    </div>
  </article>
</div>

Notice the data-post-target attributes on the header and the body tags.

With this change in place, refresh the new post page, start typing and see that the content of the preview updates as you type.

This is a great start, but we aren’t really “previewing” anything because the Stimulus controller is not parsing markdown content or substituting liquid tags.

To add useful previews, we will use the server-side PostReflex that we generated at the beginning of this section.

Server-side previews with StimulusReflex

Stimulus controllers do their work on the client-side, adding and removing elements, updating classes or attributes. Even when we are using StimulusReflex, this is still true — Stimulus controllers stay on the client-side. To add server-side functionality, we need to move to the PostReflex, at app/reflexes/post_reflex.rb.

This reflex class will be responsible for transforming the content of the preview body from markdown to HTML, and for substituting any liquid tags present in the content. Once the content is transformed, StimulusReflex will send the transformed content back to the client, where it will be inserted seamlessly into the DOM, all in ~100ms.

Before adding markdown and liquid parsing, let’s move the client-side preview updates to the server-side reflex. Update PostReflex like this:

class PostReflex < ApplicationReflex  
  def preview
    morph '#preview-title', post_params[:title]
    morph '#preview-body', post_params[:body]
  end

  private

  def post_params
    params.require(:post).permit(:title, :body)
  end
end

In this reflex, we are using two selector morphs to update the preview content, identifying the element to update with an id. Selector morphs allow us to run reflex actions without a full pass through a controller action with ActionDispatch, and are perfect for features that only update a small piece of the page, like our preview functionality.

post_params is identical to attribute whitelisting that you’ll find in a standard Rails controller — each time this reflex is called, the data from the post form will be serialized and sent to the server, giving us a handy way to reference the current content of the form.

In StimulusReflex, there are two ways to call a server-side reflex.

The first option is through a reflex data attribute on a DOM element. This approach completely bypasses the reflex’s related Stimulus controller and directly invokes the server-side reflex. This option works well when you have a simple reflex that does not need custom options to function.

Our use case requires us to use the second method for calling reflexes: using this.stimulate in a Stimulus controller. stimulate is extremely flexible and allows us to override the element passed to the server-side reflex, define options, and run any JavaScript we like before sending the reflex to the server.

To call a reflex with stimulate, head back to app/javascript/controllers/post_controller.js and update it like this:

import ApplicationController from './application_controller'

export default class extends ApplicationController {
  connect() {
    super.connect()
  }

  preview() { 
    this.stimulate("Post#preview", { serializeForm: true })
  }
}

Here, we removed the targets from the controller and preview now just calls this.stimulate.

The serializeForm option ensures the content of the closest form element in the DOM is passed to the reflex on the server. The data in the form is accessible on the server via params, as we saw in the PostReflex earlier in this section.

Now we have a reflex defined on the server, and a Stimulus controller ready to call that reflex. To make this work, we need to update the DOM to match the structure expected by the reflex.

Recall in the preview method in PostReflex, we have two morphs that rely on ids to target the right element in the DOM:

def preview
  morph '#preview-title', post_params[:title]
  morph '#preview-body', post_params[:body]
end

For the reflex to work, we need an element with a preview-title id and another with a preview-body id. Update the preview partial like this:

<div class="bg-gray-200 p-4 shadow-sm rounded-sm">
  <article class="prose">
    <h2 id="preview-title" class="text-2xl font-bold"><%= post.title %></h2>
    <div id="preview-body">
      <%= post.body %>
    </div>
  </article>
</div>

Now both the title element and the body element have ids that match the expectations of the reflex, so when the reflex runs, those elements will be updated.

Move over to the form partial to connect the post Stimulus controller to the form:

<%= form_with(model: post, class: "contents", data: { controller: "post" }) do |form| %>
  <% if post.errors.any? %>
    <div id="error_explanation" class="bg-red-50 text-red-500 px-3 py-2 font-medium rounded-lg mt-3">
      <h2><%= pluralize(post.errors.count, "error") %> prohibited this post from being saved:</h2>

      <ul>
        <% post.errors.each do |error| %>
          <li><%= error.full_message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>

  <div class="my-5">
    <%= form.label :title %>
    <%= form.text_field(
      :title,
      class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 mt-2 w-full",
      data: {
        action: "input->post#preview"
      } 
    ) %>
  </div>

  <div class="my-5">
    <%= form.label :body %>
    <%= form.text_area(
      :body,
      rows: 4,
      class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 mt-2 w-full",
      data: {
        action: "input->post#preview"
      } 
    ) %>
  </div>

  <div class="inline">
    <%= form.submit class: "rounded-lg py-3 px-5 bg-blue-600 text-white inline-block font-medium cursor-pointer" %>
  </div>
<% end %>

Here, notice the form element now has a data-controller="post" attribute, scoping the Stimulus controller to the form. We also updated the form inputs to remove the unnecessary data-post-target attributes.

Because we are serializing the entire content of the form, we no longer need a direct reference to the individual input elements in the Stimulus controller, so we do not need the target attributes.

One last step to move the preview functionality to the server. Because we connected the PostController to the form, we need to remove the controller from the wrapper div in app/view/posts/new.html.erb:

<div class="mx-auto md:w-2/3 w-full">
  <div class="flex space-x-12">
    <div class="w-1/2">
      <%= render "form", post: @post %>
    </div>
    <div class="w-1/2">
      <%= render "preview", post: @post %>
    </div>
  </div>
</div>

Previously, we needed a direct reference in the Stimulus controller to the preview elements, so we needed both the form and preview partials to be within the scope of the PostController.

Because the preview elements are now updated in the server-side reflex and referenced by id, the preview partial no longer needs to be in the PostController’s scope.

With this last change in place, head back to http://localhost:3000/posts/new, start typing and see that the preview content updates each time the form changes. To confirm that StimulusReflex is doing the work on the server, watch the Rails server logs as you type. With each key press, the server logs will output information about the reflex:

Now we are “previewing” content as the user types, but that preview still is not doing anything useful. We just added a round trip to the server, but the server is not doing anything useful with the content yet.

In the next section, we will make the server-side reflex more valuable by adding markdown and liquid tag parsing when the preview content is updated.

Add markdown and liquid parsing

We will use redcarpet to parse markdown. To do so, We need to add redcarpet to our application.

From your terminal:

bundle add redcarpet

Restart your Rails application and head to app/helpers/posts_helper.rb and add a method to parse markdown content:

module PostsHelper
  def to_markdown(content)
    return '' if content.blank?

    markdown = Redcarpet::Markdown.new(
      Redcarpet::Render::HTML,
      fenced_code_blocks: true,
      autolink: true
    )
    markdown.render(content).html_safe
  end
end

This helper takes a string, initializes a new instance of Redcarpet::Markdown as described in the documentation, and then renders the content to HTML.

The to_markdown helper will be used in two places in our application: When the preview partial is loaded during a normal request (like when visiting the post edit page) and when parsing content on the fly in the PostReflex.

Update the preview partial first, at app/views/posts/_preview.html.erb:

<div class="bg-gray-200 p-4 shadow-sm rounded-sm">
  <article class="prose">
    <h2 class="text-2xl font-bold" id="preview-title">
      <%= post.title %>
    </h2>
    <div id="preview-body">
      <%= to_markdown(post.body) %>
    </div>
  </article>
</div>

When a user visits the new or edit pages, markdown content in the body will be parsed and rendered as HTML.

Update the PostReflex to use the new to_markdown helper:

def preview
  morph '#preview-title', post_params[:title]
  morph '#preview-body', ApplicationController.helpers.to_markdown(post_params[:body])
end

Head to new or edit now, type some markdown content in the body input and see that as you type, the markdown is transformed into HTML instantly.

At this point, we have server-powered markdown parsing — nice work!

Our next step is adding liquid support, allowing users to transform liquid content into real data and see that content processed in real time.

From your terminal:

bundle add liquid

Back to the PostsHelper:

module PostsHelper
  def to_markdown(content)
    return '' if content.blank?

    markdown = Redcarpet::Markdown.new(
      Redcarpet::Render::HTML,
      fenced_code_blocks: true,
      autolink: true
    )
    markdown.render(liquified(content)).html_safe
  end

  def liquified(content)
    Liquid::Template
      .parse(content)
      .render('company_name' => 'Hotwiring Rails')
  end
end

liquified takes a string of content, scans it for matching liquid tags and objects, and translates them.

Our example implementation mocks up a simple company_name tag — in a real application we could use liquid tags to insert data about the object we are working on.

Restart your Rails application again and then go back to the new or editposts page, enter in a body with some markdown content and the {{ company_name }} tag and see that the tag is replaced as you type:

Debouncing requests

Right now, every keystroke triggers a round trip to the server. Many of these requests are unnecessary because the user will have typed another character before the request completes. A simple way to reduce the load on the server is to debounce preview function, waiting for the user to pause before triggering the server-side reflex.

To debounce the preview function, we will use lodash’s debounce. From your terminal:

yarn add lodash

And then update the Post Stimulus controller:

import ApplicationController from './application_controller'
import debounce from "lodash/debounce"

export default class extends ApplicationController {
  connect() {
    super.connect()
    this.preview = debounce(this.preview.bind(this), 50)
  }

  preview() { 
    this.stimulate("Post#preview", { serializeForm: true })
  }
}

Now, preview will wait 50ms before firing. Feel free to play around with the wait period to find the time that feels right to you.

And with that change, you have reached the end of this tutorial, great work today!

Wrapping up

Today we built a fully functional, StimulusReflex-powered markdown and liquid tag parser. Our application processes content on the server and returns it to the client without page turns, saving records in the database, or dealing with the overhead of a Rails controller action.

While building this application, we learned a bit about how to use Stimulus and StimulusReflex in Rails application and applied some basic techniques of both to create a real-time experience while staying close to core Rails principles.

Before using something like what we built today in production, a couple of things to think about:

Why not just parse things on the client?

Throughout this tutorial, you may have wondered “Why don’t we just parse the markdown on the client?”

Liquid processing was introduced to give us a reason to parse content like this on the server. We are here to learn about Stimulus and StimulusReflex, so I fit the requirements to that goal.

If your application just needs markdown parsing without the extra complications of liquid, a client-side parser is a completely reasonable (and more performant) choice!

Do you need real-time previews?

The live preview we built is useful for learning and showing off what StimulusReflex can do, but it may not be the most desirable user experience in a real application. The live preview experience works fine for some use cases, particularly when the content is only a few paragraphs in length.

As the content gets longer, a better approach is moving the “preview” content into a separate tab, hidden by default. As the user types, update the content in the hidden tab as usual, but keep the content hidden until the user requests it. That experience is likely to scale a bit better, while not being any more technically complex than the experience we built.

Live reloading with Ruby on Rails and esbuild

David Colby — Sat, 06 Nov 2021 16:24:00 +0000

As you may have heard by now, Rails 7 comes out of the box with importmap-rails and the mighty Webpacker is no longer the default for new Rails applications.

For those who aren't ready to switch to import maps and don’t want to use Webpacker now that it is no longer a Rails default, jsbundling-rails was created. This gem adds the option to use webpack, rollup, or esbuild to bundle JavaScript while using the asset pipeline to deliver the bundled files.

Of the three JavaScript bundling options, the Rails community seems to be most interested in using esbuild, which aims to bring about a “new era of build tool performance” and offers extremely fast build times and enough features for most users’ needs.

Using esbuild with Rails, via jsbundling-rails is very simple, especially in a new Rails 7 application; however, the default esbuild configuration is missing a few quality of life features. Most important among these missing features is live reloading. Out of the box, each time you change a file, you need to refresh the page to see your changes.

Once you’ve gotten used to live reloading (or its fancier cousin, Hot Module Replacement), losing it is tough.

Today, esbuild doesn’t support HMR, but with some effort it is possible to configure esbuild to support live reloading via automatic page refreshing, and that’s what we’re going to do today.

We’ll start from a fresh Rails 7 install and then modify esbuild to support live reloading when JavaScript, CSS, and HTML files change.

Before we get started, please note that this very much an experiment that hasn’t been battle-tested. I’m hoping that this is a nice jumping off point for discussion and improvements. YMMV.

With that disclaimer out of the way, let’s get started!

Application setup

We’ll start by creating a new Rails 7 application.

If you aren’t already using Rails 7 for new Rails applications locally, this article can help you get your local environment ready.

Once your rails new command is ready for Rails 7, from your terminal:

rails new live_esbuild -j esbuild
cd live_esbuild
rails db:create
rails g controller Home index

Here we created a new Rails application set to use jsbundling-rails with esbuild and then generated a controller we’ll use to verify that the esbuild configuration works.

Booting up

In addition to installing esbuild for us, jsbundling-rails creates a few files that simplify starting the server and building assets for development. It also changes how you’ll boot up your Rails app locally.

Rather than using rails s, you’ll use bin/dev. bin/dev uses foreman to run multiple start up scripts, via Procfile.dev. We’ll make a change to the Procfile.dev later, but for now just know that when you’re ready to boot up your app, use bin/dev to make sure your assets are built properly.

Configure esbuild for live reloading

To enable live reloading, we’ll start by creating an esbuild config file. From your terminal:

touch esbuild-dev.config.js

To make things a bit more consumable, we’ll first enable live reloading for JavaScript files only, leaving CSS and HTML changes to wait for manual page refreshes.

We’ll add reloading for views and CSS next, but we’ll start simpler.

To enable live reloading on JavaScript changes, update esbuild-dev.config.js like this:

#!/usr/bin/env node

const path = require('path')
const http = require('http')

const watch = process.argv.includes('--watch')
const clients = []

const watchOptions = {
  onRebuild: (error, result) => {
    if (error) {
      console.error('Build failed:', error)
    } else {
      console.log('Build succeeded')
      clients.forEach((res) => res.write('data: update\n\n'))
      clients.length = 0
    }
  }
}

require("esbuild").build({
  entryPoints: ["application.js"],
  bundle: true,
  outdir: path.join(process.cwd(), "app/assets/builds"),
  absWorkingDir: path.join(process.cwd(), "app/javascript"),
  watch: watch && watchOptions,
  banner: {
    js: ' (() => new EventSource("http://localhost:8082").onmessage = () => location.reload())();',
  },
}).catch(() => process.exit(1));

http.createServer((req, res) => {
  return clients.push(
    res.writeHead(200, {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      "Access-Control-Allow-Origin": "*",
      Connection: "keep-alive",
    }),
  );
}).listen(8082);

There’s a lot going on here, let’s walk through it a section at a time:

const path = require('path')
const http = require('http')

const watch = process.argv.includes('--watch')
let clients = []

First we require packages and define a few variables, easy so far, right?

Next, watchOptions:

const watchOptions = {
  onRebuild: (error, result) => {
    if (error) {
      console.error('Build failed:', error)
    } else {
      console.log('Build succeeded')
      clients.forEach((res) => res.write('data: update\n\n'))
      clients.length = 0
    }
  }
}

watchOptions will be passed to esbuild to define what happens each time an esbuild rebuild is triggered.

When there’s an error, we output the error, otherwise, we output a success message and then use res.write to send data out to each client.

Finally, clients.length = 0 empties the clients array to prepare it for the next rebuild.

require("esbuild").build({
  entryPoints: ["application.js"],
  bundle: true,
  outdir: path.join(process.cwd(), "app/assets/builds"),
  absWorkingDir: path.join(process.cwd(), "app/javascript"),
  watch: watch && watchOptions,
  banner: {
    js: ' (() => new EventSource("http://localhost:8082").onmessage = () => location.reload())();',
  },
}).catch(() => process.exit(1));

This section defines the esbuild build command, passing in the options we need to make our (JavaScript only) live reload work.

The important options are the watch option, which takes the watch and watchOptions variables we defined earlier and banner.

esbuild’s banner option allows us to prepend arbitrary code to the JavaScript file built by esbuild. In this case, we insert an EventSource that fires location.reload() each time a message is received from localhost:8082.

Inserting the EventSource banner and sending a new request from 8082 each time rebuild runs is what enables live reloading for JavaScript files to work. Without the EventSource and the local request sent on each rebuild, we would need to refresh the page manually to see changes in our JavaScript files.

http.createServer((req, res) => {
  return clients.push(
    res.writeHead(200, {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      "Access-Control-Allow-Origin": "*",
      Connection: "keep-alive",
    }),
  );
}).listen(8082);

This section at the end of the file simply starts up a local web server using node’s http module.

With the esbuild file updated, we need to update package.json to use the new config file:

"scripts": {
  "build": "esbuild app/javascript/*.* --bundle --outdir=app/assets/builds",
  "start": "node esbuild-dev.config.js"
}

Here we updated the scripts section of package.json to add a new start script that uses our new config file. We’ve left build as-is since build will be used on production deployments where our live reloading isn’t needed.

Next, update Procfile.dev to use the start script:

web: bin/rails server -p 3000
js: yarn start --watch

Finally, let’s make sure our JavaScript reloading works. Update app/views/home/index.html.erb to connect the default hello Stimulus controller:

<h1 data-controller="hello">Home#index</h1>
<p>Find me in app/views/home/index.html.erb</p>

Now boot up the app with bin/dev and head to http://localhost:3000/home/index.

Then open up app/javascript/hello_controller.js and make a change to the connect method, maybe something like this:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.textContent = "Hello Peter. What's happening?"
  }
}

If all has gone well, you should see the new Hello Peter header on the page, replacing the Hello World header.

If all you want is JavaScript live reloading, feel free to stop here. If you want live reloading for your HTML and CSS files, that’s where we’re heading next.

HTML and CSS live reloading

esbuild helpfully watches our JavaScript files and rebuilds every time they change. It doesn’t know anything about non-JS files, and so we’ll need to branch out a bit to get full live reloading in place.

Our basic approach will be to scrap esbuild’s watch mechanism and replace it with our own file system monitoring that triggers rebuilds and pushes updates over the local server when needed.

To start, we’re going to use chokidar to watch our file system for changes, so that we can reload when we update a view or a CSS file, not just JavaScript files.

Install chokidar from your terminal with:

yarn add chokidar -D

With chokidar installed, we’ll update esbuild-dev.config.js again, like this:

#!/usr/bin/env node

const path = require('path')
const chokidar = require('chokidar')
const http = require('http')

const clients = []

http.createServer((req, res) => {
  return clients.push(
    res.writeHead(200, {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      "Access-Control-Allow-Origin": "*",
      Connection: "keep-alive",
    }),
  );
}).listen(8082);

async function builder() {
  let result = await require("esbuild").build({
    entryPoints: ["application.js"],
    bundle: true,
    outdir: path.join(process.cwd(), "app/assets/builds"),
    absWorkingDir: path.join(process.cwd(), "app/javascript"),
    incremental: true,
    banner: {
      js: ' (() => new EventSource("http://localhost:8082").onmessage = () => location.reload())();',
    },
  })
  chokidar.watch(["./app/javascript/**/*.js", "./app/views/**/*.html.erb", "./app/assets/stylesheets/*.css"]).on('all', (event, path) => {
    if (path.includes("javascript")) {
      result.rebuild()
    }
    clients.forEach((res) => res.write('data: update\n\n'))
    clients.length = 0
  });
}
builder()

Again, lots going on here. Let’s step through the important bits.

const chokidar = require('chokidar')

First, we require chokidar, which we need to setup file system watching. Starting easy again.

Next, we setup the build task:

async function builder() {
  let result = await require("esbuild").build({
    // snip unchanged options
    incremental: true,
  })
  chokidar.watch(["./app/javascript/**/*.js", "./app/views/**/*.html.erb", "./app/assets/stylesheets/*.css"]).on('all', (event, path) => {
    if (path.includes("javascript")) {
      result.rebuild()
    }
    clients.forEach((res) => res.write('data: update\n\n'))
    clients.length = 0
  });
}

Here we’ve moved the build setup into an async function that assigns result to build.

We also added the incremental flag to the builder, which makes repeated builds (which we’ll be doing) more efficient.

The watch option was removed since we no longer want esbuild to watch for changes on rebuild on its own.

Next, we setup chokidar to watch files in the javascript, views, and stylesheets directories. When a change is detected, we check the path to see if the file was a javascript file. If it was, we manually trigger a rebuild of our JavaScript.

Finally, we send a request out from our local server, notifying the browser that it should reload the current page.

With these changes in place, stop the server if it is running and then bin/dev again. Open up or refresh http://localhost:3000/home/index, make changes to index.html.erb and application.css and see that those changes trigger page reloads and that updating hello_controller.js still triggers a reload.

Wrapping up

Today we created an esbuild config file that enables live reloading (but not HMR) for our jsbundling-rails powered Rails application. As I mentioned at the beginning of this article, this is very much an experiment and this configuration has not been tested on an application of any meaningful size. You can find the finished code for this example application on Github.

I’m certain that there are better routes out there to the same end result, and I’d love to hear from others on pitfalls to watch out for and ways to improve my approach.

While researching this problem, I leaned heavily on previous examples of esbuild configs. In particular, the examples found at these two links were very helpful in getting live reload to a functional state:

This example esbuild config, from an issue on the jsbundling-rails Github repo
This discussion on the esbuild Github repo

If you, like me, are a Rails developer that needs to learn more about bundling and bundlers, a great starting point is this deep dive into the world of bundlers. If you're intested in full HMR without any speed loss, and you're willing to break out of the standard Rails offerings, you might enjoy vite-ruby.

Finally, if you're using esbuild with Rails and Stimulus, you'll probably find the esbuild-rails plugin from Chris Oliver useful.

That’s all for today. As always - thanks for reading!

Rendering view components with Turbo Stream broadcasts

David Colby — Thu, 04 Nov 2021 14:32:29 +0000

View components, via Github’s view_component gem, are growing in popularity in the Rails community but until recently, view components and Turbo Stream broadcasts didn’t play well together. This made using both view components and Turbo Streams in the same application clunky and a little frustrating.

While there were ways to get components working with streams, thanks to a recent addition to turbo-rails, rendering view components from Turbo Streams now works seamlessly out of the box.

To demonstrate how to connect these two powerful tools together, we’ll be building a very simple Rails application that allows users to manage a list of Spies.

Each spy in the list of spies will be rendered using a view component, and when new spies are added to the database, the newly created spy record will be rendered and broadcast via a callback in the spy model.

When we’re finished, it’ll work like this:

Beautiful, I know.

This article assumes that you’re comfortable building Rails applications. You won’t need any previous experience with Turbo Streams or view components to follow along.

If you want to skip right to the end the complete code for this article can be found on Github.

Let’s start building!

Application setup

We’ll be working from a fresh Rails application. I’m working off of the latest Rails 7 release (alpha2 at the time of this writing) but everything in this tutorial will work fine on Rails 6.1 too.

If you want to follow along, you can run the below commands from your terminal, or you can clone this Github repo and skip ahead to the Building the spy component section.

rails new turbo-view-components -T
cd turbo-view-components
rails g scaffold Spy name:string mission:string
bundle add view_component
rails db:create db:migrate

If you’re using Rails 6.1 instead of 7, you’ll also need to install turbo-rails manually.

bundle add turbo-rails
rails turbo:install

Whichever route you choose, you’re ready to move on to the next section once you have view_component and turbo-rails installed in your application and a Spy resource created. Once you're setup, start up your server with rails s and head to http://localhost:3000/spies.

Building the spy component

To use view components, we need to create a component to render a spy object. We can create new components with the built-in generator view_component provides:

rails g component Spy spy

This generator will create both a spy_component.rb file and a spy_component.html.erb file in the components directory.

Since we're building a very simple component, spy_component.rb is good to go out of the box. For reference, it should look like this:

class SpyComponent < ViewComponent::Base
  def initialize(spy:)
    @spy = spy
  end
end

spy_component.html.erb contains placeholder content provided by the generator right now, so let’s update it to render information about each spy:

<div id="<%= dom_id @spy %>">
  <p>
    <strong>Name:</strong>
    <%= @spy.name %>
  </p>

  <p>
    <strong>Mission:</strong>
    <%= @spy.mission %>
  </p>

  <p>
    <%= link_to "Show this spy", @spy %>
  </p>
</div>

This is just regular old erb, essentially a copy of the default content of _spy.html.erb generated by the Rails scaffold generator we ran during application setup.

With the spy component in place, we now need to actually use it. To do that, we’ll update the spies index view to use the our new component. Update spies/index.html.erb like this:

<p id="notice"><%= notice %></p>

<h1>Spy</h1>

<div id="spies">
  <%= render(SpyComponent.with_collection(@spies)) %>
</div>

<%= link_to "New spy", new_spy_path %>

Here we’re using collection rendering to loop through each spy in @spies and render each with spy_component.html.erb.

We’ve now got our list of spies rendering using view components — next up we’ll add Turbo Stream broadcasts so that newly created spies are appended to the list automatically.

Add Turbo Stream broadcasts

First, we need to ensure that visitors to the spies index page are subscribed to the appropriate turbo stream channel.

To do this, we can use the turbo_stream_from helper from turbo-rails. Update spies/index.html.erb like this:

<!-- Snip -->
<%= turbo_stream_from "spies" %>
<div id="spies">
  <%= render(SpyComponent.with_collection(@spies)) %>
</div>
<!-- Snip -->

There are two important pieces here. First, we added the turbo_stream_from helper, with spies as the name.

This helper creates a <turbo-cable-stream-source> in the rendered HTML with a signed-stream-name that looks something like this:

<turbo-cable-stream-source channel="Turbo::StreamsChannel" signed-stream-name="aLongSecureName"></turbo-cable-stream-source>

Next, the div wrapping the list of spy components has an id of spies. This id must match the target of the Turbo Stream broadcast, which defaults to the plural name of the model we are broadcasting from. If our wrapper div doesn’t have an id, the broadcast we add next will fail.

With the stream subscription added to the view, the last step is to add a model callback in models/spy.rb to broadcast newly created spies on the spies channel.

Update spy.rb like this:

class Spy < ApplicationRecord
  after_create_commit :append_new_record

  private

  def append_new_record
    broadcast_append_to(
      'spies',
      html: ApplicationController.render(
        SpyComponent.new(spy: self)
      )
    )
  end
end

Here we’re using the new html option added to Turbo Stream broadcast methods to render the SpyComponent instead of rendering a partial.

Note that using ApplicationController.render to render a view_component isn’t officially sanctioned by the view_component team.

The view_component folks are actively discussing an official way to add support for stream broadcasts, which you can track on this issue.

With the model broadcast in place, we’re ready to test our Turbo Stream-enabled view components.

A note for Rails 7 users: If you’re on Rails 7 alpha2 (the latest release at the time of this writing) an issue exists that will prevent the broadcast from working because of a disabled session error. This issue is entirely unrelated to view components but it will break our broadcast all the same.

This issue will be fixed in the next Rails release, but until then you can prevent the issue by updating development.rb with this line:

config.action_controller.silence_disabled_session_errors = true

To see it action, refresh the index page, and then open a new tab to http://localhost:3000/spies/new, create a new spy, and see that the newly created spy is automatically appended to the list of spies automatically.

Wrapping up

Today we looked at a technique to render View Components from Turbo Stream broadcasts, leveraging the recently added ability to render html instead of a partial from Turbo Stream broadcasts.

This article’s focus is on Turbo Stream broadcasts + view_component, so we didn’t dive deep into how Turbo Streams work or how to take full advantage of the real power of view_component.

To dig deeper, you might find these resources helpful starting points:

The view_component documentation is excellent, and worth reviewing in detail to understand more about how you can use view components
Encapsulating Ruby on Rails views from Github’s blog is a nice introduction to the work behind the ViewComponent library and includes links to see how Github uses ViewComponents in their application
The Turbo Rails source code. If you’re serious about using Turbo in your Rails application, thoroughly reviewing the source and accompanying comments is highly recommend.
The Turbo handbook is the best place to start if you’re new to Turbo and want to understand the basics of Streams, Frames, and Drive

That’s all for today. As always, thanks for reading!

Filter, search, and sort tables with Rails and Turbo Frames

David Colby — Fri, 15 Oct 2021 19:34:30 +0000

Today we are going to build a table that can be sorted, searched, and filtered all at once, using Ruby on Rails, Turbo Frames, a tiny Stimulus controller, and a little bit of Tailwind for styling.

We will start with a sortable, Turbo Frame-powered table that displays a list of Players from a database. We built this sortable table in a previous article — you might find it helpful to start with that article, especially if you are new to Turbo.

When we are finished, users will be able to search for players by name, filter them by their team, and sort the table. Sorting, searching, and filtering all work together, in any combination, and they each occur without a full page turn. The end result will work like this:

This article is intended for folks who are comfortable with Ruby and Rails code. You won’t need any prior experience with Turbo Frames or Stimulus.

Let’s dive in!

Project setup

If you want to follow along with this article and you haven’t already completed the sortable table article locally, you’ll want to begin by cloning this Github repo. If you have completed the sortable table article, this one picks up exactly where that one ends, so go ahead and work from where that article finished.

To set up the application after cloning from Github, from your terminal:

bundle install
yarn install
rails db:setup

Once the application is ready, checkout the sortable branch, where this article picks up, and then run bin/dev to compile assets and start your development server.

After you start the server, head to http://localhost:3000 and see that you have a seeded database of players and that you can sort the table by clicking on each column header.

If you’re curious how the the sorting works, the sortable tables article goes through the frame-powered sorting mechanism in detail.

With setup complete, let's start building!

Add a search form

We’ll start with a simple search form, added inside the players turbo frame in app/views/players/_players.html.erb.

<%= turbo_frame_tag "players", class: "shadow overflow-hidden rounded border-b border-gray-200" do %>
  <div class="flex justify-end mb-1">
    <%= form_with url: list_players_path, method: :get do |form| %>
      <%= form.text_field :name, placeholder: "Search by name", value: params[:name], class: "border border-blue-500 rounded p-2" %>
      <%= form.button "Search", class: "bg-blue-500 text-white p-2 rounded-sm" %>
    <% end %>
  </div>
  <!-- Snip the table -->
<% end %>

This is a standard-issue Rails search form. When the form is submitted, a GET request is dispatched and PlayersController#list responds to the request. For now, the form requires the user to click the Search button to submit the search request.

Next, we’ll update the list method in app/controllers/players_controller.rb to filter the list of players when the search form is submitted:

def list
  players = Player.includes(:team)
  players = players.where('name ilike ?', "%#{params[:name]}%") if params[:name].present?
  players = players.order("#{params[:column]} #{params[:direction]}")
  render(partial: 'players', locals: { players: players })
end

Here we’ve got a clunky, functional implementation of searching by name — when the name parameter from the form’s text_field is present, we run a case insensitive query for players in the database with a name that matches the search query.

With these changes in place, refresh the page, type a query into the search form and submit it. You should see the players list update with the results of your query.

You’ll notice right away that searching clears any previously applied sorting on the table, and sorting the table clears out any search. So we’ve got a search form, but we have to click to submit the form and doing so clears out the user’s sorting preference.

We’ll fix both of those issues, starting with remove the submit button and searching as the user types instead.

Real-time searching

We’ll use a small Stimulus controller to submit the search form as the user types. First, generate the Stimulus controller with the generator built in to stimulus-rails. From your terminal:

rails g stimulus search_form

Then, fill that controller in with:

// app/javascript/controllers/search_form_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = [ "form" ]

  search() {
    clearTimeout(this.timeout)
    this.timeout = setTimeout(() => {
      this.formTarget.requestSubmit()
    }, 200)
  }
}

This controller’s search function calls requestSubmit on a form target. Since we’ll call this search function as the user is typing in a text input, we’ve add clearTimeout and setTimeout to ensure that the form isn’t submitted every time the user types a new character.

Note that requestSubmit needs a polyfill for support on Safari and IE11. As an alternative to requestSubmit, if you are using Rails/ujs in your application, Rails.fire(this.formTarget, 'submit') works without a polyfill.

With the Stimulus controller ready to go, next we’ll connect that controller the search form:

<div class="flex justify-end mb-1">
  <%= form_with url: list_players_path, method: :get, data: { controller: "search-form", search_form_target: "form", turbo_frame: "players" } do |form| %>
    <%= form.text_field :name,
      placeholder: "Search by name",
      class: "border border-blue-500 rounded p-2",
      autocomplete: "off",
      data: { action: "input->search-form#search" }
    %>
  <% end %>
</div>
<%= turbo_frame_tag "players", class: "shadow overflow-hidden rounded border-b border-gray-200" do %>
<!-- Snip table -->
<% end %>

Here we first moved the search form outside of the players turbo-frame. This is necessary because if the search form is inside of the turbo frame, the search input will be reset every time the players frame is rerendered (meaning every time our search form is submitted), like this:

Because the form is now outside of the frame, we add a data-turbo-frame to target the players frame. This tells Turbo to use the response from the form submission to replace the content of the players frame.

We also added data-controller="search-form" and data-search_form_target="form" to the form element. These Stimulus attributes connect the search-form controller to the DOM and set the form target.

Finally, we add data-action=“input->search-form#search” to the name field, which tells Stimulus to call the search function each time the input event is fired on the name field.

We moved fairly quickly through some core Stimulus concepts here. The Stimulus handbook is a great reference point if you need to spend more time with any of these concepts.

With these changes in place, we can refresh the page and see that search results update as the user types. We still cannot sort and search at the same time though, so let’s tackle that next.

Sorting and searching at the same time

The reason we can’t search and sort at the same time is because the list method relies on URL parameters to apply search and filter options. Because the search form doesn’t include the sort parameters and sorting doesn’t include the search parameter, list has no way of retaining sort and search options across requests — every new request to list starts from scratch.

There are a variety of ways to address this issue. The most direct is to move from using params to storing filter options in the session.

Our basic approach will be to use params to update a filters hash in the session object. Since session is maintained across requests, as long as we update the session filters hash with the search and sort params on each request, we can persist search and sort options across requests.

A very ugly implementation of this concept, done directly in the list method looks like this:

def list
  session['filters'] = {} if session['filters'].blank?

  session['filters'].merge!(filter_params)
  players = Player.includes(:team)
  players = players.where('players.name ilike ?', "%#{session['filters']['name']}%") if session['filters']['name'].present?
  players = players.order("#{session['filters']['column']} #{session['filters']['direction']}")

  render(partial: 'players', locals: { players: players })
end

private

def filter_params
  params.permit(:name, :column, :direction)
end

Here we ensure that session['filters'] is a hash, update its value by merging in whitelisted filter_params and then use the the filters hash to search for players by name and order the list of players, as appropriate.

This ugly code is fully functional — if you update the list method and add the filter_params method to your controller you will be able to search and sort at the same time; however, this code is clunky, difficult to follow, and quickly becomes unmaintainable as your application grows.

So, if this code is ugly and unmaintainable, why are we looking at it?

Because we are going to refactor it into something neater and more scalable. Before we do that it is helpful to see what the most direct implementation can be so we can understand what is happening at a basic level.

When we’re done, we’ll still store params in a hash in the session object, and we’ll still use the hash values to query the database based on the user’s preferences. Our code will be nicer, but it’ll still be the same basic concept.

Let’s refactor this code next.

Building a Filterable concern

To make our filtering code more scalable and less error prone, we are going to start with a generalized Filterable concern. We’ll include Filterable in the PlayersController and use it to filter players.

Filterable won’t know anything about the specifics of querying Players, instead it will just implement logic to store query parameters in the session. Once the values are stored, they’ll be used to apply filters.

First, create the filterable concern. From your terminal:

touch app/controllers/concerns/filterable.rb

Then, fill in filterable.rb with the following:

module Filterable
  def filter!(resource)
    store_filters(resource)
    apply_filters(resource)
  end

  private

  def store_filters(resource)
    session["#{resource.to_s.underscore}_filters"] = {} unless session.key?("#{resource.to_s.underscore}_filters")

    session["#{resource.to_s.underscore}_filters"].merge!(filter_params_for(resource))
  end

  def filter_params_for(resource)
    params.permit(resource::FILTER_PARAMS)
  end

  def apply_filters(resource)
    resource.filter(session["#{resource.to_s.underscore}_filters"])
  end
end

There’s a lot of code here, let’s break it down.

The filter! method is what we’ll call from the controller to apply filters in response to a request from a user. It takes a resource argument. resource will be an ActiveRecord class, like Player. filter! simply calls out to two internal methods, store_filters and apply_filters, which do the heavy lifting.

store_filters ensures that session['class_name_filters'] exists, and then writes whitelisted parameters into the session key, replicating the first two lines of our ugly implementation directly in the list method in the last section.

Once the filters are stored, apply_filters calls a filter class method from the class we’re interested in which should return a list of ActiveRecord objects.

You’ll notice here that Filterable isn’t doing much on its own. Instead, it is relying on methods to exist on the class passed in to filter!. This is by design — in a real application, we would likely need to build filtering mechanisms for many different ActiveRecord classes, and each will need to be able to filter by a unique set of columns. Trying to build all of that logic into the Filterable module would quickly become even harder to maintain than tossing everything in the controller.

Rather than building all of that complexity in to Filterable, we instead just rely on the target class to define FILTER_PARAMS and a filter method in whatever way works for that particular class.

Let’s see this in action by updating app/models/player.rb to work with our new Filterable concern.

class Player < ApplicationRecord
  belongs_to :team

  FILTER_PARAMS = %i[name column direction].freeze

  scope :by_name, ->(query) { where('players.name ilike ?', "%#{query}%") }

  def self.filter(filters)
    Player.includes(:team)
          .by_name(filters['name'])
          .order("#{filters['column']} #{filters['direction']}")
  end
end

Here we’ve defined the FILTER_PARAMS constant with the three filtering we support on the players table.

Next, we added the by_name scope to handle searching the players table by name.

Finally, we implement filter, which replaces the queries that we previously built in PlayersController#list and makes use of the new by_name scope to be a bit more readable.

With Player set up for filtering, we can update PlayersController to include Filterable and replace the filtering logic in list with the new filter! method.

class PlayersController < ApplicationController
  include Filterable
  # snip
  def list
    players = filter!(Player)
    render(partial: 'players', locals: { players: players })
  end
end

Here we simply include Filterable in the controller and then set the value of players using the filter! method provided by Filterable.

Much nicer, right?

Before moving on, you'll also notice that Filterable is in the controller/concerns directory, but it isn't truly a Concern. In our case, controller concerns is the simplest place for this module to live, but we don't need the full functionality of a true concern. You could just as easily place this module in another place if you prefer.

Our last step is to update the views to read values from the session instead of params so that we always display the correct set of applied filters to users.

First, update the table header in _players like this:

<tr>
  <th id="players-name" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer relative">
    <%= sort_indicator if session.dig('player_filters', 'column') == "name" %>
    <%= build_order_link(column: "name", label: "Name") %>
  </th>
  <th id="players-team" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer relative">
    <%= sort_indicator if session.dig('player_filters', 'column') == "teams.name" %>
    <%= build_order_link(column: "teams.name", label: "Team") %>
  </th>
  <th id="players-seasons" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer relative">
    <%= sort_indicator if session.dig('player_filters', 'column') == "seasons" %>
    <%= build_order_link(column: "seasons", label: "Seasons") %>
  </th>
</tr>

We’ve replaced references to params with session.dig calls with this change. When no filters have been applied, session['player_filters'] won’t exist, so we use dig to avoid nil errors in those cases.

Next, update app/heleprs/players_helper.rb like this:

module PlayersHelper
  def build_order_link(column:, label:)
    if column == session.dig('player_filters', 'column')
      link_to(label, list_players_path(column: column, direction: next_direction))
    else
      link_to(label, list_players_path(column: column, direction: 'asc'))
    end
  end

  def next_direction
    session['player_filters']['direction'] == 'asc' ? 'desc' : 'asc'
  end

  def sort_indicator
    tag.span(class: "sort sort-#{session['player_filters']['direction']}")
  end
end

Again we’re just replacing params with the equivalent session values so that sorting works correctly all the time and visual indicators are shown consistently.

With those changes in place, refresh the page and see that you can search and sort the table at the same time, and the UI always shows the proper sort indicator.

Nice work making it this far! We spent a good amount of time building a more scalable filtering solution, so let’s wrap up this article by putting that scalable solution to use by adding a filtering option to the table.

Add filtering by team

Right now users can search by player name and sort the table, but they can’t filter by team or season. Let’s add filtering by team to the filter options.

We’re going to use a select input for the Team filter, since team is a belongs_to relationship on the Player class — we’ll have a dropdown menu that displays all available teams by name, each dropdown option will have team_id as the value sent back to the server.

Since we’re using a select input, let’s make it look nice by taking a slight detour to install Tailwind’s forms plugin:

From your terminal:

yarn add @tailwindcss/forms

And then update tailwind.config.js to include the plugin:

plugins: [
  require('@tailwindcss/forms'),
]

Incredible stuff.

Back to adding the team filter. We’ll start by adding the team filter to the UI. In the players partial:

<%= form_with url: list_players_path, method: :get, data: { controller: "search-form", search_form_target: "form", turbo_frame: "players" } do |form| %>
  <%= form.select :team_id,
    options_for_select(
      Team.all.pluck(:name, :id),
      session.dig('player_filters', 'team_id')
    ),
    { include_blank: 'All Teams' },
    class: "border-blue-500 rounded",
    data: { 
      action: "change->search-form#search" 
    } 
  %>
<!-- Snip the search input -->
<% end %>

This is a regular Rails select helper. In it, we build a list of all teams in the database, set the selected value when one is present (session.dig, again) and fire the search function of the search-form controller each time the select input changes.

Refresh the page, change the team input and see that it doesn't work yet. We haven’t updated Player to support filtering by team yet.

Head to app/models/player.rb and update it like this:

FILTER_PARAMS = %i[name team_id column direction].freeze

scope :by_team, ->(team_id) { where(team_id: team_id) if team_id.present? }

def self.filter(filters)
  Player.includes(:team)
        .by_name(filters['name'])
        .by_team(filters['team_id'])
        .order("#{filters['column']} #{filters['direction']}")
end

Now we can start to see the benefit of the work we did in the last section. We can add filtering by a new option with just a few simple changes to the model.

We updated the model to add team_id to the list of valid FILTER_PARAMS, added the by_team scope, and then added by_team to the filters method.

No need to change our controller or touch the Filterable module — updating the model is all we need.

Refresh the page, apply a team filter and see that filtering by team works along with searching by name and sorting. Great work!

Filtering the index action

We’ll wrap up this exercise by make a few more small adjustments to avoid weirdness when a user visits the /players with filtering values already saved in their session.

First, now that we have access to the filter! method, we can update the index action to use that method instead of always setting the value of players to all players in the database.

To do that, update index in app/controllers/players_controller.rb like this:

def index
  @players = filter!(Player)
end

With that change in place, we’ll now filter the list of players properly when a user reloads players page after applying filters in a previous request, making the experience on the index page a bit more consistent.

Finally, since we’re using the session values to restore previously applied filters, we need to update the name search field to set its value from the session. Without this change, when the user applies a name search and then refreshes the page, the list of players will be filtered by name, but the search term won’t be visible in the name field.

To fix this issue, update the name field in the players partial like this:

<%= form.text_field :name,
  placeholder: "Search by name",
  value: session.dig('player_filters', 'name'),
  class: "border border-blue-500 rounded p-2",
  autocomplete: "off",
  data: { action: "input->search-form#search" }
%>

With value added to the name field, we’ll always show the correct value to users, even on the initial page load.

With these small changes in places, we’ve now got consistent filtering experience that persists cleanly across requests and can be extended with new options as our user experience requirements change.

Nice work making it this far!

You've reached the end of the tutorial portion of the article, we'll finish up by discussing a few ways we could improve this implementation in a production application.

Production-grade considerations

While what we built today works fine, there are some things to consider if we were building a real, consumer-facing application.

Our code works and is pretty easy to maintain, but before we go, let’s touch on a few points to think about for production-grade applications. These are intended simply as things to think about as you build, and we won’t be going through any code here:

Session storage limitations

We are relying on the session object to store filter options. This is fine for small applications, but as you grow, you may run into the limits of storing options like this in the session.

By default, Rails stores the session in a cookie which can only be ~4kb before it will start raising errors. You can use a different session store but you may want to consider a more flexible solution for storing filter options.

One option here is to use Kredis, a Redis-based solution that provides a nice interface for solving problems like our session persistance problem today.

Replace helper methods

The helper methods we are using to render sorting links and indicators could be implemented as ViewComponents.

This pattern allows us to write more testable and reusable view code and excels in cases like our example application. As this application grows, we should expect to have multiple tables across our application that all need sort links.

Rather than implementing them as helpers that are very specific to the players table, we could create them as generic components that can be thoroughly tested and then reused throughout the code base.

Expand Filterable implementation

Right now, Filterable relies on each model to define FILTER_PARAMS and a filter method from scratch.

In the real world, there would likely be enough overlap between the different implementations of filter in each model that we would benefit from moving filter out of each model and into a Filter class that defines some shared logic, like applying order, which is likely to be the same for every class.

For a really detailed implementation of a Filterable pattern, take a look at the filterable_reflex from StimulusReflex Patterns.

Wrapping up

Today we built on a Turbo Frame foundation to expand a sortable table view to a table that can be searched, filtered, and sorted without full page turns or lots of custom JavaScript.

Because frames are so powerful, we were able to easily hook into our existing frame code and add in searching and filtering without thinking too much about the front end implementation. It mostly just worked, once we built the filtering logic on the server.

This is the power of Turbo Frames — we can build fast, efficient user interfaces without stepping much outside of standard Rails code. The client side code stays light and maintainable, while our server looks and feels familiar to any level of Rails developer.

To dig deeper into Turbo and building modern Ruby on Rails applications with the Hotwire stack:

Read my articles on Turbo Frames and Turbo Streams on Rails
Dive into the Turbo and turbo-rails source and follow along with the Github activity for both
Join the hotwire discussion forums
(Shameless plug) Sign up for my monthly newsletter, Hotwiring Rails, to stay up to date on the latest developments in Rails-land

That’s all for today. As always, thanks for reading!

Turbo Frames on Rails

David Colby — Sat, 09 Oct 2021 13:47:04 +0000

urbo, part of the Hotwire tripartite, gives you the tools to write dramatically less custom JavaScript than you would otherwise need to build modern, performant web applications.

Turbo is composed of Turbo Drive, Turbo Frames, Turbo Streams, and Turbo Native. Each is a valuable piece of the puzzle but today we’re going to focus on Turbo Frames.

Turbo Frames “allow predefined parts of a page to be updated on request.” Used wisely, frames allow developers to decompose their UI into independently updated pieces, quickly.

Why should I use Turbo Frames?

Turbo Frames unlock a huge amount of potential with minimal changes to existing code and they can be gradually introduced to existing projects without necessitating major architectural changes.

In greenfield projects designed with Turbo Frames in mind, a small team of developers can use frames to deliver fast, efficient user interfaces in dramatically less time than would be required when build a SPA-powered front end.

While Turbo Frames can be used with many different tech stacks, Rails developers will find the tight integration of frames into Rails (via the turbo-rails gem) makes using frames in Rails a breeze.

The Turbo documentation gap

As with many new technologies, one of the barriers to getting started with Turbo Frames is inconsistent/incomplete documentation. Along with problems in the official documentation, much of the tutorial content written about Turbo Frames is already out of date.

Turbo has evolved quickly since its release in December of 2020, and the documentation and supporting tutorials from content creators have struggled to keep pace.

As an example of the documentation gap, turbo-rails doesn’t have any dedicated usage documentation, instead just linking to the base Turbo docs and letting users figure out the rest.

This means that learning to use Turbo Frames in your Rails application today often requires reading the docs, then digging through source code, and then Googling your way through Github issues and forum posts. Turbo Frames can be difficult to approach.

In time the documentation will improve and the community will coalesce around best practices and standards that can be more easily communicated to new users.

In the meantime, here we are.

What is this article? Who is it for?

Today, I’m going to share what I’ve learned over nearly a year building applications with Turbo Frames, from small hobby projects and experiments to multiple large, legacy production applications.

By doing so, I’m hoping to address the gaps in documentation, to save you from spending too much time reading source code, trawling forum posts and Github issues.

I will cover content you can find in the documentation (if you know where to look), gotchas and tricks learned from real world experience and picked up from reading way too much about Turbo and Turbo Frames since Turbo’s initial release. I’ll also share patterns that illuminate some of the common web application needs that frames are perfect for.

This content is geared towards Rails developers interested in using Turbo. The code samples and concepts will be illustrated using Ruby and Rails code and conventions. If you aren’t working in Rails, you should still find plenty of value here, but know that you may not have access to convenience methods like <%= turbo_frame_tag %> in your chosen language and framework.

Let’s dive in!

What are Turbo Frames?

At a high level, Turbo Frames are pieces of a webpage that can be updated independently, without impacting the rest of the content on the page.

Links and forms within a frame will, by default, attempt to update only the content of the containing frame, whether the server sends a completely new HTML document or only a page fragment.

Turbo Frames allow developers to decompose a page into pieces of content that can be updated individually as new information is received from a server.

In practice, common use cases for Turbo Frames include:

Tabbed content
In-line editing
Searching, sorting, and filtering data

Let's start looking at code.

Constructing a frame

A basic Turbo Frame, rendered with the built-in helper from Turbo Rails (and using erb), looks like this:

<%= turbo_frame_tag "some_id" do %>
  <div>
    Some framed content
  </div>
<% end %>

The only required argument for turbo_frame_tag is an id.

When the helper is processed, the final HTML is:

<turbo-frame id="some_id">
  <div>
    Some framed content
  </div>
</turbo-frame>

Instead of providing a static id, we can also pass in an active record object, which the helper will use to generate a unique id via dom_id(object.id).

<%= turbo_frame_tag Comment.first %>

Frames can also receive an src attribute. When src is supplied, the frame will be populated after the initial page load via a separate HTTP request to the frame’s src:

<%= turbo_frame_tag "comments", src: comments_path do %>
  <div>
    Placeholder content
  </div>
<% end %>

Here, the page will initially load the turbo frame with the placeholder div and then immediately a request to comments_path endpoint is made and the content of the Turbo Frame is replaced with the response from the server, provided our server returns HTML with a matching Turbo Frame tag.

What’s a matching Turbo Frame tag? Let’s look at that next.

Responding with frame content

The power of Turbo Frames is in replacing pieces of the page with content sent from the server — without touching the rest of the DOM.

Updating an existing frame just requires responding to a request with HTML that contains a Turbo Frame element with an id that matches the id of the frame target sent in the request.

Taking the comments example from above, when a request is made to /comments, the server should respond with HTML that contains a frame like this:

<turbo-frame id="comments">
  <!-- A list of comments, perhaps -->
</turbo-frame>

The content inside of the matched frame is replaced with the updated content from the server, without touching the rest of the page.

Navigating within frames

By default, links and forms within a Turbo Frame will perform the navigation within the frame, rather than performing a full page turn.

For a simple example, we can imagine that we have a list of comments on a page and that each comment is wrapped in a Turbo Frame tag, like this:

<% @comments do |comment| %>
  <%= turbo_frame_tag comment do %>
    <div>
      <%= link_to comment.body, edit_comment_path(comment) %>
    </div>
  <% end %>
<% end %>

This ERB results in rendered HTML:

<turbo-frame id="comment_1">
  <div>
    <a href="/comments/1/edit">Comment 1</a>
  </div>
</turbo-frame>
<turbo-frame id="comment_2">
  <div>
    <a href="/comments/2/edit">Comment 2</a>
  </div>
</turbo-frame>
<turbo-frame id="comment_3">
  <div>
    <a href="/comments/3/edit">Comment 3</a>
  </div>
</turbo-frame>

With this Turbo-powered HTML in place, clicks on the edit links will make a Turbo Frame request to /comments/:id/edit, retrieve some HTML, and return that HTML to the browser.

The Turbo Frame request is a normal HTML request with an additional Turbo-Frame header included in the request, with a value that matches the id of the target Turbo Frame.

In turbo-rails, the presence of this header can be used to identify a Turbo Frame request and respond with appropriate content, like this:

# This approach gets messy in controller actions. Read further on for a variant based approach that scales much more cleanly
if turbo_frame_request?
  render partial: "some_turbo_frame_partial"
else
  render partial: "some_other_partial"
end

When turbo-rails responds to a Turbo Frame request, it automatically removes the layout from the HTML response. Since Turbo will discard all of the HTML but the requested frame, Rails skips rendering content that it knows won't be used.

When a response to a Turbo Frame request is received, Turbo Drive replaces the content of the target frame, leaving the rest of the page untouched.

Continuing with the above comments example, the edit view may look something like this:

<%= turbo_frame_tag @comment do %>
  <%= form_with(model: @comment) do |form| %>
    <div class="inline-field">
      <%= form.label :body %>
      <%= form.text_field :body %>
    </div>
    <div class="actions">
      <%= form.submit %>
    </div>
  <% end %>
<% end %>

After clicking to edit a comment then, the updated HTML after Turbo processes the response would look something like this:

<!-- Form content rendered from /edit -->
<turbo-frame id="comments_1" src="http://localhost:3000/comments/1/edit">
  <form action="/comments/1" accept-charset="UTF-8" method="post">
    <input type="hidden" name="_method" value="patch">
    <input type="hidden" name="authenticity_token" value="some_token">
    <div class="inline-field">
      <label for="comment_body">Body</label>
      <input type="text" value="Comment 1" name="comment[body]" id="comment_body">
    </div>
    <div class="actions">
      <input type="submit" name="commit" value="Update Comment">
    </div>
  </form>
</turbo-frame>
<!-- The other frames, untouched by the /edit request -->
<turbo-frame id="comment_2">
  <div>
    <a href="/comments/2/edit">Comment 2</a>
  </div>
</turbo-frame>
<turbo-frame id="comment_3">
  <div>
    <a href="/comments/3/edit">Comment 3</a>
  </div>
</turbo-frame>

Finishing up this example, what happens when the user submits the comment form?

After submit in a normal Rails action, we might redirect the user to the comment show page. When the request occurs within a Turbo Frame, a “redirect” still occurs, but rather than redirecting the page in the browser, the redirect is followed, the new HTML content is sent from the server, and that HTML is used to update the frame.

In our example, the comment#update controller action might look like this:

def update
  respond_to do |format|
    if @comment.update(comment_params)
      format.html { redirect_to @comment }
    else
      format.html { render :edit, status: :unprocessable_entity }
    end
  end
end

And the show view:

<%= turbo_frame_tag @comment do %>
  <div>
    <%= link_to @comment.body, edit_comment_path(@comment) %>
  </div>
<% end %>

This behavior allows us to build Turbo Frame-powered interfaces while making very few or no changes to a standard Rails controller, making it possible to prototype in Rails very quickly.

With just what we’ve learned so far, we’re already in position to start building simple interfaces with Turbo Frames that allow us to add significant amounts of interactivity to our application with very few changes to the Ruby and HTML we’d have in any Rails app.

Let’s keep exploring, there’s plenty more to see.

Breaking out of a frame

While navigating within a frame is very handy, sometimes, a form or link within a frame needs to break out of the frame and perform a normal page turn.

To add that behavior to a navigation element within a frame, simply add data-turbo-frame="_top" to the element, like this:

<%= link_to comment.body, edit_comment_path(comment), data: { turbo_frame: "_top" } %>

Targeting a frame from the outside

Eventually, you’ll find yourself needing to update the content of a frame using a link that isn’t wrapped in your target frame. This often comes up when building tabbed content; the navigation menu will be placed outside of the Turbo Frame that contains the actual content.

To handle situations like this, we can use the same turbo-frame data attribute to tell Turbo that the navigation should occur in a specific turbo frame.

Using our tabbed content example, we may have a page layout like this:

<ul>
  <li>
    <a href="user/1/profile" data-turbo-frame="main">
      Profile
    </a>
  </li>
  <li>
    <a href="user/1/favorites" data-turbo-frame="main">
      Favorites
    </a>
  </li>
</ul>
<turbo-frame id="main"></turbo-frame>

Clicks on either of the user links will generate a request with a Turbo-Frame: main header and the response will update the content of the main turbo frame, even though the links are not wrapped within the frame.

Lazy loading Frames

The src attribute on a frame can be combined with loading=lazy to mark a frame as lazy-loaded. Lazy-loaded frames will not fetch their content from the server until they’re visible on the page.

Lazy loading is especially helpful for modals, popovers, and other non-critical, below-the-fold content.

Lazy loaded frames can be combined with a spinner or other loading indicator, like this:

<%= turbo_frame_tag "lazy_frame", src: comments_path, loading: "lazy" do %>
  <div>I'm a loading spinner</div>
<% end %>

Note that loading="lazy" must be combined with a src attribute, otherwise lazy loading does nothing

Frame events

Turbo comes packed with lifecycle events, including two frame specific events:

turbo:frame-render
turbo:frame-load

These events (added in Turbo 7.0.0-rc2) fire each time a frame is loaded or reloaded. Developers can use these events to attach behavior to an element within a frame or animate the entry of a frame element, and they pair nicely with Stimulus.

In addition to these built in events, a useful complement to the emitted events is the busy attribute. The busy attribute is automatically applied to a frame when a request for the frame’s content begins and is removed when the request finishes.

// From Turbo's source code: turbo/src/core/frames/frame_controller.ts
requestStarted(request: FetchRequest) {
  this.element.setAttribute("busy", "")
}

requestFinished(request: FetchRequest) {
  this.element.removeAttribute("busy")
}

This attribute can be useful for adding loading indicators to long running requests and otherwise tracking the state of frames between the beginning of a frame request and the turbo:frame-render and turbo:frame-load events firing.

Refreshing Frames

Sometimes, users need the ability to refresh the contents of a frame without refreshing the entire page.

In ideal circumstances, a Turbo Stream broadcast automatically updates the contents of the frame without needing a manual refresh, we don't always get to work in ideal circumstances.

In earlier versions of Turbo, refreshing a frame required workarounds like appending a timestamp to the src attribute. Today, those workarounds are no longer necessary and Turbo will happily update a frame any number of times with an indentical src on each request.

We can build a refreshable frame like this:

<%# app/views/games/show.html.erb %>
<%= turbo_frame_tag @game do %>
  <div><%= @game.home_score %></div>
  <div><%= @game.away_score %></div>
  <%= link_to "Update score", game_path(@game) %>
<% end %>

Here, the first time a user clicks the update link, the turbo-frame will be updated with an src like this:

<turbo-frame id="game_10" reloadable="" src="http://localhost:3000/games/10">

Additional clicks on the update link will fetch updated scores from the server and reload the content of the frame.

Note that a currently open PR (as of the time this article was last updated, December 2021) proposes an alternative implementation of reloadable frames that will prevent the reloadable attribute from being exposed while keeping the behavior intact. In future versions of Turbo the reloadable attribute may not longer exist or be neccessary.

Conditional template rendering using variants

As you use Turbo Frames in Rails, you’ll eventually run into the desire to have a single controller action respond to both Turbo Frame requests and regular, full-page requests.

A common example of this is rendering a /new page as both a standalone page and as frame content inside of a modal. You could implement a conditional in your controller action to check for the Turbo Frame header, but that quickly starts to clutter up your controllers.

An alternative approach is to use variants to render different content based on the inbound request headers, to keep your controllers cleaner.

class ApplicationController < ActionController::Base
  before_action :turbo_frame_request_variant
  private

  def turbo_frame_request_variant
    request.variant = :turbo_frame if turbo_frame_request?
  end
end

This approach adds a before_action to the ApplicationController that checks if the inbound request is a Turbo Frame request using the turbo_frame_request? method provided by turbo-rails. When the request is a turbo frame, Rails will look for a Turbo Frame variant (new.html+turbo_frame.erb, for example) and render that variant when it exists. Otherwise, the default html.erb view will be used

This approach was originally described here. While there was a proposal to add this variant-based approach to turbo-rails, those proposals were rejected. The guidance from the maintainers is that the turbo_frame_request? to detect Turbo Frame requests is the only support that will be added because "If you're branching all your responses for frames vs not, something isn't right, and we should investigate those pressures in a different way.".

In my experience, judicious use of variants to serve different content for Frame requests is sometimes the simplest and cleanest path to achieve a desired outcome but YMMV.

Limitations & Gotchas

Turbo Frames and page layouts

Turbo Frames in the DOM are implemented as custom HTML elements (the <turbo-frame> tag we've seen in this article). We can add classes to them (<%= turbo_frame_tag post, class: "classes" %>) and style them; however, because they exist in the DOM and need to wrap their content to be useful, inserting them into existing layouts can cause issues without some planning.

In particular, you can’t place a frame inside of a table row. While there are workarounds for this, it is worth knowing that tables and Turbo Frames don’t play well together out of the box.

In addition to table issues, you may sometimes run into layout issues with flex box and grid layouts when frames are the direct descendant of the container element. You'll sometimes find that your nicely spaced three element flex layout now breaks because all three elements need to be wrapped in a single <turbo-frame> tag.

A route worth exploring in these situations is adding display: contents to the <turbo-frame> element, as mentioned here.

Responding to a Turbo Frame request without a matching Turbo Frame

As you build applications with Turbo Frames, you will inevitably run into an issue in development where you click a link within a frame and all of the content within the frame disappears. You’ll check the Rails logs and see the view you expected was rendered without errors.

Why did everything disappear?

The first thing to do when this happens is to check the JavaScript console for errors. Turbo’s JavaScript expects that the HTML response to a Turbo Frame request will contain a matching Turbo Frame element. If no match is found, Turbo will empty the frame of all content and raise an error like this in the JavaScript console:

Response has no matching <turbo-frame id="target_id"> element

This can be a little confusing at first, since the content renders fine from the server but once you get used to Turbo processing the rendered HTML and updating the DOM, you’ll be able to quickly debug missing frame element errors like this one.

When in doubt, check for JavaScript errors.

Updating page URL when navigating within frame

When a user clicks on a link within a frame, the URL of the page won’t change. This makes sense most of the time — the user hasn’t navigated to a new page, they’ve simply updated some of the content on the existing page.

One use case where the URL not changing can be problematic is when the user is applying sorting and filtering options by clicking links within a frame. Imagine a table layout with links to sort the table by each column, for example.

In those cases, a developer may wish to update the URL of the page to reflect the currently applied filters so that the user can copy/paste the URL to share a specific view of the table.

As of Turbo's 7.1 release, developers can now update the page URL from a frame navigation by adding a turbo-action data attribute to the form or link that triggers the frame navigation. Options for turbo-action are replace, to replace the current URL in the browser's history, or advance, to push a new entry in the history. When building search forms, you'll likely want to use advance to update the page URL with each new search. In Rails, using a standard form_with search form, your code to push frame navigation into the browser's history might look like this:

<%= form_with url: customers_path, method: :get, data: { turbo_frame: "customers", turbo_action: "advance" } do |form| %>
  <%# Some form content goes here %>
<% end %>

Wrapping up

Today we looked in detail at the current state of Turbo Frames — what they are, how to use them in Rails, and the some of the ways frames can help you build modern, efficient applications.

Turbo Frames in Rails applications naturally pair very well with Stimulus and work exceptionally well when paired with Turbo Streams to manage broadcasted updates and more targeted content updates.

With Hotwire coming by default to new Rails 7 applications, I'm happy to report that after a year of use, building Ruby on Rails applications with the Hotwire stack is simple, straightforward, and adds very little overhead to your development experience. For mnay Rails applications, all of the reactivity you need can be achieved with the Hotwire stack, and Turbo Frames will play a key role in many applications in the years to come.

While you begin to experiment, keep in mind that Turbo is still in very active development. Throughout this article, I linked to open PRs that will improve Turbo Frames and make some of the techniques described in this article simpler to implement — as time goes on, expect Turbo and Turbo Frames to continue to improve and for turbo-rails to continue to add functionality to help Rails developers use frames effectively in their applications.

Ready to go deeper? (Some shameless self-promotion ahead, sorry!)

I wrote about using the Hotwire stack to build server rendered modal forms in Rails
Build a typeahead search interface with Turbo Frames
Use a Turbo Stream + Turbo Frame combo to render different content to different users from a single stream broadcast
Read my exploration of Turbo Streams
Sign up for my monthly newsletter to stay up to date on modern Ruby on Rails development

That’s all for today. As always, thanks for reading!

Sort tables (almost) instantly with Ruby on Rails and Turbo Frames

David Colby — Mon, 20 Sep 2021 13:10:31 +0000

One of the wonderful things about working in Rails in 2021 is that we are spoiled for options when it comes to building modern, reactive applications. When we need to build highly interactive user experiences, we don’t need to reach for JavaScript frameworks like Vue or React — the Rails ecosystem has all the tools we need to deliver exceptionally fast, efficient, and developer friendly front ends.

Yesterday, I published an article demonstrating a simple implementation of a sortable table with StimulusReflex. Today, we’re going to build the same experience with Turbo Frames instead.

Why build the same thing with two different tools? Because we have great options to choose from in Rails-land, and understanding each option is a great place to start when considering which tool is right for you and your team.

Like yesterday, our application is going to allow users to view a table of players. They’ll be able to click on each header cell to sort the table in ascending and descending order.

Sorting will happen very quickly, without a full-page turn, and we won’t be writing any custom JavaScript or doing anything outside of writing ordinary Ruby code and ERB templates.

When we’re finished, the application will work like this:

You can demo the application for yourself on Heroku (the free dyno may need a moment to wake up when you visit it) or view the complete source on Github.

This article assumes that you are comfortable building applications with Ruby on Rails and may be difficult to follow if you have never worked with Rails before. Previous experience with Turbo Frames is not required.

Let’s get started!

Setup

To begin, we’re going to create a new Rails application, skipping webpacker in favor of the newly released css and jsbundling gems.

If you prefer skipping the setup steps, you can clone down the example repo from Github. The main branch is pinned to the end of the setup process and ready for you to start building.

This article is being written using Rails 6.1. When Rails 7 releases, the install command listed below will change. Until then we need to manually add the bundling gems to our Gemfile.

First, from your terminal:

rails new player_sort_frames --skip-javascript --skip-webpack-install --skip-turbolinks
cd player_sort_frames
bundle add cssbundling-rails jsbundling-rails hotwire-rails faker
rails g model Team name:string                                                  
rails g scaffold Player name:string team:references seasons:integer
rails db:migrate

Here, in addition to the bundling gems, we added Faker to our project to allow us to quickly add seed data to the database and added a Team model and Players resource to our project.

The core of our application will be a list of players, we won’t interact with Teams directly so we skip adding a controller and views for Teams.

Next up, we’ll use the new bundling gems to install webpack to handle our JavaScript and Tailwind for CSS. From your terminal:

rails javascript:install:webpack
rails css:install:tailwind

Finally, we’ll wrap up setup by installing Hotwire in our application. Technically, we only need Turbo for this project, but having Stimulus setup won’t hurt anything. One more time, from your terminal:

rails hotwire:install

With everything installed, you can start up the server and build your assets with bin/dev from your terminal.

Build table layout

We’ll begin by updating the players index page to display a nicely styled table of all of the players in the database. Rails’ scaffolding gets us most of the way there, but instead of rendering the players table in index.html.erb we’ll move the table to a partial.

This partial will come in handy later when we use Turbo Frames to sort the list of players.

First, update app/views/players/index.html.erb like this:

<div class="max-w-7xl mx-auto mt-12">
  <%= render "players", players: @players %>
</div>

The index is now rendering a partial (players) that hasn't been created yet, so we'll create that partial next.

From your terminal:

touch app/views/players/_players.html.erb

And fill the partial in like this:

<div class="shadow overflow-hidden rounded border-b border-gray-200">
  <table class="min-w-full bg-white">
    <thead class="bg-gray-800 text-white">
      <tr>
        <th id="players-name" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
          <span>Name</span>
        </th>
        <th id="players-team" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
          <span>Team</span>
        </th>
        <th id="players-seasons" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
          <span>Seasons</span>
        </th>
      </tr>
    </thead>

    <tbody class="text-gray-700">
      <% players.each do |player| %>
        <tr>
          <td class="text-left py-3 px-6"><%= player.name %></td>
          <td class="text-left py-3 px-6"><%= player.team.name %></td>
          <td class="text-left py-3 px-6"><%= player.seasons %></td>
        </tr>
      <% end %>
    </tbody>
  </table>
</div>

This partial simply renders a table that contains a header row and then rows for each player in the players variable. The classes are all built-in Tailwind classes that are not integral to the function of the application.

Now we’ve got a nice looking table ready to display our players, but no players in the database! Let’s fix that by creating enough seed data that we can see sorting in action.

First, update db/seeds.rb:

['Dallas Mavericks', 'LA Clippers', 'LA Lakers', 'San Antonio Spurs', 'Boston Celtics', 'Miami Heat', 'New Orleans Pelicans'].each do |name|
  Team.create(name: name)
end

100.times do
  Player.create(name: Faker::Name.name, team: Team.find(Team.pluck(:id).sample), seasons: rand(25))
end

And then from your terminal, seed the database:

rails db:seed

If you haven’t already, boot up the app and build assets with bin/dev from your terminal, and then head to localhost:3000/players and see the list of randomly generated players, ready to sort.

Now that we’ve got our table populated and displaying, let’s start on the fun stuff by making the table sortable with Turbo Frames.

Add turbo frame sorting

As a reminder, our goal is for users to be able to click on a table header to sort the table by that column. We want sorting to happen without a page turn, and we want to use a Turbo Frame to update the list of players in the UI.

To start, we’ll convert the wrapper div in the players partial to a turbo_frame_tag with an id of players and the same classes that the wrapper div had. In app/views/players/_players.html.erb:

<%= turbo_frame_tag "players", class: "shadow overflow-hidden rounded border-b border-gray-200" do %>
  <table class="min-w-full bg-white">
  <!-- snip -->
  </table>
<% end %>

Don’t forget to replace the closing </div> with the <% end %> tag!

Now that the players turbo frame wraps the content of the table, links inside of this frame will automatically attempt to replace the content of the turbo frame with the content they receive from the server.

We’ll come back to this concept in a minute, but first, let’s build out the remainder of the code we need for the first pass at sorting the table.

Next, inside of the players partial still, update the table header like this:

<thead class="bg-gray-800 text-white">
  <tr>
    <th id="players-name" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
      <%= sort_link(column: "name", label: "Name") %>
    </th>
    <th id="players-team" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
      <%= sort_link(column: "teams.name", label: "Team") %>
    </th>
    <th id="players-seasons" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
      <%= sort_link(column: "seasons", label: "Seasons") %>
    </th>
  </tr>
</thead>

Here we’ve replaced the static text labeling each column with a call to the sort_link helper method, passing in a column and a label for each header cell.

This helper method doesn’t exist yet, so let’s add that next. In app/helpers/players_helper.rb:

module PlayersHelper
  def sort_link(column:, label:)
    link_to(label, list_players_path(column: column))
  end
end

sort_link renders a standard Rails link_to, using label to display the link to the user, and column to append a parameter to the generated URL.

The link_to points to list_players_path, which we haven’t defined yet. Let’s do that next, in config/routes.rb:

resources :players do
  collection do
    get 'list'
  end 
end

And finally, we need to update our controller to define an action for the new list route we’ve added.

In app/controllers/players_controller.rb, add a new list method, like this:

def list
  players = Player.includes(:team).order("#{params[:column]} asc")
  render(partial: 'players', locals: { players: players })
end

Here we’ve defined a new controller action that queries the database for all of the players, includes the teams table in the query, and orders the players using the value of params[:column].

The includes(:team) is necessary both to allow sorting players by their team name and for performance, since the players partial makes a call to player.team.name to display the players name on each row.

Once the players are retrieved, the players partial is rendered and sent back to the browser.

With the controller update in place, refresh the page, click on a column header, and, if all has gone well, you should see that the list of players is updated (almost) instantly with the correct column sorting applied.

When you sort by a column, you should see output in your server logs like this:

Started GET "/players/list?column=seasons"
Processing by PlayersController#list as HTML
  Parameters: {"column"=>"seasons"}
  Player Load (0.5ms)  SELECT "players".* FROM "players" ORDER BY seasons asc
  ↳ app/views/players/_players.html.erb:18
  Team Load (0.2ms)  SELECT "teams".* FROM "teams" WHERE "teams"."id" IN (?, ?, ?, ?, ?, ?, ?)  [["id", 3], ["id", 1], ["id", 2], ["id", 6], ["id", 4], ["id", 5], ["id", 7]]
  ↳ app/views/players/_players.html.erb:18
  Rendered players/_players.html.erb (Duration: 5.9ms | Allocations: 3994)
Completed 200 OK in 7ms (Views: 5.6ms | ActiveRecord: 0.6ms | Allocations: 4224)

Nice work so far, let’s pause here to step back and talk about how this all ties together.

We started by wrapping the players table in a Turbo Frame with an id of players. Then we added a link to each of the header cells, pointing to players/list.

Because the link is wrapped in a turbo frame, when the response is sent back from the server, Turbo scans the response for a turbo frame with the same id (players) and replaces the existing frame content with the new frame content.

In our case, this means that the updated list of players, rendered by players/list, replaces the content of the players table without touching the rest of the page.

This use of Turbo Frames, to replace the content of a matching frame, is the simplest approach to using Turbo Frames.

In more advanced cases, we can have a link inside of a frame break out of a frame, with target=_top or use data-turbo-frame to tell Turbo that a link from outside of a frame should target that frame.

Turbo Frames enable us to make fast, efficient page updates without adding significant complexity to our code.

Now that we’ve got a little more context for how Turbo Frames are enabling sorting in our application, let’s finish up by adding the ability to sort in both ascending and descending order and inserting a visual indicator when sorting is applied.

Add descending sorting

We want users to be able to sort in descending order by clicking on the same column header twice in a row. The first click will sort in ascending order, the next click will sort in descending order.

Here’s a demonstration of the desired user experience for this section of the article:

First, we’ll modify the sort_link helper that we added in the last section to send a direction as well as a column in the list request.

In app/helpers/players_helper.rb:

def sort_link(column:, label:)
  if column == params[:column]
    link_to(label, list_players_path(column: column, direction: next_direction))
  else
    link_to(label, list_players_path(column: column, direction: 'asc'))
  end
end

def next_direction
  params[:direction] == 'asc' ? 'desc' : 'asc'
end

sort_link now adds a second parameter into the link_to. The new direction parameter is set to the value of the next_direction helper method if we are generating the sort link for a column that is being used for sorting; otherwise, direction is set to ascending.

next_direction simply inverts the current sort direction so the sort direction changes with each click.

Next we’ll update the list method in players_controller.rb to use the new direction parameter in the order clause:

def list
  players = Player.includes(:team).order("#{params[:column]} #{params[:direction]}")
  # snip
end

With this change in place, we can now sort our table in either direction. Incredible stuff, nice work making it this far!

One more set of changes left: Giving users feedback in the UI that sorting is active.

Add visual indicator of sort direction

Our final task is to add an indicator next to the column name when that column is being used to sort the table. The indicator will be a small triangle, pointing up when sorting in ascending order and down when sorting in descending order.

We’ll start by updating the table header in the players partial like this:

<thead class="bg-gray-800 text-white">
  <tr>
    <th id="players-name" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer relative">
      <%= sort_indicator if params[:column] == "name" %>
      <%= sort_link(column: "name", label: "Name") %>
    </th>
    <th id="players-team" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer relative">
      <%= sort_indicator if params[:column] == "teams.name" %>
      <%= sort_link(column: "teams.name", label: "Team") %>
    </th>
    <th id="players-seasons" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer relative">
      <%= sort_indicator if params[:column] == "seasons" %>
      <%= sort_link(column: "seasons", label: "Seasons") %>
    </th>
  </tr>
</thead>

Here we’ve added a conditional call to sort_indicator into each header cell.

Since we only want to add the indicator when the column is being used to sort the table, we use if params[:column] to skip the sort_indicator call on inactive columns.

We also added relative to the <th> elements class lists because the sort indicator will be absolutely positioned inside of the header cell.

Next up, we’ll define sort_indicator in app/helpers/players_helper.rb:

def sort_indicator
  tag.span(class: "sort sort-#{params[:direction]}")
end

sort_indicator simply returns a span with a class that matches the current sort direction, read from params[:direction]

Finally, we’ll add css so our sort indicator isn’t just an invisible span on the page.

For convenience, we’ll insert the css right into app/assets/stylesheets/application.css

.sort {
  position: absolute;
  top: 1rem;
  left: 0.5rem;
  width: 0;
  height: 0;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
}

.sort-desc {
  border-top: 8px solid #fff;
}

.sort-asc {
  border-bottom: 8px solid #fff;
}

With the CSS added and our new sort_indicator helper defined, refresh the page, click on the column headers, and see that the table is sorted and a visual indicator is shown for the current column and sort direction:

Great job following along, we've reached the end of the code for today!

Wrapping up

Today we learned how to build a sortable table with Rails and Turbo Frames. Our table can be sorted without a page turn, and we built the interface using basic set of tools familiar to any Rails developer.

While our table only supports sorting today, our frame-based approach can be enhanced to support filtering and searching without deviating from the core concept of using Turbo Frames to display and update the table.

Turbo Frames, along with the rest of the Hotwire stack, give Rails developers the ability to quickly build fast, modern user experiences without adding the weight and complexity that can come with JavaScript frameworks.

You'll note that I did not compare the approach in this article directly to the approach in yesterday's article where we built the same UI with StimulusReflex. Rather than attempting a direct, side-by-side comparison, I prefer presenting both options as standalone projects that show how to build simple experiences using each tool so that readers can learn how each tool works, begin experimenting, and see which feels right.

Both StimulusReflex and Turbo (Frames and Streams) can deliver world-class user experiences in production applications while providing an unbeatable developer experience. The right choice for you and your team is almost certain to be the option that your team feels most comfortable with and most productive in.

Whichever routet you choose, with the Hotwire stack, StimulusReflex, and CableReady available, Rails is well-positioned for the future.

If you’re ready to go further with on your Turbo journey, here are a few places to start:

Review the Turbo documentation
Dive in to the Turbo Rails source code on Github
Spend time with Stimulus, the other side of the Hotwire stack
Learn from the community in the Hotwire discussion forum
Join the StimulusReflex discord, where folks will happily help you learn more about building reactive web applications with Rails

That’s all for today. As always, thanks for reading!

Sort tables (almost) instantly with Ruby on Rails and StimulusReflex

David Colby — Sun, 19 Sep 2021 14:03:38 +0000

Today we’re going to use Ruby on Rails and StimulusReflex to build a table that sorts itself each time a user clicks on a header column.

Sorting will occur without a page turn, in less than 100ms, won't require any custom JavaScript, and we'll build the whole thing with regular old ERB templates and a little bit of Ruby.

The end result will be very fast, efficient, simple to reason about, and easy to extend as new functionality is required.

It'll be pretty fancy.

When we're finished, it will work like this:

You can view the finished product on Heroku, or find the full source on Github.

This article will be most useful to folks who are familiar with Ruby on Rails, you will not need any previous experience with Stimulus or StimulusReflex to follow along. If you’ve never worked with Rails before, some concepts here may be a little tough to follow.

Let’s get started!

Setup

As usual, we’ll start with a brand new Rails 6.1 application, with Tailwind and StimulusReflex installed. Tailwind is not a requirement, but it helps us make our table look a little nicer and the extra setup time is worth the cost.

If you’d like to skip the copy/pasting setup steps, you can clone down the example repo and skip ahead to the Building the Table section. The main branch of the example repo is pinned to the end of the setup process and ready for you to start writing code.

If you’re going to follow along with the setup, first, from your terminal:

rails new player_sorting -T
cd player_sorting
bundle add stimulus_reflex
bundle add faker
rake stimulus_reflex:install
rails g model Team name:string
rails g scaffold Player name:string team:references seasons:integer
rails db:migrate

Assuming you’ve got Rails and Yarn installed, this will produce a brand new Rails 6.1 application (at the time of this writing), install StimulusReflex, and scaffold up the Team and Player models that we’ll use to build our sortable table.

If you don’t care to use Tailwind for this article, feel free to skip past this next section, Tailwind is a convenient way to make things look presentable, but if you just want to focus on sorting the table without any styling, Tailwind is not necessary!

If you want to install Tailwind, start in your terminal:

yarn add tailwindcss@latest postcss@latest autoprefixer@latest
npx tailwindcss init
mkdir app/javascript/stylesheets
touch app/javascript/stylesheets/application.scss

And then update tailwind.config.js:

module.exports = {
  purge: [
    './app/**/*/*.html.erb',
    './app/helpers/**/*/*.rb',
    './app/javascript/**/*/*.js',
    './app/javascript/**/*/*.vue',
    './app/javascript/**/*/*.react'
  ],
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

And postcss.config.js:

module.exports = {
  plugins: [
    require("tailwindcss")("./tailwind.config.js"),
    require("postcss-import"),
    require("postcss-flexbugs-fixes"),
    require("postcss-preset-env")({
      autoprefixer: {
        flexbox: "no-2009",
      },
      stage: 3,
    }),
  ],
}

Next we’ll update app/javascripts/stylesheets/application.scss to import Tailwind:

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

And then include that stylesheet in app/javascripts/packs/application.js:

import "../stylesheets/application.scss"

Finally, update the application layout to include the stylesheet generated by webpacker:

<%= stylesheet_pack_tag 'application', 'data-turbolinks-track': 'reload', media: 'all' %>

Whew. We’re through the setup and ready to start building.

Building the table

First up, let’s get our bearings.

The core of our application is the Players resource. We are going to construct a table that displays all of the players in our database, with the players name, their team’s name, and their seasons played as columns.

We’ll only use the Team model created during setup in the context of Players, so we don’t need a controller or views for teams.

We’ll start by moving the table from the players index view to a partial. From your terminal:

touch app/views/players/_players.html.erb

And fill that partial in with:

<div id="players" class="shadow overflow-hidden rounded border-b border-gray-200">
  <table class="min-w-full bg-white">
    <thead class="bg-gray-800 text-white">
      <tr>
        <th id="players-name" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
          <span>Name</span>
        </th>
        <th id="players-team" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
          <span>Team</span>
        </th>
        <th id="players-seasons" class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer">
          <span>Seasons</span>
        </th>
      </tr>
    </thead>

    <tbody class="text-gray-700">
      <% players.each do |player| %>
        <tr>
          <td class="text-left py-3 px-6"><%= player.name %></td>
          <td class="text-left py-3 px-6"><%= player.team.name %></td>
          <td class="text-left py-3 px-6"><%= player.seasons %></td>
        </tr>
      <% end %>
    </tbody>
  </table>
</div>

Most of the markup here is Tailwind classes for styling the table.

The functionally important pieces are the ids set on the wrapper div (#players) and the ids set on the table header cells. These ids will be used later to update the DOM when the user clicks to sort the table.

Next update the index view to use the new partial:

<div class="max-w-7xl mx-auto mt-12">
  <%= render "players", players: @players %>
</div>

With these changes in place, we have a nice looking table ready to display the players in the database, but we don’t have any players. Since we’re going to be sorting, let’s make sure the database has plenty of data in it.

Copy this into db/seeds.rb:

['Dallas Mavericks', 'LA Clippers', 'LA Lakers', 'San Antonio Spurs', 'Boston Celtics', 'Miami Heat', 'New Orleans Pelicans'].each do |name|
  Team.create(name: name)
end

100.times do
  Player.create(name: Faker::Name.name, team: Team.find(Team.pluck(:id).sample), seasons: rand(25))
end

And then, from your terminal:

rails db:seed

Now start up your Rails server and head to localhost:3000/players.

If all has gone well, you should see a table populated with 100 randomly generated players.

Next up, we’ll build our sorting mechanism with StimulusReflex.

Sorting with StimulusReflex

To sort the table, we’re going to create a reflex class with a single action, sort.

When the user clicks on a table header, we’ll call the reflex action to sort the players and update the DOM.

We’ll start by generating a new Reflex. From your terminal:

rails g stimulus_reflex Table

This generator creates both a reflex in app/reflexes and a related Stimulus controller in app/javascripts/controllers.

For this article, we won’t make any modifications to the Stimulus controller. Instead, we’ll focus on the reflex found at app/reflexes/table_reflex.rb

Fill that reflex in with:

class TableReflex < ApplicationReflex
  def sort
    players = Player.order("#{element.dataset.column} #{element.dataset.direction}")
    morph '#players', render(partial: 'players', locals: { players: players })
  end
end

The first line of sort is a standard Rails ActiveRecord query. In it, we retrieve all of the players from the database, ordered by attributes sent from the DOM when the reflex action is triggered.

Reflex actions have access to a variety of properties. In our case, the property we’re interested in is element.

element is a representation of the DOM element that triggered the reflex and it includes all of the data attributes set on that element, accessible via element.dataset.

This means that in reflex actions, we can always access data attributes from the element that triggered the reflex as if we were working with that element in JavaScript. Handy.

For our purposes, we care about two data elements that don’t yet exist in the DOM — column and direction. The ActiveRecord query to retrieve and order players uses those values to know which column to order the results by, and in which direction (ascending or descending) the results should be ordered.

After we’ve retrieved the ordered list of players from the database, we use a selector morph to update the DOM, replacing the content of the players partial we created earlier with the updated list of players.

Our reflex is built, but there’s no way for a user to trigger the reflex. Let’s add that next.

In the players partial, update the header row like this:

<tr>
  <th 
    id="players-name" 
    class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer"
    data-reflex="click->Table#sort"
    data-column="name"
    data-direction="asc"
  >
    <span>Name</span>
  </th>
  <th 
    id="players-team" 
    class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer"
    data-reflex="click->Table#sort"
    data-column="teams.name"
    data-direction="asc"
  >
    <span>Team</span>
  </th>
  <th 
    id="players-seasons" 
    class="text-left py-3 px-6 uppercase font-semibold text-sm hover:cursor-pointer"
    data-reflex="click->Table#sort"
    data-column="seasons"
    data-direction="asc"
  >
    <span>Seasons</span>
  </th>
</tr>

Here we’ve updated each header cell with the three data attributes we need for the reflex to be triggered and to run successfully.

First, data-reflex is used to tell StimulusReflex that this element should trigger a reflex when some action occurs. In our case, it will be called on click.

Each cell also gets a unique data-column value, which we use to sort the players result by the matching database column. Finally, each header cell also starts with a direction of asc which is used to set the direction of the order query.

Let’s look at the Reflex code again and review what’s happening now that we’ve updated the DOM to call this reflex.

def sort
  players = Player.order("#{element.dataset.column} #{element.dataset.direction}")
  morph '#players', render(partial: 'players', locals: { players: players })
end

The sort method we’ve defined matches the name of the data-reflex on each header cell. When the header cell is clicked, this reflex will run.

The header cell that that the user clicks will be passed to the reflex as element, giving us access to the element’s data attributes, which we access through element.dataset.

Once the value of players is set by the database query, we use a selector morph to tell the browser to update the element with the id of players with the content of the players partial, using the updated, reordered list of players.

This is the magic of StimulusReflex in action. With just a couple of data attributes and a few lines of simple Ruby code, our users can now click on a table header and, in < 100ms, they’ll see a table sorted to match their request.

Refresh the page and try it out for yourself. If all has gone well, clicking on a header cell should sort the table by that column in ascending order. While this is nice, we have a few more items to address before our work is complete.

Next up, we’ll address an error with the order query, and then finish this article by modifying the sort reflex to allow users to sort in both ascending and descending order and display visual feedback to indicate what column is being sorted.

Fixing an ordering error

First, sharp eyed readers might have noticed that sorting by the team name column doesn’t work yet.

Each header cell’s column data attribute matches a column in the database, so we can generate the order query dynamically. This works fine for the name and season because those columns live on the Players table. ActiveRecord knows how to order by name and seasons without any extra effort.

For the team name column, we’re passing teams.name to the order call in our query, which ActiveRecord trips over with an error like this:

# The text will vary depending on the database adapter you're using!
Reflex Table#sort failed: SQLite3::SQLException: no such column: teams.name

We can fix this by updating the query slightly:

players = Player.includes(:team).order("#{element.dataset.column} #{element.dataset.direction}")

Here we added includes(:team) to the existing order query, making the Teams table accessible in the order clause and fixing the “no such column” error that was thrown when attempting to sort by team name.

Note that joins instead of includes would also fix the error, but since we need to use team name when we render the players partial (to display each player’s team), includes is the better choice.

Before moving on, you’ll notice that we are using user-accessible values to generate a SQL query — anyone can modify data-attributes in their browser’s dev tools.

Prior to Rails 6, this could have opened up our application to SQL injection; however, since Rails 6, Rails will raise an error automatically if anything but a table/column name + a sort direction are passed in to order.

Adding descending ordering

With the work we've done so far, sorting the table works great as long as the user only wants to sort in ascending (A - Z) order. Since the sort direction is read from a data attribute that is always “asc”, there is no way to sort in descending (Z - A) order. Let's add that functionality next.

Before jumping in to the code, let’s outline the desired user experience.

When a user clicks on a column header, the table should be sorted by that column, in ascending order. When the user clicks on the same column header again, the table should be sorted by that column in descending order. And then we alternate, forever, between ascending and descending on subsequent clicks.

Sorting by a different column should always sort in ascending order on the first click.

Here’s a gif of what we’re aiming for:

To achieve the desired user experience, we need to track the next sort direction for each header cell, so that when the sort reflex is called, the right direction can be sent to the order query.

To do this, we’re going to take advantage of CableReady’s tight integration with StimulusReflex. We’ll update the sort reflex to include a cable_ready operation that changes the direction data attribute of the element that triggered the reflex.

To do this, update TableReflex like this:

def sort
  # snip
  set_sort_direction
end

private

def next_direction(direction)
  direction == 'asc' ? 'desc' : 'asc'
end

def set_sort_direction
  cable_ready
    .set_dataset_property(
      selector: "##{element.id}",
      name: 'direction',
      value: next_direction(element.dataset.direction)
    )
end

Here we’ve added two private methods to the TableReflex class. next_direction is a simple helper method that takes the current value of direction and returns the next value.

set_sort_direction is more interesting. In it, we use CableReady’s set_dataset_property operation to set the value of the element’s direction data attribute to the value of next_direction .

Finally, we call set_sort_direction in the sort reflex, which adds the set_dataset_property operation to the queue each time the sort reflex runs.

With this in place, refresh and click on the same column multiple times to see that each click reorders the table, toggling between ascending and descending order.

Order of operations: Not just for math class

Before moving on, it is important to pause and think about how this code works. When a reflex includes CableReady operations, a specific order of operations is always followed.

First, broadcasted CableReady operations execute. Next, StimulusReflex morphs execute. Finally, CableReady operations that are not broadcasted execute (that’s our set_dataset_property operation).

Because the StimulusReflex morph runs before the CableReady operation, each table header cell has its direction data attribute reset to asc when sort is triggered. This behavior lets us “reset” sort directions when moving between columns without having to add logic in the partial.

Immediately after the StimulusReflex morph, set_dataset_property runs and updates the value of direction on the currently active sort column.

If we appended .broadcast to the set_dataset_property operation, the direction property would be updated before the StimulusReflex morph, causing the CableReady update to be overwritten by the morph, breaking the ability to sort in descending order.

This order of operations is important to understand, and helps unlock a new level of functionality within reflexes.

Before moving on, now that we understand the order of operations in reflex actions, we can use that knowledge to make a small optimization to the sort reflex.

We know that every time the reflex runs, each header cell will have its data-direction value set to asc before the active sort column is updated by the CableReady set_dataset_property operation.

Since the value of data-direction is already asc, if the next sort direction is asc, set_dataset_property won’t do anything useful.

Let’s update sort to skip the CableReady operation in that case:

def sort
# snip
  set_sort_direction if next_direction(element.dataset.direction) == 'desc'
end

Now set_sort_direction will only be run when necessary, simplifying our DOM updates at the cost of slightly more complexity in our ruby code.

Let’s finish up our sortable table implementation by adding a visual indicator to the table when sorting is active.

Sort direction visuals

To indicate which column is being sorted, and in which direction, we’ll draw a triangle with CSS, with an upward pointing triangle indicating ascending order, and a downward triangle indicating descending order.

Only the column that is being used for sorting will display the icon.

When we’re finished, the indicator will look like this:

Let’s start with the CSS.

We’ll insert the CSS directly into our main application.scss file to keep things simple:

.sort {
  position: absolute;
  top: 5px;
  left: -1rem;
  width: 0;
  height: 0;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
}

.sort-desc {
  border-top: 8px solid #fff;
}

.sort-asc {
  border-bottom: 8px solid #fff;
}

We’ll use the base .sort class along with a dynamic .sort-asc or .sort-desc to display the sort indicator. If you’re interested in how this CSS works, this is a nice introduction to drawing shapes with CSS.

With the CSS ready, next we’ll create a partial to render the indicator, from your terminal:

touch app/views/players/_sort_indicator.html.erb

And fill that in with:

<div class="relative">
  <span class="sort sort-<%= direction %>"></span>
</div>

Nothing fancy here, just appending the local direction variable to the class name to ensure our triangle points in the right direction.

We’ll finish up by updating the sort reflex to insert the sort indicator into the DOM, again relying on a CableReady operation that runs immediately after the StimulusReflex morph.

class TableReflex < ApplicationReflex
  def sort
    # snip
    insert_indicator
  end

  private

  # snip
  def insert_indicator
    cable_ready
      .prepend(
        selector: "##{element.id}",
        html: render(
          partial: 'players/sort_indicator',
          locals: { direction: element.dataset.direction }
        )
      )
  end
end

Here we added another private method to the reflex to handle inserting the sort indicator when the sort reflex is called.

insert_indicator uses CableReady’s prepend operation to insert the content of the sort_indicator partial into the DOM, before the target element’s first child.

With this in place, we can refresh the page and see the sort indicator added each time the sort reflex runs, pointing up for ascending sorts and down for descending sorts:

An implementation note

During this article I made a choice to use cable_ready operations to add the sort indicator and update the data attribute.

Instead of cable_ready operations, another approach would be to assign instance or local variables for things like "active column" and "next direction" during the sort reflex. We could then read those variables when rendering the players partial, using them to render the sort indicator and set the next sort direction.

This approach would allow us to eliminate the cable_ready operations; however, doing so would complicate the view. Either approach is fine, my personal preference is to rely on the very fast cable_ready operations to simplify the view.

Using cable_ready also has the added benefit of letting us talk more about how StimulusReflex works, which is a bonus in a tutorial article like this one. As you spend more time with StimulusReflex, experiment with different approaches and find what works best for you.

Wrapping up

Today we built a sortable table interface with Ruby on Rails, StimulusReflex, and CableReady. Our table is fast, updates efficiently, is easy to extend, and is no where near production ready yet. What we built today was part one of a two part series. Next up, we’ll extend the sortable table by adding filtering and pagination, getting closer to the full-featured implementation seen in Beast Mode.

While there are numerous ways to implement a sortable table interface, for Rails developers, StimulusReflex is worthy of strong consideration. SR’s fast, efficient mechanisms for updating and re-rendering the DOM, including bypassing ActionDispatch’s overhead with selector morphs, allow us to sort and render the updated table extremely quickly, with minimal code complexity or additional mental overhead. Its tight integrations with CableReady and Stimulus combine into an extremely powerful tool in any Rails developers kit.

To go further into StimulusReflex and CableReady:

Review StimulusReflex patterns for thoughtfully designed solutions in StimulusReflex, including filterable for working with complex sorting and filtering requirements
Join the StimulusReflex discord and connect with other folks building cool stuff with StimulusReflex, CableReady, and Rails

That’s all for today, as always, thanks for reading!

Server-rendered modal forms with Ruby on Rails, CableReady, Mrujs, Stimulus, and Tailwind

David Colby — Fri, 10 Sep 2021 03:09:11 +0000

The Rails ecosystem continues to thrive, and Rails developers have all the tools they need to build modern, reactive, scalable web applications quickly and efficiently. If you care about delivering exceptional user experiences, your options in Rails-land have never been better.

Today we’re going to dive into this ecosystem and use two cutting edge Rails projects to allow users to submit forms that are rendered inside of a modal.

The form will open in a modal with content populated dynamically by the server, the server will process the form submission, and the DOM will updated without a full-page turn.

To accomplish this, we’ll use Stimulus for the front-end interactivity, CableReady’s brand new CableCar feature to send content back from the server, and Mrujs to enable AJAX requests and to automatically process CableCar’s operations.

It’ll be pretty fancy.

When we’re finished, our application will look like this:

This article includes a fair amount of JavaScript and assumes a solid understanding of the basics of Ruby on Rails.

If you've never used Rails before, this article might move a little too quickly for you. While comfort with Rails and JavaScript are needed, you don't need to have any prior experience with CableReady or Stimulus.

As usual, you can find the complete source code for this article on Github.

Let's dive in!

Setup

If you prefer to skip the setup steps and jump right in to coding, you can clone the main branch of this repo and then scroll down to the Customers Layout section.

To get everything installed, we’re going to walk on the wild side by using the newly released, very-much-still-alpha jsbundling-rails and cssbundling-rails gems.

First, we’ll create a Rails application and use the alpha js/cssbundling gems to install Webpack and Tailwind, from your terminal:

rails new tiny_crm --skip-webpack-install --skip-javascript
cd tiny_crm
bundle add jsbundling-rails cssbundling-rails
rails javascript:install:webpack
rails css:install:tailwind
bin/dev

Note that these gems are VERY new, if you bump into errors, check the documentation to see if commands have changed or reach out to me and let me know what error you’re encountering.

With Webpack and Tailwind installed, next we’ll install the core dependencies for this guide, Stimulus, CableReady (plus Action Cable), and Mrujs, from your terminal:

bundle add hotwire-rails
be rails hotwire:install

And then update your Gemfile to pull in the latest cable_ready.

gem "cable_ready", github: "stimulusreflex/cable_ready"

Note that if you're reading this in the future, we're using 5.0 for this guide.

And then from your terminal:

bundle
yarn add mrujs cable_ready @rails/actioncable

Next, update app/javascript/packs/application.js like this, to pull in the new dependencies and configure Mrujs to use its CableCar plugin.

import "./controllers"
import mrujs from "mrujs";
import CableReady from "cable_ready"
import { CableCar } from "mrujs/plugins"
import * as Turbo from "@hotwired/turbo"

window.Turbo = Turbo;

mrujs.start({
  plugins: [
    new CableCar(CableReady)
  ]
})

That’s a lot of dependencies to setup. Do we really need all of this to display a modal? No, no not really.

The techniques we’ll use in this article only require Action Cable (a core Rails library), CableReady, and Mrujs.

Tailwind and Stimulus are requirements to follow along with the guide step-by-step, but we’re just using them to do things that can be done with your own CSS and vanilla JavaScript, if that’s your preference.

Ultimately, the only UI component you need is a modal that can open and close. Stimulus and Tailwind are a simple way to get there, but they're not the only way!

Moving on, to wrap up the copy/pasting setup work, we’ll be creating and editing Customers in this application, so let’s scaffold up that resource:

rails g scaffold Customer name:string
rails db:migrate

Setup is complete! Great work so far. Now we can start writing code.

Customers layout

First, we’ll apply some basic styling to the customers index page:

<div class="max-w-3xl mx-auto mt-8">
  <div data-controller="modal" class="flex justify-between items-baseline mb-6">
    <h1 class="text-3xl text-gray-900">Customers</h1>
    <%= link_to 'New Customer', new_customer_path, class: "text-blue-600", data: { action: "click->modal#open" } %>
    <%= render 'modal' %>
  </div>
  <div id="customers" class="flex flex-col items-baseline space-y-6 p-4 shadow-lg rounded">
    <% @customers.each do |customer| %>
      <%= render "customer", customer: customer %>
    <% end %>
  </div>
</div>

The index view renders a list of customers, plus a header that includes a link to create a new customer.

The header container div includes a controller="modal" data attribute which is a reference to a Stimulus controller that doesn’t exist yet. Likewise, the new customer link references the same modal controller in its data-action attribute.

We’ll create that controller soon, for now though, clicking on the new customer link will navigate the browser to customers/new

The index view also renders two partials that don’t exist yet, modal and customer. Let’s create and fill those in next so that we can render the index page again.

First, the customer partial:

touch app/views/customers/_customer.html.erb

The customer partial just renders the customer’s name for now:

<div class="text-gray-700 border-b border-gray-200 w-full pb-2">
  <%= customer.name %>
</div>

Next create the modal partial:

touch app/views/customers/_modal.html.erb

And fill that in:

<div data-modal-target="container"
     class="hidden fixed inset-0 overflow-y-auto flex items-center justify-center"
     style="z-index: 9999;">
  <div class="max-w-lg max-h-screen w-full relative">
    <div class="m-1 bg-white rounded shadow">
      <div class="px-4 py-5 border-b border-gray-200 sm:px-6">
        <h3 class="text-lg leading-6 font-medium text-gray-900">
          Customer
        </h3>
      </div>
      <form id="customer_form"></form>
    </div>
  </div>
</div>

The important items here are the modal-target="container" data attribute, which the Stimulus controller will use to open/close the modal and the empty <form> element.

This form element will eventually be filled in with content from the server when the user opens the modal.

With the index markup in place and your server running via bin/dev, head to http://localhost:3000/customers and make sure everything is displaying as expected.

Next we will create the modal Stimulus controller and fill it in with content rendered from the server. I’m excited too.

Showing the new customer modal

First we need to create a new Stimulus controller, using the handy generator. From your terminal:

rails g stimulus modal

And fill the controller in with:

// Credit: This controller is an edited-to-the-essentials version
// of the modal component created by @excid3 as part of the essential 
// tailwind-stimulus-components package found here:
// https://github.com/excid3/tailwindcss-stimulus-components

// In production, use the full component from the 
// library or expand this controller to allow for 
// keyboard closing and dealing with scroll positions

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
static targets = ['container'];

  connect() {
    this.toggleClass = 'hidden';
    this.backgroundId = 'modal-background';
    this.backgroundHtml = this._backgroundHTML();
    this.allowBackgroundClose = true;
  }

  disconnect() {
    this.close();
  }

  open() {
    document.body.classList.add('fixed', 'inset-x-0', 'overflow-hidden');
    this.containerTarget.classList.remove(this.toggleClass);
    document.body.insertAdjacentHTML('beforeend', this.backgroundHtml);
    this.background = document.querySelector(`#${this.backgroundId}`);
  }

  close() {
    if (typeof event !== 'undefined') {
      event.preventDefault()
    }
    this.containerTarget.classList.add(this.toggleClass);
    if (this.background) { this.background.remove() }
  }

  _backgroundHTML() {
    return `<div id="${this.backgroundId}" class="fixed top-0 left-0 w-full h-full" style="background-color: rgba(0, 0, 0, 0.7); z-index: 9998;"></div>`;
  }
}

There’s a lot of JavaScript here, but it isn’t doing anything too fancy.

In connect, we set default values the controller needs to function.

open simply applies classes to the body and the modal container to make the modal visible on the screen and apply the standard grayed-out background to the rest of the page.

When close is called, the background is removed and the modal is hidden.

If you decide to use this approach in a real project, consider using the Stimulus component this code is derived from. The above code was edited for brevity and the edits will introduce issues with scrolling and accessibility that the full component handles cleanly.

With the Stimulus controller created, we’re almost ready to render the modal. Before we proceed, let’s step back and make sure we’re clear on what we want to achieve.

Our goal is to create a server-rendered modal that allows a user to create a new customer. After the form in the modal is submitted, the newly created customer should be inserted into the list of customers, and the modal should close.

The first task is to open the modal and display the content from the server, which means that when a user clicks on the New Customer link on the index page:

A request should be made to the server to retrieve the content for the customer form
The content should replace the empty customer form that the modal partial renders on the initial page load
The modal should open

This will be easier than it sounds.

We’ll use Mrujs to make an AJAX request to customers#new, we’ll queue up operations with CableCar, and Mrujs will automatically process those operations for us.

First we need to tell Mrujs to convert the New Customer link to a CableCar-enabled link.

As described in the documentation, we’ll do that by updating the link on the index page like this:

<%= link_to 'New Customer', new_customer_path, class: "text-blue-600", data: { action: "click->modal#open", cable_car: "" } %>

Here we’ve added data-cable-car="", and Mrujs takes care of the rest for us.

With this change in place, when the user clicks on the New Customer link, an AJAX request will be sent to customers#new.

Since we’re going to be rendering the form partial shortly, let’s go ahead and update that partial now:

<%= form_with(model: customer, id: "customer_form") do |form| %>
  <div class="px-4 pt-5 pb-4 sm:p-6 sm:pb-4">
    <% if customer.errors.any? %>
      <div class="p-4 border border-red-600">
        <h2>
          Could not save customer
        </h2>
        <ul>
          <% customer.errors.full_messages.each do |message| %>
            <li><%= message %></li>
          <% end %>
        </ul>
      </div>
    <% end %>

    <div class="form-group">
      <%= form.label :name %>
      <%= form.text_field :name %>
    </div>

  </div>
  <div class="rounded-b mt-6 px-4 sm:grid sm:grid-cols-2 sm:gap-3 sm:grid-flow-row-dense">
    <%= form.button class: "w-full sm:col-start-2 bg-blue-600 px-4 py-2 mb-4 text-white rounded-sm hover:bg-blue-700" %>
    <button data-action="click->modal#close" class="mt-3 w-full sm:mt-0 sm:col-start-1 mb-4 bg-gray-100 hover:bg-gray-200 rounded-sm px-4 py-2">
      Cancel
    </button>
  </div>
<% end %>

Most of this is standard Tailwind classes to apply some light styling to the form.

The important pieces are the id of the form, assigned on line 1, and the data-action assigned to the close button, which fires the close function we defined in the modal Stimulus controller earlier.

We can also make the form look nicer with Tailwind’s form plugin. This is optional, but if you’d like to use it, first install it with yarn, from your terminal:

yarn add @tailwindcss/forms

Then update tailwind.config.js:

module.exports = {
  mode: 'jit',
  purge: [
    './app/views/**/*.html.erb',
    './app/helpers/**/*.rb',
    './app/javascript/**/*.js'
  ],
  plugins: [
    require('@tailwindcss/forms')
  ]
}

Next we need to update the new method in the CustomersController to render CableReady operations, using the newly introduced CableCar. To do that, we’ll make two changes to the CustomersController.

First update the controller to include CableReady::Broadcaster to give the controller access to cable_car:

class CustomersController < ApplicationController
  include CableReady::Broadcaster
  # snip
end

Feel free to place the include in ApplicationController if you prefer.

Then update the CustomersController new method as follows:

def new
    html = render_to_string(partial: 'form', locals: { customer: Customer.new })
    render operations: cable_car
      .outer_html('#customer_form', html: html)
end

Here we’re rendering the form partial to a string which we then pass to cable_car and use in an outer_html operation, targeting the (currently empty) customer form.

With all this in place, head back to http://localhost:3000/customers and click on the New Customer link. If all has gone well, you should see the modal open and the customer form render.

Incredible work so far.

Next up we'll use this same CableCar approach to handle form submissions.

Submitting the form

This section is going to look pretty familiar. We’ll start by updating the customer form with the cable car data attribute, just like we added to the new customer link in the last section:

<%= form_with(model: customer, id: "customer_form", data: { cable_car: "" }) do |form| %>

Again, this tells Mrujs to submit the form with an AJAX request and to expect CableReady operations to perform in response.

Next, head back to customers_controller.rb and update the create method:

def create
  @customer = Customer.new(customer_params)

  if @customer.save
    html = render_to_string(partial: 'customer', locals: { customer: @customer })
    render operations: cable_car
      .append('#customers', html: html)
  else
    # TODO: Handle errors
  end
end

Here we’re again rendering a partial to a string and passing that string to an operation (this time, append). The target is the list of the customers rendered in the customers index view, where the newly created customer will be added to the bottom of the list. If you prefer, use prepend to add the customer to the top of the list instead.

With this in place, open up the modal, type in a name, and submit the form. You should see the newly created customer get appended to the list like expected but the modal doesn’t close.

That’s not ideal.

How do we close the modal when the form submission is successful? By tapping into some of what makes CableReady so powerful — chaining operations and emitting custom DOM events.

To make this work, we’ll first add another operation to the operations chain sent back to Mrujs:

def create
    # snip
    render operations: cable_car
      .append('#customers', html: html)
      .dispatch_event(name: 'submit:success')
end

The dispatch_event operation allows us to emit whatever event we like. With this new event dispatched on successful submission, closing the modal is as simple as adding an event listener to the modal’s Stimulus controller, like this:

open() {
  document.addEventListener("submit:success", () => {
    this.close()
  }, { once: true });
  // snip
}

When the modal opens, an event listener is created, tuned to the event name that is dispatched from the cable_car payload.

Now when you submit the modal form, both the append and the dispatch_event operations are sent back in response to a successful form submission, Mrujs magic automatically performs the operations, and the submit:success event listener closes the modal.

Handling errors

Wonderful work stuff so far. Next we'll deal with form errors using render operations again.

First, make it possible for a customer submission to have a validation error by adding validates_presence_of :name to models/customer.rb

With that in place, when the form is submitted with a blank name, the form submission will fail. When that happens, we want to render the customer form inside of the modal, with the validation errors attached.

To render errors in response to a failed submission, update the create method like this:

def create
  @customer = Customer.new(customer_params)

  if @customer.save
    html = render_to_string(partial: 'customer', locals: { customer: @customer })
    render operations: cable_car
      .append('#customers', html: html)
      .dispatch_event(name: 'submit:success')
  else
    html = render_to_string(partial: 'form', locals: { customer: @customer })
    render operations: cable_car
      .inner_html('#customer_form', html: html), status: :unprocessable_entity
  end
end

In the else branch, we again render the partial to a string and render operations. This time, since we don’t want the modal to close and we don’t need to replace the <form> element itself, we can just use one inner_html operation.

Open up the modal, submit a blank form, and see that the form is re-rendered with the errors as expected.

You’re a star for making it this far. Let’s finish up by seeing how easy it is to reuse this modal for editing customers, and adding some small optimizations to the modal opening.

Cable Car customer edits

A cool thing about the empty customer form modal is that we can reuse it with no modifications for editing existing customers, leaving us with just one tiny modal container that we can reuse for any number of modals on the page.

First, add a cable_car enabled modal link to the customer partial:

<div class="text-gray-700 border-b border-gray-200 w-full pb-2" id='<%= "customer-#{customer.id}" %>'>
  <%= link_to customer.name, edit_customer_path(customer), data: { cable_car: "", action: "click->modal#open" } %>
</div>

Here we setup the relevant data attributes on the link and, on the wrapper div, we added a unique id. We’ll use that id to replace the content of the customer when the edit form is submitted.

Next up, back to the CustomersController to adjust the edit and update methods:

def edit
  html = render_to_string(partial: 'form', locals: { customer: @customer })
  render operations: cable_car
    .replace('#customer_form', html: html)
end

def update
  if @customer.update(customer_params)
    html = render_to_string(partial: 'customer', locals: { customer: @customer })
    render operations: cable_car
      .replace("#customer-#{@customer.id}", html: html)
      .dispatch_event(name: 'submit:success')
  else
    html = render_to_string(partial: 'form', locals: { customer: @customer })
    render operations: cable_car
      .inner_html('#customer_form', html: html), status: :unprocessable_entity
  end
end

This should look pretty familiar. The edit method is a mirror of the new method, and the update method is a mirror of the create method. Again, we dispatch the submit:success event when the customer is updated, otherwise the form re-renders with errors.

Finally, to use the same modal controller for every modal link on the page, we’ll move the data-controller="modal" declaration one level up the DOM tree. In customers/index.html.erb:

<div class="max-w-3xl mx-auto mt-8" data-controller="modal">
  <div class="flex justify-between items-baseline mb-6">
    <!-- Snip -->
  </div>
</div>

With these changes in place, refresh the customers index page, click on a customer’s name, and see that updating the customer happens in a modal, and the customer is updated in place in the list on a successful form submission.

Optimizing modal opening

Something you may have noticed as you’ve worked through this guide is that the modal opens before the content from the server has rendered, causing a very brief flash as the modal opens and then quickly replaces the empty form or the form’s previous contents:

This happens because the modal opens instantly when a modal link is clicked but the round trip to the server to retrieve the form partial is not quite instant.

We have options for how to prevent this, including adding a loading state to the modal to make the re-render less jarring, but the method I’ll demonstrate is keeping the modal hidden until the content has been retrieved from the server. This gives us another chance to use CableReady and Stimulus, and that’s what we’re all here for, right?

First, add another event listener to the modal controller:

open() {
  document.addEventListener("modal:loaded", () => {
    this.containerTarget.classList.remove(this.toggleClass);
  }, { once: true });
  document.addEventListener("submit:success", () => {
    this.close()
  }, { once: true });

  document.body.classList.add('fixed', 'inset-x-0', 'overflow-hidden');
  document.body.insertAdjacentHTML('beforeend', this.backgroundHtml);
  this.background = document.querySelector(`#${this.backgroundId}`);
}

Here we updated open to move the containerTarget.classList.remove call from happening instantly to happening in response to modal:loaded DOM event.

This change means that all of the modal links are now broken because the modal:loaded event never occurs and so containerTarget.classList.remove never runs and the modal container stays hidden.

We can fix the modal links by updating CustomersController like this:

def new
  html = render_to_string(partial: 'form', locals: { customer: Customer.new })
  render operations: cable_car
    .outer_html('#customer_form', html: html)
    .dispatch_event(name: 'modal:loaded')
end

def edit
  html = render_to_string(partial: 'form', locals: { customer: @customer })
  render operations: cable_car
    .outer_html('#customer_form', html: html)
    .dispatch_event(name: 'modal:loaded')
end

In both the new and edit methods, we again take advantage of CableReady’s chainable operations to dispatch modal:loaded after the outer_html is replaced.

With this change, the sequence of events when the user clicks on a modal link is:

Request to server begins
Open action is triggered
Modal backdrop is applied to the page, no visible modal yet
Form content is replaced
Modal loaded event is dispatched
Hidden class is removed from the modal, making it visible

This sequence happens rapidly enough in our circumstances for the user to barely notice the delay between the backdrop being applied and the modal displaying. In a production environment, you may find that a loading state for an immediately-opened modal is a more scalable option, but we’re here to learn about CableReady and Mrujs, not build a production application.

With these changes in place, the modal will open with the updated content already populated, eliminating the flash of old content.

The single modal connected div can be used to display any number of modals, serving as a way to reduce the initial page load in a more traditional application which might pre-render each edit modal.

Wrapping up

Today we learned how to build a server rendered modal form, powered by Stimulus, CableReady, and Mrujs.

Stimulus and CableReady are two powerful, battle-tested tools with a mature feature set that should be considered for any modern Rails application. CableReady can stand alone as a way to deliver real-time updates to end users through a variety of methods or it can be powered-up with StimulusReflex to deliver a SPA-link experience, minus the SPA.

Mrujs is a newer tool, under active development, and is intended to serve as a modern, stable replacement for rails/ujs, which is no longer under active development and which will be deprecated when Rails 7 releases.

In addition to the tight integration with CableReady’s Cable Car that we saw today, Mrujs gives you access to simple confirmation dialogs, disabled links, and the other niceties from Rails UJS, in a modern package.

An important note before we go: we could build a very similar user experience with a variety of tools in the Rails ecosystem, including Turbo Streams (here's a guide for that).

While the full Hotwire stack can deliver this experience with about the same amount of effort, the power and flexibility of CableReady's chainable operations makes CableReady + Mrujs a better fit for this particular use case than the full Hotwire stack, in my very, very humble opinion.

What's really exciting about this is that as Rails developers, our cups are overflowing with powerful tools to build real-time, reactive applications. That means we all win, no matter which tool we reach for most often.

Continue your journey with CableReady, Stimulus, and Mrujs with these resources:

The CableReady documentation
The Stimulus docs
The Mrujs docs
Explore the StimulusReflex documentation when you’re ready
Join the StimulusReflex discord if you get stuck with CableReady or StimulusReflex
(Shameless plug) Subscribe to my monthly newsletter, Hotwiring Rails, to stay up to date on the latest on building modern, performant applications with Rails and tools like CableReady and Stimulus

That’s all for today.

As always, thanks for reading!

DEV Community: David Colby

User notifications with Rails, Noticed, and Hotwire

Application setup

Noticed setup

Message notifications

Real-time notifications with Turbo Streams

Wrapping up & further reading

Toggling view layouts with Kredis, Turbo Frames, and Rails

Application setup

Build the list and card views

Using Kredis to store preferences

Adding a Turbo Frame

Improving our Kredis usage

Wrapping up

Turbo Rails 101: Building a todo app with Turbo

Application setup

Create new todos with Turbo Streams

Turbo Streams can target any element, not just Turbo Frames

Turbo Streams do not require WebSockets

Editing existing todos

Handling form errors

Deleting todos

Mark todos as complete

Complete/incomplete todos in separate tabs

Degrading gracefully

Wrapping up

Pagination and infinite scrolling with Rails and the Hotwire stack

Application setup

Pagination the old fashioned way

Navigate pages with Turbo

Manual “infinite scroll”

Automatic infinite scroll

Wrapping up

Real-time previews with Rails and StimulusReflex

Application setup

Adding a Stimulus controller

Server-side previews with StimulusReflex

Add markdown and liquid parsing

Debouncing requests

Wrapping up

Why not just parse things on the client?

Do you need real-time previews?

Further reading

Live reloading with Ruby on Rails and esbuild

Application setup

Booting up

Configure esbuild for live reloading

HTML and CSS live reloading

Wrapping up

Rendering view components with Turbo Stream broadcasts

Application setup

Building the spy component

Add Turbo Stream broadcasts

Wrapping up

Filter, search, and sort tables with Rails and Turbo Frames

Project setup

Add a search form

Real-time searching

Sorting and searching at the same time

Building a Filterable concern

Add filtering by team

Filtering the index action

Production-grade considerations

Session storage limitations

Replace helper methods

Expand Filterable implementation

Wrapping up

Turbo Frames on Rails

Why should I use Turbo Frames?

The Turbo documentation gap

What is this article? Who is it for?

What are Turbo Frames?

Constructing a frame

Responding with frame content

Navigating within frames

Breaking out of a frame

Targeting a frame from the outside

Lazy loading Frames

Frame events

Refreshing Frames