Here is the problem: every time you make a change, you overwrite the last version.

Designing directly in code has become incredibly fast with LLMs. You describe what you want, you get working HTML and CSS back in seconds. But the speed creates a new problem. You generate version one, tweak the prompt, generate version two, and now version one is gone. You want to compare them. You want to send both to your designer or PM and ask which one feels better. You want to open them side by side and squint at the differences.

Instead, you are copying files into _old suffixes, creating git branches for each variation, or pasting markup into a notes app just to preserve your options. This is friction that slows you down right when you should be moving fast.

What you really want is simple: a way to maintain multiple versions of the same view, switch between them instantly, and share any version with a URL.

ActionVersionPreview solves your Rails design version problems.

ActionVersionPreview: Multiple Designs, Zero Configuration

ActionVersionPreview is a Rails gem that lets you preview multiple versions of your UI simultaneously. Add it to your Gemfile:

gem "action_version_preview"

Run bundle install. That is it. No initializer. No configuration. No database migrations. No backend dependencies.

Just Name Your Files

The gem uses Rails' native view variants, which have a simple naming convention:

app/views/dashboard/show.html.erb           # default
app/views/dashboard/show.html+v2.erb        # variant :v2
app/views/dashboard/show.html+v3.erb        # variant :v3
app/views/dashboard/show.html+redesign.erb  # variant :redesign

The +variant suffix tells Rails this is an alternative template. ActionVersionPreview lets you switch between them with a URL parameter:

/dashboard           # renders show.html.erb
/dashboard?vv=v2     # renders show.html+v2.erb
/dashboard?vv=v3     # renders show.html+v3.erb

That is the entire interface. Create a file, add the suffix, visit the URL. No registration of variants. No config files. No enum definitions. Just files and URLs.

The Variant Switcher

Drop this helper in your layout:

<%= variant_switcher %>

A floating widget appears when the vv parameter is present. It auto-detects which variants exist for the current page by scanning your view directory. Click to switch between versions without editing the URL.

Side-by-Side Comparison

Open three browser tabs:

• Tab 1: /dashboard

• Tab 2: /dashboard?vv=v2

• Tab 3: /dashboard?vv=v3

All three are logged in as you. All three show your real data. Arrange them side by side and compare instantly.

Share With a URL

Getting feedback is trivial:

Hey, can you look at https://staging.myapp.com/dashboard?vv=redesign
and tell me if the new nav makes sense?

Your teammate clicks the link, sees the variant, gives feedback. No setup required on their end.

Works Everywhere Rails Looks for Templates

Variants apply to layouts, partials, mailers, and ViewComponent templates. If you have:

app/views/shared/_header.html.erb
app/views/shared/_header.html+v2.erb

When rendering with the v2 variant active, Rails automatically uses _header.html+v2.erb. Your entire render tree respects the variant.

Helper Methods

These are available in controllers and views:

current_variant         # => :v2 or nil
detected_variants       # => ["v2", "v3", "redesign"]
variant_preview_active? # => true when ?vv param is present
can_preview_variants?   # => true if current user has access

Optional Configuration

The defaults work for most cases. If you need to customize:

# config/initializers/action_version_preview.rb
ActionVersionPreview.configure do |config|
  # Change the URL parameter (default: :vv)
  config.param_name = :variant

  # Control access (default: dev/test only)
  config.access_check = ->(controller) {
    Rails.env.development? ||
    Rails.env.test? ||
    controller.current_user&.admin?
  }
end

In production, restrict access to admins or staff so random users cannot access your experimental designs.

Why Not Feature Flags?

You might be thinking: I already have Flipper (or LaunchDarkly, or whatever). Why not use that?

Feature flags solve a different problem. They answer the question: "Which users should see this feature?" They are built for:

• Percentage rollouts to production users

• A/B testing with statistical significance

• Gradual migrations where you need a kill switch

• User-specific targeting based on attributes

This is not what you need when iterating on designs. You are not rolling out to users. You are not measuring conversion rates. You are trying to look at three versions and pick one.

Feature flags add complexity you do not need for design work. You end up with conditional logic in your views:

<% if Flipper.enabled?(:new_dashboard, current_user) %>
  <!-- new design -->
<% else %>
  <!-- old design -->
<% end %>

This pollutes your templates with branching logic. With variants, each version is a clean, separate file. No conditionals. No flag checks. Just the design.

Use feature flags when you need controlled rollouts to real users. Use ActionVersionPreview when you need to compare options and collect feedback before choosing what to ship.

How It Works

The implementation is simple. When you visit /dashboard?vv=v2:

1. A before_action checks for the vv parameter

2. If present, it sets request.variant = :v2

3. Rails' template resolver looks for show.html+v2.erb

4. If found, it renders that. If not, it falls back to show.html.erb

The variant persists across navigation through default_url_options. Click a link on the page and the vv parameter carries forward. No cookies, no sessions, no database writes. Just URL parameters.

The switcher widget detects variants by globbing the view directory:

Dir.glob("app/views/dashboard/show.html+*.erb")
# => ["show.html+v2.erb", "show.html+v3.erb", "show.html+redesign.erb"]

Standard Rails variants like mobile, tablet, and phone are filtered out so they do not clutter your switcher.

Credits

This pattern builds on Rails' native view variants, which have been in the framework since Rails 4.1. The approach of using URL parameters for variant selection was inspired by these posts:

• Easy Redesign in Rails: Run Old and New Side by Side with Variants by dotruby

• Releasing a Redesign Using Feature Flags and Rails Variants by The Rails Runner, which documents how the Wrapbook team combined Flipper with URL parameter overrides during their UI rewrite

I extracted the variant-only approach into this gem because the feature flag complexity is unnecessary when all you want is to compare designs.

Conclusion

LLMs have made generating UI variations trivially easy. The bottleneck is no longer creating options. It is comparing them and getting feedback.

ActionVersionPreview removes that bottleneck. Create variant files, visit URLs, compare side by side. Share with your team using nothing but a link. Pick the winner, delete the losers, ship it.

No database. No Redis. No configuration. No view conditionals. Just Rails doing what Rails already knows how to do.

gem "action_version_preview"

Now go iterate.

Support for view transitions just hit the Turbo library with the release of Turbo 2.0. Along with DOM morphing support and combined with the rest of Rails, it's a powerful combination where you can achieve some impressive reactivity with really minimal effort, code, and complexity. Let me show you.

All the code for the application is on GitHub and you can see a demo of view transitions with turbo.

Everything here applies to Rails 7 and Turbo 2.0. It's worth upgrading your applications to the modern Rails stack (I just did an update from 6 to main and besides some stuff with webpacker, it really wasn't that bad).

Setup

Our application has Photos that have URLs and likes count. In db/seed.rb I create a few photos. There's also a PhotosController that has index, show and update actions. That's about all you need to know.

Classic View Transitions

The transition we want to implement is the one between the index and show views. When you click on a photo in the index, it should animate the transition to the show view. The first step to accomplish this is to add <meta name="view-transition" content="same-origin" /> to your layout. With that, having nothing to do with Rails, you actually will already get a nice fade transition between the two views as that's the default view transition.

There are great articles on how view transitions work so I'm not going to cover the default use-case in detail.

The basics are that the browser is taking a screenshot of the current page and a screenshot of thew new page and transitioning them between two CSS pseudo-elements of ::view-transition-old and ::view-transition-new. The browser then animates the transition between the two screenshots, the default being a fade. The browser is apparently really great at this effect as we will see.

Focusing the Transition to an Element

Rather than fading the entire page between views, we can focus the transition on a specific element. You're telling the browser to explicity focus the transition of the element from the old to the new view. All you have to do is give the presence of the elements you want to focus the transition on the same view-transition-name property.

This actually took me a second to understand how to use correctly but in our example, what we want to do is tell the browser that the thumbnail of the photo is being transitioned to the full photo element. Instead of just fading the entire page, the browser will focus the transition on moving the thumbnail of the photo into the full photo, which creates a lovely effect of the thumbnail moving and growing into the full photo.

I updated the thumbnail to have a unique view-transition-name property based on the photo id.

app/views/photos/index.html.erb

<img
  class="h-auto max-w-full rounded-lg"
  src="<%= photo.url %>"
  alt="<%= photo.name %>"
  style="view-transition-name: photo_<%= photo.id %>"
>

Now that the thumbnail has a unique view-transition-name, we can tell the browser to focus the transition on the full photo element by giving it the same name.

app/views/photos/_photo.html.erb

content_tag :div, 
  class: "photo-viewer", 
  style: "view-transition-name: #{dom_id(photo)}", 
  id: dom_id(photo)

That's it. Now when you click on a photo, the transition will focus on the thumbnail and animate it into the full photo.

Turbo Frames and Custom Transitions

For my next trick, let's use a custom view transition animation for an element within a turbo frame by implementing an updating "Like" button.

app/views/photos/_photo.html.erb

<%= turbo_frame_tag dom_id(photo, :likes) do %>
  <div class="photo-viewer__like-button" style="view-transition-name: zoom">
    <%= form_for(photo) do |f| %>
      <%= f.button type: 'submit', class: "like-button__link" do %>
        <span class="like-button__icon">❤️</span>
        <span class="like-button__count"><%= photo.likes_count %></span>
      <% end %>
    <% end %>
  </div>
<% end %>

When you click the Like button, it will submit the form looking for the turbo frame with the same id in the response in order to update just the frame contents. After the server updates likes_count, it sends back photos/show.html.erb again which contains the same turbo frame and thus that is the only element to update. Just standard turbo frame magic. If you're curious, here's photos#update, nothing special.

def update
  @photo.increment(:likes_count)
  @photo.save
  redirect_to photo_path(@photo)
end

If you noticed, the element within the turbo frame has a view-transition-name of zoom.

<div class="photo-viewer__like-button" 
  style="view-transition-name: zoom">

This means this element will be animated with a custom view transition we can define called zoom.

But before we can define that zoom transition, we do have to tell Turbo to actually fire the view transition when the turbo frame updates. From How to use View Transitions in Hotwire Turbo:

We need to override the default rendering function for Turbo Frames in the turbo:before-frame-render event handler with a custom one that utilizes View Transitions.

In app/javascript/controllers/application.js:

addEventListener("turbo:before-frame-render", (event) => {
  if (document.startViewTransition) {
    const originalRender = event.detail.render;
    event.detail.render = (currentElement, newElement) => {
      document.startViewTransition(() => originalRender(currentElement, newElement));
    };
  }
});

The handler code first checks whether View Transitions are supported by the browser and if so, it wraps the original rendering function with the document.startViewTransition function. Now when a frame is rendered, the browser will use view transitions to animate the changes.

With that, we can define the zoom transition in our CSS.

