OnRailsBlog

Interactive Modals

Sat, 01 Jun 2024 14:58:15 +0000

There is a lot of talk about modals in Rails, and this tutorial shows you how with some Stimulus sprinkles, you can have very interactive modals.

https://youtu.be/VKJ_1qoPTsE

The code for the demo can be found on Github: https://github.com/OnRailsBlog/interactive_modal

Headless UI with StimulusJS and an Outlet

Wed, 08 May 2024 15:09:37 +0000

Headless UI 2.0 just came out from TailwindLabs. I often find myself using their components in my projects, and I wanted to show you my process for converting their React components to use Stimulus, since I haven’t been using React in any of my projects.

https://youtu.be/fvm0F_f5oBA

Switching on Interactivity

The component I wanted to use was the Switch. It’s styled after the native iOS switch toggle, where you turn an option on or off. Tapping anywhere on the button will transition the inner circle from one side to the other. The version of this switch uses CSS animations, and all our controller would need to do is update a data-checked attribute on the button, and CSS will animate the sliding action.

First, I copied the HTML from the rendered React component, and you get:

Let’s generate a Stimulus controller called switch that will handle the clicks for us:

$ ./bin/rails g stimulus switch

Add the controller and an action to the

Animate Filtering Data in HOTWire

Tue, 23 Apr 2024 17:30:18 +0000

We can progressively enhance the filtering search. In the previous tutorial, we saw how easy it is to use Turbo 8’s morphing and a very simple Stimulus controller to trigger the request back to the server. We can dig deeper into the events and get a very satisfying animation of Todos disappearing when they’re filtered out, and reappearing when they are back in the list.

https://youtu.be/cDZ1gTEnABI

Listening for Morphing

Our Stimulus controller is going to get some new methods. It will hook into the Turbo event stream. The first change is to add the replace option to the Turbo visit in the controller. This will effectively make Turbo morph the new changes on the page ¹. We want morphing, because we can listen for the upcoming changes, and tweak the behavior for elements that are changing. This will fire the morphing events.

Animating removals

Removing items is easier, since we get the items that are going to be removed from the page, and we tell Turbo not to remove them. Now, we handle the removal, after a pleasing animation.

Add a new action to the Search controller: turbo:before-morph-element@document->search#animateRemovals. This will be called every time an element inside the page is going to change, so I added a data attribute to the Todo items to flag that they should be animated away: data-animate-exit="true" . The animateRemovals method in the Search controller will check that this property exists. turbo:morph-element will have a property called newElement if the element getting replaced. Since the Todos are getting filtered, and will no longer be on the page, the newElement will be null. Once we have the element to animate away, calling preventDefault() on the event will cancel the element form being removed. Our controller takes over the responsibility for removing the element by calling a animateExit() function that can be tweaked for the preferred animation style.


  animateRemovals(event) {
    if (event.detail.newElement == null && event.target.dataset.animateExit) {
      event.preventDefault();
      this.animateExit(event.target);
    }
  } 

  async animateExit(target) {
    target.animate(
      [
        {
          transform: `scale(1, 1)`,
          transformOrigin: "center",
          height: "auto",
          opacity: 1.0,
        },
        {
          transform: `scale(0.9, 0.7)`,
          opacity: 0.2,
          height: "80%",
          offset: 0.8,
        },
        {
          transform: `scaleY(0.8, 0)`,
          transformOrigin: "center",
          height: 0,
          opacity: 0,
        },
      ],
      {
        duration: 75,
        easing: "ease-out",
      }
    );
    await Promise.all(
      target.getAnimations().map((animation) => animation.finished)
    );
    target.remove();
  }

The animation in this case uses keyframes to collapse and shrink the Todo as its opacity changes. Play around with what makes sense for your application.

Animating Insertions

Animating new elements is trickier. It requires listening for the turbo:morph-element event, which fires after all the changes have been made on the page, but before the page is redrawn. This allows us to make some visual changes to the new Todo elements. The challenge is figuring out which elements need to be animated in. In the case of this event, event.details.newElement refers to the old list, and event.target refers to the list in the dom. First, it goes through the old list to collect all the existing Todo ids. Then it goes through the new list to find ids that are new, and then it animates each of those new Todos.

  animateInsertions(event) {
    if (
      event.target.childNodes.length > event.detail.newElement.childNodes.length
    ) {
      var existingIds = new Set();
      for (var i = 0; i < event.detail.newElement.childNodes.length; i++) {
        let child = event.detail.newElement.childNodes[i];
        if (
          child.nodeName != "#text" &&
          child.dataset.animateEntrance &&
          child.id != null
        ) {
          existingIds.add(child.id);
        }
      }
      for (var i = 0; i < event.target.childNodes.length; i++) {
        let child = event.target.childNodes[i];
        if (
          child.nodeName != "#text" &&
          child.dataset.animateEntrance &&
          child.id != null &&
          !existingIds.has(child.id)
        ) {
          this.animateEntrance(child);
        }
      }
    }
  }

The animation first sets the height to 0, and shrinks the Todo, and animates the it expanding to fit the size of its original view. Make sure you play around with these different values depending on what you need for your application.

  async animateEntrance(target) {
    target.animate(
      [
        {
          transform: `scale(0.8, 0.0)`,
          transformOrigin: "center",
          height: "0",
          opacity: 0.0,
        },
        {
          transform: `scale(0.9, 0.7)`,
          opacity: 0.2,
          height: "80%",
          offset: 0.2,
        },
        {
          transform: `scale(1, 1)`,
          transformOrigin: "center",
          height: "auto",
          opacity: 1,
        },
      ],
      {
        duration: 100,
        easing: "ease-out",
      }
    );
  }

Final enhancement

As I was playing with the searching, I realized I don’t necessarily want to hint to the reordering features. I found hiding the buttons was a visual indicator that you may not want to do that. What’s neat is using CSS to hide the buttons when there is text in the search field.

#search:not(:placeholder-shown) + div {
  .todo > div > button.up,
  .todo > div > button.down {
    animation-duration: .2s;
    animation-name: fadeOut;
    animation-timing-function: ease-in-out;
    animation-fill-mode: forwards;
  }
}

@keyframes fadeOut {

  0% {
    transform: scale(1);
    transform-origin: center;
    height: "auto";
    opacity: 1.0;
  }

  20% {
    transform: scale(1.2);
    transform-origin: center;
    height: "auto";
    opacity: 0.8;
  }

  100% {
    transform: scale(0);
    transform-origin: center;
    height: 0;
    opacity: 0;
    visibility: hidden;
  }
}

Interactive Apps

It’s quite possible, and very straightforward to add nice animations as enhancements of our existing applications with just a little Stimulus and the amazing Javascript animations the browsers all support.

You can find the source code at this point on Github.

https://turbo.hotwired.dev/handbook/drive#application-visits ↩

Filtering Data in HOTWire

Tue, 09 Apr 2024 14:02:12 +0000

When we have a long list of Todos, sometimes we want to filter them by name. We can easily do this using Turbo’s morphing and a Stimulus controller to update the page from the server.

https://youtu.be/MNKb1Xbu298

One previous way to get this interactivity was to use a Stimulus controller that filtered the HTML. This still works, and might be a strategy depending on your situation. This technique will send the request to the server, and leverage the Database to perform the filtering. This might work better if you have pagination, or don’t want to load hundreds or thousands of records onto a page to perform filtering.

Filtering on the Server

Start by updating todos_controller.rb and the index action. The controller should have default query of the Todos:

@todos = Todo.all.order("priority")

We will look for a query parameter called :todo that we’ll use to filter the name of the Todo. The action checks for the presence of the parameter, and that it isn’t blank. It lowercases the param, and then performs a lower case query of all the names in the Todo. If the todo parameter is missing, it pulls in all the Todos. It then sorts the values by priority.

    query = if params[:todo] && !params[:todo].nil? && !params[:todo].blank?
      name = "%#{params[:todo].downcase.strip}%"
      Todo.where("lower(name) like ?", name)
    else
      Todo.all
    end
    @todos = query.order("priority")

The Stimulus Search controller

You can generate a new controller we’ll call search:

$ ./bin/rails g stimulus search

This controller will have a parameter value for the url to visit, and a single action, search. When the search action triggers, it will read the name and value from the target that fired the event, append that to the urlValue, and tell Turbo to visit the page. Turbo will make the request, and perform the morphing.

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

// Connects to data-controller="search"
export default class extends Controller {
  static values = { url: String };

  search(event) {
    Turbo.visit(`${this.urlValue}?${event.target.name}=${event.target.value}`);
  }
}

Wiring up the HTML

First, we can add an input field for our search controller.

The action will call to our Stimulus controller, and fetch the updated results. The form gets set to whatever was passed, so that the page refreshes have the correct information in the search field. The input field is also set as data-turbo-permanent so that it keeps focus when the server results come back, and the page is morphed. If it wasn’t there, the text field would lose focus after every keystroke, which provides for a poor user experience.

Now you have a simple way to filter data on your page.

HOTWire & Turbo Tutorial: Animated Deletions and Insertions

Mon, 01 Apr 2024 18:54:06 +0000

With the addition of the new Todo form appearing at the bottom of the Todos, and the delete action removing a Todo, we have a very functional app. It would be nice if those additions and removals had a little animation to emphasize what’s happening on the page. If there was a long list, we might miss the deletion, especially if a network request caused a delay in the removal of the Todo. We can hook into Turbo streams, and run some animations on these actions to make them appear and disappear.

https://youtu.be/OY_YraWRXds

Not animated vs. animated

Adding a Custom Turbo Action

Turbo allows for the addition of custom actions to enhance the experience. Each StreamAction is passed a StreamElement, which contains the Turbo Frame that was sent from the server. We’re going to add two action which we’ll call animated_append and animated_remove to match the append and remove actions. The animated version of the remove action will perform the same removal, but after some animations run that scale and change the height of the removed element. These animations could be customized depending on the design of the web app. The animated append is a little trickier, but it first adds the elements, and then immediately changes the height to 0 to height it, and then animates the scaling. Add the actions in application.js:

