DEV Community: Dr Nic Williams

Broadcasting custom Turbo actions like set_title, morph, and more

Dr Nic Williams — Wed, 28 Dec 2022 22:33:42 +0000

One of the great new features of Hotwire Turbo 7.2 was custom actions. Originally, Turbo allowed us to send stream actions to the browser to add, remove, or replace some HTML. Now, we can tell the browser to do anything: console log, set title, play sounds, and use the morphdom library for powerful changes.

There are two ways for a Rails app to emit Stream Actions:

return one or more of them from a controller action with a turbo_stream format, and an turbo_stream.erb action template file.
broadcast them to subscribers of a Turbo Stream

In this post I will recap how to send custom actions via turbo_stream action responses, and then cover the new thing I had to figure out: how to broadcast custom actions to all subscribers of a Turbo Stream.

What are the built-in actions?

Hotwire Turbo provides a small set of Stream Actions out of the box:

append
prepend
remove
replace
update

What makes a Turbo Stream Action is determined by the JavaScript side of the Turbo library. When an append or remove action is sent to the browser -- by controller action response, or broadcast stream -- the client-side JavaScript looks at the Action and determines how to handle it.

In all 5 built-in actions above, the client-side JavaScript mutates the browser DOM to add, change, or remove elements.

Sending built-in actions to the browser

As mentioned above, we can send Stream Actions to the browser from controller action responses, or via broadcasts.

For controller action responses,

1) your action needs to specify the turbo_stream response format:

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

2) you need a corresponding create.turbo_stream.erb view template file. Within it, you are yielded a turbo_stream object upon which you construct Stream Actions that will be send back to the browser:

<%= turbo_stream.remove :new_button %>

For broadcasting actions,

1) you setup client-side subscriptions called Streams, by using the turbo_stream_from helper. Below, the resulting page will subscribe to any actions associated with a specific Book instance.

<%= turbo_stream_from @book %>

2) now broadcast actions from anywhere on the server-side and they will be sent to the required browsers. For example, we can broadcast replacement HTML if a Book instance changes from within the Book class:

class Book < ApplicationRecord
  after_update_commit -> {
    broadcast_replace_later_to self,
      target: dom_id(self),
      partial: "books/book_summary",
      locals: {book: self}
  }
end

The broadcast_replace_later_to helper will construct a replace Stream Action, including the newly rendered partial app/views/books/_book_summary.html.erb, and ask the background job system to send out the request to 0+ subscribers.

What are custom actions?

So if an action is implemented in client-side JavaScript, why can't we do arbitrary things? Log something to the browser console? Dispatch events to the DOM? Activate client-side JavaScript?

Thanks to Turbo 7.2 we now can dispatch arbitrary "custom" actions, and provide our own JavaScript to handle them.

Marco Roth's article Turbo 7.2: A guide to Custom Turbo Stream Actions is the go-to guide.

Moar custom actions

Marco also wrote a huge library of Stream Actions you might want to use called Turbo Power.

Here's a screenshot for dramatic effect:

In your controller turbo_stream.erb response you can set the page title, and log a message to the console:

<%= turbo_stream.set_title("New Page Title goes here") %>
<%= turbo_stream.console_log("We're hiring if you can see this!") %>

Broadcasting custom actions

But what if you want to broadcast a set_title custom action to all subscribers of a stream, not just one user?

The good news is that a Stream Action that is sent to the browser via controller actions or via broadcasting is the same message. What changes is how we build the Stream Action and broadcast it.

Whilst there are nice helpers like broadcast_replace_later_to for built-in actions, I could not find an equivalently concise way to broadcast arbitrary custom actions.

As of writing, I found I had to use some low-level methods to broadcast custom actions.

class Book < ApplicationRecord
  include Turbo::Streams::ActionHelper
  include Turbo::Streams::StreamName

  after_update_commit -> {
    content = turbo_stream_action_tag(:set_title, title: "Book: #{title}")
    ActionCable.server.broadcast(stream_name_from(self), content)
  }
end

Send multiple Stream Actions to the same subscribers by concatenating them together:

content = turbo_stream_action_tag(:set_title, title: "Book: #{title}")
content += turbo_stream_action_tag(:console_log, message: "Book: #{title}")
ActionCable.server.broadcast(stream_name_from(self), content)

Excellent, now we can broadcast to all stream subscriber any arbitrary custom Stream Action; and thanks to Marco's turbo-power library we can now do just about anything to the browser without needing to write some bespoke JavaScript to handle it. Lovely.

Epilogue

After posting, I chatted with Marco and after a few iterations he suggested the following syntax idea that I like a lot:

Friendly IDs for Ruby on Rails

Dr Nic Williams — Thu, 20 Oct 2022 22:08:15 +0000

Do you have URLs like /books/1 or /secret_things/10 and wish that they were friendlier? Also, wish the IDs were sequential and guessable?

I like Stripe's URLs, such as https://dashboard.stripe.com/test/products/prod_MG5m4q7sKvGto8. If I see the ID value prod_MG5m4q7sKvGto8 anywhere I know it belongs to a Stripe Product. cus_MG5sTiccdSlpjw? A Stripe Customer ID. Very friendly.

And the IDs are not sequential. Friendly and random. I want this.

I'm going to show you the project I use for friendly IDs, and how I add them to my Rails scaffolding generators so they are automatically enabled for every model.

rails generate scaffold Book title description:text

And my URLs automatically pop out looking like /books/book_qYlVPJvDprRabHa0wy1xz3n9.

A quick tweak of the generated class and they might become even nicer, /books/bk_qYlVPJvDprRabHa0wy1xz3n9.

Yeah, you want this too.

prefixed_ids gem

The magic is provided by Chris Oliver's prefixed_ids rubygem.

The only requirement is that your models' id column is bigint or some other integer. I was not successful using the gem with uuid columns. But you won't need UUID IDs because you'll have publicly friendly, random IDs, and internally sequential IDs.

bundle add prefixed_ids

Trying it out

Before we go and edit your scaffold generators, let's try it out on an existing model.

Add has_prefix_id :thing to one of your models, and go and view it in your app.

class Book
  has_prefix_id :bk

Your boring IDs now look gloriously friendly, /books/bk_x912t423.

The gem hijacks the find and to_param methods. Everything just works.

Adding it to your model generator

You definitely want friendly IDs for all your future models. That is, when you run either:

rails g model Book title
rails g scaffold Book title

You want the resulting app/models/book.rb to include the has_prefix_id :bk link from above.

First, copy the current Rails model.rb.tt template into your app.

If you're using Jumpstart Pro, you can skip this step.

mkdir -p lib/templates/active_record/model
curl https://raw.githubusercontent.com/rails/rails/main/activerecord/lib/rails/generators/active_record/model/templates/model.rb.tt \
  -o lib/templates/active_record/model/model.rb.tt

This file will be used to generate all your future model class files.

In the newly created model.rb.tt file, add the 3rd line:

<% module_namespacing do -%>
class <%= class_name %> < <%= parent_class_name.classify %>
  has_prefix_id :<%= singular_name %>

If you were to generate a Book model, it would look like:

class Book
  has_prefix_id :book
end

You can edit :book to :bk. Pick an abbreviation that resonates with your URL-appreciating customers.

Show them you care.

./bin/commits-since-last-production-deploy

Dr Nic Williams — Wed, 23 Mar 2022 21:10:53 +0000

When you work in a team, with multiple people taking on responsibility for moving work into production, it can mean that you are never 100% confident whether the current main/master branch has been fully deployed or not. What's running on prod?

Or rather, what's NOT running on prod yet?

Can I deploy my new commits merged into main through to production because they are all mine, and mine alone?

Or are there some gnarly new contributions that have been foisted on to the shared work branch, and you thoroughly want to review them before you take responsibility for sending them off into production, and potentially causing problems for customers, support team, and then the dev team in a few minutes or hours?

I wrote a script to that I have started adding to every Heroku-hosted project ./bin/commits-since-last-production-deploy that is shown below and hosted on a Gist.

To compare the current branch against a specific Heroku application:

./bin/commits-since-last-production-deploy -a myapp-stg

Any additional args are forwarded on to the git log command, such as --oneline:

./bin/commits-since-last-production-deploy -a myapp-stg --oneline

If you have a default heroku remote so you can git push heroku HEAD:main like a wild thing, then you can drop the -a flag:

./bin/commits-since-last-production-deploy

The script is below, and is hosted on a Gist

#!/bin/bash

help() {
  echo "Usage: ./bin/commits-since-last-production-deploy [-a myapp ] [ -h ]"
  exit 2
}

if ! command -v heroku &>/dev/null; then
  echo "Install 'heroku' CLI"
  exit 1
fi

if ! command -v jq &>/dev/null; then
  echo "Install 'jq' CLI"
  exit 1
fi

while getopts 'a:h' opt; do
  case "$1" in
  -a)
    appname="$2"
    shift 2
    ;;
  -h | --help)
    help
    exit 2
    ;;
  esac
done

last_deploy_result=$(heroku releases ${appname:+-a $appname} --json | jq -r ".[0].description")