app/assets/stylesheets/application.tailwind.css

@keyframes zoomIn {
  from {
    transform: scale(0.5);
    opacity: 0;
  }
  to {
    transform: scale(1);
    opacity: 1;
  }
}

@keyframes zoomOut {
  from {
    transform: scale(1);
    opacity: 1;
  }
  to {
    transform: scale(0.5);
    opacity: 0;
  }
}

::view-transition-new(zoom) {
  animation: zoomIn 0.5s ease forwards;
}

::view-transition-old(zoom) {
  animation: zoomOut 0.5s ease forwards;
}

And viola! We get a really nice effect when the like button is clicked all the while only updating the turbo-frame content.

Turbo Streams and Real-Time Updates

But wait, there's more! We can make the like button update in real-time when another user likes the photo and still have the same view transition firing to animate the change.

First, let's implement the real-time updates. Hold on because it's really complicated with Rails (sarcasm).

Subscribe photos/show to a stream for the photo:

<%= turbo_stream_from @photo %>

Tell the Photo model to broadcast a refresh whenever an instance of Photo is changed.

class Photo < ApplicationRecord
  broadcasts_refreshes
end

And then...well that's it.

We're not done, let's make this even better.

First, now that we're using turbo streams and broadcasting the changes, we can entirely remove the turbo frame from the view. The form will submit and the turbo stream will update the like count and the button on the page you are on as well as any other browser that is viewing the same photo.

Second, we're updating a lot of DOM in this interaction because the turbo stream is broadcasting an entire page update when all that has changed is literally the number inside the like button. Wouldn't it be amazing if we could just update that number and change nothing else? You guessed it, we can. Turbo 8 ships with DOM morphing built-in, we just need to enable it.

To enable this, we just add <%= turbo_refreshes_with method: :morph, scroll: :preserve %> to application.html.erb layout.

Now pay attention to what DOM gets updated when like button is pressed.

Ya, that's right, it's only updating the content of the like button's count (and the form authenticity token because that changed too). Otherwise, nothing about the page's DOM is changed. This is a huge win for performance and user experience. And we literally implemented this with one line of code and 0 Javascript.

Conclusion

Just stop and think for a second about what we've accomplished here. We have an element that will update in real-time across browsers and animate itself and we wrote no Javascript. In fact, we barely wrote any code to accomplish this at all.

The real-time update with morphing totaled 3 lines of code.

1. Subscribe to the stream.
2. Broadcast the refresh.
3. Enable morphing.

All the animations are handled by view transitions. And that's just one of the features, let's not forget where the post started with the cool transition between the thumbnail and the photo.

If you enjoyed this post, please follow me on X/Twitter for more. I'm also available for contract work.

Sortable Table Headers

The first step is to create the sortable table headers as simple links. I wrote a few helper methods in Ruby to make this easier.

module ApplicationHelper
  def sortable_table_header(title, column, path_method, **)
    content_tag(:th, class: "invoices__th") do
      sortable_column(title, column, path_method)
    end
  end

  def sortable_column(title, column, path_method, **)
    direction = (column.to_s == params[:sort].to_s && params[:direction] == "asc") ? "desc" : "asc"

    query_params = request.query_parameters.merge(sort: column, direction: direction)

    path = send(path_method, query_params)
    link_to(path, class: "flex items-center", **) do
      concat title
      concat sort_icon(column)
    end
  end

  def sort_icon(column)
    return unless params[:sort].to_s == column.to_s

    if params[:direction] == "asc"
      svg_icon("M5 15l7-7 7 7")
    else
      svg_icon("M19 9l-7 7-7-7")
    end
  end

  def svg_icon(path_d)
    content_tag(:svg, xmlns: "http://www.w3.org/2000/svg", class: "ml-1 inline w-4 h-4", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor") do
      "<path stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='#{path_d}'></path>".html_safe
    end
  end
end

The important one is sortable_column which creates the link to with the sort and direction query parameters. With that method, we can make each table header a link to sort the table by that column, alternating between ascending and descending order. In our main view, we can use it like this:

<thead class="invoices__thead">
  <tr>
    <%= sortable_table_header 'ID', :id, :invoices_path, class: 'invoices__row--header' %>
    <%= sortable_table_header 'Amount', :amount, :invoices_path, class: 'invoices__row--header' %>
    <%= sortable_table_header 'Status', :status, :invoices_path, class: 'invoices__row--header' %>
    <%= sortable_table_header 'Created At', :created_at, :invoices_path, class: 'invoices__row--header' %>
  </tr>
</thead>

Now when you click on a column header, the table will be sorted by that column by making a full request to the server and redrawing the entire page, you know, the way links work out of the box. We'd also have to update our controller code to support the sort and direction params, so let's do that.

class InvoicesController < ApplicationController
  def index
    sort_column = params[:sort] || "created_at"
    sort_direction = params[:direction].presence_in(%w[asc desc]) || "desc"

    @invoices = Invoice.order("#{sort_column} #{sort_direction}").page(params[:page]).per(10)
  end
end

I'm using the kaminari gem for pagination, so I'm using the page and per methods to paginate the results. The order method is used to sort the results by the column and direction specified in the query parameters. It works pretty well out of the box.

This is the nice, classic, beauty of Ruby on Rails. Clean backend code written in Ruby to do the heavy lifting, and simple, clean HTML to render the table.

The only issue is that as you can see, every time we click on a column header, the browser is redrawing the entire page. Notice the html, head, and body tag being updated?

That means that any other content on the page that won't need to be updated from the new request is redrawn anyway.

In the spirit of reactive applications, we want to alter the dom as little as possible to keep the user experience smooth and fast and only redraw the updated part of the page, the table. That's where Turbo Frames come in.

Turbo Frame Table

We're going to wrap the entire table in a turbo frame. A turbo frame is a container that can be updated without a full page reload. It's a way to make a part of the page reactive, but without the complexity of a frontend framework or even any change to our backend at all.

<%= turbo_frame_tag "invoices" do %>
  <div class="flow-root mt-8">
    <div class="-mx-4 -my-2 overflow-x-auto sm:-mx-6 lg:-mx-8">
      <div class="inline-block min-w-full py-2 align-middle sm:px-6 lg:px-8">
        <div class="invoices__table--shadow">
          <table class="invoices__table">
            <thead class="invoices__thead">
              <tr>
                <%= sortable_table_header 'ID', :id, :invoices_path, class: 'invoices__row--header' %>
                <%= sortable_table_header 'Amount', :amount, :invoices_path, class: 'invoices__row--header' %>
                <%= sortable_table_header 'Status', :status, :invoices_path, class: 'invoices__row--header' %>
                <%= sortable_table_header 'Created At', :created_at, :invoices_path, class: 'invoices__row--header' %>
              </tr>
            </thead>
            <tbody class="invoices__tbody">
              <% @invoices.each do |invoice| %>
                <tr>
                  <td class="invoices__row invoices__row--id">
                    <%= invoice.id %>
                  </td>
                  <td class="invoices__row invoices__row--amount">
                    <%= number_to_currency(invoice.amount) %>
                  </td>
                  <td class="invoices__row invoices__row--status">
                    <%= status_badge(invoice.status) %>
                  </td>
                  <td class="invoices__row invoices__row--created-at">
                    <%= invoice.created_at.strftime('%m/%d/%Y') %>
                  </td>
                </tr>
              <% end %>
            </tbody>
          </table>
        </div>
      </div>
    </div>
    <%= paginate @invoices %>
  </div>
<% end %>

The cool thing is that any link within the turbo frame when clicked will automatically change the source property of its parent frame to the href of the link. This means that when we click on a sortable column header, the turbo frame will automatically update itself with the new sorted table. No need to write any JavaScript or even any additional backend code. It just works.

With the update, the browser is no longer redrawing the entire page. It's only redrawing the turbo frame, which is the table. This makes the user experience much smoother and faster and means any other content on the page will be maintained and not rerendered or anything. It's just way less work for the browser.

That's really it. The only issue is that clicking on a column header doesn't change the URL, so you can't share the state of the sorted table with anyone. But fixing that is easy with Turbo. By adding a data-turbo-action="advance" attribute to the link, we can change the URL without a full page reload, essentially advancing the page state to the new sorted table URL, but only redrawing the turbo frame.

I updated the sortable_column method to include the data-turbo-action attribute.

def sortable_column(title, column, path_method, **)
  direction = (column.to_s == params[:sort].to_s && params[:direction] == "asc") ? "desc" : "asc"

  query_params = request.query_parameters.merge(sort: column, direction: direction)

  path = send(path_method, query_params)
  link_to(path, data: {turbo_action: "advance"}, class: "flex items-center", **) do
    concat title
    concat sort_icon(column)
  end
end

With that we can see that the URL changes when we click on a column header, but only the table is redrawn.

Now you can share the state of the sort with people.

Conclusion

I wish there was more to say about implementing this feature, it's just so simple and easy to do with Turbo and Rails. I also updated the pagination links to use the data-turbo-action="advance" attribute so that the URL changes when you click on a page number, but only the table is redrawn.

The rest of the code in the application is worth exploring for some nice BEM and Tailwind patterns, but the main feature is the sortable, paginated table. Checkout the final source:

• Sortable Table Helper
• Sortable Table View
• Sortable Table Controller
• Kaminari Pagination for Tailwind
• BEM Style Tailwind CSS Tables

You can checkout the full source code Github and play with it at Turbo Sortable Paginated Tables.

If you have any questions or comments or just liked the demo, feel free to reach out to me on X.

We've got a bunch of jobs, each with 4 facets. A job has a commitment, like Full Time, Part Time, it has a location, a category, and whether it is remote. For each of those facets we have a search filter in the interface, a few using select boxes, and one using a checkbox. When we change the value of any of these filters, the list of jobs will be updated to only show jobs that match the selected filters.

Let's get started. You can see the entire source for the project at Turbo Frames Search Filter

Step 1: Setting Up the Rails App

Let's start by generating a scaffold for our jobs. I just used rails g scaffold Job title:string description:text commitment:integer location:string category:string remote:boolean. The migration looks like:

class CreateJobs < ActiveRecord::Migration[7.2]
  def change
    create_table :jobs do |t|
      t.string :title
      t.text :description
      t.integer :commitment, index: true
      t.string :location, index: true
      t.string :category, index: true
      t.boolean :remote, index: true

      t.timestamps
    end
  end
end

And with that we're setup to start building our search filters. I went to app/views/jobs/index.html.erb and added the following to create the search form and filters.

app/views/jobs/index.html.erb

<div class="flex justify-end mb-5 ml-8">
  <%= form_with(url: jobs_path, method: :get, class: "mt-0") do %>
    <div class="flex flex-col gap-4">
      <div class="flex flex-col justify-end mt-2">
        <%= label_tag :category, 'Category' %>
        <%= select_tag :category,
              options_for_select(['Engineering', 'Marketing', 'Design', 'Sales', 'Customer Service'],
              selected: params[:category]),
              include_blank: true,
              class: 'rounded-lg border-gray-300 mt-2' %>
      </div>
      <div class="flex flex-col justify-end mt-2">
        <%= label_tag :location, 'Location' %>
        <%= select_tag :location,
              options_for_select(['New York', 'San Francisco', 'Berlin', 'Tokyo', 'London', 'Paris', 'Sydney', 'Toronto', 'Singapore', 'Remote'],
              selected: params[:location]),
              include_blank: true,
              class: 'rounded-lg border-gray-300 mt-2' %>
      </div>
      <div class="flex items-center justify-start">
        <%= check_box_tag :remote, '1',
              params[:remote].present?, class: 'mr-2' %>
        <%= label_tag :remote, 'Remote' %>
      </div>
      <% Job.commitments.keys.each do |commitment| %>
        <div class="flex items-center justify-start">
          <%= check_box_tag "commitments[]", commitment,
                params[:commitments]&.include?(commitment),
                id: "commitment_#{commitment}",
                class: 'mr-2' %>
          <%= label_tag "commitment_#{commitment}", commitment.humanize %>
        </div>
      <% end %>
    </div>
  <% end %>
</div>

With Rails we get to re-use a lot of the same actions for different purposes. In this case, we're using the index action to both show the list of jobs, and to filter the list of jobs. We'll need to update the index action in our controller to handle the filtering. Here's what I added to app/controllers/jobs_controller.rb.

app/controllers/jobs_controller.rb

def index
  @jobs = Job.all
  @jobs = @jobs.where(category: params[:category]) if params[:category].present?
  @jobs = @jobs.where(location: params[:location]) if params[:location].present?
  @jobs = @jobs.where(remote: true) if params[:remote].present?
  @jobs = @jobs.where(commitment: params[:commitments]) if params[:commitments].present?
  @jobs = @jobs.order(created_at: :desc).limit(20)
end

If we submitted the form without Turbo Frames, the entire page would reload, and we'd see the filtered list of jobs. But we want to use Turbo Frames to only update the list of jobs. So let's add a Turbo Frame to the index page.

Step 2: The jobs Turbo Frame

I added the following to app/views/jobs/index.html.erb.

app/views/jobs/index.html.erb

<%= turbo_frame_tag "jobs", class: "min-w-full" do %>
  <%= render @jobs %>
<% end %>

What this means is that anytime the response from the server includes a turbo frame with the id of jobs that page will only replace the contents of that frame, avoiding an entire page refresh and even the normal Turbo visit behavior of redrawing the entire page.

By the way, we could just have the form submission target the jobs turbo frame and it would work, but we're going to use Stimulus to make it a little more interactive so that you don't need to click a submit button to update the list of jobs, but rather you can just click on any of the filters and it will update. For that we need a Stimulus controller and we need to bind it to the form and the fields.

Step 3: The filter Stimulus Controller

What we want to do is bind a Stimulus controller to the form and the fields so that when the form is submitted, or when any of the fields change, we submit the form. Here's what I added to app/javascript/controllers/filter_controller.js.

app/javascript/controllers/filter_controller.js

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  submit(e) {
    const form = this.element;
    const formData = new FormData(form);

    const params = new URLSearchParams(formData);
    const newUrl = `${form.action}?${params.toString()}`;

    Turbo.visit(newUrl, { frame: "jobs" });
    history.pushState({}, "", newUrl);
  }
}