Turbo.StreamActions.animated_remove = async function () {
  this.targetElements.forEach(async (target) => {
    target.animate(
      [
        {
          transform: `scale(1)`,
          transformOrigin: "top",
          height: "auto",
          opacity: 1.0,
        },
        {
          transform: `scale(0.8)`,
          opacity: 0.2,
          height: "80%",
          offset: 0.8,
        },
        {
          transform: `scale(0)`,
          transformOrigin: "top",
          height: 0,
          opacity: 0,
        },
      ],
      {
        duration: 75,
        easing: "ease-out",
      }
    );
    await Promise.all(
      target.getAnimations().map((animation) => animation.finished)
    );
    target.remove();
  });
};

Turbo.StreamActions.animated_append = async function () {
  this.removeDuplicateTargetChildren();
  this.targetElements.forEach(async (target) => {
    target.append(this.templateElement.content);
    target.lastElementChild.animate(
      [
        {
          transform: `scaleY(0.0)`,
          transformOrigin: "top",
          height: "0",
          opacity: 0.0,
        },
        {
          transform: `scale(0.8)`,
          opacity: 0.2,
          height: "80%",
          offset: 0.2,
        },
        {
          transform: `scaleY(1)`,
          transformOrigin: "top",
          height: "auto",
          opacity: 1,
        },
      ],
      {
        duration: 100,
        easing: "ease-out",
      }
    );
  });
};

Sending the frame actions

The next bit is to send the frames from the server with those actions. An animated append of the new Todo form can be as simple as:

And removing a Todo from the list could be this:

The action field on the Turbo Stream needs to correspond to the name of the actions we added in application.js.

Adding helpers in Rails

We can add custom helpers in our Rails app to make those templates available. Add a helper file in app/helpers/ called turbo_streams_actions_helper.rb. We’ll append two actions that will mirror the TagBuilder in Turbo Rails.

module TurboStreamsActionsHelper
  module CustomTurboStreamActions
    def animated_remove(target)
      action :animated_remove, target, allow_inferred_rendering: false
    end

    def animated_append(target, content = nil, **, &block)
      action(:animated_append, target, content, **, &block)
    end
  end

  Turbo::Streams::TagBuilder.prepend(CustomTurboStreamActions)
end

We can use the actions like any other Turbo Stream action.

<%= turbo_stream.append "todos" do %> becomes

<%= turbo_stream.animated_append "todos" do %> in app/views/todos/new.html.erb

And in todos_controller.rb, the destroy action changes from format.turbo_stream { render turbo_stream: turbo_stream.remove(@todo) } to format.turbo_stream { render turbo_stream: turbo_stream.animated_remove(@todo) }.

Progressively Enhancing

The neat bit about this change is that we don’t need to completely rewrite the partials to get animations as the page changes. We go from portions of the page the appear suddenly or leave suddenly to a pleasant coming and going look to help the app feel more alive, and more similar to what you’d expect in a mobile application.

HOTWire: Where do I store my HTML state?

Tue, 26 Mar 2024 13:58:48 +0000

We’re used to storing all of our data in the database, and letting Active Record pull it out, Action View to format it, and Action Controller to manage the request and response. But when we want quick client side interactivity, sometimes we need some extra data annotations on the HTML side that we can use without needing to communicate with the server. Most of this data is used by Stimulus, but Turbo has a few tags that can be useful.

https://youtu.be/9wf9yXVJ2d8

State

Other Javascript frameworks, like Vue.js, React, and Angular, typically generate HTML on the client side, in Javascript. We can use the fact we’re sending server generated HTML Over The Wire to store information we might need in the ' tag of the page. Turbo will keep these values in sync as each page loads. Rails also has a provides helper that can be used insert a tag into the head of the page. For example, if an account-id should be in the head, you can use this anywhere in a view:

<% provide :head, tag.meta(name: "account-id", content: "1") %>

If your layout, like application.html.erb has this line:

<%= yield :head %>

The account id meta tag will look like:

Now, in a Stimulus controller, you could add a function like:

function getMetaValue(name) {
  const element = document.head.querySelector(`meta[name="${name}"]`);
  return element.getAttribute("content");
}

This will help read that value from the head, and you can include it wherever you want:

let accountId =  getMetaValue("account-id")

Controller State

The Stimulus controller is a Javascript object, so properties can be set on the editor. You may have be using a third party library to create an object and keep it around during the controller’s life. For example, if you’re using Tributeto add mentions in a textfield, you can use this and store it to a variable:

connect() {
  this.tribute = new Tribute({
    collection: []
  });
}

And in a different method, you can access the tribute variable:

addNames() {
  this.tribute.appendCurrent([
    { name: "Howard Johnson", occupation: "Panda Wrangler", age: 27 },
    { name: "Fluffy Croutons", occupation: "Crouton Fluffer", age: 32 }
  ]);
}

Data Attributes

Stimulus provides two mechanisms to make data available for your controller.

Values properties

The first is the values properties. These allow you to set parameters for the controller. For example, if you had a toggle like you would find in iOS, you may have an enabled attribute on it.

If the controller is named toggle, then adding a data attribute enabled looks like this:

HOTWire: Considering Morphing or Turbo Frames

Tue, 26 Mar 2024 09:00:00 +0000

With the new morphing features in Turbo 8, you now need to decide on when to use Turbo streams or Turbo frames instead of full page refreshing. Thankfully, all three techniques work together. Let’s take the Todo app that we’ve been working on, and see where using Streams or Frames makes sense.

https://youtu.be/y08mnpYrDmA

Turbo Streams for a new Todo form

The current new Todo interaction is a new page when clicking the New Todo button on the top of the page. If we add the data-turbo-stream attribute, the GET request now appears to the server as a TURBO_STREAM request. The response, new.turbo_stream.erb can append the form to the bottom of the list of Todos, and then when the form is submitted, the full page refresh will display the new Todo in the same place.

First, add the data-turbo-stream to the New Todo link on todos\index.html.erb:

<%= link_to "New todo", new_todo_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium", data: {turbo_stream: true} %>

Then add the file todos\new.turbo_stream.erb:

<%= turbo_stream.append "todos" do %>
  <%= turbo_frame_tag 'new_todo', target: "_top", class: "flex items-center py-3 pl-3 bg-white border-b pr-11 gap-x-4 todo" do %>
    <%= render partial: 'form', locals: { todo: @todo } %>
  <% end %>
<% end %>

This will append the new form to the bottom of the Todos list. The target is set to _top so that the successful creation and redirection bring the page back to the index action. Otherwise, since there wouldn’t be a Turbo Frame named new_todo, Turbo wouldn’t have anything to replace the interior content.

Now we are using Turbo Streams to load a new form. The form, todos\_form.html.erb, should be changed to fit inline:

<%= form_with(model: todo, class: "flex-1 flex flex-row gap-x-4 items-center") do |form| %>
  <%= form.check_box :completed, class: "ml-8" %>
  
    <%= form.text_field :name, class: "block shadow rounded-md border border-gray-200 outline-none px-3 py-2 w-full" %>
  
  
    <%= form.submit class: "rounded-lg py-3 px-5 bg-blue-600 text-white inline-block font-medium cursor-pointer" %>
  
<% end %>

And you get a nice new Todo form. Clicking the Create Todo button saves the Todo, performs a redirect to the Todos#index, which Turbo morphs and shows the new Todo at the bottom of the list.

Editing in place

Using Turbo Frames, we don’t have to make many other changes to get in place editing of each Todo. First, change the div of each Todo in todos\_todo.html.erb to a turbo_frame_tag. The original:

becomes:

<%= turbo_frame_tag todo, class: "flex items-center py-3 bg-white border-b gap-x-4 todo", data: { reorderable_path: todo_priority_path(todo), reorderable_id: todo.id }, draggable: true do %>
	
<% end %>

The next change is to update the todos\edit.html.erb partial to wrap the form in a turbo_frame_tag. Change the following lines:

    <%= render "form", todo: @todo %>
    <%= link_to "Show this todo", @todo, class: "ml-2 rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium" %>

And wrap the form like this:

    <%= turbo_frame_tag @todo, class: "flex items-center py-3 bg-white border-b gap-x-4 todo"  do %>
      <%= turbo_stream_from @todo %>
      <%= render "form", todo: @todo %>
      <%= link_to "Back", @todo, class: "mr-10 rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium" %>
    <% end %>

Clicking the “Edit” button will send a request for the edit.html.erb. Turbo will just get the contents of the frame, and replace the inside with the form. Clicking “Back” will make a request to the show.html.erb, which has the same frame id since it renders the _todo.html.erb partial.

Deleting Todos

Lastly, we can use Turbo actions to remove a Todo from the list. Add a delete button to the _todo.html.erb partial:

<%= link_to todo_path(todo), data: {turbo_method: "delete", turbo_confirm: "Are you sure?" }, class: "rounded-full p-2 ml-2 bg-red-500 inline-block font-medium mr-1 text-red-50" do %>
    
  <% end %>

This uses Heroicons trash icon and you get a nice delete button.

Clicking the trashcan will send the request to the destroy method on the TodosController, so add a new response in the respond_to block:

format.turbo_stream { render turbo_stream: turbo_stream.remove(@todo) }

This will send a response back that removes the Todo from the list.

Putting it all together

Turbo Morphs fits right on top of how an existing app works. It layers on a new performance feel without needing to rewrite the who app to work with a new feature. That’s the best kind of upgrade.

You can find the source code on Github here.

Animating the Insertions and Deletions

You can animate the additions and removals from the page easily. Check out the tutorial here.

Stimulus Tutorial: Moving & Animating Todos

Mon, 18 Mar 2024 15:56:29 +0000

Drag and drop functions are a fun interaction, but they may not be the best interface in every situation. Buttons are a great affordance, and we can hook them up into our existing drag and drop code without any issue. Then we’ll look into animating the movement on the page so that it still feels interactive.

https://youtu.be/RGsvL3z_Lz8

Demo of the movement when clicking the up and down buttons

Adding Buttons

