Forem: leastbad

The CableReady Language Implementation Project

leastbad — Sun, 28 Nov 2021 12:42:38 +0000

We believe that CableReady can become the universal standard tool for developers to dynamically control client browsers from the server. While the project has roots in the Ruby on Rails community, the JS client is unopinionated about how the simple JSON structure that it consumes is created.

// Detect dark theme var iframe = document.getElementById('tweet-1464595363961180162-368'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1464595363961180162&theme=dark" }

We would like to announce support for Python, Go, C#, Java, PHP and NodeJS server libraries in early 2022. While there's a broad set of features a server library could implement, there's a baseline that we'd like to make sure all implementations can offer.

Background

CableReady was started in 2017 by Nate Hopkins. It predates LiveView and the HTML-on-the-wire trend by 18 months. It sees roughly 15,000 downloads per week and offers 36 different operations.

CableReady is currently a client-side JS module and a server-side Ruby module.

Key concepts

available everywhere
multiple operations per payload
schemaless
simple JSON wire format
method chaining
transport agnostic
extensible via custom operations

Available everywhere

Rails developers can access a cable_ready singleton from just about anywhere in their application, and we believe it's a big part of the secret sauce. While every language and framework has their own idioms, we encourage implementors to remove barriers and make it easy to call CableReady anywhere it could be useful.

https://cableready.stimulusreflex.com/v/v5/cableready-everywhere

Operations and their options

Operations are the basic atomic unit of activity in CableReady. Each operation typically has a very specific focus and often mimics the DOM JS spec for the activity in question. Operations have options passed to them which specify their exact behavior.

Multiple operations can be prepared together. They will be executed in the order that they were created. Different operation types can be mixed together in one payload.

The Ruby implementation offers two interfaces; the (original) primary mechanism delivers the operations to a WebSocket channel in what we refer to as a "broadcast". The other - known as "cable car" - returns a JSON string that can be sent, persisted or displayed for any purpose.

Schemaless

CableReady operations each have their own mandatory and optional options, along with options that are provided to every operation by the library. However, arbitrary additional options can be passed to an operation and they will be forwarded to the client. This makes it easy for CableReady to form the basis of much larger projects, such as StimulusReflex.

JSON wire format

As of v5.0, the CableReady JSON wire format is an array of objects, where each object represents one operation. It's intentionally very simple.