Ugh, I just love how stupidly little Javascript that is. But back to explaining it.

If the form is bound to this stimulus controller, this.element will be the form itself.

The submit function is what we want to trigger anytime one of the form values is changed. When it fires we're going to grab the form data, serialize it into a query string, and then use Turbo to visit the new url. We're passing in the frame option to tell Turbo to only update the jobs frame. And then we're using history.pushState to update the url in the browser so that if you refresh the page, you'll see the same list of jobs.

Now all that's left is binding the controller to the form and the fields so that when any of the values of the fields change, this submit function will fire.

Step 4: Binding the filter Stimulus Controller

We need to bind the filter controller to the form and the fields. We can do that by adding the following to app/views/jobs/index.html.erb.

app/views/jobs/index.html.erb

<%= form_with(url: jobs_path, method: :get, class: "mt-0",
          data: {controller: "filter"}) do %>

And then we need to bind the controller to the fields. We can do that by adding data: {action: "change->filter#submit"} to each form filter. Now the entire form looks like:

app/views/jobs/index.html.erb

<%= form_with(url: jobs_path, method: :get, class: "mt-0",
      data: {controller: "filter"}) do %>
  <div class="flex flex-col gap-4">
    <div class="flex flex-col justify-end mt-2">
      <%= label_tag :category, 'Category' %>
      <%= select_tag :category, options_for_select(['Engineering', 'Marketing', 'Design', 'Sales', 'Customer Service'], selected: params[:category]), include_blank: true, class: 'rounded-lg border-gray-300 mt-2',
        data: {action: "change->filter#submit"} %>
    </div>
    <div class="flex flex-col justify-end mt-2">
      <%= label_tag :location, 'Location' %>
      <%= select_tag :location, options_for_select(['New York', 'San Francisco', 'Berlin', 'Tokyo', 'London', 'Paris', 'Sydney', 'Toronto', 'Singapore', 'Remote'], selected: params[:location]), include_blank: true, class: 'rounded-lg border-gray-300 mt-2',
        data: {action: "change->filter#submit"} %>
    </div>
    <div class="flex items-center justify-start">
      <%= check_box_tag :remote, '1', params[:remote].present?, class: 'mr-2',
        data: {action: "change->filter#submit"} %>
      <%= label_tag :remote, 'Remote' %>
    </div>
    <% Job.commitments.keys.each do |commitment| %>
      <div class="flex items-center justify-start">
        <%= check_box_tag "commitments[]", commitment, params[:commitments]&.include?(commitment), id: "commitment_#{commitment}", class: 'mr-2',
          data: {action: "change->filter#submit"} %>
        <%= label_tag "commitment_#{commitment}", commitment.humanize %>
      </div>
    <% end %>
  </div>
<% end %>

And that's it! Now when you change any of the form values, the list of jobs will update without a page refresh. And if you refresh the page, you'll see the same list of jobs.

The important thing to notice is that only the turbo-frame is being updated. Even though the index action is sending back the entire HTML for the page, the only DOM that changes is the turbo-frame. This is the power of Turbo Frames.

PS - I tested this with half a million records on SQLite and it was stupid fast.

PPS - Having to add history.pushState({}, "", newUrl); to advance the browser to the new URL so you could reload the page or share the URL to the state of the filters shouldn't be needed, Turbo.visit(newUrl, { frame: "jobs", action: advance }); should have worked but there's a bug that will be fixed shortly.

It's really easy it turns out to implement this with a Turbo Frame. Let's do it.

Step 1: The Slide Over Turbo Frame

First, we need to create a Turbo Frame that will be the slide over. We'll call it slide-over and we'll put it at the bottom of the post index page.

app/views/posts/index.html.erb

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

  <div class="flex items-center justify-between">
    <h1 class="text-4xl font-bold">Posts</h1>
    <%= link_to "New post", new_post_path %>
  </div>

  <div id="posts" class="min-w-full">
    <%= render @posts %>
  </div>
</div>

<!-- This will be empty when the page loads -->
<%= turbo_frame_tag "slide-over" %>

We've basically create a frame or a slot that the eventual slide over will occupy on the dom the second that frame is given a URL to load content from.

We want to trigger that frame to load when we click on the new post button. So let's give that button the target of the slide-over turbo frame.

<%= link_to "New post", new_post_path,
      class: "btn btn-primary",
      data: {turbo_frame: "slide-over"} %>

Simple enough. When we click on that button now, it will change the source of the slide-over turbo frame and essentially load whatever HTML is the response to /posts/new.

The next step is to turn that into the slide over.

Step 2: The Slide Over

app/views/posts/new

<%= turbo_frame_tag "slide-over" do %>
  <div aria-labelledby="slide-over-title" role="dialog" aria-modal="true">

    <div class="backdrop animate-fade-in"></div>

    <section>
      <div class="absolute inset-0 overflow-hidden">
        <div class="fixed inset-y-0 right-0 flex max-w-full pl-10 pointer-events-none">
          <div class="w-screen max-w-md pointer-events-auto">

            <div class="flex flex-col h-full py-6 overflow-y-scroll bg-white shadow-xl">
              <div class="px-4 sm:px-6">
                <div class="flex items-start justify-between">
                  <h2 class="text-base font-semibold leading-6 text-gray-900" id="slide-over-title">New Post</h2>
                  <div class="flex items-center ml-3 h-7">
                    <button type="button" data-action="remove#remove slide-over#slideOut" class="relative text-gray-400 bg-white rounded-md hover:text-gray-500 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">
                      <span class="absolute -inset-2.5"></span>
                      <span class="sr-only">Close panel</span>
                      <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true">
                        <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
                      </svg>
                    </button>
                  </div>
                </div>
              </div>

              <section>
                <%= render "form", post: @post %>
              </section>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
<% end %>

We're putting a basic tailwind slide over as the content for the slide-over turbo frame. Within there is the new post form.

With that, clicking on the new post button will display the slide over but without any of the fancy animations. Let's add that by building a quick stimulus controller.

Step 3: Slide Over Animations

What we want to do is bind the slide over to a stimulus controller so that we can say when the controller connects, which will happen upon the injection of the slide over html into the DOM, trigger the animation classes.

First, let's bind the slide over to a stimulus controller.

app/views/posts/new

<%= turbo_frame_tag "slide-over" do %>
  <div aria-labelledby="slide-over-title" role="dialog" aria-modal="true"
    data-controller="slide-over">

    <!-- The rest of the slide over -->

  </div>
<% end %>

By giving that div the data-controller attribute of slide-over stimulus will look for a slide_over_controller.js file and controller. So let's build that so that it triggers animations upon connecting to it's DOM.

app/javascript/controllers/slide_over_controller.js

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  connect() {
    console.log("The Slide Over has Appeared");
  }
}

Now, when we click on the new post button, we should see that log in the console.

The next step is to create a target for the animation classes, the DOM element that we want to apply the animations to.

app/views/posts/new