On the right side of each Todo row, let’s add an up and down arrow button. These will get their own actions, moveUp and moveDown on the Stimulus controller that will be refactored into moving the Todo up and down, and sending the change to the server. The icons come from Heroicons.

Hiding Unnecessary Buttons

If you just refresh the HTML, you’ll see the top row has a button to move up, and the bottom row has a button to move down. This doesn’t make sense, and looks sloppy. We can use the power of CSS to hide those buttons automatically, and save us some work. Add these lines to your CSS file:

div.todo:first-of-type > div > button.up {
  visibility: hidden;
}
div.todo:last-of-type > div > button.down {
  visibility: hidden;
}

The outermost div in todos\_todo.html.erb gets a new class todo and each button has either the up or down class classes. We set up CSS selectors to hide the up button in the first Todo row, and the dow button on the last Todo row.

Updating the Stimulus controller

The Stimulus controller gets refactored into a few new methods. The first is moveItems which moves the items on the page, and then performs the network update call.

moveItems(item, target) {
    if (
      target.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_FOLLOWING
    ) {
      let result = target.insertAdjacentElement("beforebegin", item);
    } else if (
      target.compareDocumentPosition(item) & Node.DOCUMENT_POSITION_PRECEDING
    ) {
      let result = target.insertAdjacentElement("afterend", item);
    }

    let formData = new FormData();
    formData.append("reorderable_target_id", target.dataset.reorderableId);

    fetch(item.dataset.reorderablePath, {
      body: formData,
      method: "PATCH",
      credentials: "include",
      dataType: "script",
      headers: {
        "X-CSRF-Token": getMetaValue("csrf-token"),
      },
      redirect: "manual",
    });
  }

The moveDown and moveUp functions now use this moveItems function. First the item checks to see if there is a sibling node in the requested direction, and if that sibling has a reorderable id.

async moveUp(event) {
    let parent = getDataNode(event.target);
    if (
      parent.previousSibling.dataset != null &&
      parent.previousSibling.dataset.reorderableId != null
    ) {
      this.animateSwitch(parent.nextSibling, parent);
      await Promise.all(
        parent.getAnimations().map((animation) => animation.finished)
      );
      this.moveItems(parent, parent.previousSibling);
    }
    event.preventDefault();
  }

  async moveDown(event) {
    let parent = getDataNode(event.target);
    if (
      parent.nextSibling.dataset != null &&
      parent.nextSibling.dataset.reorderableId != null
    ) {
       this.animateSwitch(parent.nextSibling, parent);
      await Promise.all(
        parent.getAnimations().map((animation) => animation.finished)
      );
       this.moveItems(parent, parent.nextSibling);
    }

    event.preventDefault();
  }

The best part is the animateSwitch method. It takes two rows, which it’s assumed are next to each other, and uses the transform property of an item to move the row either up or down in the vertical/Y direction. Once the animations are done, the moveItems will actually change the location of the rows in the DOM.

animateSwitch(from, to) {
    from.animate([{ transform: `translateY(-${from.clientHeight}px)` }], {
      duration: 300,
      easing: "ease-in-out",
    });

    to.animate([{ transform: `translateY(${to.clientHeight}px)` }], {
      duration: 300,
      easing: "ease-in-out",
    });
  }

Accessible and Interactive

Now, we have buttons that someone can use to move the Todos up and down, and we can use animation as an affordance that the change happened. And we use basic animations, rather than needing to import a whole UI framework.

You can see all the changes on Github.

HOTWire Tutorial: Listening for changes over ActionCable

Thu, 14 Mar 2024 15:49:59 +0000

Many of the changes in Turbo 8 are incredibly promising for improving the perception of speed and interactivity on our web apps.

A lot of my Stimulus Tutorials need an update since they were first written, so follow along to update existing tutorials and rethink them with the newest tools available. Today we obsolete the tutorials Grabbing ActionCable with Stimulus.js and Subscribing to many channels in ActionCable.

https://youtu.be/HnJef2x4HVA

Moving on from the Stimulus controllers

The initial tutorials required creating a Stimulus controller and calling the ActionCable code to setup the web socket connection. Now, Turbo automatically sets up those connections if the HTML includes the turbo_stream_from directive. In the Todo example, this means we could add the following to todos\_todo.html:

<%= turbo_stream_from todo %>

The generated HTML will look something like:

Turbo has its own channel that will subscribe to all the names, and the channel name gets encrypted to protect from someone trying to guess the value.

No extra Channels

The previous examples also required setting up a ActionCable channel to stream events. Since we use the Turbo channel, this is no longer required. Instead, the model that needs to stream updates adds a helper method, and on creation, updates, and deletion, it gets events broadcasted over the Turbo channel. The change in Turbo 8 is that instead of needing to send new HTML over the web socket, the page refreshes and morphs the new elements to make it appear like everything changed.

The Todo item needs broadcasts_refreshes and all these updates are sent automatically to the front end for those Todos that are listened to.

Listening for new Todos

When creating a new Todo, there isn’t an existing channel listening for that Todo. Turbo handles this by broadcasting creations to a model specific channel, "todos" in this case. In todos\index.html.erb: adding the stream from directive will load in the Todos to the list:

<%= turbo_stream_from Todo.model_name.plural %>

Touch to broadcast changes

When dragging and dropping the Todos, the upsert operation doesn’t automatically toggle a broadcast to make the front end refresh. By calling the touch method on the todo that was dragged, the front end is notified of the change, and the page refreshes with the updates.

@todo.touch

Simplifying

The changes to Turbo over the past few years have allowed for better interactivity and better developer speed. These improvements are exceptional.

You can see the code on Github.

Hotwire Tutorial: How Do I Drag and Drop Items in a List?

Fri, 08 Mar 2024 22:38:02 +0000

If you’ve been following the changes in Turbo 8, it looks incredibly promising for improving the perception of speed and interactivity on our web apps.

A lot of the Stimulus Tutorials could use an update since they were first written, so I thought it would be good to over existing tutorials and rethink them with the newest tools available. Join me as we rebuild the Stimulus Tutorial “How do I Drag and Drop Items in a list

https://youtu.be/riBrFASNaHs

Client side tutorial

https://youtu.be/NuWWk6iWgwg

Server side Tutorial

Setting Priority

We’ll build off the previous example and add a priority order. This will be used sort the Todos.

$ rails g migration AddPriorityToTodo priority:integer
$ rails db:migrate

If there are existing Todos in the database, go ahead and set the priority to the id of the existing Todo:

$ rails c
* Todo.all.each do |todo|
*   todo.priority = todo.id
*   todo.save
> end

In the todos_controller.rb, make the index method sort the Todos by this new priority field:

def index
  @todos = Todo.all.order("priority")
end

And when creating a new Todo, we should set the priority to its ID after creating it by using a callback. This is a simplification since we only have a single Todo model in our application, and you may want to set priority based on other models that you design, like a Project or a List.

class Todo < ApplicationRecord
  after_create :set_priority

  private

  def set_priority
    self.priority = id
    save
  end
end

There are two parts we need to build next. A stimulus controller for the front end, and new rails controller to shuffle around the Todos and put them in the correct order by priority.

Reorder Stimulus Controller

Like in the previous drag and drop tutorial, the controller needs to listen to a number of events to handle the dragging of an item. You can generate it with this command:

$ rails g stimulus reorder

The controller will use the css classes feature to apply styling as the list of Todos becomes active, as the dragged item moves around, and as a potential drop target is hovered over. This creates a very interactive effect, and helps show what the drag is doing. These go at the top of the controller:

  static classes = ["activeDropzone", "activeItem", "dropTarget"];

The first event the controller listens for is dragstart. The dragstart() method will add the CSS classes to the element and the dragged item to provide more visual information as the drag happens. The drag event can transfer information, and the controller will set the id of the item that’s being dragged so when it can be referred to when it’s dropped.

  dragstart(event) {
    this.element.classList.add(...this.activeDropzoneClasses);
    const draggableItem = getDataNode(event.target);
    draggableItem.classList.add(...this.activeItemClasses);
    event.dataTransfer.setData(
      "application/drag-key",
      draggableItem.dataset.reorderableId
    );
    event.dataTransfer.effectAllowed = "move";
  }

The next event is dragover. It’s important to listen and respond to true so that we can eventually drop the Todo in the list.

  dragover(event) {
    event.preventDefault();
    return true;
  }

At the bottom of the controller, there is a helper helper to get the parent div of the Todo that holds the reorderable id:

function getDataNode(node) {
  return node.closest("[data-reorderable-id]");
}

This is used in the next few methods. dragenter and dragleave work together to change the appearance of the potential drop target. Both find the Todo node in the DOM. dragenter() adds the drop target styling with CSS classes, and then sets all the children pointer events to none so that the inner items, like the checkbox, the text, and the buttons don’t fire their own dragenter events. dragleave() removes the CSS classes, and unset’s the pointer events on the children elements.

  dragenter(event) {
    let parent = getDataNode(event.target);
    if (parent != null && parent.dataset.reorderableId != null) {
      parent.classList.add(...this.dropTargetClasses);
      for (const child of parent.children) {
        child.classList.add("pointer-events-none");
      }
      event.preventDefault();
    }
  }

  dragleave(event) {
    let parent = getDataNode(event.target);
    if (parent != null && parent.dataset.reorderableId != null) {
      parent.classList.remove(...this.dropTargetClasses);
      for (const child of parent.children) {
        child.classList.remove("pointer-events-none");
      }

      event.preventDefault();
    }
  }

The drop() method uses a helper method to get the CSRF token:

function getMetaValue(name) {
  const element = document.head.querySelector(`meta[name="${name}"]`);
  return element.getAttribute("content");
}