if [[ $last_deploy_result =~ ^(Deploy (.*)) ]]; then
  sha="${BASH_REMATCH[2]}"
  git log "$sha"..HEAD "$@"
else
  echo "Last deploy to production did not succeed"
  echo "--> $last_deploy_result"
  exit 1
fi

Fundamentally, this runs heroku releases on your app, gets the Git SHA-1 that was deployed, then compares it against the list of commits on the current branch.

If you see no output, then there are no new commits that are not yet on production. You are free. Production is all yours. BWAHAHA.

What is my current Tailwind CSS breakpoint?

Dr Nic Williams — Tue, 01 Mar 2022 22:56:27 +0000

When you're designing your site and fiddling around with which Tailwind CSS classes should apply starting at each breakpoint, mobile (the default), sm:, md:, and beyond, it can be very handy for your browser to tell you definitively what breakpoint is currently active.

Create a partial/fragment/component with the following HTML, which uses the sticky z-50 top-2 left-2 classes to ensure your little badge always appears in the top left corner.

<div class="sticky z-50 top-2 left-2 max-w-xs text-gray-900 bg-gray-50">
  <p class="p-2 text-xs">
    Breakpoint:
    <span class="sm:hidden">mobile</span>
    <span class="hidden sm:inline md:hidden">sm</span>
    <span class="hidden md:inline lg:hidden">md</span>
    <span class="hidden lg:inline xl:hidden">lg</span>
    <span class="hidden xl:inline 2xl:hidden">xl</span>
    <span class="hidden 2xl:inline 3xl:hidden">2xl</span>
    <span class="hidden 3xl:inline 4xl:hidden">3xl</span>
    <span class="hidden 4xl:inline">4xl+</span>
  <p>
</div>

Next, in your most outer layout, inject this partial/component when the current page's parameters include dev=1 or similar, near the top of the <body> tag.

For example, in Ruby on Rails you might put the following inside your application.html.erb:

<%= render "shared/sticky_panel" if params[:dev].presence %>

Want to try it out? It's currently live to the public at https://app.rcrdshp.com/?dev=1.

How to display Admin-only links with CSS

Dr Nic Williams — Mon, 21 Feb 2022 22:39:58 +0000

It is very convenient for staff/admins to sprinkle "admin-only" links around the application. Since you're always a staff/admin user, how do you distinguish staff-only links from normal links? How do you make sure you're not exposing "dead" admin-only links to customers?

I like to annotate my admin-only links with a little SVG icon to indicate that this link is for staff/admin only:

This is a normal <a> link with a class admin-only:

<a href="/admin/deals/1234" class="admin-only">Internal docs</a>

This is implemented with a tiny piece of CSS to use the magic ::after pseudo-element, and the content property.

a.admin-only {
  position: relative;
}
a.admin-only::after {
  position: absolute;
  top: -2px;
  right: -14px;
  content: url('data:image/svg+xml; utf8, <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M4 8V6a6 6 0 1 1 12 0v2h1a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2v-8c0-1.1.9-2 2-2h1zm5 6.73V17h2v-2.27a2 2 0 1 0-2 0zM7 6v2h6V6a3 3 0 0 0-6 0z"/></svg>');
  display: block;
  width: 12px;
  height: 12px;
  color: #444;
}

The content value could be plain text, such as (admin).

The top/right help to place the SVG icon to the right of the <a> text on the screen. Maybe you'll need different values for different sized icons or fonts.

I love that I can inject any SVG into the content property, and with the ::after pseudo property I can place these SVG icons after any text. Seems a perfect use case to indicate which links are admin-only.

What is the ordering of Ruby on Rails controller filters?

Dr Nic Williams — Tue, 10 Aug 2021 01:00:30 +0000

Some of my application's controllers are a blend of modules from other people's Rubygems, such as ShopifyApp library. They inject before and after action filters around my actions. Sometimes they abort the request and redirect somewhere else. I wanted to know what filters were being invoked and in what order:

class ProductsController < AuthenticatedController
  def index
    __callbacks[:process_action].map { |c| [c.kind, c.instance_variable_get(:"@key")] }
  end
end

The output was like:

[
  [:around, 82000],
  [:before, :set_shop_host],
  [:before, :redirect_to_splash_page],
  [:before, :set_locale],
  [:after, :set_test_cookie],
  [:before, :verify_authenticity_token],
  [:after, :verify_same_origin_request],
  [:after, :set_esdk_headers],
  [:before, :login_again_if_different_user_or_shop],
  [:around, :activate_shopify_session],
  [:before, :set_shop_origin]
]

How to isolate your Rails blobs in subfolders

Dr Nic Williams — Fri, 11 Jun 2021 04:20:04 +0000