<%= turbo_frame_tag "slide-over" do %>
  <div aria-labelledby="slide-over-title" role="dialog" aria-modal="true"
    data-controller="slide-over remove"
    data-remove-target="element">

    <div class="backdrop animate-fade-in"></div>

    <section>
      <div class="absolute inset-0 overflow-hidden">
        <div class="fixed inset-y-0 right-0 flex max-w-full pl-10 pointer-events-none">

          <!-- This element should be the target -->
          <div class="w-screen max-w-md pointer-events-auto"
            data-slide-over-target="slideOver">
            <div class="flex flex-col h-full py-6 overflow-y-scroll bg-white shadow-xl">
              <div class="px-4 sm:px-6">
                <div class="flex items-start justify-between">
                  <h2 class="text-base font-semibold leading-6 text-gray-900" id="slide-over-title">New Post</h2>
                  <div class="flex items-center ml-3 h-7">
                    <button type="button" class="relative text-gray-400 bg-white rounded-md hover:text-gray-500 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2"
                      data-action="remove#remove slide-over#slideOut">
                      <span class="absolute -inset-2.5"></span>
                      <span class="sr-only">Close panel</span>
                      <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true">
                        <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
                      </svg>
                    </button>
                  </div>
                </div>
              </div>

              <section>
                <%= render "form", post: @post %>
              </section>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
<% end %>

We can add that target to the stimulus controller and add the animation classes to it upon connection.

app/javascript/controllers/slide_over_controller.js

import { Controller } from "@hotwired/stimulus";

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

  connect() {
    this.slideOverTarget.classList.add("translate-x-full");
    setTimeout(() => {
      this.slideOverTarget.classList.remove("translate-x-full");
      this.slideOverTarget.classList.add(
        "transform",
        "transition",
        "ease-in-out",
        "duration-300",
        "sm:duration-700",
        "translate-x-0"
      );
    }, 100);
  }

  slideOut() {
    this.slideOverTarget.classList.remove("translate-x-0");
    this.slideOverTarget.classList.add(
      "transform",
      "transition",
      "ease-in-out",
      "duration-300",
      "sm:duration-700",
      "translate-x-full"
    );
  }
}

Now, when we click on the new post button, the slide over will slide in from the right. And when we click on the close button, it will slide out.

That's it!

For such a common pattern, I always scratch my head a little when I have to implement it. Generally, I end up doing it entirely in JS and make use of some sort of <template> tag. There's even a great Stimulus Component for Nested Forms that works exactly this way.

For whatever reason, I decided to implement the pattern using as little JS as possible, no templates, and rely on Turbo Streams to handle the DOM manipulation. I'm not sure if this is a good idea or not, but it was a fun experiment. Here's how it works.

You can browse the code for the demo app here.

Add Tags

The first step is to wire up the "Add Tag" button. When the user clicks the button, we want to add a new tag to the form. We'll do this by rendering a new tag partial and appending it to the DOM using Turbo Stream.

Step 1: Wire Turbo Stream Request

The Add Tag button needs to make a request for a turbo stream. To do that, we set the data-turbo-stream attribute to true (or anything) on the button.

app/views/posts/_form.html.erb

<%= link_to "Add Tags +", posts_tags_path, class: "btn", data: {turbo_stream: true} %>

That will trigger the GET request to fire with the text/vnd.turbo-stream.html format triggering the correct MIME type response.

Step 2: Append the Tag Field

We need to send back the turbo stream response by creating app/views/posts/tags/new.turbo_stream.erb which will render in response to the get request (because GET /posts/tags/new routes to posts/tags#new wired up to render this template).

app/views/posts/tags/new.turbo_stream.erb

<%= turbo_stream.append "tags" do %>
  <li data-controller="remove" data-remove-target="element">
    <%= text_field_tag "post[tags][]", "", id: "", data: {controller: "focus", focus_focus_value: "now"} %>
    <button data-action="remove#remove">Remove</button>
  </li>
<% end %>

Don't worry about the stimulus parts yet. For now we're just adding an li to the tags list. That should get it to appear when we click on the Add Tags button.

text_field_tag "post[tags][]" is a Rails helper that will generate a text field with the name post[tags][] which will be an array of tags. We'll use this later to create the tags in the controller.

Step 3: Focus the Tag Field

When the person clicks on Add Tag, it would be nice if the field that just came on the page was in focus so they can just start typing. I built a little stimulus controller called focus for this.

app/javascript/controllers/focus_controller.js

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static values = { focus: String };

  connect() {
    if (this.focusValue == "now") {
      this.element.focus();
    }
  }
}

Because our text field had data: {controller: "focus", focus_focus_value: "now"}, the focus controller will connect to that element supplying the stimulus value for focus as now. When the controller connects, if that value is now, it will focus the element that just came into view.

Step 4: Remove the Tag Field

We also want to be able to remove tags. To do that, we have a Remove button <button data-action="remove#remove">Remove</button>. When that is clicked, the remove action in the stimulus controller will fire. The entire li is bound to the remove controller additionally supplying it with a stimulus target of element, basically saying, "I am the element to be removed." <li data-controller="remove" data-remove-target="element">

app/javascript/controllers/remove_controller.js

import { Controller } from "@hotwired/stimulus";

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

  connect() {}

  remove(e) {
    e.preventDefault();
    this.elementTarget.classList.add("animate-fade-out");
    setTimeout(() => this.elementTarget.remove(), 200);
  }
}

Conclusion

This feels easier to me than the straight JS approach. I also think following this pattern for editing tags on a post will be easier than using a JS approach. I'll do that next.

Quick Review

Just for fun, I thought we'd add a feature where after the upload is complete we display an audio player for the track that was just uploaded. If we look back at our code, in our Upload class, we have the process method:

app/javascript/controllers/uploadzone_controller.js

  process() {
  this.insertUpload();

  this.directUpload.create((error, blob) => {
    if (error) {
      // Handle the error
    } else {
      const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

      post("/tracks", {
        body: trackData,
        contentType: "application/json",
        responseKind: "json",
      });
    }
  });
}

After the upload is sent to s3 via this.directUpload.create, in the callback for that we have our post call where we send the uploaded track information to our rails backend so that we can create the Track in our database and attach the file we uploaded to it. That post request, if you remember, returns a JSON representation of the Track created.

app/controller/tracks_controller.rb

def create
  @track = Track.new(track_params)
  @track.audio_file.attach(params[:signed_blob_id])
  if @track.save
    render json: @track, status: :created
  end
end

The return for that looks like:

Adding the Audio URL to JSON

Commit

If we just include the URL of the track we just uploaded in that JSON, we could insert an audio tag into the DOM. Let's modify the JSON to include the URL for the Track. Let's update the TracksController to include a signed URL from S3 that will allow the Mp3 to be played:

app/controller/tracks_controller.rb

def create
  @track = Track.new(track_params)
  @track.audio_file.attach(params[:signed_blob_id])
  if @track.save
    render json: {
      track: @track,
      audio_url: @track.audio_file.url
    }, status: :created
  end
end

Now the response from our post looks like this:

Processing the JSON Response

With that we can grab the audio_url and replace the progress bar with an audio tag. Let's jump back to our Upload class in our uploadzone_controller.js and make that happen.

The first change is to make the callback to this.directUpload.create an async method so that we can tell it to await for the post request to complete. Then we need to capture the resulting JSON. For now, let's just log it to the console to make sure it works.

  process() {
    this.insertUpload();

    this.directUpload.create(async (error, blob) => {
      if (error) {
        // Handle the error
      } else {
        const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

        const trackResponse = await post("/tracks", {
          body: trackData,
          contentType: "application/json",
          responseKind: "json",
        });

        if (trackResponse.ok) {
          const trackJSON = await trackResponse.json;
          console.log(trackJSON);
        }
      }
    });
  }

Becaues this method is getting a bit long, let's make a mental note to refactor it, but the relevant addition we made is:

const trackResponse = await post("/tracks", {
  body: trackData,
  contentType: "application/json",
  responseKind: "json",
});

if (trackResponse.ok) {
  const trackJSON = await trackResponse.json;
  console.log(trackJSON);
}

We're getting the response, making sure it was a 200 and it worked, then converting it to json and logging it. If we upload a track we'll see:

Inserting the Audio Tag

With the audio_url, we have all the data we need to take the next step and replace the progress bar with an audio tag.

Let's make a new method for that, insertAudio and pass in the audio_url.

insertAudio(audioURL) {
  // Find the progressBarDiv
  const progressBarDiv = document.querySelector(`#upload_${this.directUpload.id} .progress`);

}

The first thing we're doing is finding the progress bar div that we made in insertUpload. Once we have that div, we want to create an audio element, make some adjustments to the wrapper of the progress bar to make it taller, and then append the audio tag and remove the progress bar:

insertAudio(audioURL) {
  const progressBarDiv = document.querySelector(`#upload_${this.directUpload.id} .progress`);

  // Create audio element
  const audio = document.createElement("audio");
  audio.controls = true;
  audio.src = audioURL;
  audio.classList.add("w-full");

  // Make the parent progressWrapper div taller
  progressBarDiv.parentElement.classList.add("h-14");
  progressBarDiv.parentElement.classList.remove("h-4");

  // Insert the audio tag and remove the progress bar.
  progressBarDiv.parentElement.appendChild(audio);
  progressBarDiv.remove();
}

With that we get this really awesome effect:

A fully functional audio player after the upload.

Refactoring

Commit

There are 3 code smells for me.

1. The process method is a bit long.
2. We're passing an argument into insertAudio.
3. We're finding a DOM element that we previously created.

Smells 2 and 3 are somewhat related, which is that whenever I'm in a pure object oriented paradigm, if I'm passing data that relates to the instance, like the audio_url, or finding data that I previously made again (like firing a SQL statement twice), I think to myself, hmm, shouldn't this be a part of the instance as a property?

Smell 1 is just that process seems to be doing 2 things, uploading the track and now processing json, that seems like a clear division. Let's do that refactor first and remove the logic for creating the track into its own method that we'll pass to the this.directUpload.create callback:

process() {
 this.insertUpload();

 this.directUpload.create((error, blob) => this.createTrack(error, blob));
}

async createTrack(error, blob) {
 if (error) {
   // Handle the error
 } else {
   const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

   const trackResponse = await post("/tracks", {
     body: trackData,
     contentType: "application/json",
     responseKind: "json",
   });

   if (trackResponse.ok) {
     const trackJSON = await trackResponse.json;

     this.insertAudio(trackJSON.audio_url);
   }
 }
}

Tada! Love a good extract method refactor.

Now the basic premise of passing arguments or refinding data in object orientation is make it a property. If we want to use trackJSON.audio_url in insertAudio, let's just make it a property of the instance of Upload instead of passing it around.

Instead of const trackJSON = await trackResponse.json; we'll do this.trackJSON = await trackResponse.json;

That's it. Once the trackJSON is part of the instance, inside insertAudio we can just read it when we need it. And we don't need to pass it when we call insertAudio.