The drop method gets the id the Todo that was dragged and the Todo that was dropped down. It doesn’t do anything special to validate the ordering, but it uses the fetch API to send an update to the rails controller we’ll add in the next section. It also repositions the dragged item in the DOM by comparing the document position and then inserting the item as an adjacent element.

  drop(event) {
    this.element.classList.remove(...this.activeDropzoneClasses);

    const dropTarget = getDataNode(event.target);
    dropTarget.classList.remove(...this.dropTargetClasses);
    for (const child of dropTarget.children) {
      child.classList.remove("pointer-events-none");
    }

    var data = event.dataTransfer.getData("application/drag-key");
    const draggedItem = this.element.querySelector(
      `[data-reorderable-id='${data}']`
    );

    if (draggedItem) {
      draggedItem.classList.remove(...this.activeItemClasses);

      if (
        dropTarget.compareDocumentPosition(draggedItem) &
        Node.DOCUMENT_POSITION_FOLLOWING
      ) {
        let result = dropTarget.insertAdjacentElement(
          "beforebegin",
          draggedItem
        );
      } else if (
        dropTarget.compareDocumentPosition(draggedItem) &
        Node.DOCUMENT_POSITION_PRECEDING
      ) {
        let result = dropTarget.insertAdjacentElement("afterend", draggedItem);
      }

      let formData = new FormData();
      formData.append(
        "reorderable_target_id",
        dropTarget.dataset.reorderableId
      );

      fetch(draggedItem.dataset.reorderablePath, {
        body: formData,
        method: "PATCH",
        credentials: "include",
        dataType: "script",
        headers: {
          "X-CSRF-Token": getMetaValue("csrf-token"),
        },
        redirect: "manual",
      });
    }
    event.preventDefault();
  }

Finally, the dragend event is used to remove CSS classes:

  dragend(event) {
    this.element.classList.remove(...this.activeDropzoneClasses);
  }

Priority Controller

First, put in a new directive to the routes.rb file to add a route to the priorities_controller.rb:

  resources :todos do
    resource :priority, only: [:update]
  end

The priorities_controller.rb will only have one method, update. It will find the Todo that was dragged, and the Todo that was the drop target. Then, depending on the ordering, the priority on the all the Todos between those two items are swapped. The Upset command is used to update all the Todos at once.

class PrioritiesController < ApplicationController
  def update
    @todo = Todo.find_by_id params[:todo_id]
    @new_priority_todo = Todo.find_by_id params[:reorderable_target_id]

    if !@new_priority_todo.nil?
      old_priority = @todo.priority
      new_priority = @new_priority_todo.priority

      if old_priority > new_priority
        todos = todos(new_priority..old_priority)
        (0..(todos.length - 2)).each do |i|
          first_todo = todos[i]
          second_todo = todos[i + 1]
          temp_priority = first_todo[:priority]
          first_todo[:priority] = second_todo[:priority]
          second_todo[:priority] = temp_priority
        end
        todos[todos.length - 1][:priority] = new_priority
        Todo.upsert_all(todos)
      elsif old_priority < new_priority
        todos = todos(old_priority..new_priority)
        (todos.length - 1).downto(1).each do |i|
          first_todo = todos[i - 1]
          second_todo = todos[i]
          temp_priority = first_todo[:priority]
          second_todo[:priority] = first_todo[:priority]
          second_todo[:priority] = temp_priority
        end
        todos[0][:priority] = new_priority
        Todo.upsert_all(todos)
      end
    end
  end

  private

  def todos(range)
    Todo.where(priority: range).order(:priority)
      .pluck(:id, :priority, :updated_at, :created_at)
      .map { |id, priority, created_at, updated_at| {id: id, priority: priority, updated_at: updated_at, created_at: created_at} }
  end
end

Wiring up the Front End

Finally, let’s add the annotations Stimulus needs in order to work. First, add the controller directives in todos\index.html.erb. Note the six drag actions that direct the drag and drop actions. The CSS classes are also setup with a number of Tailwind CSS classes.

The todos/_todo.html.erb needs three values, and then a visual drag icon is added. The first one is setting draggable to true, and set the reorderable-id and the reorderable-path that are used by Stimulus.

Now there is some very interactive Drag and Drop functionality on the Todo list.

https://youtu.be/GEig8DlS5xs

Quick demo of Drag and Drop functionality

You can find the code on Github here.

Stimulus.js and HotWired Tutorial: Update Model with Checkbox using Turbo Morphing

Wed, 06 Mar 2024 14:28:00 +0000

If you’ve been following the changes in Turbo 8, it looks incredibly promising for improving the perception of speed and interactivity on our web apps.

A lot of the Stimulus Tutorials could use an update since they were first written, so I thought it would be good to over existing tutorials and rethink them with the newest tools available. Join me as we rebuild the first Stimulus Tutorial, and it’s updated version, “How do I Remotely Update My Model from a checkbox”.

https://youtu.be/dB7vFHX7aqY

First, start by creating a fresh Rails app. I’m using Rails 7.1 and Ruby 3.3.

$ rails new todo_app -c tailwind

We need to update the application.html.erb file to use the Turbo 8 Morphing by adding these lines inside the tag.

<% turbo_refreshes_with method: :morph, scroll: :preserve %>
<%= yield :head %>

Let’s scaffold out a Todo Item that has a name and its completed state.

$ rails g scaffold Todo name:string completed:boolean
$ rails db:migrate

The default views for the Todo could use some tweaking to make it look more like actionable item, so update the todos/_todo.html.erb view to this:


  >
  <%= todo.name %>
  <% if action_name != "show" %>
    <%= link_to "Show this todo", todo, class: "rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium" %>
    <%= link_to "Edit this todo", edit_todo_path(todo), class: "rounded-lg py-3 ml-2 px-5 bg-gray-100 inline-block font-medium" %>
  <% end %>

We need to tweak the checkbox so that changing the value will be updated on the server.

Change the checkbox input to a small form that will trigger a form submission when it’s toggled.


  <%= form_with model: todo, data: { controller: "form" } do |form| %>
    <%= form.label :completed, for: dom_id(todo, :completed) do %>
      <%= form.check_box :completed, id: dom_id(todo, :completed), data: { action: "form#submit" } %>
    <% end %>
  <% end %>
  <%= todo.name %>
  <% if action_name != "show" %>
    <%= link_to "Show this todo", todo, class: "rounded-lg py-3 px-5 bg-gray-100 inline-block font-medium" %>
    <%= link_to "Edit this todo", edit_todo_path(todo), class: "rounded-lg py-3 ml-2 px-5 bg-gray-100 inline-block font-medium" %>
  <% end %>

Add a Stimulus controller, form_controller.js that will submit the form when the checkbox is changed:

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

export default class extends Controller {
  submit() {
    this.element.requestSubmit();
  }
}

Change the todos_controller.rb update method to redirect back to the Todos list:

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

Now, we get the same benefits of a remotely filled in form, while using leaning on Turbo’s morphing ability.

Displaying Progress in a Long Running Background Job using HOTWire

Mon, 07 Nov 2022 14:31:42 +0000

Fast UIs need to feel like a lot is happening, even if that’s in the background and out of site of your user. On a mobile app, usually that means moving network calls outside the “main thread” and into a background thread that calls back. On websites, it means making every request back to the server as short as possible, and then waiting for some update back from the server. This could be accomplished by polling the server, but with ActionCable and Turbo Streams, you can let the server do whatever background work is needed and have it push those updates to you.

One example is processing CSV files from your users. Sometimes APIs are great for getting data into your app, and you can’t beat comma separated values for updating records. The general idea is updating several records based off rows in a spreadsheet. This can be broken down into two steps: upload the file, and process the file.

Uploading the file can be done with JavaScript and a loading bar, so we know when the file is done uploading, and how much more progress there is. Processing the file happens on the backend, and that’s where getting visibility into the process can be tough. Do we create a database record that we use to keep track of the progress? Does that record get purged after the upload and processing are complete? Those are business problems that can be different depending on the situation. But given that the server that renders a webpage might be different from the server that processes the file, putting the file into a cloud bucket makes the most sense, at least until we’re done with the processing.

On the server side, using web sockets to communicate progress back to the front end can provide a sense of progress, and relief that something is actually happening, whether it’s 10 or 10,000 rows in the spreadsheet.

You can probably come up with other processes that need to display background progress, such sending out batches of notifications, but let’s work through processing books like in our previous Book example.

Uploading a CSV file

We can use ActiveStorage to help get the file into our system, and to help keep track of progress throughout the upload and processing. Each Blob in ActiveStorage has a database record, and can be purged once the whole process is complete. ActiveStorage also has a mechanism to put the file directly into the cloud or file storage we’re using, and it emits off progress events that we can use to show a loading indicator on the page. Once the file is uploaded, then we send the key back to the server and start processing the file.

Start with a clean app:

$ rails new BookImports -c tailwind
$ cd BookImports 
$ rails g scaffold Book title:string author:string publisher:string category:string isbn:string dewey_decimal_number:string binding:integer
$ bin/rails active_storage:install 
$ rails db:migrate

We’re going to make binding an enum since there are only a few options, so change models/book.rb to this:

class Book < ApplicationRecord
  enum binding: [:hardcover, :paperback]
end

To test our system with plenty of books, We will use the Faker gem to create about 100 fake books in a CSV file that we can upload.

In our Gemfile:

gem 'faker'

Then run

$ bundle install

Then we’ll create the books in our db/seeds.rb file.

require 'csv'

path = 'public/books.csv'

CSV.open(path, 'w', headers: ['title', 'author', 'publisher', 'category', 'isbn', 'dewey_decimal_number', 'binding'], write_headers: true) do |csv|
  100.times do |i|
    csv << [Faker::Book.title, Faker::Book.author, Faker::Book.publisher, Faker::Book.genre, "#{Faker::Number.number(digits: 3)}-#{Faker::Number.number(digits: 1)}-#{Faker::Number.number(digits: 2)}-#{Faker::Number.number(digits: 6)}-#{Faker::Number.number(digits: 1)}", "#{Faker::Number.number(digits: 3)}.#{Faker::Number.number(digits: 3)}", Faker::Number.between(from: 0, to: 1)]
  end
end

Working on the import pages, generate the controller:

$ rails g controller Import show create

Change the route for create into a post in routes.rb:

post 'import/create'

In the form, we’re going to set it as multipart, so we can upload a file, but first, let’s create the Stimulus controller that will show the upload progress.