Ruby on Rails has a very nice abstraction for storing user-provided assets and images to any cloud (AWS S3, Google, Azure, local files etc) called Active Storage. If you are spinning up new deployments of your application with each branch/pull request, you will want the uploaded assets to go nicely into their own subfolders. Much easier to clean them up later. Unfortunately this is not possible out of the box.

Fortunately, with Ruby, we can fix anything.

Firstly, we need a solution that does not alienate all existing blobs. We only want to put new blobs into subfolders. Existing blobs can stay exactly where they are.

I've deployed two demonstration apps that show the internal key to demonstrate that the images are stored in different subfolders:

The new files in each app are now being stored in subfolders, whilst legacy files are kept in their original file in the root of the bucket:

$ aws s3 ls s3://mybucket/
                           PRE subfolder-demo-1111/
                           PRE subfolder-demo-2222/
2021-06-11 12:08:16    1579488 g7643rle6b6bgn38v16734062wqw
2021-06-11 13:50:33    5034683 ki79m2n0p5ib3hg8l6bf1z7yrclt

In the sample solution below, I'm going to prefix all uploaded blobs with the name of the deployment. On Heroku this is available at runtime from the environment variable $HEROKU_APP_NAME after you turn on dyno metadata.

Each user-provided file is stored in your blobstore and registered in your database with an ActiveStorage::Blob. The ActiveStorage::Blob#key value guarantees that two files uploaded with the same name will be stored with unique file names.

If we change #key to have different prefix for each deployment then our blobs will be stored in isolated subfolders.

To feel good about myself as a professional, let's write a test first.

# spec/lib/activestorage_blob_spec.rb
require "rails_helper"

RSpec.describe ActiveStorage::Blob do
  let(:blob) { ActiveStorage::Blob.create_and_upload! io: StringIO.new("This is a test file"), filename: "test.txt" }
  let(:key) { blob.key }

  it "keys have no special prefix by default" do
    expect(ENV).to receive(:[]).with("HEROKU_APP_NAME").and_return(nil)
    # default key looks like "nk2gxeujmuoldqr6o8ng6gov9g5c"
    expect(key).to match(%r{\w{28}})
  end

  it "keys have no special prefix by default" do
    expect(ENV).to receive(:[]).with("HEROKU_APP_NAME").and_return("rcrdcp-pr-123").twice
    # expect like "rcrdcp-pr-123/nk2gxeujmuoldqr6o8ng6gov9g5c"
    expect(key).to match(%r{rcrdcp-pr-123/\w{28}})
  end
end

If the application is not running on Heroku, then keep using the default #key — a 28-character long random string.

If the app is running on Heroku, then put the app name at the front of the string, e.g. myapp-pr-123/nk2gxeujmuoldqr6o8ng6gov9g5c.

Currently, the #key value is created indirectly by has_secure_token :key before the creation of an ActiveStorage::Blob.

Our solution will be to re-create this key value with an additional before_create call.

# config/initializers/active_storage.rb

Rails.configuration.to_prepare do
  ActiveStorage::Blob.class_eval do
    before_create :generate_key_with_prefix

    def generate_key_with_prefix
      self.key = if prefix
        File.join prefix, self.class.generate_unique_secure_token
      else
        self.class.generate_unique_secure_token
      end
    end

    def prefix
      ENV["HEROKU_APP_NAME"]
    end
  end
end

You can use any environment variable that differentiates your deployments.

On Heroku, to access the $HEROKU_APP_NAME variable you need to turn on dyno metadata and deploy the app again.

heroku labs:enable runtime-dyno-metadata

Thanks to Arian Faurtosh for the starting point for this solution https://github.com/rails/rails/issues/32790#issuecomment-844095704. I found I needed to take a different route due to the behaviour of has_secure_token which might a recent change.

Automatically sorting your Tailwind CSS class names

Dr Nic Williams — Tue, 08 Jun 2021 21:28:38 +0000

When Steve Jobs returned to Apple he opted to make one less decision everyday: he always wore the same black top. He was now liberated to make one additional, more important, decision during his day. I've been making tiny decisions every day and I want to be set free: I do not want to decide the order of my Tailwind CSS classes.

I want tools to do it. Tools that everyone on the team today and in the future will keep using consistently.

Never again will I need to decide the ordering of CSS classes in my HTML:

<div class="flex flex-grow-0 justify-between items-center px-2 -mt-7 text-xs text-white uppercase">
  <div class="flex items-center space-x-2">
    <div class="flex justify-center items-center w-5 h-5 text-gray-900 rounded-full bg-brand-primary-surface">