[{\"message\":\"Hello!\",\"operation\":\"consoleLog\"}]

Each operation has camelCased key/value pairs that convey options. Every operation must have an operation value, or the client will raise an exception.

Method chaining

Developer experience is a high priority. We take pride in the readability and expressiveness offered by our server API. The basic pseudocode structure we provide looks like:

cable_ready[:foo].operation(options).broadcast

In other words, the first method cable_ready starts a method chain by returning self, and then each operation is a method that also returns the chain started by the initial method. In this way, you can chain together as many operations as you like. Finally, we have a broadcast method which takes the current chain and broadcasts it via WebSockets to the :foo channel.

We also have our "cable car" interface which emits JSON when to_json is called. This makes it perfect for responding to Ajax fetch requests:

cable_car.operation(options).to_json

The cable_car might be assembled in steps, perhaps via a control loop:

inspiration = cable_car.console_log(message: "Hello there!").dispatch_event(name: "fred", detail: {inspiring: true})
3.times do |i|
  inspiration.console_log(message: "Still here: #{i}")
end
inspiration.to_json

The main expectation that should hold between languages is that you will start the chain with a command, add one or many operation methods, and then execute the chain.

Transport agnostic

CableReady started its life as a WebSocket library, but the neutral JSON format has potential far beyond just WebSocket usage. We now frequently return CableReady JSON payloads via Ajax as well. There's nothing stopping you from embedding payloads into a DOM element attribute, for example.

We believe that a minimally viable CableReady server library must be able to produce compatible JSON. There's no hard requirement that it interface with WebSockets, although we do find this to be a major sweet spot and will do our best to provide support.

Custom operations

While CableReady ships with an impressive number of operations out of the box, users should be able to add their own operations. Admittedly, the method used to dynamically create all of the methods for each operation is the most sophisticated one in our framework, but again, we're here to help.

https://cableready.stimulusreflex.com/v/v5/customization#custom-operations

Get involved!

We have a wonderful community with over 1600 folks on our Discord server, helping people get started. Come join https://discord.gg/stimulus-reflex and drop by the #cable_ready channel with any questions.

Async Redis key mutation notifications in Rails

leastbad — Sun, 27 Jun 2021 14:55:42 +0000

Update 10/7/2022: I prepared a simple Rails 7 app that demonstrates the functionality described in this article.

I am a huge fan of Kredis. It allows Rails developers to see Redis as far more than just a fragment cache and "where jobs are".

Working with Kredis made me want to be able to run arbitrary operations in my Rails app when specific keys are modified via specific Redis commands. Redis has an excellent pub/sub infrastructure, and all Redis commands publish messages.

Why would someone want this?

While it's true that changes to data that occur within a typical Rails app are already well covered by model callbacks, state machines and other standard tooling, an entire world of real-time stream processing, ETL and multi-application use cases open up when you can run redis-cli set leastbad rules on your terminal and pick it up in your app.

Problem #1: Listening for messages blocks execution.
Solution #1: Spin up a thread!

Problem #2: Every dyno/server is going to receive the same messages, causing mayhem as developers respond to those messages with database updates. Side-effect chaos!
Solution #2: A standalone process that can be registered as a worker in Procfile... sort of like Sidekiq.

At first, I was just planning on borrowing 95% of Mike Perham's battle-hardened code. Then I realized that the Venn diagram of "people who want a Redis changeset firehose" and "Sidekiq users" is close to 100%... so I just bolted what I needed onto Sidekiq.

Try it out!

What follows is the MVP of my new gem. In fact, it's not a gem, yet: it's an initializer! It has no tests and is hours old. My janky code would make poor Mike bleed out. The goal is to see if folks actually need/want this to exist. I'm looking for feedback on what the ideal Rails-side API would actually look like.

Your Rails app needs to be up and running with Sidekiq. Just stick this in config/initializers/sidekiq.rb:

module Sidekiq
  class Subscriber
    include ::Sidekiq::Util

    def initialize
      @done = false
      @thread = nil
    end

    def start
      @thread ||= safe_thread("subscriber") {
        until @done
          Sidekiq.redis do |conn|
            # https://redis.io/topics/notifications#configuration
            conn.config(:set, "notify-keyspace-events", "E$lshz")
            # https://redis.io/topics/notifications#events-generated-by-different-commands
            conn.psubscribe("__key*__:*") do |on|
              on.psubscribe do
                @firehose = Firehose.new
              end
              on.pmessage do |pattern, command, key|
                @firehose.process(command.split(":").last.to_sym, key)
              end
              on.punsubscribe do
                @firehose = nil
              end
            end
          end
        end
        Sidekiq.logger.info("Subscriber exiting...")
      }
    end

    def terminate
      @done = true
      if @thread
        t = @thread
        Thread.kill(@thread)
        @thread = nil
        t.value
      end
    end
  end
end

module CoreExtensions
  module Sidekiq
    module Launcher
      attr_accessor :subscriber

      def initialize(options)
        @subscriber = ::Sidekiq::Subscriber.new
        super(options)
      end

      def run
        super
        subscriber.start
      end

      def quiet
        subscriber.terminate
        super
      end

      def stop
        subscriber.terminate
        super
      end
    end
  end
end

Sidekiq.configure_server do
  require "sidekiq/launcher"
  ::Sidekiq::Launcher.prepend(CoreExtensions::Sidekiq::Launcher)
end

I'm using CableReady to send console log notifications to the Console Inspector whenever a key is updated with the Redis SET command. I have a simple AllUsers ActionCable Channel in play for testing. This lives in app/lib/firehose.rb:

class Firehose
  include CableReady::Broadcaster

  attr_reader :redis

  def initialize
    @redis = ::ActionCable.server.pubsub.redis_connection_for_subscriptions
  end

  def process(command, key)
    case command # https://github.com/rails/kredis#examples
    when :set    # string, integer, json
      cable_ready["all_users"].console_log(message: "#{key} was just updated to #{redis.get(key)}").broadcast
    when :rpush  # list
    when :lrem   # unique_list
    when :sadd   # set
    when :incr
    when :decr
    when :incrby
    when :decrby
    when :exists
    when :del
      cable_ready["all_users"].console_log(message: "#{key} was deleted").broadcast
    else
    end
  end
end

As Seinfeld would say, is this anything?

Live previews with Rails and StimulusReflex

leastbad — Wed, 24 Mar 2021 06:40:36 +0000

This morning I read Live previews with Rails and Stimulus 2, a post which compares the experience of implementing a text preview feature using server-rendered code. The author choose to use a "pure Ajax" approach with Stimulus, as well as what the same project would look like using Turbo Frames.

This post will present a 3rd option: StimulusReflex. The full source for this example is available on Github. Don't forget to change to the previews branch!

First, we'll need a template. I'm just going to use a vanilla tag helper:

<%= text_area_tag :body,
                  nil,
                  data: { reflex: "input->Composer#preview" } %>

<div id="preview"></div>

The only thing required to make this feature work is a Reflex declared on the textarea element. input events captured will initiate a preview action on the Composer Reflex class. I also assigned an id attribute to the strong element so that we have a destination for the preview content.

class ComposerReflex < ApplicationReflex
  def preview
    morph "#preview", element.value
  end
end

The preview action takes the value of the element which triggered the Reflex, and updates the #preview element in the browser. Behind the scenes, this is done using one of CableReady's 33 operations, inner_html.

That's it... there are no further steps. You don't need any extra templates, routes or Stimulus controllers.

If you open the Console Inspector, you'll see that each Reflex takes about 5ms, round-trip.

StimulusReflex and CableReady offer a simple but powerful RPC model for building reactive applications. The functionality of this stack eclipses Turbo in every meaningful dimension:

CR has ~7x as many verbs/operations as Turbo Streams (just CRUD)
CR supports adding custom operations
CR is incredibly flexible in terms of who or what you send updates to
CR operations can be chained and target multiple elements
CR can broadcast from anywhere in your app: jobs, reflexes, controllers, rake tasks, channels
CR can provide visual feedback when elements are updated
SR provides a transaction wrapper around each request
SR has a full life-cycle of events and callbacks on the server and client
SR Reflex updates use DOM diffing, not innerHTML, so Stimulus controller state is preserved
SR Reflexes can be initiated by JS or declared in markup
SR offers a highly performant RPC mechanism with Nothing Morphs
SR benefits from tight coupling with Stimulus
SR has really powerful server and client debug tooling
SR has exceptionally thorough documentation
SR has incredible free support
SR has a 2000+ person Discord community that is incredibly supportive

I hope that you'll consider updating your post with a third option, Josef!

Developer Happiness: StimulusReflex v3.4

leastbad — Fri, 18 Dec 2020 16:52:39 +0000

It's red letter day: after three months of development and nine pre-release candidates, StimulusReflex v3.4 has finally dropped.

The introduction of Morphs in September elevated StimulusReflex from a cool proof-of-concept to a promising tool for building reactive UIs.

Open source projects need to think creatively to stand out. Hiring an actor to record a fake testimonial by a beloved fictional douchebag didn't compute for some. The initial tweet was watched 9,100 times with 111 re-tweets, resulting in 27,000 impressions and 4,200 engagements. The YouTube version has been viewed 5,800 times to date. This prompted a flurry of high profile articles, most notably Rails legend Obie Fernandez's epic "React is dead. Long live Reactive Rails. Long live StimulusReflex and ViewComponent". StimulusReflex was the featured story in Ruby Weekly. Jason Charnes announced that a course is in the works. Ruby Hero Ryan Bates asked Digital Ocean to donate $5,000 to the project. Membership on our Discord has doubled, and our weekly downloads went from under 5,000 to over 12,000.

Perhaps most importantly, we've crossed the rubicon from being mocked to being seen as a threat. Given the thousands of hours passionately invested in building and supporting StimulusReflex and CableReady, $600 to 5x our name recognition and establish this stack as a preferable alternative to JS-based SPAs - pretty much over night - seems like a solid return on investment.

Knowing that we're influencing the direction of Rails itself is possibly the most gratifying upside of all. As evidenced by DHH gradually walking-back earlier statements saying the long-promised NEW MAGIC is "unrelated" to StimulusReflex, the narrative has progressively evolved from "similar in intent" to "an alternative to" StimulusReflex. We want Rails to kick ass and we're glad to be keeping one of our heroes on his toes. Granted, it's getting harder and harder for him to imply that he "discovered" these ideas in a fevered burst of primordial creative insight.

When I think about what "developer happiness" means to me, it comes down to two things:

a magical sense of "things just work", made possible by ideas like the Principle of Least Surprise, intelligent defaults, methods that you hope will be there and they are, and the defenestration of ceremony and boilerplate code
the anticipation and mitigation of painful things that could otherwise reduce my happiness

Things Just Work

The recent method chaining capability of CableReady v4.4 combined with the magic cable_ready method available inside of Reflex actions is a great example of things working very well. In StimulusReflex v3.3, using CableReady to replace an element for the current user looked like this:

Here's the same thing in StimulusReflex v3.4. How's that for "conceptual compression"?

As of StimulusReflex v3.4 and CableReady v4.3, every time a DOM event is created, a jQuery event with the same name and details is also created - but only if the jQuery library is present and detected in the current application. We welcome the millions of jQuery users with open arms.

There are two new features that are subtle but exciting:

we've introduced a new finalize life-cycle stage that runs after all CableReady operations triggered by Morphs have finished. It's perfect for initiating animations and Turbolinks navigations
there's now an optional "tab isolation" mode, which makes sure that Morphs only impact the DOM of the browser tab that initiated the Reflex

You can also magically unpack signed Global IDs right into ActiveRecord models. As the Great Dane often says, "look at all of the code I didn't have to write!"

Mitigation of Pain

It has to be the ultimate cliche in software development that every new release is described as faster, with fewer bugs and far more robust.

v3.4 isn't just faster, with fewer bugs and far more robust... it's also substantially smaller, with the client footprint shrinking to just 11kb including CableReady, morphdom and ActionCable.

Stimulus 2 Just Works. You can use v1.1, too. Whatever you like.

Significant client-side refactoring made our vastly improved logging module, tab isolation and the finalize stage possible while ensuring that multiple concurrent Reflexes can be in-flight without corruption or side-effects. We're also far more forgiving in scenarios where the element which initiates a Reflex is replaced - a major source of confusion for newcomers in the past.

It's not just the client that has been given white glove treatment, either: v3.4 introduces a brand new server-side logging module that is disturbingly customizable without being "too much":

We've added an initializer, but the defaults are so intelligent, it's very likely that you'll never change them. That said, it's nice to know that if you need your Page Morphs to support Rack middleware, it's super easy.

Speaking of pain: weird bugs due to mismatched gem + npm package versions are now a thing of the past. StimulusReflex will now yell loudly and abort if versions don't match... unless you turn warnings off in the initializer.

One more thing... while it's not technically part of the SR/CR stack, I released a Stimulus controller called radiolabel that gives you visual feedback on your CableReady operations as they happen in development. It's an easy way to make debugging your app faster and more explicit.

The coolest and most profound changes in v3.4 came from community contributors, sometimes making their first PRs. In particular, I'd like to call out the code and support efforts of folks like Roland Studer, Konnor Rogers, Piotr Wodz, Chris Oliver and Rafe Rosen.

Meanwhile, Josh LeBlanc and his View Component Reflex might rightfully be considered our secret weapon(s).

A personal thanks to all of the contributors, including my co-conspirators Nate Hopkins, Julian Rubisch and Marco Roth.

NEW MAGIC is a wing of the #resistance, and the #resistance is kicking ass.

Remember: a reflex is faster than a reaction. ❤️

StimulusReflex v3.3 Morphs has been released

leastbad — Tue, 22 Sep 2020 13:33:48 +0000

TL;DR: scroll down for game-changing new features, a declaration of war and a legitimate celebrity endorsement.

I have a secret: I've been developing software my entire conscious life, but StimulusReflex was my first Open Source project and I came to it out of distress, not curiousity. Instead of sensing opportunity, I was in a crush of desperation.

I'm a Rails developer. I learned some React to help my partner human with her ambition to become a coder. Every day, I felt more sad and upset that she was being taught a stack that fetishized complexity. I needed to channel my grief into a solution, because complaining about how broken things had become was driving her nuts. I was on a mission.

Fast-forward 18 months, 90,000 downloads, 60 releases and 500 community members later. People like it... they really like it!

And now, the most exciting update to the original vision has arrived. We spent a year improving things incrementally, listening carefully to the problems and requests people brought to our Discord. I spent a lot of time asking people why they wanted to do things. Like the landscapers at Ohio State University, we didn't rush to conclusions or prescribe what we imagined people wanted.

Earlier this year, regular updates paused. Coccoons were spun. Epic Github pull request conversations helped us iterate our design until Morphs took shape.

Originally, a Reflex would regenerate the current page, going through most of the Rails stack as it executed the controller action and ultimately sent the entire page back to the browser, even if you just wanted to change 1 to 2. It worked great in spite of being a potentially heavy request, but we knew we could do better.

A Selector Morph completely skips ActionDispatch. Instead, you can now render a partial or ViewComponent and send the result to the client, where it will update a surgically targeted DOM element. In fact, you can update multiple elements in one request. And boy, is it ever fast. If you think of Rails as slow, you'll have a hard time explaining the 12ms updates.

Morphs can also update nothing at all. This is really handy when you want to launch an ActiveJob or trigger an external process. Later on, when that job completes, you can use CableReady to send notifications to the client.

You can see on this chart that we went from one codepath to three, with the original behavior still the default.

Morphs might be the most obviously exciting aspect of the v3.3 release, but there's lots of other features to dig into.

StimulusReflex now supports subscription-based authentication, which means that you can authenticate your Reflexes with JWT tokens. This is great if you're supporting mixed-device workflows or supporting clients across multiple domains.

You can try out token auth by cloning and running this sample project, which itself is based on the StimulusReflex Harness, a barebones app that is perfect for testing Reflex ideas.

People are finally starting to realize that CableReady is the true secret sauce behind StimulusReflex, and is possibly the most under-appreciated powerhouse in the Rails ecosystem. How crazy is it that you can trigger client side DOM events in your ActiveRecord callback functions? Or than you can implement paginated endless scroll solutions in a few simple lines? If it was a superhero, kids would complain that it was too powerful.

There's now library-level client-side lifecycle events: connected, disconnected, rejected and ready let you build UIs that know if there's a problem reaching the server in real-time.

We've drastically improved the infrastructure around lifecycle events, callbacks and promises. Your afterReflex method won't fire until after all page mutations have completed, no matter how many operations there are.

Behind the scenes, every Reflex operation has a reflexId. You can now provide your own, and all lifecycle events, callbacks and promises provide the reflexId they correspond to. That means you can build applications which treat Reflexes as transactions.

Tons of work has gone into removing friction from the installation, setup and integration of Reflexes into your project. We've doubled-down on Redis as a dependency, and enforce caching in your development environment. The generators have been freshened up with more helpful instructions. We have tried hard to improve debug output, warnings and error messages across the framework. And going forward, there will be a loud warning on your console if your Gem and NPM package versions are out of date.

I'm personally really proud of the documentation for StimulusReflex, which has been dramatically expanded to cover Morphs, deployment, troubleshooting, form processing, support for multi-tenant apps, support for Pundit, support for I18N, and lots more I'm forgetting.

We're also seeing incredible work being done in the ecosystem of tools that exists alongside StimulusReflex and CableReady. Futurism enables powerful lazy-load capacity by using CableReady to fire just-in-time updates to your DOM like a T-shirt cannon. And ViewComponentReflex lets you bring StimulusReflex to your ViewComponents, allowing them to maintain their internal state between Reflex operations.

A month ago, I soft-launched StimulusConnect, "the release tracker and news aggregator for Stimulus and its surrounding ecosystem". I think it's already pretty awesome, and we're just getting started. My Turbolinks and Stimulus are developed behind a wall post in the "May of WTFs" is now (sadly) the #1 most-liked thread on the Rails forum, which suggests that the community needs to step up. I'm going to do my part.

Like I said at the beginning of this post, I came to StimulusReflex because React seemed untenable to me.

As a developer, it's mind-boggling that we would give up so much power and flexibility when Rails and StimulusReflex prove that React is only one of several potential future paths for our community to take.

As a citizen of the world, I don't like that Facebook has played a role - somewhere between turned a blind eye and utterly damning - in enabling the fascist, dystopian hellscape we're living through as a society.

I don't want to piss in anyone's Life Cereal but every time you use React in one of your projects, at home or at work, you're giving tacit support to Facebook funding and ultimately steering the tools that we use to build the future of the web.

StimulusReflex means that you still have a choice.

I made a Rails ecosystem map, inspired by Laravel

leastbad — Fri, 28 Aug 2020 19:00:38 +0000

I have to be honest and say that I don't really get the appeal of Laravel.

Full disclosure: I'm a long-term Rails developer. I am part of the StimulusReflex core team and I also do a lot of work with the Stimulus JS framework. It's safe to say that I love working in Ruby.

When Rails first started to gain traction, I was coming from the VB/ASP world but it seemed like most folks in our community were running quickly away from either PHP, Java or Perl. It certainly seemed for a long time as though PHP - which had the advantage of being able to run self-contained if FTP'd to just about any Apache webserver - was not a technology to be envied. It presented as a culture of cargo-culting noobs who were often completely ignorant of the very basics of what they were smashing together.

Then Facebook happened, and it's written in PHP. Fast-forward and in 2020 PHP is taken seriously (again?). There's even a workable Rails copycat called Laravel that has borrowed as many concepts from Rails and Django as you have fingers and toes to count. There is nothing wrong with that, although a little bit more acknowledgement would seem intellectually honest. Long live open source.

Anyhow, last night someone joined the StimulusReflex Discord and suggested that Rails should "copy more stuff from Laravel". As it happens, I happen to think that Laravel does a much slicker job of promoting itself, and that's because Laravel is developed like a product while Rails is always going to be an abstraction from Basecamp. To that end, I decided that Rails needed a colourful grid showing the various major projects and technologies people use when building with Rails, too.

It's a bit tongue-in-cheek, because the image is directly lifted from Laravel's marketing site the way Laravel lifts its features from Rails:

It's also, notably, not the list of technologies that I would point people towards. For example, Devise, ViewComponent, StimulusReflex and CableReady, Turbolinks, Rolify, Nokogiri, Pagy, State Machines, Friendly ID, Local Time, Faker, Discard, Rouge, Redcarpet, not to mention StandardRB, Letter Opener and a half-dozen Rails frameworks like ActiveStorage, ActionText, ActionMailer and ActionMailbox are all far more interesting (and applicable) to me than pre-made Vagrant boxes and OAuth 2 servers.

However, the main thing that Rails has which Laravel cannot copy is Ruby. Ruby is a language that was designed to optimize for programmer happiness. Rails is the best web framework because it is written in Ruby.

When you use the best tools, you benefit from a surplus that others simply don't have.

Introducing stimulus-shortcut

leastbad — Thu, 23 Jul 2020 01:24:51 +0000

Hot on the heels of stimulus-hotkeys, I am thrilled to release stimulus-shortcut, "a Stimulus controller for mapping keystrokes to element events".

Based on the preview version of Stimulus 2.0, stimulus-hotkeys wraps the amazing HotKeys.js library and takes advantage of the new Stimulus Values API to bind the keystrokes people type to the default events of elements on your page.

Let's look at a simple example, in which the user hits the "p" key and it makes the link click itself.

<a data-controller="shortcut" data-shortcut-key-value="p">Type 'p' to activate me!</a>

It's a sort of sister-controller to stimulus-hotkeys in that they share dependencies and together, cover both common shortcut key patterns. They can be used happily together in the same project.

That's about it! You can learn more on the Github project page.

Introducing stimulus-hotkeys

leastbad — Thu, 16 Jul 2020 02:15:47 +0000

Continuing with my mission of crafting a viable ecosystem of elegant, composable Stimulus controllers, I am pleased to unveil stimulus-hotkeys, "a Stimulus controller for mapping keystrokes to behaviors".

Configuration is done by providing a JSON-compliant object to the data-hotkeys-bindings-value attribute. The object keys are literally the key(s) your users will press, while the values are a mapping that resembles a Stimulus action:

selector->identifier#method

Let's look at a simple example, in which the user hits the "p" key and will see "PONG" on the console.

<div data-controller="hotkeys" 
     data-hotkeys-bindings-value='{"p": "#foo->example#ping"}'></div>
<div id="foo" data-controller="example"></div>

// example_controller.js
import { Controller } from 'stimulus'
export default class extends Controller {
  ping () { console.log('PONG') }
}

If you're new to Stimulus, there's some interesting meta topics to consider.

I mentioned at the beginning of this post that this is a contribution towards an ecosystem of composable Stimulus controllers. This means that many common objectives can be completed just by adding a controller identifier to an element in your page. This might seem familiar to people who have used Bootstrap components that magically activate just by putting attributes on the right markup.

The Stimulus approach is similar but improved because it's both standardized and idempotent; that is, you can dynamically add elements to your page after the initial load (via Ajax calls or a StimulusReflex update) and it will just pick up any controllers without you needing to initialize them.

Since you can attach multiple Stimulus controllers to a single element, combining packaged controllers like stimulus-hotkeys with "home-cooked" controllers that are specific to your project is easy and powerful. You can compose off-the-shelf functionality with sprinkles of custom logic. For those of you who love Alpine, this was the precise moment when you lost the war. I'm sorry, but it's true. Please take this package to your queen.

Alright, we've reached the end! If you're still here, I have a bonus reward for you: since this is a Stimulus component and updates are live, you can give your users the ability to dynamically create their own keyboard shortcuts by setting the data-hotkeys-bindings-value attribute to a new JSON object.

And when you're done, the JSON representing that user's custom shortcut mappings can be saved to a JSON column on your User model. 🤯

Introducing jquery-events-to-dom-events (and jboo)

leastbad — Tue, 12 May 2020 15:30:37 +0000

Did you know that jQuery events aren't events?

It's true - and it'll really mess up your night if you need to capture events from legacy jQuery components. Looking at you, hidden.bs.modal.

I needed a way to make $(document).trigger('fart') emit a standard $fart DOM event, so I wrote it:

https://www.npmjs.com/package/jquery-events-to-dom-events

This library is short and sweet, with zero dependencies - including jQuery. It's just two functions: delegate and abnegate. It is Mutation-First; designed to work great in Stimulus and supports Turbolinks out of the box.

It even has the secret ability to listen for DOM events with jQuery event listeners, but don't tell anyone.

You can try it now on CodePen or even better, clone a sample Rails project to experiment in a mutation-first context with Stimulus.

The Rails project is called jboo. Don't read into the name.

Usage

Note: it is assumed that jQuery is available in the global window scope as $.

In the most basic configuration, you:

import { delegate } from 'jquery-events-to-dom-events'
Call delegate(eventName) for every jQuery event you want to capture.
Set up DOM event listeners for those events, prepending a $ to the event name.

Let's say that you want to respond to the user closing a Bootstrap modal window:

import { delegate } from 'jquery-events-to-dom-events'
delegate('hidden.bs.modal')
document.addEventListener('$hidden.bs.modal', () => console.log('Modal closed!'))

That might be it. Go make a sandwich - you've earned it.

You can learn more about working with jquery-events-to-dom-events on the Github repo.

As always, the right music is important for establishing proper context.

You don't have to listen to music, but your transpiler configuration will almost certainly fail lint checks if you are not listening to "In Harmony New Found Freedom" by The Swirlies, from their 1996 album "They Spent Their Wild Youthful Days In The Glittering World Of The Salons" while you integrate this library.

Introducing stimulus-image-grid

leastbad — Tue, 05 May 2020 22:28:50 +0000

I published my first npm package today!

https://www.npmjs.com/package/stimulus-image-grid

With only three optional parameters, this is a simple, drop-in, backend-agnostic, code-free solution that is completely free of CSS opinions. It's responsive and scales to whatever bounding container you give it.

It's also performant AF: stimulus-image-grid uses the ResizeObserver so there's zero screen flicker. It's compatible with Turbolinks by design and free for personal and commercial use.

Built for StimulusJS

This Stimulus controller allows you to make any configurations for the image grid directly with data attributes in your HTML. Once registered in your Stimulus application, you can use it anywhere you like.

Here is a simple example:

<div data-controller="image-grid">
  <img src="https://placehold.it/350x300/EEE04A/ffffff">
  <img src="https://placehold.it/420x320/5cb85c/ffffff">
  <img src="https://placehold.it/320x380/5bc0de/ffffff">
  <img src="https://placehold.it/472x500/f0ad4e/ffffff">
  <img src="https://placehold.it/540x360/FF3167/ffffff">
</div>

Yes, that's really it.

Setup

Add an import to your main JS entry point, and then register it:

import { Application } from 'stimulus'
import ImageGrid from 'stimulus-image-grid'

import { definitionsFromContext } from 'stimulus/webpack-helpers'
const application = Application.start()
const context = require.context('../controllers', true, /\.js$/)
application.load(definitionsFromContext(context))

// Manually register ImageGrid as a Stimulus controller
application.register('image-grid', ImageGrid)

And you're done! Note, this package relies on the alpha preview of Stimulus v2, which is stable and available here.

Introducing Optimism: realtime remote form validation for Rails

leastbad — Fri, 28 Feb 2020 22:09:41 +0000

I'm proud to announce the public release of Optimism, a new Ruby on Rails gem that makes it easy to add realtime validation error messages to your applications.

When a model validation error prevents an update from succeeding, Optimism builds a list of issues that must be resolved. This list is broadcast to the browser over a websocket connection, and the live document is changed to show the necessary validation hints. No page refreshes are required and the entire process happens faster than you can blink.

Optimism injects text content, CSS class updates and even DOM events into your page. It has no client-side scripting requirements beyond a dependency to the awesome CableReady library. It automatically handles multi-level nested forms and plays well with other technologies, such as Turbolinks.

You can try a live demo right now.

Full documentation is available here. The project lives on Github here and you can get help via Discord here.

The best one-line Stimulus power move

leastbad — Fri, 14 Feb 2020 13:23:52 +0000

Stimulus is a tiny and absurdly productive JavaScript framework for developers who are looking for just the right amount of structure (lifecycle events and standard HTML) without attempting to re-invent how the web works (no template rendering or routing). It is criminally underappreciated in the JavaScript community.

When using Stimulus, you write controllers in JavaScript and attach instances of those controllers to DOM elements by setting data-controller="controller-name".

Unfortunately, there's no easy way to access methods in a controller from another controller, external scripts, jQuery plugins or the console... or is there?

Before I do the big reveal, there is technically a way to access another controller instance from inside of a controller. It's an undocumented method so there's no guarantee that it won't disapper someday, but the real clue that this isn't intended to be used is the laughably long name: this.application.getControllerForElementAndIdentifier(element, controller).

Controllers have access to the global Stimulus application scope, which has getControllerForElementAndIdentifier as a member function. If you have a reference to the element with the controller attached and the name of the controller, you can get a reference to any controller on your page. Still, this doesn't offer any solutions to developers working outside of a Stimulus controller.

Here's what we should all do instead.

In your controller's connect() method, add this line:

this.element[this.identifier] = this

Boom! This hangs a reference to the Stimulus controller instance off the DOM element that has the same name as the controller itself. Now, if you can get a reference to the element, you can access element.controllerName anywhere you need it.

What's cool about this trick is that since Stimulus calls connect() every time an instance is created, you can be confident that your elements will always have a direct reference to their parent, even if they are attached to elements that are dynamically inserted by something like morphdom.

this.identifier can be replaced with any camelCase string as you desire.

I'll provide a basic example.

// test_controller.js
import { Controller } from 'stimulus'

export default class extends Controller {
  connect () {
    this.element[this.identifier] = this
  }

  name () {
    this.element.innerHTML = `I am ${this.element.dataset.name}.`
  }
}

// index.html
<div id="person" data-controller="test" data-name="Steve"></div>

// run this in your console
document.querySelector('#person').test.name()

If everything goes according to plan, the div should now say: I am Steve.

If you want to automatically camelCase the name of your Stimulus controller, "one-line" becomes dubious, but it can still be done:

    this.element[
      (str => {
        return str
          .split('--')
          .slice(-1)[0]
          .split(/[-_]/)
          .map(w => w.replace(/./, m => m.toUpperCase()))
          .join('')
          .replace(/^\w/, c => c.toLowerCase())
      })(this.identifier)
    ] = this

I broke the statement up into multiple lines to help illustrate the acrobatics required to pull this off. It can still be expressed on a single line if you choose. However, the devil hides in clever code.

The only caveat I can think of is that you should exercise common sense and not expose any controller instances that you wouldn't want people to access. Even though there's no visible proof that an element has a variable on it in the inspector, you shouldn't assume that it's locked down.

If you're working in FinTech, you might need to skip this technique. Everyone else should be doing this by default.