$ rails g stimulus uploads

Add the ActiveStorage direct upload library with your current JavaScript management tool, for example with importmap:

$ ./bin/importmap pin @rails/activestorage

Add ActiveStorage to your javascript/application.js:

import * as ActiveStorage from "@rails/activestorage";
ActiveStorage.start();

The uploads_controller.js is going to listen for two events: direct-upload:initialize@window which will trigger showing the progress indicator, and direct-upload:progress@window, which will give us the current upload progress. The controller has a wrapper around the progress indicator and the progress indicator itself, which are updated by these events.

import { Controller } from "@hotwired/stimulus"

// Connects to data-controller="uploads"
export default class extends Controller {
  static targets = ["progress", "progressWrapper"];

  initializeDirectUpload() {
    this.progressWrapperTarget.classList.remove("hidden");
  }

  progressDirectUpload(event) {
    const { id, progress } = event.detail;
    this.progressTarget.style.width = `${progress}%`;
  }
}

The form, views/import/show.html.erb, is as follows:


  Import Books
  <%= form_with url: import_create_path, multipart: true do %>
    
      
        
          Data File (CSV):
          
            
              
                
                  
                    <%= file_field_tag :file, class: 'input', direct_upload: true %>
                  
                
                
                  Uploading file
                  
                    
                  
                
              
            
          
        
        
          
            <%= submit_tag "Upload File", class: "inline-flex justify-center py-2 px-4 border border-transparent shadow-sm text-sm font-medium rounded-md text-white bg-blue-700 hover:bg-blue-800 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-red-500" %>
          
        
      
    
  <% end %>

At this point, when you upload the file, you get a nice progress indicator, but the controller doesn’t respond appropriately, so nothing happens on the page. We need to handle the uploaded file. Let’s start by creating a background job that will process the CSV.

$ bin/rails generate job ImportBooks

The create action on the import controller will queue the import job by passing in the blob, and then pass back the HTML that will display the progress indicator, and create the ActionCable channel that will listen for progress updates. Let’s wrap the form from the show.html.erb page with a turbo_frame_tag so that the response can replace that part of the response.


  Import Books
  <%= turbo_frame_tag "import" do %>
    <%= form_with url: import_create_path, multipart: true do %>
      
    <% end %>
  <% end %>

The create template should be renamed to create.turbo_stream.erb and will have:

<%= turbo_stream.replace "import" do %>
  <%= turbo_stream_from @blob.key %>
  
    
      
        Data File (CSV):
        
          
            
              
                
                  <%= @blob.filename %>
                
              
              
                Processing file
                
                  <%= render partial: "blob_progress", locals: { blob: @blob, progress: 0 } %>
                
              
            
          
        
      
      
        
          <%= link_to "View Results", books_path, class: "inline-flex justify-center py-2 px-4 border border-transparent shadow-sm text-sm font-medium rounded-md text-white bg-blue-700 hover:bg-blue-800 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-red-500" %>
        
      
    
  
<% end %>

We’re removing the form, but keeping the layout similar to what’s replaced. It uses the turbo_stream_from tag to listen on the blob’s key. This gets around the fact that ActiveStorage::Blob has a different result for the identify method that the TurboStream class uses to create the channel.

Finally, the ImportBooksJob is queued in the create action:

class ImportController < ApplicationController
  def show
  end

  def create
    @blob = ActiveStorage::Blob.find_signed params[:file]
    ImportBooksJob.perform_later @blob
    respond_to do |format|
      format.turbo_stream
    end
  end
end

Processing a file

In this sample, we’re using a CSV and the processing will be in the background job ImportBooks. The job will download the file from file storage, use Ruby’s CSV library to read each row, and then update or insert records depending on what the file contains. One technique I’ve used is to farm out each record into its job, so that if any errors occur, they don’t stop the entire import, but We’ll keep this simple for now. The progress will be reported back to the front end through the TurboStream connection.

Let’s create a little template that we’ll use to render the progress, app/views/application/_blob_progress.html.erb:

This takes in the blob and the amount of progress as local variables.

The ImportBooksJob is passed the blob, downloads the file, and parses the CSV. After each iteration, it sends the progress to the front end, and we get a nice loading bar on the page.

require 'csv'

class ImportBooksJob < ApplicationJob
  queue_as :default

  def perform(blob)
    blob.open do |file|
       csv = CSV.read(file, headers: true)
       row_count = CSV.read(file, headers: true).size
       csv.each_with_index do |row, progress|
        Turbo::StreamsChannel.broadcast_replace_to blob.key, 
                                                  target: blob, partial: "blob_progress", 
                                                  locals: { blob: blob, progress: ((progress.to_f / row_count) * 100) }
       end
    end
  end
end

The Turbo::StreamsChannel can broadcast to the front end. The first parameter, blob.key which matches what we are listening for on the page. The target matches the DOM id on the page, which is the progress indicator, and the partial and locals named parameters are considered the rendering block. This all gets wrapped into a template, and replaced on the front page.

Passive yet Interactive

The user wanted to load up a lot of records into the app. We provided a way to use a CSV to upload all the records, so they wouldn’t have to add each one manually. They get a progress bar for the upload, which is delightful if we have a big file, but it still feels luxurious for our website to tell us what’s going on. Once the files been uploaded, a new progress indicator shows how the record import is going. The whole action by the user was a few clicks, but they feel in control because they know what’s going on the whole time. This is the kind of interactivity uses crave in a web app, and a lot of it comes for free in Rails.

Adding Loading Screen with Turbo

Mon, 31 Oct 2022 13:57:05 +0000

One great aspect of Turbo frames is lazy loading. You can use this behavior to quickly load in the shell of a UI, and then lazy load all the data. Adding an animating loading status will help give the feeling of immediacy and “a lot of work is happening in the background” without the frustration that the page is stuck. We don’t even need any extra Javascript, since we can animate the page with CSS.

https://youtu.be/lXxFzPU-_uE

Full tutorial

Loading many books

This tutorial will start from a previous example, Modeling More Complex Datasets, which used a Book model. We’ll start from scratch with a fresh Rails app and use TailwindCSS for the style.

$ rails new BookData -c tailwind
$ cd BookData 
$ rails g model Book title:string author:string publisher:string category:string isbn:string dewey_decimal_number:string binding:integer
$ rails db:migrate

We’re going to make binding an enum since there are only a few options, so change models/book.rb to this:

class Book < ApplicationRecord
  enum binding: [:hardcover, :paperback]
end

To test our system with plenty of books, We will use the Faker gem to create about 2000 fake books.

In our Gemfile:

gem 'faker'

Then run

$ bundle install

Then we’ll create the books in our db/seeds.rb file.

2_000.times do |i|
  Book.create!( title: Faker::Book.title, 
	author: Faker::Book.author, 
	publisher: Faker::Book.publisher,
	category: Faker::Book.genre,
	isbn: "#{Faker::Number.number(digits: 3)}-#{Faker::Number.number(digits: 1)}-#{Faker::Number.number(digits: 2)}-#{Faker::Number.number(digits: 6)}-#{Faker::Number.number(digits: 1)}",
	dewey_decimal_number: "#{Faker::Number.number(digits: 3)}.#{Faker::Number.number(digits: 3)}",
	binding: Faker::Number.between(from: 0, to: 1))
  print '.' if i % 100 == 0
end

Now we have a lot of books records that we can use.

Let’s build an index page so that we can look at our books.

$ rails g controller books index

This will update routes.rb:

Rails.application.routes.draw do
  get 'books/index'
end

And we need to update app/controllers/books_controller.rb file with an index action, and we’ll start by loading all the books.

class BooksController < ApplicationController
  def index
    @books = Book.all
  end
end

And finally, a view at app/views/books/index.html.erb.


  All Books
  
      <% @books.each do |book| %>
        
      <% end %>
    
    
      
        Title
        Author
        Publisher
        Category
      
    
    
          <%= book.title %>
          <%= book.author %>
          <%= book.publisher %>
          <%= book.category %>

Title	Author	Publisher	Category
<%= book.title %>	<%= book.author %>	<%= book.publisher %>	<%= book.category %>

Run ./bin/dev and visit it in the browser.

Lazy Loading

The URL path /books/index is a little awkward. It would be great if it would load when the site loads up. Let’s add a root controller that will load the books page:

$ rails g controller root index

Change the routes.rb file to load at the root page:

Rails.application.routes.draw do
  get 'books/index'
  root "root#index"
end

Add a turbo-frame element to the root/index.html.erb page:


  Root Page
  <%= turbo_frame_tag "books", src: books_index_path %>

If you don’t change the book’s index page, this will load all the books in, and overwrite the URL. We want to hide the /books/index path, so let’s wrap the table in views/books/index.html.erb in a turbo_frame_tag:


  All Books
  <%= turbo_frame_tag "books" do %>
    
        <% @books.each do |book| %>
          
        <% end %>
      
      
        
          Title
          Author
          Publisher
          Category
        
      
      
            <%= book.title %>
            <%= book.author %>
            <%= book.publisher %>
            <%= book.category %>
          
    
  <% end %>

Title	Author	Publisher	Category
<%= book.title %>	<%= book.author %>	<%= book.publisher %>	<%= book.category %>

Now, when you load the root page, there is a skeleton that loads in the books table.

Animate the loading

Loading all these books could take a while. This could stand in for a different page with more complicated database calls that could take a few seconds. Let’s put in a small skeleton, animate a shimmering effect, and give the appearance that the page is working in the background. Look at the revised /views/root/index.html.erb:


  Root Page
  <%= turbo_frame_tag "books", src: books_index_path do %>
    
        <% (1..10).each do %>
          
        <% end %>
      
      
        
          Title
          Author
          Publisher
          Category
        
      
      
            
            
            
            
          
    
  <% end %>

The turbo-frame now has a block that puts in a skeleton table. It uses the tailwind animate-pulse class, which is a pulsing CSS animation. Instead of iterating through book records, it generates 10 rows. Each td cell has a rounded div that acts a visual placeholder. Loading the page shows a pleasant placeholder while all the books come in over the wire.