Well known Tailwind CSS utility classes are sorted first, and bespoke classes come last. What is the ordering of utility classes? Why is flex before w-5 which is before text-gray-900?

Who cares. You don't either. Let the tools below do their job and everyone's CSS class names will look the same, and look fantastic.

There are three tools that help:

Headwind - a VS Code extension that sorts your CSS classes on save
Rustywind - a CLI that can update all your files' CSS classes at once
Overcommit - run rustywind --write during git commit to update your files before you send them off to git

Update: @fractaledmind fixed an issue where rustywind is installed via package.json -- we must wrap it in an npm run rustywind-fix script.

Headwind

I use VS Code and once of its exemplar qualities is the magnificent library of community extensions. VS Code provides the ability for one or more installed extensions to run when you save a file. This is brilliant for automatically formatting your file before it hits the disk. Let's use this hook to format any series of CSS class names in our file.

Enter, Headwind.

Install it into VS Code, go to any of your HTML files, re-save the file and BOOM!! all the series of CSS class names are reordered consistently.

Rustywind

This is great for you. You installed the VS Code extension. Unfortunately, statically speaking, someone you work with uses Vim. You know who they are because they would have told you.

So let's take steps towards ensuring everyone who works on your projects is always formatting their CSS class name lists using the same tool.

Enter, Rustywind. It is a CLI rustywind that is installed via npm but written in Rust. I didn't know you could do that either.

From what I read, Rustywind was inspired by Headwind, but now looks to be used by Headwind itself. Very nice.

You can fix a single file with rustywind:

rustywind path/to/my/template.html --write

Or fix all the files:

rustywind . --write

To ensure everyone installs rustywind, add it to your project's package.json with npm or yarn to taste:

$ yarn install -D rustywind

# or

$ npm i --save-dev rustywind

Everyone will have rustywind installed into the application when they next run npm i or yarn.

Next, create a local npm script in your package.json:

  "scripts": {
    "rustywind-fix": "rustywind --write ."
  },

Any developers of your repository can now access the local rustywind via:

npm run rustywind-fix

Overcommit

Finally, let's help everyone run rustywind all the time. Or, at least, run it before they commit their files to the Git repository.

If you're familiar with git hooks, you'll know you could create or edit .git/hooks/pre-commit and run the rustywind . --write command. Alas, these git hooks are local to you. Your hooks aren't assured to be the same as everyone else. You're formatting with rustywind but no one else is.

Fortunately, you can share git hooks, and make them pretty. How pretty?

Yes, you want that now, I know.

Enter, Overcommit: a tool to manage and configure Git hooks.

Create a configuration file for your project that runs Rustywind called .overcommit.yml:

PreCommit:
  Rustywind:
    enabled: true
    required: true
    command: ['npm', 'run', 'rustywind-fix']

Now that you've added this .overcommit.yml file to the root of your git repo, we now need everyone to do something for the greater good. They need to install Overcommit and activate it for their local git clone.

Overcommit is a CLI that is distributed as a RubyGem.

gem install overcommit

If your project is a Ruby project with a Gemfile, then add the gem:

group :development do
  # A fully configurable and extendable Git hook manager
  gem "overcommit"
end

And run bundle install. I like this best.

The second manual step for everyone is to activate the Git hooks. Everyone needs to run:

overcommit

Thanks everyone. You're making the world a better place. Next, net zero carbon emissions.

Every developer will now see Rustywind during their next commit.

$ git commit -a -m "Doing the things"
Running pre-commit hooks
Run Rustywind.............................................[Rustywind] OK

✓ All pre-commit hooks passed

If you're a Ruby developer and also want everyone to run the Ruby formatter and linter StandardRB, then extend your .overcommit.yml file:

PreCommit:
  Rustywind:
    enabled: true
    required: true
    command: ['npm', 'run', 'rustywind-fix']
  StandardRB:
    enabled: true
    required: true
    command: ['bundle', 'exec', 'standardrb'] # Invoke within Bundler context
    flags: ['--fix']

When you commit the two commands rustywind and standardrb --fix will be run in parallel:

$ git commit -a -m "Doing the things"
Running pre-commit hooks
Run Rustywind.............................................[Rustywind] OK
Run StandardRB...........................................[StandardRB] OK

✓ All pre-commit hooks passed

Freedom by abdication

"But I don't agree with the order that Rustywind sorts the classes!"

Whether its a syntax formatter for your programming language whitespace or a tiny tool that has a preference for CSS class orders, just pick one and let it care more than you do. It will consistently do its thing over and over.

You really don't care that much about the order of the classes to not use a free, instant, shareable, pretty, and consistent tool do you?