insertAudio() {
 const progressBarDiv = document.querySelector(`#upload_${this.directUpload.id} .progress`);

 // Create audio element
 const audio = document.createElement("audio");
 audio.controls = true;
 audio.src = this.trackJSON.audio_url;
 audio.classList.add("w-full");

 // Make the parent progressWrapper div taller
 progressBarDiv.parentElement.classList.add("h-14");
 progressBarDiv.parentElement.classList.remove("h-4");

 // Insert the audio tag and remove the progress bar.
 progressBarDiv.parentElement.appendChild(audio);
 progressBarDiv.remove();
}

No more argument and the important line is audio.src = this.trackJSON.audioURL;

The final code for createTrack looks like:

async createTrack(error, blob) {
 if (error) {
   // Handle the error
 } else {
   const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

   const trackResponse = await post("/tracks", {
     body: trackData,
     contentType: "application/json",
     responseKind: "json",
   });

   if (trackResponse.ok) {
     this.trackJSON = await trackResponse.json;

     this.insertAudio();
   }
 }
}

We're going to do a similar thing for the progress div. Once we create that element in insertUpload, we're just going to make a reference to that element in the DOM a property of the instance. We'll change const progressBar = document.createElement("div"); to this.progressBar = document.createElement("div");`.

Our insertUpload method now looks like this, with every reference to progressBar changed to be the property.

insertUpload() {
  const fileUpload = document.createElement("div");

  fileUpload.id = `upload_${this.directUpload.id}`;
  fileUpload.className = "p-3 border-b";

  fileUpload.textContent = this.directUpload.file.name;

  const progressWrapper = document.createElement("div");
  progressWrapper.className = "relative h-4 overflow-hidden rounded-full bg-secondary w-[100%]";
  fileUpload.appendChild(progressWrapper);

  this.progressBar = document.createElement("div");
  this.progressBar.className = "progress h-full w-full flex-1 bg-primary";
  this.progressBar.style = "transform: translateX(-100%);";
  progressWrapper.appendChild(this.progressBar);

  const uploadList = document.querySelector("#uploads");
  uploadList.appendChild(fileUpload);
}

Now that the progressBar is a property of the instance, we can simplify our insertAudio yet again:

insertAudio() {
  // Create audio element
  const audio = document.createElement("audio");
  audio.controls = true;
  audio.src = this.trackJSON.audio_url;
  audio.classList.add("w-full");

  // Make the parent progressWrapper div taller
  this.progressBar.parentElement.classList.add("h-14");
  this.progressBar.parentElement.classList.remove("h-4");

  // Insert the audio tag and remove the progress bar.
  this.progressBar.parentElement.appendChild(audio);
  this.progressBar.remove();
}

Everything still works! The final javascript controller looks like:

That's it for this series, post comments below and please follow me @aviflombaum.

The problem is pretty obvious, there is absolutely no visual feedback in the UI letting us know what is happening or what works. In fact, looking at that, we don't even kno what happened. Let's fix.

Adding the Uploads to a List

Commit

Let's start by adding a list of files that are being uploaded. We'll add a div to div#uploads for each file that is being uploaded,

At what point in our code do we know that the user wants to upload a file so that we can grab it and put the file to be uploaded into div#uploads?

If you open up app/javascript/controllers/uploadzone_controller.js you'll see that we have a uploadFile method that gets called to upload a file. Let's modify that so that before the upload starts, we can insert a div with the file name. After the DirectUpload instance is created but before we call create on it to upload it, we'll insert our code.

app/javascript/controllers/uploadzone_controller.js

uploadFile(file) {
  const upload = new DirectUpload(file, "/rails/active_storage/direct_uploads");

  this.insertUpload(upload);

  upload.create((error, blob) => {
    // Rest of upload logic
  });
}

Because there's going to be a good amount of logic to insert the element into the dom, instead of implementing it there, we are just going to call the non-existent method insertUpload. We pass it the instance of upload so that it has access to the upload.file.

Now we need to write the insertUpload method.

app/javascript/controllers/uploadzone_controller.js

insertUpload(upload) {
  const fileUpload = document.createElement("div");
  fileUpload.textContent = upload.file.name;

  const uploadList = document.querySelector("#uploads");
  uploadList.appendChild(fileUpload);
}

If you try an upload now, you should see:

So we are getting some visual feedback. The next thing we want to do, in addition to styling these elements a bit, is add a div.progress element to the div so that we can update it with the file progress as the file is being uploaded. Most of this is just tailwind classes, but the important thing to pay attention to is the id of the div for the fileUpload.

app/javascript/controllers/uploadzone_controller.js

  insertUpload(upload) {
    const fileUpload = document.createElement("div");

    fileUpload.id = `upload_${upload.id}`;
    fileUpload.className = "p-3 border-b";

    fileUpload.textContent = upload.file.name;

    const progressWrapper = document.createElement("div");
    progressWrapper.className = "relative h-4 overflow-hidden rounded-full bg-secondary w-[100%]";
    fileUpload.appendChild(progressWrapper);

    const progressBar = document.createElement("div");
    progressBar.className = "progress h-full w-full flex-1 bg-primary";
    progressBar.style = "transform: translateX(-100%);";
    progressWrapper.appendChild(progressBar);

    const uploadList = document.querySelector("#uploads");
    uploadList.appendChild(fileUpload);
  }

The most important part is setting the id of the fieUpload. Each upload instance gets an id, which is the index of the upload (so if we were uploading 4 files, the second one would be 2). By doing this, as we are getting progress for the upload, we can find this div easily again to update the .progress element.

If we upload a few files now, the UI looks way better.

Updating the Progress Bar

If you look deep in the ActiveStorage documentation, you will find a section for tracking the progress of a file upload. We're going to use that.

Basically, if we pass DirectUpload a third argument, a context, DirectUpload can attach the xhr request to it and trigger a callback, directUploadWillStoreFileWithXHR on the context passing it the request object of the xhr request.

This part gets confusing, so hang on.

In order to track the individual progress of each upload, we need to represent each upload as an instance of something that can have its own scope so that we can use that as the context for the DirectUpload instance. Without this, it would be impossible to know which xhr request relates to which upload.

The good news is that even if you don't quite get that, and by the way, the first 3 times I built this, I didn't get that and just took code samples for granted, the code we're going to implement is a logical refactor anyway.

What we're going to do is extract all this upload logic, which is now a lot, out of our controller and into a model of sorts, an Upload class. Every time we want to upload a file, we will instantiate an instance of Upload and let that object do all the work. Our controller will be lean and clean and our Upload class will be responsible for all the upload logic.

Extracting Upload

Normally I would put this class in app/javascript/models/Upload.js but because that would mean having to import it into the controller, which means another interaction with importmaps which is confusing enough, I'm just going to put it in app/javascript/controllers/uploadzone_controller.js for now. We can always move it later.

At the top of app/javascript/controllers/uploadzone_controller.js add:

import { Controller } from "@hotwired/stimulus";
import { DirectUpload } from "@rails/activestorage";
import { post } from "@rails/request.js";

class Upload{

}

export default class extends Controller {

Now we've got a place to define this class and the controller will have access to it because it's in the same file.

The extraction point, the point at which we want to pass control from the controller to the Upload class is in the files loop of acceptFiles. Instead of calling this.uploadFile(file) we'll call new Upload(file) and then some sort of method to basically say do your thing or more programmatically process().

Let's define a constructor for Upload and stub out a process method, and make this cut so that we can then move over the rest of the upload logic out of the controller and into this instance.

class Upload {
  constructor(file) {
    // Here's where we will instantiate the DirectUpload instance.
  }

  process() {
    // Here's where we will actually kick off the upload process.
  }
}

We're also going to make the refactor cut and instead of directly calling this.uploadFile in acceptFiles, we're going to instantiate an instance of Upload and call process on it.

acceptFiles(event) {
  event.preventDefault();
  const files = event.dataTransfer ? event.dataTransfer.files : event.target.files;
  [...files].forEach((f) => {
    new Upload(f).process();
  });
}

It's nice to test out that this is working by either putting a console.log or a debugger in the process method and making sure it's being called once per file.

Extract Class/Method

The basic refactoring technique we're using here is Extract Class and Extract Method. We've already extracted our class, and now we want to extract all the methods relating to upload into this class.

What's really nice here is that we're basically following the Model/Controller paradigm of MVC in our Stimulus controller.

The controller itself is responsible for the controller logic, taking things from the view, the dropzone, and passing them to the model.

Much like it takes a second in Rails to realize you can just introduce POROs (Plain Old Ruby Objects) wherever you want and maintain really nice Object Orientation, in Stimulus, your controller can and probably should, interact with other well encapsulated POJOs (Plain Old JavaScript Objects). This is a really nice way to keep your code clean and organized and makes testing so much easier.

Implementing Upload

Let's just move over one method at a time and update its variables and scope to maintain the current functionality. Let's start with uploadFile.

class Upload {
  constructor(file) {
    // Here's where we will instantiate the DirectUpload instance.
  }

  process() {
    // Here's where we will actually kick off the upload process.
    console.log(this);
  }

  uploadFile(file) {
    const upload = new DirectUpload(file, "/rails/active_storage/direct_uploads");

    this.insertUpload(upload);

    upload.create((error, blob) => {
      if (error) {
        // Handle the error
      } else {
        const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

        post("/tracks", {
          body: trackData,
          contentType: "application/json",
          responseKind: "json",
        });
      }
    });
  }
}

Looking at this, uploadFile basically looks like it should be our process implementation. So we're going to move all the logic into there.

We're also going to move the DirectUpload instance into the constructor so that we can make the instance an instance property and then access it from process.

We're doing all of this after all so that instances can properly maintain their own scope and data.

class Upload {
  constructor(file) {
    this.directUpload = new DirectUpload(file, "/rails/active_storage/direct_uploads");
  }