Free Interactivity

This shows how we can use a lazy loading page to add interactivity to our page with little extra work, and no extra JavaScript. You could imagine having to see up a Stimulus controller that loaded data in when it connected. Turbo allows us to skip even that step, and just use basic HTML and an extra Rails controller. You could even build a dashboard that loaded data from several sources.

Interactive HOTWire Notifications with Turbo Streams

Mon, 19 Sep 2022 10:00:00 +0000

Rails’ use of flash messages is a great way to provide context for customer actions. If they delete an object, flashing a notice that the delete action succeeded, or perhaps failed, gives them more context to make the next decision. With HOTWire’s asynchronous nature, you don’t get those notifications in the same way, especially if you’re just replacing a part of a page.

Refactoring Notifications

Let’s refactor the flash messages into the upper-left corner of the app, where they’ll float. Using a TailwindUI design, the key component is something with an id where Turbo can append the notification. I’m using a div with the id="notifications". I refactored the HTML for an alert or a notice into a partial, which I put in the app/views/layouts folder as _alert.html.erb and _notice.html.erb.

Displaying Alerts from TurboStreams

In any *.turbo_stream.erb view, add the following to check if there is an alert or notification:

<% if notice %>
  <%= turbo_stream.append 'notifications' do %>
    <%= render 'layouts/notice' %>
  <% end %>
<% end %>

<% if alert %>
  <%= turbo_stream.append 'notifications' do %>
    <%= render 'layouts/alert' %>
  <% end %>
<% end %>

This will append the notification to the notifications' element, and display the notification.

Building the notifications

You can start with a new project, and scaffold a Post model:

$ rails new notification_test -c tailwind
$ rails g scaffold Post title:string body:text
$ rails db:migrate

We’re going to add the HTML code to display our notifications. In app/views/layout/application.html.erb, add the notifications “home”, which won’t show anything, but Turbo will append notification onto it.


  
    
      
        <% if notice %>
          <%= render 'layouts/notice' %>
        <% end %>
        <% if alert %>
          <%= render 'layouts/alert' %>
        <% end %>
      
    
    <%= yield %>

In the app/views/layouts folder, add two almost identical partials that will display the alert or notice. Here is app/views/layout/_alert.html.erb:


  
    
      
        
      
      
        Alert!
        <%= alert %>
		<%# Need to clear flash[:alert] once displayed %>
        <% flash[:alert] = nil %>

Here is the notice in app/views/layout/_notice.html.erb:


  
    
      
        
        
      
      
        Notice!
        <%= notice %>
      	<%# Need to clear flash[:notice] once displayed %>
        <% flash[:notice] = nil %>

Now, when you perform an action, like creating a Post, you’ll see the notification floating above.

Hopefully, you noticed the Stimulus alert controller that will make this floating notification disappear after appearing, or allow the user to click the X to remove the notification. This uses the el-transition library to manage the animations. Add it with your current JavaScript management tool, for example with importmap:

$ ./bin/importmap pin el-transition

or yarn:

$ yarn add el-transition

Add the Stimulus controller, alert_controller.js:

import { Controller } from "@hotwired/stimulus";
import { enter, leave } from "el-transition";

let TIMEOUT_MILLISECONDS = 2000;

export default class extends Controller {
  connect() {
    enter(this.element).then(() => {
      setTimeout(() => {
        this.close();
      }, TIMEOUT_MILLISECONDS);
    });
  }

  close() {
    leave(this.element).then(() => {
      this.element.remove();
    });
  }
}

Now we have a nice floating notification layout, with a Stimulus controller providing the entering and leaving animations, and a timeout that removes the notification after a few seconds. Let’s add the Turbo Stream magic.

TurboFrames and TurboStreams

First, on the posts/index.html.erb page, let’s wrap the “New Post” button in a turbo_frame_tag.

<%= turbo_frame_tag 'new_post' do %>
  <%= link_to 'New post', new_post_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
<% end %>

In the posts/new.html.erb, wrap the key part of the form in the same turbo frame. This will be styled to be a modal that appears in the middle of the page:

<%= turbo_frame_tag 'new_post' do %>
  
    
      
        New post
        <%= render "form", post: @post %>
      
    
  
<% end %>

Turbo is going to handle the replacement, so the page will load the new form in the middle of the page.

When the “Create Post” button is clicked, a request goes to Posts controller on the create action. Add a new format response to the create action, complete with the flash notices:

  # POST /posts or /posts.json
  def create
    @post = Post.new(post_params)

    respond_to do |format|
      if @post.save
        format.turbo_stream { flash[:notice] = 'Post was successfully created.' }
        format.json { render :show, status: :created, location: @post }
      else
        format.turbo_stream { flash[:alert] = 'Post was not created.' }
        format.json { render json: @post.errors, status: :unprocessable_entity }
      end
    end
  end

Let’s add the posts/create.turbo_stream.erb template that will append the new post to the page, replace the “New Post” button, and append our notice to the notifications' element.

<%= turbo_stream.append 'posts' do %>
  <%= render @post %>
<% end %>

<%= turbo_stream.replace 'new_post' do %>
  <%= turbo_frame_tag 'new_post' do %>
    <%= link_to 'New post', new_post_path, class: "rounded-lg py-3 px-5 bg-blue-600 text-white block font-medium" %>
  <% end %>
<% end %>

<% if notice %>
  <%= turbo_stream.append 'notifications' do %>
    <%= render 'layouts/notice' %>
  <% end %>
<% end %>

<% if alert %>
  <%= turbo_stream.append 'notifications' do %>
    <%= render 'layouts/alert' %>
  <% end %>
<% end %>

Now, we can create a post, and get the SPA look, without having to resort to rendering everything from JavaScript.

The whole notification look

It’s HTML Over The Wire at its best.

Stylizing ActionMailers with Maizzle

Tue, 13 Sep 2022 14:58:35 +0000

I’ve been using Tailwind CSS for all my new projects, and I’ve been migrating my other projects over slowly. With Tailwind’s Rails gem, it’s been incredibly easy to drop in Tailwind, include my old CSS, and then move pages over. Tailwind is incredibly deferential to other CSS frameworks because it has a unique utility system, rather than trying to redefine the .button class yet again. Maizzle is a tool, written in Javascript, that takes Tailwind styled HTML for a mailer, and generates hardcoded styles. It optimizes for inboxes, so it makes some default decisions, such as column width. If you have an existing theme in your app, you can easily customize all your mailers to match your website’s theme and design.

How I’m using it

I purchased one of the theme packs from the craftingemails as a great starting point. One nice thing about Maizzle is that you can bring your CSS, and it will add the styles so that it looks correct in as many email clients as possible. I added my theme colors to make the templates match my project.

Setting it up

If you’ve already set up Rails on your machine, with Tailwind CSS, you should have the correct version of node setup. You can follow the directions at https://maizzle.com/docs/introduction, but here’s what I did.

First, download the email template or the starter version from GitHub.

Then, install maizzle and the dependencies:

$ npm install

Then, start the development server, which watches the source folder, and builds them.

$ maizzle serve

The one change necessary is to change the baseURL in the config.production.js file. Set it to an empty string so that nothing is prepended for image tags or links.

module.exports = {
  baseURL: "",
  // ... other options
}

Designing the templates

Since Maizzle just uses CSS, we can take a basic HTML template, and make it look great. This means you’ll want to change the views/layouts/mailer.html.erb to get rid of all the boilerplate to just 1 line:

<%= yield %>

All the header and HTML tags will be in each email template.

When designing the template in the maizzle folder, you’ll need to create dummy data to fill in. When you want to replace the data in the actual template that you’ll copy into your Rails app, you could manually add the ERB tags. You could also use Maizzle’s built-in preprocessors to use dummy data for development and actual ERB tags in the production build. For example, the Maizzle starter on GitHub has a transactional template that includes the logo. In Rails, we’ll want to use the asset_path to the icon instead of a local path.

Here is the icon:

If we test the page.env value, we can select the right tags:


     " width="70" alt="Maizzle" class="max-w-full align-middle [border:0]">

Now, you can see the image when you’re designing the template, but when it’s built for distribution, it includes the ERB tag, so you can copy and paste it into your mailer’s view, without have to tweak anything.

Occasionally, you don’t mind the ERB tags in the design, so you can just add them and know they’ll be converted on the Rails side.

Example of ERB tags in the output during design

Move Into Rails

Once you’ve got your design working, you should run the build command:

$ maizzle build production

This will optimize the CSS in the templates, and perform any switching we needed for the Rails side.

Look for the template in the dist folder. Copy all the HTML from the template, and the preview the email with your app’s Rails mailer previews.

Fancy Email Templates

Now, you have prettier looking email templates generated with your Tailwind theme. This should make all your transactional emails feel on brand when you correspond with your customers.

Stimulus.js & HOTWire Tutorial: Interactive Deletes

Fri, 24 Jun 2022 10:48:35 +0000

Interactive websites have that feeling of immediacy. Clicked links respond in milliseconds, and there is never a need to wait… Waiting for a remote record to delete, and then the whole page refresh afterwards can feel like an eternity in web’s modernity. But a little Stimulus works well with Turbo to make items on a page disappear immediately, all while a network request happens in the background. This tutorial takes a remote deletion link, adds an in-place confirmation message, and then hides the element when the delete request is sent to the server. When the request comes back with a success, the element is removed from the page, or with an error, the element put right back in place.

The controller is going to listen for a few different events emitted by Turbo¹ when the delete link is clicked. It stops the remote request the first time the link is clicked, and puts a confirmation message in the link. This feels better than the usual full alert modal that adding confirmation message usually throws up. Clicking the link a second time lets the request go back to the server. The element’s style is then set to display:none; so that it disappears immediately. A successful Turbo Stream response removes the element entirely, and an unsuccessful response reverts the style, so the element appears again. A timeout is added after the first click to reset the state of the controller and the link if it isn’t clicked a second time.

The HTML

I’m working with a simple ActiveRecord Post model which has a title, author, and text. The controller is similar to what you could generate from the Rails scaffold command. On the index.html.erb view, this is the HTML:

  All Posts
  <%= link_to "New Post", new_post_path %>
  <% @posts.each do |post| %>
    
      
        
<%= link_to post.title, post %>
        <%= post.author %>
        

        <%= post.created_at.strftime("%l:%M %P") %>
        

        <%= link_to "Delete", post_path(post), data: { 'turbo-method': "delete", 'delete-target': "link", action: "turbo:click->delete#captureClick turbo:before-fetch-request@window->delete#deleteAndHide" } %>
      
    
  <% end %>

There is a div element for the delete controller. The delete link towards the bottom is a target of the delete controller, since the controller needs to use it when getting click events and manipulate the message on it. The controller listens for the turbo:click and the turbo:before-fetch-request events so that the controller can add our visual interactivity. The controller doesn’t need to change anything else with how Rails sends and receives the delete request, meaning less work for the Stimulus controller and fewer chances for bugs.

The Stimulus Controller

The delete_controller.js Stimulus controller is the component in charge of the delete actions. It keeps track of the click state, changes the link text, and handles the result of the server’s response.

On connect(), the controller sets its delete state to false. This dictates later on how the click handler behaves. It sets a value called clickedController to false. This is used to keep state between the turbo:click event and the turbo:before-fetch-request.

In Turbo, the click event allows Javascript to cancel a Turbo request, and have the browser send the request normally. The controller uses it know that a click has happened, because the the turbo:before-fetch-request event is called on the document, and that’s the event similar to the UJS ajax:success event that the controller will use to cancel the request and change the confirmation message.

On a call to deleteAndHide(event) when delete is false, the controller records the current delete link text, changes the delete link to a new confirmation message, sets a reset timeout, and then stops the click event. On a call to deleteAndHide(event) when delete is true, the controller hides its element, and adds listeners for the server response. The response proceeds back to the server as usual.

The handleResponse(event) method resets the element back to the way the element looked, and makes the element visible again. It doesn’t do anything on success, because Turbo will remove it based on the server response.

The resetState() method removes the event listeners, sets the delete link back to the original test, and resets the delete state back to false.

const RESET_TIMEOUT_MILLIS = 3000;

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

export default class extends Controller {
  static targets = ["link"];
  static values = { message: String };

  connect() {
    this.delete = false;
    this.clickedController = false;
  }

  async captureClick(event) {
    this.clickedController = this.linkTarget == event.target;
  }

  async deleteAndHide(event) {
    if (this.clickedController) {
      this.clickedController = false;
      if (this.delete) {
        this.element.style = "display: none;";
        document.addEventListener(
          "turbo:before-fetch-response",
          this.handleResponse.bind(this)
        );
      } else {
        this.oldMessage = this.linkTarget.innerHTML;
        this.linkTarget.innerHTML = this.messageValue;
        this.delete = true;

        this.timeout = setTimeout(() => {
          this.resetState();
        }, RESET_TIMEOUT_MILLIS);
        event.preventDefault();
        return false;
      }
    }
  }

  handleResponse(event) {
    clearTimeout(this.timeout);
    this.resetState();
    console.log(this);
    console.log(this.element);
    if (event.detail.fetchResponse.response.status != 204) {
      this.element.style = "";
    }
  }

  resetState() {
    if (this.delete) {
      document.removeEventListener(
        "turbo:before-fetch-response",
        this.handleResponse.bind(this)
      );
      this.linkTarget.innerHTML = this.oldMessage;
      this.delete = false;
    }
  }
}

Ruby Controller

The delete method on the rails controller needs to respond to the turbo stream format. This is accomplished by adding format.turbo_stream. It’s using a nifty inline render of the turbo_stream remove command, so we don’t need to write an ERB partial.

  def destroy
    @post.destroy

    respond_to do |format|
      format.turbo_stream { render turbo_stream: turbo_stream.remove(@post) }
    end
  end

Practice?

Try to add something to alert the deleter on the page when the deletion fails. It can assume that failure isn’t a likely case, so the error message should be very disruptive to the page flow.

Interactivity

By making actions on a web page feel immediate, web app users feel more confident that the app registered their wishes. Deletion is definitely a good spot for double checking about someone’s intention, but by changing the delete link text, instead of an alert, it’s not as disruptive as usual. Imagine having to delete hundreds of records, and having to move the cursor multiple times for each action, and you’ll see this method is better for everyone.

Want To Learn More?

Try out some more of my Stimulus.js Tutorials. This is an update of previous tutorial that used Rails UJS, Stimulus.js Tutorial: Interactive Deletes with Rails UJS.

https://turbo.hotwired.dev/reference/events ↩︎

Interactive HOTWired paginated deletes

Wed, 01 Jun 2022 20:16:26 +0000

When you have a lot of records, it makes sense to paginate the table. That way, instead of loading thousands of records, you can load a subset, with better performance, and allow your user to move through the pages as leisure. It’s also better for usability, because it’s easier to go back to a particular page rather than scroll through a long list.

I like to use Basecamp’s geared_pagination gem to manage the pagination, offsets, and current page. I’ve found that when I want to delete a particular record, I could the HOTWire or javascript to remove the individual row. But it wouldn’t update the page counts, or make add in another record. This was a usability problem when I had to delete lots of rows. I would eventually remove all the rows on the page, and then I had to refresh to pull more records from the database.

I realized I can use Turbo Frames to replace the entire table, which will update the page counts, and add data back on to the page. Here is how it works below:

Interactive deletes on a paginated table using HOTWire

Here’s how it all works. This tutorial assumes Rails 7, and HOTWire configured with the turbo-rails gem.

The Controller

I’m going to use a Book model, but you can really use any of your records. Here is the books_controller.rb:

# frozen_string_literal: true

class BooksController < ApplicationController
  def index
    set_page_and_extract_portion_from Book.all
  end

  def destroy
    @book = Book.find params[:id]
    @book.destroy

    set_page_and_extract_portion_from Book.all
  end
end

The index method will use Geared pagination’s method to extract a selection from all the Book records. The destroy method is going to destroy the record, ad you would expect, and then it’s going to call the pagination method again. This will bring up the records we’ll use in the Turbo Stream to replace the table.

The Views

Since there are two actions in the controller, we’ll use two corresponding erb files. First, here is a partial that will be shared between the two actions, _book_records.html.erb:

<% unless page.first? %>
  <%= link_to "Prev", books_path(page: page.number - 1 ) %>
<% end %>

  Showing page <%= page.number %> of <%= page.recordset.page_count %>
  (<%= page.recordset.records_count %> total)

<% unless page.last? %>
  <%= link_to "Next", books_path(page: page.next_param) %>
<% end %>

    <% page.records.each do |book| %>
      
    <% end %>
  
  
    
      Title
      Author
      Publisher
      Category
      
    
  
  
        <%= book.title %>
        <%= book.author %>
        <%= book.publisher %>
        <%= book.category %>
        <%= link_to "Delete", book_path(book, page: page.number), data: { 'turbo-method': :delete, 'turbo-confirm': "Are you sure?" } %>

Title	Author	Publisher	Category
<%= book.title %>	<%= book.author %>	<%= book.publisher %>	<%= book.category %>	<%= link_to "Delete", book_path(book, page: page.number), data: { 'turbo-method': :delete, 'turbo-confirm': "Are you sure?" } %>

The first part of this partial is the pagination code that moves the page back and forth. The recordset count will show how many records are left, so we can confirm that a Book was deleted successfully. The Delete link will include the current page in the request so the paginate method will load the correct set of records. It also uses the turbo-method and the turbo-confirm data attributes, which are different from the traditional Rails UJS data annotations. They behave the same, but will be used by Turbo instead of Rails UJS.

The index.html.erb will have a turbo_frame_tag so that Turbo knows which section to replace. The action is supposed to update the page’s URL so that when the page reloads, it shows the proper page of records.

Paginate Through Books
<%= turbo_frame_tag "books", action: "advance" do %>
  <%= render partial: 'book_records', locals: {page: @page} %>
<% end %>

The destroy.turbo_stream.erb will use the replace command to reload the page of records. There is no need to remove the destroyed Book, because it is no longer in the database and won’t appear.

<%= turbo_stream.replace "books" do %>
  <%= turbo_frame_tag "books", action: "advance" do %>
    <%= render partial: 'book_records', locals: {page: @page} %>
  <% end %>
<% end %>

Notice how both actions use the book_records partial and pass the @page variable as a local parameter.

Amazing Interactivity

One of the great things about HOTWire is how very little changes in the controllers and views. By rethinking how the destroy method is used, we can get a very interactive app without having to build any front end JavaScript.

Rails PWAs using Turbo HHNPWA #7

Tue, 02 Mar 2021 20:53:02 +0000

Does your app even need to be a Progressive Web App? The answer lies in what is missing from your web app.

Would it help to have some information available in the situation where no internet connection is available?

Do you need to be available immediately, just like a native app?

Progressive Web Apps, even if visited through the normal browser chrome, can provide some nice enhancements to your web app’s experience. Thankfully, the minimum configuration to get this experience is very small. If you’ve been following along, you’ll see we started with a regular, performant and interactive Rails app, and only now are we going to turn on the PWA switch.

Setting it up

What makes any web site a progressive web app? Two small pieces tell the browser to treat your web page as a progressive web app. You’ll need a:

JSON Manifest
Service worker JavaScript file

The browser now grants your app the ability to run a parallel JavaScript process with the ability to inspect and modify all HTTP requests. The biggest advantage of having a service worker is offline access. Offline access stores important information on device, or give your user a small experience of the full online experience. I think the biggest gap in PWAs is that most services require a constant online connection. However, perhaps a Calendar or ToDo service could perform well in this situation. They could keep a cached copy of your events or todos, and then update any changes when the network is available.

Adding the Required Files

There are a number of techniques for making your Rails App a PWA. The biggest challenge with the current asset pipeline / webpacker setup is sending the service worker to the client. The PWA specification sets the root of the service worker at the path that it’s served from. If it’s example.org/service-worker.js, then the service worker gets to proxy all traffic for example.org. However, if it’s example.org/packs/js/service-worker.js, then it can only proxy requests under /packs/js/.