  process() {
    //this.insertUpload(upload);

    this.directUpload.create((error, blob) => {
      if (error) {
        // Handle the error
      } else {
        const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

        post("/tracks", {
          body: trackData,
          contentType: "application/json",
          responseKind: "json",
        });
      }
    });
  }
}

Way better. This should be functional. Try it out in your browser and see if you still see the upload requests firing.

Let's move on to insertUpload. Extracting that is mostly about identifying out of scope references and correcting them. There doesn't look to be any as long as we're passing in this.directUpload as an argument. from process. If we make that change, we should see the method work as expected. It does.

But there's no reason to pass that argument in as it is a property of the instance so we can just update the method to use this.directUpload directly and remove the argument from the method call in process.

insertUpload() {
  const fileUpload = document.createElement("div");

  fileUpload.id = `upload_${this.directUpload.id}`;
  fileUpload.className = "p-3 border-b";

  fileUpload.textContent = this.directUpload.file.name;

  const progressWrapper = document.createElement("div");
  progressWrapper.className = "relative h-4 overflow-hidden rounded-full bg-secondary w-[100%]";
  fileUpload.appendChild(progressWrapper);

  const progressBar = document.createElement("div");
  progressBar.className = "progress h-full w-full flex-1 bg-primary";
  progressBar.style = "transform: translateX(-100%);";
  progressWrapper.appendChild(progressBar);

  const uploadList = document.querySelector("#uploads");
  uploadList.appendChild(fileUpload);
}

And that's it! We've entirely extracted the upload logic out of the controller and into a separate class. We're now at the point where we can implement the progress bar.

Implementing the Progress Bar

Now that we have a context that represents the indiviual uploads we can pass that context, which is the instance of the Upload itself into DirectUpload.

constructor(file) {
  this.directUpload = new DirectUpload(file, "/rails/active_storage/direct_uploads", this);
}

What this means is that DirectUpload can now call methods on the instance of Upload that it's been passed. This is how we're going to implement the progress bar. Specifically, we're going to implement the directUploadWillStoreFileWithXHR method. This is the hook that DirectUpload provides and passes the xhr request object too. Once we have that object, we can add an event listener to it to be notified of the progress of the upload.

Within the Upload class, continue by defining:

directUploadWillStoreFileWithXHR(request) {
  request.upload.addEventListener("progress", (event) => this.updateProgress(event));
}

This method gets automatically called by DirectUpload during create as it actually conducts the upload. We listen to the progress event on the request.upload object and call updateProgress with the event.

For now, let's implement updateProgress to just log the event and the two properties we care about, event.loaded and event.total.

updateProgress(event) {
  console.log(event.loaded, event.total);
}

This is great. We're getting the progress of the upload. Now we just need to update the progress bar. We're going to convert the loaded and the total to percentages and then update the progress bar translateX value to move the black div to the right, representing progress.

updateProgress(event) {
  const percentage = (event.loaded / event.total) * 100;
  const progress = document.querySelector(`#upload_${this.directUpload.id} .progress`);
  progress.style.transform = `translateX(-${100 - percentage}%)`;
}

Who remembers why #upload_${this.directUpload.id} .progress finds the correct elements for this upload's progress to update?

It's because in insertUpload when we add the upload to the DOM, we set the id of the upload to upload_${this.directUpload.id}. This means that we can find the upload by its id and then find the progress bar within it.

This was the entire point of the Upload refactor. To be able to maintain the scope of each individual upload. Basically, to encapsulate the upload into an instance that could then later refer to itself and find it's progress bar again.

With that code, we're done.

Here's the entire app/javascript/controllers/uploadzone_controller.js file:

import { Controller } from "@hotwired/stimulus";
import { DirectUpload } from "@rails/activestorage";
import { post } from "@rails/request.js";

class Upload {
  constructor(file) {
    this.directUpload = new DirectUpload(file, "/rails/active_storage/direct_uploads", this);
  }

  process() {
    this.insertUpload();

    this.directUpload.create((error, blob) => {
      if (error) {
        // Handle the error
      } else {
        const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

        post("/tracks", {
          body: trackData,
          contentType: "application/json",
          responseKind: "json",
        });
      }
    });
  }

  insertUpload() {
    const fileUpload = document.createElement("div");

    fileUpload.id = `upload_${this.directUpload.id}`;
    fileUpload.className = "p-3 border-b";

    fileUpload.textContent = this.directUpload.file.name;

    const progressWrapper = document.createElement("div");
    progressWrapper.className = "relative h-4 overflow-hidden rounded-full bg-secondary w-[100%]";
    fileUpload.appendChild(progressWrapper);

    const progressBar = document.createElement("div");
    progressBar.className = "progress h-full w-full flex-1 bg-primary";
    progressBar.style = "transform: translateX(-100%);";
    progressWrapper.appendChild(progressBar);

    const uploadList = document.querySelector("#uploads");
    uploadList.appendChild(fileUpload);
  }

  directUploadWillStoreFileWithXHR(request) {
    request.upload.addEventListener("progress", (event) => this.updateProgress(event));
  }

  updateProgress(event) {
    const percentage = (event.loaded / event.total) * 100;
    const progress = document.querySelector(`#upload_${this.directUpload.id} .progress`);
    progress.style.transform = `translateX(-${100 - percentage}%)`;
  }
}

export default class extends Controller {
  static targets = ["fileInput"];
  connect() {
    this.element.addEventListener("dragover", this.preventDragDefaults);
    this.element.addEventListener("dragenter", this.preventDragDefaults);
  }

  disconnect() {
    this.element.removeEventListener("dragover", this.preventDragDefaults);
    this.element.removeEventListener("dragenter", this.preventDragDefaults);
  }

  preventDragDefaults(e) {
    e.preventDefault();
    e.stopPropagation();
  }

  trigger() {
    this.fileInputTarget.click();
  }

  acceptFiles(event) {
    event.preventDefault();
    const files = event.dataTransfer ? event.dataTransfer.files : event.target.files;
    [...files].forEach((f) => {
      new Upload(f).process();
    });
  }
}

Recap and Next Steps

This post covered a lot! Let's summarize the major steps and why we took them.

1. First we added a representation of the upload into the DOM. This was the insertUpload method.

2. Upon building that, we realized we couldn't refer to each individual upload because we didn't have a way to scope it. So we created the Upload class to encapsulate each upload.

3. We moved all the upload related methods from the controller into the Upload class. We updated any scope issues.

4. We sent the upload instance to DirectUpload so that it could call methods on it.

5. We then added the directUploadWillStoreFileWithXHR method to the Upload class to be able to listen to the progress of the upload.

6. Finally, we added the updateProgress method to update the progress bar.

So it was a lot.

I'm going to write one more quick post tomorrow on using the response from Rails to update the upload with the track's name and link to it and embed a small music player. Then we'll be done with this series and you'll have built a pretty awesome drag and drop upload experience.

The S3 Direct Upload Process

The process of uploading a file to S3 is a little more complicated than just sending a file to S3. The file needs to be signed by AWS, and then sent to S3.

Luckily, Rails makes this way easier by providing you with a URL to use that will give you the presigned URL. In fact Rails provides javascript library that abstracts the entire two step process of getting the signed URL and then sending the file along that URL to s3 into a super easy to use library, @rails/activestorage.

The ActiveStorage Direct Upload Process

Commit

The first step is to add the @rails/activestorage library to your project. There are instructions in the Direct Upload section of the npm package docs. Since our example application is using importmaps, we'll pin the library. Run the following:

./bin/importmap pin @rails/activestorage

A Quick and Dirty Upload

Commit

Let's make sure everything is working and just get uploading working and then we will refactor it and add the ability to see live progress. The API of the library is pretty easy.

const upload = new DirectUpload(file, url);

The file is the file you want to upload, and the url is the static URL that Rails gives you to get the presigned URL, as far as I can tell, it's always /rails/active_storage/direct_uploads.

Instances of this DirectUpload object have a create that handles the actual uploading and accepts a callback for what you want to do after the upload is complete. Let's just put a debugger in there and put it all together.

In our controller, we're going to add an uploadFile method that will accept each file and upload it via the DirectUpload process described above.

First, import the library to the controller. Then add the method.

app/javascript/controllers/uploadzone_controller.js

import { Controller } from "@hotwired/stimulus";
import { DirectUpload } from "@rails/activestorage";

export default class extends Controller {
// Rest of class

  uploadFile(file) {
    const upload = new DirectUpload(file, '/rails/active_storage/direct_uploads');
    upload.create((error, blob) => {
      if (error) {
        // Handle the error
      } else {
        debugger;
      }
    });
  }
}

Now let's pass each file from acceptFiles to this method and see what happens.

app/javascript/controllers/uploadzone_controller.js

acceptFiles(event) {
  event.preventDefault();
  const files = event.dataTransfer ? event.dataTransfer.files : event.target.files;
  [...files].forEach((f) => {
    this.uploadFile(f);
  });
}

With that you should be able to try the application and end up in a debugger with access to the blob from the upload.

If you look at the blob in console, you'll see.

We did it! The file has been uploaded to S3 and Rails even created the ActiveStorage instance and saved it for us. Which is to say, this file is in our database. All we need to do now is attach it to our track!

Attaching the File to the Track

Commit

While we created an attachment, we still have to create the Track that has that attachment.

What we want to do is send a request to our server to attach the blob to the track. We'll do this by sending a POST request to /tracks with the signed_blob_id, essentially a unique identifier with which to identify the attachment, along with the filename and allow our controller action to create the post and attach the file.

Let's get our form data ready to send to the server.

const trackData = {track: {filename: blob.filename}, signed_blob_id: blob.signed_id}};

We're basically setting up the params object that we want to submit to tracks#create in our Rails application.

Rails gives you a great library for making requests to your server, @rails/request.js. We'll use that to make the request.

Let's pin that to our application too.

./bin/importmap pin @rails/request.js

If we import the library, we can use it to make a request to our server.

app/javascript/controllers/uploadzone_controller.js

import { Controller } from "@hotwired/stimulus";
import { DirectUpload } from "@rails/activestorage";
import { post } from "@rails/request.js";

We now have a post function that we can use to submit post requests via AJAX and not have to worry about CSRF and other rails security stuff.

app/javascript/controllers/uploadzone_controller.js

uploadFile(file) {
  const upload = new DirectUpload(file, "/rails/active_storage/direct_uploads");
  upload.create((error, blob) => {
    if (error) {
      // Handle the error
    } else {
      const trackData = { track: { filename: blob.filename }, signed_blob_id: blob.signed_id };

      post("/tracks", {
        body: trackData,
        contentType: "application/json",
        responseKind: "json",
      });
    }
  });
}

We're taking the trackData, submitting it as JSON, and expecting a JSON response. We're not doing anything with the response yet, but we will in a minute. Let's see if this submits the request and then jump to the Rails backend.

That worked! We submitted a POST request to /tracks with the trackData as the body. We can now jump to the Rails backend and handle this request.

Creating the Track

First let's create the correct route as the attempt resulted in a 404 above.

Add to config/routes.rb

post "tracks", to: "tracks#create"

Then, and I'm moving through the rails part a little fast, let's create the controller action.

app/controllers/tracks_controller.rb

def create
  @track = Track.new(track_params)
  @track.audio_file.attach(params[:signed_blob_id])
  if @track.save
    render json: @track, status: :created
  end
end

private

def track_params
  params.require(:track).permit(:title, :artist_name, :filename)
end

The key line here is @track.audio_file.attach(params[:signed_blob_id]), which will attach the file to the track using the signed_blob_id that we sent in the request.