Putting the service worker and manifest file as JSON templates lets you use the most of the Rails stack. You can specify images through the asset pipeline, and you can use routing to prefetch pages that should be available online.

This can be done with a controller called service_worker_controller.rb and two methods, like so:

class ServiceWorkerController < ApplicationController
  protect_from_forgery except: :service_worker

  def service_worker
  end

  def manifest
  end
end

The protect from forgery for the service_worker method allows the javascript to be served without any forgery request problems in rails.

Update the routes file:

get '/service-worker.js' => "service_worker#service_worker"
get '/manifest.json' => "service_worker#manifest"

In the views folder, make a folder called service_worker and add a manifest.json.erb file that looks something like this:

{
"short_name": "HHNWPA",
"name": "HOTWire Hacker News Progressive Web App",
"icons": [
  {
    "src": "<%= asset_path('icon_192.png') %>",
    "type": "image/png",
    "sizes": "192x192"
  },
  {
    "src": "<%= asset_path('icon_512.png') %>",
    "type": "image/png",
    "sizes": "512x512"
  }
],
"start_url": "<%= root_path %>",
"background_color": "#fff",
"display": "standalone",
"scope": "<%= root_path %>",
"theme_color": "#000"
}

Asset paths are available, with means that all the Rails asset pipeline or WebPacker features are available. Those icons referenced above also need to be provided, so if you don’t have them, remove them from the manifest.

Now, add a service-worker.js.erb file that looks something like this:

var CACHE_VERSION = 'v1';
var CACHE_NAME = CACHE_VERSION + ':sw-cache-';

function onInstall(event) {
  console.log('[Serviceworker]', "Installing!", event);
  event.waitUntil(
    caches.open(CACHE_NAME).then(function prefill(cache) {
      return cache.addAll([
        '<%= asset_pack_path 'application.js' %>',
        '<%= asset_pack_path 'application.css' %>',
        '<%= asset_path 'application.css' %>'
      ]);
    })
  );
}

function onActivate(event) {
  console.log('[Serviceworker]', "Activating!", event);
  event.waitUntil(
    caches.keys().then(function(cacheNames) {
      return Promise.all(
        cacheNames.filter(function(cacheName) {
          // Return true if you want to remove this cache,
          // but remember that caches are shared across
          // the whole origin
          return cacheName.indexOf(CACHE_VERSION) !== 0;
        }).map(function(cacheName) {
          return caches.delete(cacheName);
        })
      );
    })
  );
}

function onFetch(event) {
  event.respondWith(
    // try to return untouched request from network first
    fetch(event.request).catch(function() {
      // if it fails, try to return request from the cache
      return caches.match(event.request).then(function(response) {
        if (response) {
          return response;
        }
        // if not found in cache, return default offline content for navigate requests
        if (event.request.mode === 'navigate' ||
          (event.request.method === 'GET' && event.request.headers.get('accept').includes('text/html'))) {
          console.log('[Serviceworker]', "Fetching offline content", event);
          return caches.match('/offline.html');
        }
      })
    })
  );
}

self.addEventListener('install', onInstall);
self.addEventListener('activate', onActivate);
self.addEventListener('fetch', onFetch);

Whatever files need caching are added in the onInstall function. This template only has the webpack pack files and the asset pipeline CSS, but any images, or asset pipeline files that should be cached can be added here.

Loading the service worker with Stimulus

I’ve found a Stimulus controller can load the Service Worker, and it neatly keeps JavaScript out of your other ERB templates. It also provides a cleaner JavaScript communication point between your HTML and the Service Worker.

It’s weird to say it, since this is the seventh tutorial on this website, but we’ll need to install Stimulus.

rails webpacker:install:stimulus

In the connect() function, the controller sees if the Service worker is running.

If the service worker isn’t running, the controller registers the service worker, and sets up a chain of callbacks, waiting for the installation and activation to complete.

Here is service_worker_controller.js

import { Controller } from "stimulus";
export default class extends Controller {
  connect() {
    if (navigator.serviceWorker) {
      if (navigator.serviceWorker.controller) {
        // If the service worker is already running, skip to state change
        this.stateChange();
      } else {
        // Register the service worker, and wait for it to become active
        navigator.serviceWorker
          .register("/service-worker.js", { scope: "./" })
          .then(function (reg) {
            console.log("[Companion]", "Service worker registered!");
            console.log(reg);
          });
        navigator.serviceWorker.addEventListener(
          "controllerchange",
          this.controllerChange.bind(this)
        );
      }
    }
  }

  controllerChange(event) {
    navigator.serviceWorker.controller.addEventListener(
      "statechange",
      this.stateChange.bind(this)
    );
  }

  stateChange() {
    // perform any visual manipulations here
  }
}

Testing?

Google’s Lighthouse is the best way to test how an app matches the specification. Lighthouse will give recommendations, and list what’s missing. It can even test accessibility. Progressive Web Apps need HTTPS when not being served from localhost, so testing in Google Chrome during development is the easiest option.

Next Steps

Subscribe for updates as this project takes shape. You can see all the code at Github: https://github.com/OnRailsBlog/hhnpwa.

HOTWiring an existing Rails Monolith: Forms!

Thu, 18 Feb 2021 14:20:23 +0000

Let’s say your majestic monolith is looking for more interactivity, and you’ve picked up Turbo. What aspects of a Rails app change that may cause some headaches? Add Turbo, and then follow along!

Forms

First, you need to test all your forms. Turbo dramatically changes the behavior of each form. The biggest change you will see is that your form redirects don’t behave the same way. Since Turbo is adding Single Page Application (SPA) functionality to your app, you will likely need to reengineer the frontend to behave more like a SPA. I think the quickest way to get Turbo working, and give you flexibility to incrementally update your forms is turn off remote forms, and tell Turbo to ignore the form. This worked best on my forms that made some change, and then redirected to a new page. This meant adding some data-turbo and data-remote attributes, like so:

<%= form_with model: @order, url: orders_path, data: { turbo: false, remote: false } do |form| %>

Setting the remote and turbo data attributes to false makes the form submission occur outside the JavaScript environment. This will blow away the JavaScript environment, so you’ll want to figure out a way reengineer your forms, which I’ll show you in the next section.

I don’t want to indict Turbo at all for this change. Adding Turbo is a rethinking of the way your Rails app interacts with the browser, and this is a stop gap to your existing app works, and you can refactor the front end to include more interactivity.

HOTWiring an Existing Rails Monolith

Thu, 28 Jan 2021 09:14:21 +0000

How do you add Turbo to your existing Rails app? What do you need to watch out for as you transition to a full HOTWire approach? I found it to be very straight forward, and mostly a search and replace operation.

Add Turbo Rails gem to the Gemfile and remove Turbolinks:

gem 'turbo-rails'

Then run ./bin/bundle install and

run ./bin/rails turbo:install

Search through your code base for turbolinks to see where you are using it. The first change I found was in the html layouts. 'data-turbolinks-track' became 'data-turbo-track'.

You may have configured some links that you didn’t want Turbolinks to follow, by setting the data-turbolinks attribute to false. This attribute is now data-turbo, so look for those throughout your code base.

You may have used the permanent attribute, data-turbolinks-permanent, which kept elements between page visits, and mimicked the behavior of single page applications. This attribute is now data-turbo-permanent.

If you have any JavaScript code that listened for turbolinks events, you should make sure the names of the events now start with turbo instead of turbolinks. I have a couple Stimulus controllers that listen to the turbolinks:before-visit event, so those are now turbo:before-visit. You can see all the Turbo events and compare them with the Turbolinks events.

Of course, run your tests after all these changes, and QA all your pages to make sure nothing is broken.

I’m looking forward to taking advantage of more of the features of Turbo, including lazy loading frames and an easier to use broadcast method for changes on the page.

OnRailsBlog

Interactive Modals

Headless UI with StimulusJS and an Outlet

Switching on Interactivity

Adding an Outlet for the Switch

In Closing

Animate Filtering Data in HOTWire

Listening for Morphing

Animating removals

Animating Insertions

Final enhancement

Interactive Apps

Filtering Data in HOTWire

Filtering on the Server

The Stimulus Search controller

Wiring up the HTML

HOTWire & Turbo Tutorial: Animated Deletions and Insertions

Adding a Custom Turbo Action

Sending the frame actions

Adding helpers in Rails

Progressively Enhancing

HOTWire: Where do I store my HTML state?

State

Controller State

Data Attributes

Values properties

Classes properties

Action Params

Data everywhere

HOTWire: Considering Morphing or Turbo Frames

Turbo Streams for a new Todo form

Editing in place

Deleting Todos

Putting it all together

Animating the Insertions and Deletions

Stimulus Tutorial: Moving & Animating Todos

Adding Buttons

Hiding Unnecessary Buttons

Updating the Stimulus controller

Accessible and Interactive

HOTWire Tutorial: Listening for changes over ActionCable

Moving on from the Stimulus controllers

No extra Channels

Listening for new Todos

Touch to broadcast changes

Simplifying

Hotwire Tutorial: How Do I Drag and Drop Items in a List?

Setting Priority

Reorder Stimulus Controller

Priority Controller

Wiring up the Front End

Stimulus.js and HotWired Tutorial: Update Model with Checkbox using Turbo Morphing

Displaying Progress in a Long Running Background Job using HOTWire

Uploading a CSV file

Import Books

Import Books

Processing a file

Passive yet Interactive

Adding Loading Screen with Turbo

Loading many books

All Books

Lazy Loading

Root Page

All Books

Animate the loading

Root Page

Free Interactivity

Interactive HOTWire Notifications with Turbo Streams

Refactoring Notifications

Displaying Alerts from TurboStreams

Building the notifications

TurboFrames and TurboStreams

New post

Stylizing ActionMailers with Maizzle

How I’m using it

Setting it up

Designing the templates

Move Into Rails

Fancy Email Templates

Stimulus.js & HOTWire Tutorial: Interactive Deletes