If we do all that and then try to upload a file, we'll see that it returned a valid JSON response of the newly created track, which is to say, we did it.

We can even go into our console and get the URL of the track that was just uploaded.

Recap

In this post we focused on uploading the track to S3 and creating track record in our database as well as attaching the uploaded audio file to the track as an attachment.

We did this by:

1. Used DirectUpload from @rails/activestorage to upload the file to S3.
2. Constructed a trackData object that we could send to our Rails backend using the blob object returned from `DirectUpload.
3. Used post from @rails/request.js to submit a POST request to our Rails backend with the trackData
4. Built a create action in our Rails controller that takes the data and creates a Track with it. It uses the signed_blob_id to attach the audio_file to the track.

Wow! Really awesome. The final step that we'll cover in part 3 is adding progress to the uploads and replacing them with an audio player when the track is done uploading.

It might get complex and there are a lot of steps, but its worth it and you can totally do it.

If you want more resources on the topic, Chris has a great video on Activestorage with Direct Uploads.

The Setup

If you want to follow along, the first thing I did was clone my Rails Starter template. But any Rails app will do. The only thing that's special about my template for the sake of this demo is that it is using importmaps to manage JS dependencies. But we're not going to have any dependencies so it shouldn't matter.

You can follow along by following the commits in the series github repo.

Setup Your Model

Commit

We're going to use a Track model where a track will have a filename, title and artist_name. We'll also add a has_one_attached :audio_file to the model.

rails g model Track filename title artist_name

Then let's install ActiveStorage.

bin/rails active_storage:install

And finally lets add the has_one_attached :audio_file to the model.

app/models/track.rb

class Track < ApplicationRecord
  has_one_attached :audio_file
end

Run your migrations with rails db:migrate.

Let's make sure this worked by uploading an mp3 file to a new track in the console.

track = Track.new
track.audio_file.attach(io: File.open("./spec/fixtures/Plastikbeat - Babarabatiri Loop (Original Mix).mp3"), filename: "01 - The Beatles - I Saw Her Standing There.mp3")
track.save

If you want that file, you can grab it here and put it in spec/fixtures.

Setup S3

Commit

The next step is setting up S3. This has been covered in a lot of places, the Rails Guide are fine. Just make sure to configure the corect CORS settings for a direct upload.

And don't forget to add the aws-sdk-s3 gem with bundle add aws-sdk-s3.

Configure the Correct CORS for Your Bucket

Make sure you configure the correct CORS settings to allow direct uploads. Again, the Rails Guides on CORS are fine. Just make sure you edit the AllowedOrigins section. My CORS looked like this:

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT"
        ],
        "AllowedOrigins": [
            "http://localhost",
            "http://127.0.0.1",
            "http://localhost:3000",
            "http://127.0.0.1:3000"
        ],
        "ExposeHeaders": [
            "Origin",
            "Content-Type",
            "Content-MD5",
            "Content-Disposition"
        ],
        "MaxAgeSeconds": 3600
    }
]

Okay, I'm assuming that you setup S3 and changed your ActiveStorage settings to use S3/Amazon.

If you've done all that you should be able to create another track in your console as we did above and this time, after you track.save, try calling track.audio_file.url. You should get back a nice looking S3 URL.

The View

Commit

Let's setup our view.

overmind

If you're using my starter template, I use overmind to manage my processes. If you're not using overmind, I highly recommend it. Learn how to use overmind instead of foreman or here Without overmind, you can still run rails s but you should also run bin/rails tailwindcss:watch in another terminal.

If your app is working, you should see my nice starter page.

Tracks Controller

To get our views going, let's generate a tracks_controller with a new and create action.

rails g controller tracks new create

Let's go over to http://localhost:3000/tracks/new

To make our view, we're going to do two things.

First, let's drop the HTML we're going to use in our view.

app/views/tracks/new.html.erb

<div class="w-full">
  <div class="p-6">
    <div id="uploadzone">
      <button
        class="w-full rounded-lg bg-muted border-2 border-dashed border-gray-300 p-8 text-center hover:border-gray-400 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">
        <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="mx-auto h-12 w-12 text-gray-400"><path d="M17.5 22h.5c.5 0 1-.2 1.4-.6.4-.4.6-.9.6-1.4V7.5L14.5 2H6c-.5 0-1 .2-1.4.6C4.2 3 4 3.5 4 4v3"></path><polyline points="14 2 14 8 20 8"></polyline><path d="M10 20v-1a2 2 0 1 1 4 0v1a2 2 0 1 1-4 0Z"></path><path d="M6 20v-1a2 2 0 1 0-4 0v1a2 2 0 1 0 4 0Z"></path><path d="M2 19v-3a6 6 0 0 1 12 0v3"></path></svg>
        <span class="mt-2 block text-sm font-semibold text-gray-900 dark:text-white">Drag Tracks to Upload or Click Here</span>
      </button>
    </div>
  </div>
  <div id="uploads" class="flex flex-col overflow-y-scroll divide-y border h-[calc(100vh-18em)]">
  </div>
</div>

That's just a bunch of tailwind stuff but it'll make a pretty nice looking upload zone page with a locked container to store all the files that get uploaded in a scrollable window. It'll look like this:

You also have to open app/views/layouts/application.html.erb and change the margin top from 28 to 8 using mt-8.

Building the Upload Zone

We need to have our upload zone be able to accept files. We're going to use the HTML5 File API to do this but it's not that complicated. You could always use a great library like Dropzone.js, but I accidentally promised this would be dependency free even though I used Dropzone.js for production.

Triggering the File Upload

Commit

We need to make it so that when you click on the uploadzone it triggers the familiar File Upload dialog. We're going to do this with a little bit of JavaScript.

The first step is adding a hidden file input field to our HTML, <input type="file" class="hidden" multiple />.

Let's now create a stimulus controller to handle the upload zone.

rails g stimulus uploadzone

Let's build a method in the controller to handle the triggering of the file upload dialog.

app/javascript/controllers/uploadzone_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {}

  trigger() {
    this.element.querySelector("input[type=file]").click();
  }
}

Before we talk about refactoring that at all, let's add the controller and action to our HTML.

Let's make the entire uploadzone div bound to the stimulus controller and add a click event to it.

Edit app/views/tracks/new.html.erb and add the following to the uploadzone div.

<div id="uploadzone" data-controller="uploadzone" data-action="click->uploadzone#trigger">

Now, when you click on the uploadzone div, it'll trigger the trigger method in the controller which will click the hidden file input which will trigger the dialog.

Lovely.

Refactor to Use a Target

Instead of doing our querySelector, let's make the hidden file input a target of our controller named fileInput.

app/javascript/controllers/uploadzone_controller.js

import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["fileInput"];
  connect() {}

  trigger() {
    this.fileInputTarget.click();
  }
}

And in our HTML, to bind the file input as a target:

app/views/tracks/new.html.erb

<input type="file" class="hidden" multiple data-uploadzone-target="fileInput">

Everything should still work.

Drag and Drop

Commit

Preventing Default Drag and Drop Behavior

Now that we have the file input triggering, let's make it so that we can drag and drop files into the uploadzone.

In order to do this, the first thing we need to do is prevent the browser from doing what it normally does when you do a drag and drop.

Let's add this to our stimulus controller:

app/javascript/controllers/uploadzone_controller.js

connect() {
  this.element.addEventListener("dragover", this.preventDragDefaults);
  this.element.addEventListener("dragenter", this.preventDragDefaults);
}

disconnect() {
  this.element.removeEventListener("dragover", this.preventDragDefaults);
  this.element.removeEventListener("dragenter", this.preventDragDefaults);
}

preventDragDefaults(e) {
  e.preventDefault();
  e.stopPropagation();
}

Because our uploadzone is bound to the entire div we want to monitor for the drag and drop, we can do this in our connect hook. this.element represents that uploadzone div, the element of the controller. We're adding listeners to dragover and dragenter which will tell the browser to not do what they normally do by calling our preventDragDefaults method.

When the controller disconnects, let's clean that up by removing the listeners.

You should be able to drag a file into the space and see nothing happen (as opposed to the browser opening your file).

Accepting Files from the Drag and Drop

Now that we've prevented the browser from doing what it normally does, we need to accept the files that are being dragged into the uploadzone. Let's bind another action to our uploadzone div, drop->uploadzone#acceptFiles.

app/views/tracks/new.html.erb

    <div id="uploadzone" data-controller="uploadzone" data-action="click->uploadzone#trigger drop->uploadzone#acceptFiles">

That will make it so that when we drop files into the uploadzone, it'll call the acceptFiles method in our controller.

app/javascript/controllers/uploadzone_controller.js

acceptFiles(event) {
  event.preventDefault();
  const files = event.dataTransfer.files
  debugger;
}

We're going to use the dataTransfer property of the event to get the files that were dropped into the uploadzone. If you now drop a file into the uploadzone, you'll see that the files variable is an array of files in your debugger.

Quick Recap

1. Set up the HTML for the uploadzone.
2. Set up the stimulus controller to handle the triggering of the file upload dialog.
3. Set up the stimulus controller to handle the drag and drop of files into the uploadzone.
4. Set up the stimulus controller to accept the files that were dragged into the uploadzone.

Our drag and drop left us with a nice array of files that we're going to be able to pass off to some function that handles uploading them. However, we didn't get left with a nice array of files after the click of the uploadzone. Let's fix that so that we have parity between the events, at the end of the file dialog and at the end of the drag and drop we should be left with a nice array of files to pass off to some upload function.

Getting Files from the File Dialog

Commit

The file dialog when completed changes the value of the file input. We can use that to get the files that were selected. We're actually going to be able to re-use our acceptFiles method to do this after a slight modification.

Let's add a change event to our file input in our HTML.

app/views/tracks/new.html.erb

<input type="file" class="hidden" multiple data-uploadzone-target="fileInput" data-action="change->uploadzone#acceptFiles">

Now when that input is changed it will send that event to our acceptFiles method.

What we want to do is modify our acceptFiles to either look for drag and drop dataTransfer files or from files from the file input.

app/javascript/controllers/uploadzone_controller.js

acceptFiles(event) {
 event.preventDefault();
 const files = event.dataTransfer ? event.dataTransfer.files : event.target.files;
 debugger;
}

If event.dataTransfer exists, we know the event was the drag and drop and we can get the files from the dataTransfer. Otherwise, we know the event was from the file input and we can get the files from the target.files.

What We've Built

At this point we've basically built a Drag and Drop file upload component. In fact, we built the shadcn on rails dropzone component.

Cool, right? Now we're ready for the upload which we will cover in part 2 tomorrow.

To recap, so far we've covered a lot about Rails-Components.com

• What's Rails-Components.com?
• Why Ruby on Rails Needs Components
• Rails Components: More Installer Over Library

It's time to show you how to use Rails Components and the underlying simplicity of the implementation.

Stay Close to the Framework

Indirection is at the heart of complexity when it comes to tools and frameworks.

/ Begin Diatribe /

I think one of the most prevelant cases of this in web development is React. In the end, React is building web applications, composed of HTML, CSS, and Javascript. Yet, the HTML you're writing in React isn't HTML, it's JSX. You can't actually write HTML, there's no mechanism to drop down to interact with the medium upon which you build. Try using attaching an event listener to the ready event of the document object. Nope, you can't interact with the document's native lifecycle. Look, I'm not saying this is bad, I'm just saying it's indirect and complex. It is complex to understand how React, given this indirection, is actually building you a web application composed of HTML, CSS, and Javascript when you are so rarely actually interacting with those tools. The rub is that it's entirely possible to know how to build a React application and have no idea how to build a web application. Given how absolutely beautiful I think the native web medium is, I think that indirection is tragic.

/ End Diatribe /

But coming back to Rails Components and how to use them and how they work, my general philosophy in design was to stay as close to Rails as possible. What this means is using as few dependencies as possible and using the framework's tools and conventions.

To answer a question I've gotten a lot, this philosophy is why I did not implement any of these components in the wonderful [ViewComponent or Phlex libraries.

General Architecture

I'm mostly using the built in ActionView helpers, ERB, HTML, and wrapping all of that in helper methods. A component tends to look like:

app/helpers/components/<component>_helper.rb
app/views/components/_<component>.html.erb

Pretty simple. The next convention is that there is a single helper method responsible for the end result of the markup. Those helper methods are always named render_<component>. Why? Because it is declarative, it's literally what the method does. Plus, you could get some conflicts if you named something <%= button %> or <%= input %>. I felt that the method prefix added a nice sort of prefix to the concept. It also means that you can say render_input across different Rails Component libraries. That is to say, the API stays consistent as the underlying theme can change.

Slots, capture(), content_for and yield

It turns out a lot of rubyists figured out the power of this pattern in making structured components without much need for external libraries. I tend to see that confluence as both the elegance of Ruby and Rails and the correctness of the approach. Basically, nice_partials and Chris at GoRails (worth subscribing too but not just for this video but because the entire library is awesome) discovered the almost identical manner in which I implemented the components.

The point of the component is to abstract away the underlying markup or div soup that goes into making complex interfaces. You have the divs, the nesting, the classes and html attributes, it's a lot of code to look at that is either devoid of logic (it should be at least), or is a really write once and forget it kind of situation.

However, because of the nesting and the requirement to position content in certain areas of the markup's tree, you need to a way of saying "this content goes here" and "that title goes there." Plus you need to be able to say "this is a piece of content composed of this other complex piece of markup content." Take a Dropdown Menu for example:

<% render_dropdown_menu do %>
  <%= dropdown_menu_trigger do %>
  <% end %>

  <%= dropdown_menu_content do %>
    <%= dropdown_menu_label %>

    <%= dropdown_menu_item %>
    <%= dropdown_menu_item do %>
    <% end %>
    <%= dropdown_menu_item %>
  <% end %>
<% end %>

That is concealing a ton of markup. Well let me just show you. Okay, I was going to but it's absurd, just take my word for it. And parts have to go in different parts. Luckily, Rails gives us a powerful way to break partials into content areas using content_for.

This is the menu's underlying partial:

<%= render_popover do %>
  <%= popover_trigger do %>
    <%= content_for(:dropdown_menu_trigger) %>
  <% end %>
  <%= popover_content class: "p-1 w-56" do %>
    <% if content_for?(:dropdown_menu_label) %><div class="px-2 py-1.5 text-sm font-semibold"><%= content_for(:dropdown_menu_label) %></div><% end %>
    <%= content_for(:dropdown_menu_content) %>
  <% end %>
<% end %>

What's cool is that the dropdown menu is itself just composed of a popover. But you can see how it partitions it into discrete content_for blocks.

The ones that are seemingly missing are the ones for the individual dropdown_menu_items. They get globbed up into the content_for the dropdown_menu_content block via capture.

  def dropdown_menu_item(label = nil, **options, &block)
    content = (label || capture(&block))
    render "components/ui/shared/menu_item", content: content
  end

Each menu item is basically independently rendered in it's own context and returned to the area of the dropdown_menu_content. It's as if the menu items were hardcoded as HTML inside that block by the time the dropdown_menu_content is rendered.

Now you can see the entire architecture of the component's helper.

module Components::DropdownMenuHelper
  def render_dropdown_menu(**options, &block)
    content = capture(&block) if block
    render "components/ui/dropdown_menu", content: content, **options
  end

  def dropdown_menu_trigger(&block)
    content_for :dropdown_menu_trigger, capture(&block), flush: true
  end

  def dropdown_menu_label(label = nil, &block)
    content_for :dropdown_menu_label, (label || capture(&block)), flush: true
  end

  def dropdown_menu_content(&block)
    content_for :dropdown_menu_content, capture(&block), flush: true
  end

  def dropdown_menu_item(label = nil, **options, &block)
    content = (label || capture(&block))
    render "components/ui/shared/menu_item", content: content
  end
end

Each slot is essentially a combination of content_for and capture allowing you to create a complex markup structure in very neat ruby without any serious magic.

More importantly, between the simplicity of the partial's markup and the helper's ruby, I believe these components are easy to maintain and take ownership of. The code is readable and declarative allowing you to safely make edits because you understand, especially after reading this, how they work.

Originally I was going to cover everything about how they work in one post, but as you've probably surmised if you've been reading, I tend to err on the verbose side and have no qualms about waxing philosophical about code. So, rather than try to cover everything about how the libraries work, I want to cover one major design decision about them.

tl;dr by the end of this post, I actually argue myself into indecision and remain unsure of whether to make the gems library dependencies and installers or just installers. In fact, I'm leaning towards dependency and installer. 🤷

Installer More than Library

The library that really inspired all this, shadcn has an interesting philosophy when it comes to component libraries as dependencies. More to the point, the library aims to not be a dependency itself but rather boilerplate that you install into your application, take over, and use as a base for your own internal component library and design system. From the site:

This is NOT a component library. It's a collection of re-usable components that you can copy and paste into your apps.

What do you mean by not a component library?

I mean you do not install it as a dependency. It is not available or distributed via npm.

Pick the components you need. Copy and paste the code into your project and customize to your needs. The code is yours.

Use this as a reference to build your own component libraries.

I really liked that idea. I tend to think that dependency bloat, especially in production applications (as opposed to your greenfield weekend project), is a real thing. We're spoiled in the Ruby world that bundler and RubyGems are so awesome and reduce a lot of the problems of say, NPM. Philosophically I think that dependencies should be exactly that, dependencies, external packages your application actually 100% depends on and could not function without.

omniauth is a dependency, it's providing you with an entire infrastructure for accomplishing a specific task that is fully encapsulated and you would never want to change within your application (you'd only want to use it by at most extending it).

To me, a component library is not a dependency, it's a collection of code that you want to be able to change and customize to your needs. It's not a black box, in fact using it means exposing its internals.

The first big decision I've made regarding the rails component libraries I'm authoring is fully embracing the idea of installer over library. Including the shadcn-ui gem only adds rails generators to your application, not the helpers or views that make the components.

So bundle add shadcn-ui doesn't actually give you any component in the library, it just gives you a generator to install any component you want into your application. It's not mounting the helpers to your applications scope. Its similar to how devise let's you generate the controller and views it uses into your application so you can customize them but different in that you can't use them at all if you don't generate them into your application.

rails generate shadcn-ui alert

That's how you use the gem. That command will copy the required files, a full unit with no external dependencies, into your application (generally only 3 files). Once installed, the code is yours to customize and maintain.

If you update the gem and there's a new version of the component, you could re-install it into your application, but it would mean overwriting the files previously installed, which is potentially an issue I'll discuss later.

In speaking to a few people, this seems to be a controversial choice. It would be nothing to make the gem include the views and helpers in your application without copying files and also providing the installer SHOULD you want to customize them. Basically exactly like devise works. So, I could give people the choice to use the gem as a traditional library dependency or as an installer. Instead, for now, I've chosen to enforce installer over library.

Why?

Well I guess this line really spoke to me "Pick the components you need. Copy and paste the code into your project and customize to your needs. The code is yours." I like the idea of your application actually not having the code or access to the code for components you aren't using. While off the top of my head I can't think of any issues with that, it's not that much code, certainly by simply not putting that in your applications space, there won't be any conflicts or weird behavior associated with having 50+ components included in your application when you're only using 10.

"Use this as a reference to build your own component libraries." I think by mandating the installer approach, the library is enforcing a philosophy. These components are based on the originals but are now yours and are your responsibility. They bootstrap your apps design system, but you must implement and take ownership over them. The reality is they are going to need to be customized. They should be otherwise we're going to get a lot of really homogenous designs.

I believe that tools influence their usage and influence how we think and how we approach problems. By crafting rails components as installers over dependencies, I'm trying to get you to think about your components and not take them for granted or relegate them again to citizens outside the domain of your application and framework.

Upgrading and Version Drift

Another issue people have pointed out with this approach is that it makes upgrading components more difficult. If you've customized a component and a new version comes out, you have to manually merge the changes into your customized version. Now that's not 100% true because it really depends on how you customized them. If you extended them, say by wrapping them in a new helper method or by wrapping them in a ViewComponent, then as long as the API is maintained, upgrading by overwriting the original installed files isn't a problem.

But if you've customized the base main helper methods or the main component partial, there will be version drift and merge conflicts and overwriting the files for the upgrade would mean losing your customizations, which I won't do. This sounds like a big problem but I think in reality, it is not, or it hasn't proven to be in my usage of the original React shadcn library.

One, I tend to extend the components in their usage and composition with each other more than want to edit the individual files. Though saying that out loud makes me wonder why expose the source of the components then to the application at all through installation over dependency. Two, when I've customized the source component files, the upgrades tend to either be easy to see and integrate with basic diffing or something I don't care about because the component works well enough in my application. However, those are most likely not going to be true universally.

Or Maybe Not

Look, to be honest it's a very good argument for being flexible and allowing the dependency to be inherited while also including the installer. To be totally honest, by the end of writing this post, I'm still undecided. Given bundler and rubygems, there seems less harm here and perhaps I'm being needlessly ideological. I would really love to hear your opinion as by a 1.0 release of the first two libraries, I want them working the same and cementing these crucial initial design decisions that are one way doors that are going to be hard to change in the future. Please reach out to me with your opinions or confusions, @aviflombaum.