mikewilson.dev

Client Side Form Validation With Stimulus and Rails

Mon, 27 May 2019 00:00:00 GMT

One of the things I miss the most when working on a non-framework application, such as Angular or Ember, is how easy it is to do form validation. With Angular, you have an in-memory version of your form, and can easily run some Javascript for doing validation.

There are times when you really don’t want or need a full-blown Javascript app, which is where a tool such as Stimulus and server-generated HTML becomes extremely useful.

Fortunately, browsers have a lot of built-in validations that we can use.

I know what you’re probably thinking - the native form validations UI is super ugly and extremely difficult to style. I agree! Fortunately, with a sprinkling of Stimulus, we can hook into the functionality that browsers provide, while doing all of the styling ourself.

Be sure to always validate on the server, even if you’re implementing client-side validation

Setting up our Form

We’ll start with a very basic form in any generic Rails application. For this simple example, we’ll scaffold a post that has a title and a slug, both of which will be required fields.

rails generate scaffold Post title:sting slug:string

Let’s take a look at the form that Rails creates for us, and change a few things to add some validation.

<%= form_with(model: post, local: true) do |form| %>
  <div class="field">
    <%= form.label :title %>
    <%= form.text_field :title %>
  </div>

  <div class="field">
    <%= form.label :slug %>
    <%= form.text_field :slug %>
  </div>

  <div class="actions">
    <%= form.submit %>
  </div>
<% end %>

The first thing we’ll want to do is change our form to be a remote form, by removing local: true. This will allow RailsUJS to handle our form submissions for us.

Next, we’ll want to mark our title as a required field. This tells the browser that this form is required, but our form won’t actually enforce it just yet.

<%= form.text_field :title, required: true %>

If we load the page and try and submit, we’ll get some pretty nasty looking validation errors.

To remove the ugly validation, add the novalidate: true html attribute to our form. This will turn off any form validation for now, but in the next section we’ll see how we can hook into that functionality with some Javascript and CSS to provide a better user experience.

Here is what our form should look like now:

<%= form_with(model: post, html: { novalidate: true }) do |form| %>
  <div class="field">
    <%= form.label :title %>
    <%= form.text_field :title, required: true %>
  </div>

  <div class="field">
    <%= form.label :slug %>
    <%= form.text_field :slug %>
  </div>

  <div class="actions">
    <%= form.submit %>
  </div>
<% end %>

Add a sprinkling of Stimulus

For the purposes of this article, we won’t go into how to install Stimulus in the rails application. We’ll assume that’s already been done.

Now, we’ll want to create a Stimulus form_controller that we’ll use to hook into the form submit action and manually validate our fields.

import { Controller } from "stimulus";

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

  submitForm(event) {
    console.log("form submitted");
  }
}

So far, this is a pretty basic form. We’ve setup a target which will be the form element itself, and created a placeholder action for when the form is submitted.

Let’s go back and modify our form to use this new controller and setup our actions:

<%= form_with(model: post,
              html: {
                  novalidate: true
              },
              data: {
                  controller: "form",
                  target: "form.form",
                  action: "ajax:beforeSend->form#submitForm"
              }) do |form| %>
  <div class="field">
    <%= form.label :title %>
    <%= form.text_field :title, required: true %>
  </div>

  <div class="field">
    <%= form.label :slug %>
    <%= form.text_field :slug %>
  </div>

  <div class="actions">
    <%= form.submit %>
  </div>
<% end %>

What we’ve done is modified our form to add some data attributes. data-controller specifies the name of our newly created Stimulus controller, while data-target tells Stimulus which element is our form. Finally, we use data-action: "ajax:beforeSend->form#submitForm" to tell Stimulus to hook into the Rails UJS event that gets fired.

If we submit our form now, it still goes through without validation, but we should at least see our console.log statement. Now we know we can hook into a form submit, and run whatever code we need to run. Let’s flesh out our submitForm method a bit more now.

Validating the form with Javascript

Fortunately, even though we’ve turned off form validation using novalidate: true in our form, we can still hook into the attributes that the browser applies to the form for us, such as :required or later on, :invalid.

What we want to do is to search our form for any input elements that are required, and check to see if they have any content. Let’s see what that looks like:

import { Controller } from "stimulus";

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

  submitForm(event) {
    let isValid = this.validateForm(this.formTarget);

    // If our form is invalid, prevent default on the event
    // so that the form is not submitted
    if (!isValid) {
      event.preventDefault();
    }
  }

  validateForm() {
    let isValid = true;

    // Tell the browser to find any required fields
    let requiredFieldSelectors = "textarea:required, input:required";
    let requiredFields = this.formTarget.querySelectorAll(
      requiredFieldSelectors,
    );

    requiredFields.forEach((field) => {
      // For each required field, check to see if the value is empty
      // if so, we focus the field and set our value to false
      if (!field.disabled && !field.value.trim()) {
        field.focus();

        isValid = false;
      }
    });

    return isValid;
  }
}

What we’re doing is looking up any required fields and manually checking the value, to see if they have any values. If any required field is empty, then we return isValid as false. In order to tell the Rails UJS library not to submit the form, all we have to do is preventDefault on the event, and the form submission will be cancelled, and the required field will be focused.

Other validation types

Another feature that browsers have these days is pattern validation. We can tell the browser what the required pattern is on an input field, and if the input doesn’t match, we can hook into that validation.

Let’s create an arbitrary example, and say that our post slugs must be required and be alphanumeric.

Here is what our input field for our slug would look like:

<%= form.text_field :slug, required: true, pattern: "[a-zA-Z0-9]+" %>

If we submit now with a valid title and an empty slug, the form submission will still go through. We need to modify our validateForm method to now look for :invalid elements.

  validateForm() {
    let isValid = true;

    let requiredFieldSelectors = 'textarea:required, input:required';
    let requiredFields = this.formTarget.querySelectorAll(requiredFieldSelectors);

    requiredFields.forEach((field) => {
      if (!field.disabled && !field.value.trim()) {
        field.focus();

        isValid = false;

        return false;
      }
    });

    // If we already know we're invalid, just return false
    if (!isValid) {
      return false;
    }

    // Search for any browser invalidated input fields and focus them
    let invalidFields = this.formTarget.querySelectorAll('input:invalid');

    invalidFields.forEach((field) => {
      if (!field.disabled) {
        field.focus();

        isValid = false;
      }
    });

    return isValid;
  }

Just like before, we query the elements in the form for invalid input fields. This time, we don’t need to do any manual validation ourself, as the browser does that for us. When a browser has an invalid field, it adds the :invalid attribute to it, and we can use that for querying and styling. All we have to do is find those elements, focus them and set our isValid property if we find any.

Now, if we try and submit a post with an invalid slug, the submission will be prevented, and the slug field will be focused. Not bad for only a few lines of Javascript!

Wrapping up

As you can see, it’s fairly easy to add some basic form validation using Stimulus. With this technique, there is plenty more we can do, such as adding custom data-attributes for other custom validations, and styling the fields when they are invalid using the input:invalid CSS selector.

It’s worth keeping in mind that although it might seem easy enough to just add validation on the front end, you should always make sure to add the proper model validations on the server.

To see an example, a bare-bones repository used in this example is available on Github at mike1o1/stimulus-validation.

Dynamic Dialogs with Hotwire and Minimal Javascript

Wed, 04 Aug 2021 00:00:00 GMT

Dialogs are a staple of almost every modern web application. No matter how hard I try when designing an application, there always seem to be scenarios where a dialog is the best option.

Fortunately, there are some newer techniques that we can employ to make modal dialogs less of a headache, and we can combine Hotwire, some minimal Javascript and some clever CSS to make some good looking dialogs. If we’re being extra ambitious, we can even use View Components to make our markup less daunting.

Styling

To get us started, we’ll create some very bare-bones modal dialogs using nothing but CSS. We can get pretty far just relying on base browser behavior and some clever CSS and pseudo-elements.

Summary/Details Element

The main tool we’ll be relying on is the Details element, and the summary element underneath. This is an element that can give us a native expandable content, which we can use CSS to style into a modal dialog.

The markup to create a detail/summary element will look like the below:

<details class="modal-details">
  <summary>Click me</summary>
  <div class="modal">Modal content.</div>
</details>

Without any styling, we’ll get a basic expandable element:

Add Some Style

We can add some styling using CSS to help things look not as ugly. The first thing we’ll want to do take our actual modal and position it on the screen. There are many different approaches, but we’ll keep things simple for now and have the modal be in a fixed position towards the top of the page.

.modal-details {
  // We'll just create a single modal for now, but we can optionally create different
  // size or positioned modals as well
  .modal {
    background-color: #ffffff;
    display: flex;
    flex-direction: column;
    width: 448px;
    position: fixed;
    margin: 10vh auto;
    top: 0;
    left: 50%;
    transform: translateX(-50%);
    z-index: 999;
    max-height: 80vh;
    max-width: 90vw;
  }
}

If we were to take a look at the above snippet, things start to look a little bit better. We’re getting there!

Adding A Backdrop

When displaying a modal, it’s good to have some kind of backdrop to help the content standout a bit. Fortunately, we can implement this using pure css. According to the documentation we can use the open attribute to know when the content is expanded or not. We can use this as a selector to add a pseudo-element to the summary element. Let’s see what that would look like:

.modal-details {
  &[open] {
    summary {
      cursor: default;

      &:before {
        content: "";
        display: block;
        width: 100vw;
        height: 100vh;
        background: black;
        position: fixed;
        top: 0;
        left: 0;
        opacity: 0.5;
        z-index: 99;
      }
    }
  }
}

What we’re doing is taking our modal-details element, and adding a :before element to the summary element, but only when the open attribute is present. The open attribute is handled by the browser when the user clicks on the summary element, so that part is handled for us.

Let’s see what that looks like in practice.

Wow - that’s actually not bad at all, considering we haven’t even written any Javascript yet. Since our backdrop is added to the summary element, we get the added benefit of having the modal automatically close when user clicks on the backdrop, as it’s the same as toggling the summary element - nice!

A Sprinkling of Stimulus

In this section, we’ll add a little bit more functionality to our modal dialogs, such as loading turbo frames and adding some nice touches such as closing the modal if the user hits escape.

Let’s start with hitting escape to close the dialog. I’ll assume you’re familiar with Stimulus, but if not head over to their docs to get familiar.

First, we’ll want to create our controller. I use Typescript for all of my Stimulus controllers, so that’s what I’ll use in the snippets below, but it should be pretty easy to translate it to normal Javascript.

import { Controller } from "stimulus";

export default class extends Controller {
  // Helper method since I don't want to have to cast this every time
  // But this is necessary in Typescript in order for `open` to be a valid property
  get detailElement() {
    return this.element as HTMLDetailsElement;
  }

  disconnect() {
    this.close();
  }

  public toggleDialog() {
    if (this.detailElement.open) {
      this.open();
    } else {
      this.close();
    }
  }

  public open() {
    this.detailElement.open = true;
  }

  public close() {
    this.detailElement.open = false;
  }

  public closeOnEscape(event: KeyboardEvent) {
    if (event.key === "Escape") {
      event.stopPropagation();
      this.close();
    }
  }
}

In short, we’re adding a few public methods, for toggling the dialog, which can be helpful if we wanted to close or hide the dialog programmatically outside of the summary element, and we’re also adding a quick helper to close on escape.

Let’s take the next step and actually wire-up our markup.

<details
  class="modal-details"
  data-controller="modal"
  data-action="toggle->modal#toggleDialog keydown->modal#closeOnEscape"
>
  <summary>Click me!</summary>
  <div class="modal">
    Modal content.

    <button type="button" data-action="modal#close">Close me</button>
  </div>
</details>

We’ve added an action on the toggle event provided by the details element. It doesn’t really do much yet, as the browser already sets the open state for us, but we’ll take advantage of that in the next section. You might notice we also added a basic close button, which triggers the #close action on the controller. This would allow us to add some styling to get a nice “x” in the corner or an “Ok” button or something.

We also trigger the #closeOnEscape action, which simply inspects the event, looks at the key, and closes if the user hit escape. Aside from accessibility nice-to-haves, this is a pretty complete solution for handling modal dialogs, with very, very little lines of Javascript.

In part two, we’ll go over how to incorporate Turbo Frames to load content dynamically, and then use a View Component to make the markup a little bit more reusable.

Ember CLI - Easily toggle between mocks and live server

Mon, 02 Feb 2015 00:00:00 GMT

One of the great things about Ember is how productive I feel, and how it allows me to focus solely on the front end. Ember CLI makes this even faster, as it makes it super easy to create http-mocks of the backend, which allows me to continue working on the front-end while the Web API portion of the application is still being developed or finalized. If the same team member is working on both, sometimes an approach of starting with the UI also helps vet out the requirements for the Web API as well.

However, I was recently looking for an easy way to toggle between using my mocks and using a live development server to validate everything. In addition, I sometimes work completely offline and want to solely rely on my http mocks. Fortunately, with some tweaks to the generated code from Ember CLI, this was very easy to do.

Creating an http-mock with Ember CLI is very easy to do. All it takes is a call to

$ ember generate http-mock user

This will create a few things the first time it’s run. The first, is it creates a server folder under your application, an index.js file under the server folder which sets up the server, as well as a file for the mock API you wish to stub out.

However, one of the problems with the Ember CLI generated code is that out of the box, it wires up both http-proxy’s as well as http-mocks.

module.exports = function (app) {
  var globSync = require("glob").sync;
  var mocks = globSync("./mocks/**/*.js", { cwd: __dirname }).map(require);
  var proxies = globSync("./proxies/**/*.js", { cwd: __dirname }).map(require);

  // Log proxy requests
  var morgan = require("morgan");
  app.use(morgan("dev"));

  mocks.forEach(function (route) {
    route(app);
  });
  proxies.forEach(function (route) {
    route(app);
  });
};

This can be problematic if you want to use alternate back and forth between a mock and your dev server, or if you want to exclusively use mocks (for example if you don’t have access to your dev server), or exclusively use your proxy without blowing away your mocks.

Diving into the source

An easy, but hidden, way of doing this is to modify the generated and get access to the options which are passed in from the ember server command.

If you dive into the ember-cli source, specifically into express-server.js, you’ll see that the processAppMiddlewares function is where the server is being initiated, and that two properties are passed in: app and options. The options object is what contains a reference to the environment the server is started with.

processAppMiddlewares: function(options) {
    if (this.project.has(this.serverRoot)) {
        var server = this.project.require(this.serverRoot);

        if (typeof server !== 'function') {
            throw new TypeError('ember-cli expected ./server/index.js to be the entry for your mock or proxy server');
        }

        server(this.app, options);
    }
}

When the ember server commandline task is called, you can pass in any type of arguments you want for the environment, and now you can access that environment on the options.environment within your server/index.js method! This allows you to easily toggle back and forth between using mocks or proxies. This can also be really helpful if you want to do development against a live server, but only hit a mock when running ember test.

See the example below, where if I want to use mocks when environment=offline, otherwise use a proxy to my dev server.

All I then have to do is call ember server --environment=offline and I can use my mocks.

module.exports = function (app, options) {
  var globSync = require("glob").sync;
  var mocks, proxies;

  if (options.environment === "offline") {
    mocks = globSync("./mocks/**/*.js", {
      cwd: __dirname,
    }).map(require);
  } else {
    proxies = globSync("./proxies/**/*.js", {
      cwd: __dirname,
    }).map(require);
  }

  // Log proxy requests
  var morgan = require("morgan");
  app.use(morgan("dev"));

  if (mocks) {
    mocks.forEach(function (route) {
      route(app);
    });
  }

  if (proxies) {
    proxies.forEach(function (route) {
      route(app);
    });
  }
};

Hopefully this helps those of you who might do development against a server not running on your machine, but still want offline access, or simply want a way to easily toggle between your mocks and a live server.

Preventing Minitest Focus During CI

Fri, 26 Apr 2019 00:00:00 GMT

I really love using Minitest along with Minitest Focus during the development process with Rails.

All it takes is adding focus before a test (or multiple tests), and running rails test will only run those tests. This makes it very handy when working through a specific issue and continually running only those selected tests.

require "test_helper"

class MyControllerTest < ActionDispatch::IntegrationTest

    focus
    test "should render index page" do
        # Test goes here.
        # Only this test will run
    end

    test "should render show page" do
        # Test goes here.
        # This will get skipped
    end
end

The way minitest-focus works is that it basically changes the arguments passed to minitest to only include tests defined after the focus statement. Very helpful!

However, one issue that I’ve run across during development of Kwikcal is accidentally leaving a focus statement in a PR. It’s a small line, so easy to miss during code reviews. When this happens, your CI integration might give a false positive as your CI might only execute the focused tests!

Aside from catching this during a code review, a simple way to prevent accidentally leaving focus statements in a pull request is to patch the method to throw an exception while in a CI environment.

To do this, I created a file named prevent_focus_in_ci.rb and placed it in my test/support folder, as these files are automatically loaded in my test helper.

if ENV["CI"] # Or "CIRCLECI"
    class Minitest::Test
        def self.focus
            raise StandardError.new("FOCUS CALLED IN ERROR: #{self.name}")
        end
    end
end

With this little snippet you’ll get notified through a failing test suite if this method is ever left over in any of your test files. The raised error will let you know the test file it was added to.

Below is example output from Circle CI

1: from /home/circleci/project/test/models/example_test.rb:61:in `<class:ExampleTest>'
/home/circleci/project/test/support/prevent_focus_in_ci.rb:8:in `focus': FOCUS ADDED IN ERROR: [ExampleTest] (StandardError)

Very handy for making sure your entire test suite runs on CI, while still being able to use the very helpful focus method during development.

Rails Vanity URL's With Route Constraints

Sat, 27 Apr 2019 00:00:00 GMT

A vanity URL is a great way to get a cleaner URL for your users, and is also a great way to improve SEO. Providing vanity URL’s to your users if they have a public facing page is also a great feature to add to give your users more personalization.

An example of a vanity URL would be linking to a username, instead of a user ID to see a users posts:

https://www.example.com/users/2348 - This is an example of a non-vanity URL https://www.example.com/users/john-smith - This is a vanity URL and looks much friendlier

There are plenty of articles on how to add vanity URL’s, or slugs, with Rails, with the easiest method to be using a gem like friendly_id.

What happens when you want to make the URL be on your root page, while still having a catch-all route, or use a gem such as high_voltage? It’s still doable, if not a little tricky.

Setting up the initial route

The first thing you’ll want to do is add a route in your routes.rb to specify the resource, and provide a root level path. This will tell rails that anything to your root level route should try and load the user resource.

    # Place at the end of your routes.rb file
    resources :users, path: ""

This should setup a URL, such as example.com/john-smith, where john-smith is the id passed to the route. Now, whenever somebody visits example.com/john-smith, it will hit your UsersController where you use a friendly finder method to find the user details.

What if we have a catch-all route setup further down our routing file to provide better error pages, or we use a gem such as high_voltage for our static page routing?

Unfortunately, the users route will kick in first and we’ll never be able to navigate to our static pages or other catch-all routes. This is where Route Constraints come in.

Route Constraints

Routing constraints can be a very powerful tool to give you flexibility over your routes. A route constraint is an object that responds to matches? and tells Rails whether the route matched or not.

We can use a Route Constraint on our users route, so that if the :id from the route doesn’t match a username in our system, we return false and Rails moves on to the next route.

Let’s see it in action:

module Constraints
    class UsernameRouteConstrainer
        def matches?(request)
            # Get our username from the route params
            username = request.params[:id]

            # Check if this name exists for any users
            User.where(slug: username).any?
        end
    end
end

This is a pretty straight forward class. We pull the username out of the request parameters, and then look to see if the user exists in the system.

Now we’ll want to modify our routing configuration to tell routes to use this new route constraint:

constraints(Constraints::UsernameRouteConstrainer.new) do
    # Same route as before, only within the constraints block
    resources :users, path: ""
end

Note: You might need to restart spring to pick up files in the new constraints folder.

Now anytime we try and load our page, such as example.com/john-smith, we’ll see Rails make a request to see if john-smith is a valid slug in our Users table.

Performance Improvements

There are a few things that we can do to make our route constrainer even better. If we are using high_voltage for our static pages, we might notice that Rails makes a User lookup each time, even if we are loading a static page. This happens because Rails checks our route, sees that it fails, and then the high_voltage Engine or catch-all route is then triggered.

Can we try and tell our route constrainer to automatically fail if we’re loading a known static page? Yes we can!

The high_voltage gem provides some handy tools, one of which is a list of all of the known static pages that high_voltage is going to manage. This is available in the HighVoltage::page_ids method, which returns an array of pages.

All we have to do in our route constrainer is add a check to see if that /:id param exists in those page ids, and fail if it does. This helps, as Rails will no longer do a needless database lookup, that we know will fail.

Here is what that method might look like:

def is_static_page?(param_id)
    HighVoltage::page_ids.include?(param_id)
end

This method will check the param and see if it is a high_voltage page id. Let’s see what the full route constraint looks like now:

module Constraints
    class UsernameRouteConstrainer
        def matches?(request)
            # Get our username from the route params
            username = request.params[:id]

            return false if param_id.blank?

            return false if is_static_page?(username)

            # Check if this name exists for any users
            User.where(slug: username).any?
        end

        private

            def is_static_page?(param_id)
                HighVoltage::page_ids.include?(param_id)
            end
    end
end

Much better. Now we get the benefits of root level vanity URL’s for our users, as well as the ease and flexibility of other catch-all routes further down the routing table. We’ve also added a few short-circuits to our route constraint, to improve performance and remove any unnecessary database look ups.

Example

For full code for this example, see the following repository on GitHub:

mike1o1/route-constraints-example

Redirecting to static webpacker Content With Rails

Wed, 22 May 2019 00:00:00 GMT

With the release of Rails 6, webpacker will be the new default compilation pipeline for Javascript assets. This is a great thing once you wrap your head around how to use webpack and webpacker.

One of the benefits of webpacker, is like sprockets, the automatic compilation and fingerprinting of assets for production builds. Fingerprinting is very handy as it will automatically break any browser caches when new versions of that asset are compiled.

What if you have a Javascript snippet that you want others to use dynamically, such as a widget or html snippet? The fingerprinting of assets then makes it very difficult, as the filename will keep changing over and over again.

Fortunately with a combination of a Rails route and diving into the webpacker gem, this can be accomplished fairly easily using redirects.

Rails Routing

Let’s say you have a Javascript widget that you want your customers to embed on their site. You want something easy to remember, such as https://www.example.com/external/widget.js.

Let’s first setup our routes:

get :widget, to: "widgets#show", path: "external/widget"

Our controller needs to then respond to the request, find the webpacker asset, and then respond with a redirect to the fingerprinted asset. Let’s look at the code:

class WidgetsController < ApplicationController
    include ActionView::Helpers::AssetUrlHelper
    include Webpacker::Helper

    protect_from_forgery except: :show

    def show
        respond_to do |format|
            format.js { redirect_to widget_javascript_source }
        end
    end

    private

        def widget_javascript_source
            asset_pack_url("widget.js")
        end

end

Most of this is fairly straight forward. The first thing we want to do is tell Rails not to worry about protecting from anti-forgery requests. Since this will be used from external applications, it’s not something we’re worried about.

The real magic comes in our widget_javascript_source method, which refers to the asset_pack_url that is included in the Webpacker::Helper module.

What does webpacker actually do?

To figure out what asset_pack_url does, it’s good to know what webpacker actually does for us behind the scenes.

The webpacker gem is a wrapper around webpack, and hides away a lot of the complexity of webpack. For our use case, the most important thing is compiling our assets. Instead of using sprockets, we can now rely on webpack to do all of our assets, and with that, we can hook into the broader webpack ecosystem. Part of that includes asset compilation if we’re using Typescript, asset transpiling using a tool such as babel, and minification and fingerprinting to optimize the assets we are serving.

One thing that webpacker does for us when it compiles all of these assets for us is it creates a manifest.json file with a list of entrypoints and a mapping of the compiled asset name. This is what the new javascript_pack_tag ends up doing for us. We pass in the friendly name, and it uses that manifest file to find the fingerprinted asset name.

If we look at the manifest.json file in the public/packs folder, we’ll see an example

{
  "application.js": "/packs/application-feff836d0a539cc07796.js",
  "application.js.map": "/packs/application-feff836d0a539cc07796.js.map",
  "widget.js": "/packs/widget-feff836d0a539cc07796.js",
  "widget.js.map": "/packs/widget-feff836d0a539cc07796.js.map",
  "entrypoints": {
    "application": {
      "js": ["/packs/application-feff836d0a539cc07796.js"],
      "js.map": ["/packs/application-feff836d0a539cc07796.js.map"]
    },
    "widget": {
      "js": ["/packs/widget-feff836d0a539cc07796.js"],
      "js.map": ["/packs/widget-feff836d0a539cc07796.js.map"]
    }
  }
}

What webpacker is doing is reading the content of our manifest file, looking up the friendly name of our asset (widget.js), and then returns to us the properly compiled, minified and fingerprinted asset.

So, all we need to ask webpacker for us the name of our compiled widget.js and then redirect from there!

After looking through some of the internals of webpacker gem, we can see just how easy it is to hook into the compiled assets from our Rails controllers. This allows us to continue to modify and enhance our external widget.js file, and even work on it in a language such as Typescript, while still providing a single, easy to use snippet for others to embed in their own websites.

Supporting refresh tokens with Ash Authentication

Tue, 18 Mar 2025 00:00:00 GMT

Recently, I’ve been working a lot with Elixir and have migrated a recent side project to use the Ash Framework, which gives fantastic support for modeling your domain and deriving everything you need from it. Ash Framework provides support for Authentication via Ash Authentication.

Ash Authentication is a pretty modular framework and comes with various strategies, such as magic link or password authentication. For the project I’m working on, I’m powering the backend of a mobile-first application, and I wanted to use password authentication. I won’t go through the whole setup here, as the docs cover it much better than I can, but eventually you’ll end up with a user resource that looks something like this:

defmodule MyApp.Accounts.User do
  use Ash.Resource,
    otp_app: :my_app,
    domain: MyApp.Accounts,
    extensions: [AshAuthentication],
    data_layer: AshPostgres.DataLayer


  authentication do
    tokens do
      enabled? true

      # ...
    end

    strategies do
      password :password do
        identity_field :email

        # ...
      end
    end
  end

  actions do
    read :sign_in_with_password do
      # ...

      argument :email, :ci_string, allow_nil?: false
      argument :password, :string, allow_nil?: false, sensitive?: true

      prepare AshAuthentication.Strategy.Password.SignInPreparation

      metadata :token, :string, allow_nil?: false
    end

    create :register_with_password do
      # ...
    end
  end
end

There is a lot more setup, but this is the gist of what we’ll be working on. With this setup, we get great support for password-based authentication out of the box. For a GraphQL endpoint, this gives us token-based authentication that we can use to authenticate access to the API’s. Each time a request is made to the sign_in_with_password action, a Token is generated and returned with the response.

If we were to set up GraphQL (using Ash GraphQL), then we’d login with a query like this:

query LoginWithPassword {
  signInWithPassword(email: "test@example.com", password: "password") {
    token
  }
}

In our response, we’d get an access token. We can then add it to any outgoing request by setting the Authorization header with the value of Bearer #{token}. Our plug would decode and verify the token, ensure it’s not expired, parse out the user and confirm access.

This works great on the web, but it’s not the best experience on mobile as the token only lasts for 14 days, meaning the user would have to reauthenticate themself after the token expires. It’s much more common to use Access and Refresh Tokens in mobile apps. In short, after authenticating, we would return a short-lived access token, similar to what we do today, but also a refresh token that the client can exchange for another access token. In this post, we’ll explore a way to do that with Ash, while still keeping a lot of the really nice benefits that we get from Ash Authentication, such as the ability to store and revoke tokens.

Additional Actions

To implement refresh tokens, we need to augment the existing :sign_in_with_password action to generate a refresh token, and we will also need to add a new action to exchange the refresh token for a new access token.

The lifecycle will be:

To get started, we’ll take the first step of generating the access token when signing in with a password.

Generating Access Tokens

Fortunately, Ash Authentication password strategy already does a lot of the hard work for us by validating the user and password in a preparation, named AshAuthentication.Strategy.Password.SignInPreparation. This preparation does two jobs, before and after the query executes. The after-job is where the password is verified and the initial access token is generated. Fortunately, there’s nothing we need to do here!

However, if we want to generate an access token, we’ll want to do our own preparation, which we’ll name GenerateRefreshToken. We’ll want to take a similar approach to the built-in preparation, which is to add an after_action hook to generate a refresh token. Tokens in Ash can be generated by supplying a user, a map of additional claims and an optional set of options (such as expiration time).

AshAuthentication.Jwt.token_for_user(user, %{"extra_claim" => "hooray"}, options)

# Returns
{:ok, token, claims}

So, let’s get started by writing our own preparation.

defmodule MyApp.Accounts.User.Preparations.GenerateRefreshToken do
  require Ash.Query

  alias Ash.{Query, Resource}

  def prepare(query, options, context) do
    query
    |> Query.after_action(&generate_refresh_token(&1, &2, context))
  end

  defp generate_refresh_token(query, [user], context) do
    {:ok, [user]}
  end

  defp generate_refresh_token(_query, result, _context) do
    {:ok, result}
  end
end

We can then use this preparation in our action by adding it after the SignInPreparation action. New installs of Ash (and the default in Ash 4.0) will execute after_action hooks in the order that they’re declared. To ensure you get that behavior, you’ll want to make sure you’re on Ash 3.4.69 or higher and have config :ash, :read_action_after_action_hooks_in_order?, true set in your configuration. Otherwise, if you’re on an older version of Ash 3.0, you’ll want to make sure your new preparation is declared before the SignInPreparation block.

So, our action should now look something like:

read :sign_in_with_password do
  get? true

  argument :email, :ci_string, allow_nil?: false
  argument :password, :string, allow_nil?: false

  prepare AshAuthentication.Strategy.Password.SignInPreparation
  prepare MyApp.Accounts.User.Preparations.GenerateRefreshToken

  metadata :token, :string, allow_nil?: false
end

The reason we want our after_action hook to execute after the built-in one, is we want to see if there is an access token already generated for the user and placed on that users metadata. If there is, we know that authentication was successful.

Let’s see that in action. Let’s go back to our preparation, specifically our first pattern match:

# The second argument might look a bit weird, but it's because Ash queries always
# return lists, even if we're only expecting one user. So, we pattern match on that
# and extract the user
defp generate_refresh_token(query, [user], context) do
  # Get the token
  token = Ash.Resource.get_metadata(user, :token)

  # If token is not nil, then we know that Ash Authentication
  # generated an access token for us. Thanks!

  case token do
    token when not is_nil(token) ->
      # Generate refresh token and add to user metadata
      {:ok, refresh_token, _claims} = generate_token(user, context)

      user = user |> Ash.Resource.put_metadata(:refresh_token, refresh_token)

      # Return a list of users, as that is what Ash.Query is expecting
      {:ok, [user]}

    other ->
      # No token was generated, we should return an error
      {:error, "Unable to retrieve token"}
  end
end

defp generate_token(user, context) do
  opts = Ash.Context.to_opts(context) |> Keyword.put(:token_lifetime, {30, :days})

  AshAuthentication.Jwt.token_for_user(user, %{"purpose" => "refresh_token"}, opts)
end

Note here that we’re adding some metadata to the user resource. In order to actually read that in our action, we need to add it as a metadata field on the action itself. Let’s modify our action to add the new refresh_token field.

read :sign_in_with_password do
  # Existing code...

  metadata :token, :string, allow_nil?: false

  # Add the refresh token
  metadata :refresh_token, :string, allow_nil?: false
end

We’ll also want to modify our tokens block to update the token lifetime.

authentication do
  ...

  tokens do
    # existing config

    token_lifetime {1, :hours}
  end
end

With this change, our GraphQL schema should update to add the new refresh token to our query:

query LoginWithPassword {
  signInWithPassword(email: "test@example.com", password: "password") {
    token
    refreshToken
  }
}

If we were to execute this query now, we should see both tokens in our response. Nice!

{
  "data": {
    "signInWithPassword": {
      "refreshToken": "eyJhb...StGg",
      "token": "eyJhb...FwKM"
    }
  }
}

This is excellent! If we were to take a look at our tokens in iex, we’ll see two tokens for the same user, with different purposes and expiration times. Nice!

iex(1)> AshAuthentication.Jwt.peek("myRefreshToken")
{:ok, %{
  ...,
  "exp" => 1744927645,
  "purpose" => "refresh_token",
  "sub" => "user?id=myId"
}}

iex(2)> AshAuthentication.Jwt.peek("myAccessToken")
{:ok, %{
  ...,
  "exp" => 1742339245,
  "purpose" => "user",
  "sub" => "user?id=myId"
}}

We can see now that we’re getting two tokens back, one a long-lived refresh token of 30 days and the other a short-lived access token of 1 hour. All that’s left now is to support exchanging the refresh token for a new access token. To do that, we’ll want to add a new action to our user resource:

actions do
  # existing actions

  read :exchange_refresh_token do
    get? true

    argument :refresh_token, :string, allow_nil?: false, sensitive?: true

    metadata :token, :string, allow_nil?: false
    metadata :refresh_token, :string, allow_nil?: false

    prepare set_context(%{strategy_name: :password})

    prepare MyApp.Accounts.User.Preparations.ExchangeRefreshToken
  end
end

Here we’re defining a new action, which takes a single refresh_token argument, and we’re returning two additional pieces of metadata - a new access token, and a new refresh token. Since our initial refresh token was only valid for 30 days, it’s important that each time a new refresh token is requested to be exchanged, we need to not only return a new (short-lived) access token, but also an updated refresh token. This gives us a built-in sliding 30 day expiration, so as long as the user is active within those 30 days, they won’t need to reauthenticate with their username and password.

Now, let’s define this preparation. This preparation will be a bit more involved as we can’t rely on anything Ash did for us already, so let’s dive in. With this preparation we’ll want to do three things:

Verify the token
Revoke the old refresh token
Generate new access and refresh tokens

defmodule MyApp.Accounts.User.Preparations.ExchangeRefreshToken do
  use Ash.Resource.Preparation

  require Ash.Query

  alias Ash.{Query, Resource}
  alias AshAuthentication.{Info, Jwt, TokenResource}

  def prepare(query, options, context) do
    # Get details about this auth strategy. We'll need this for revoking the tokens
    {:ok, strategy} = Info.find_strategy(query, context, options)

    query
    |> Query.before_action(&verify_token(&1, strategy, context))
    |> Query.after_action(&revoke_refresh_token(&1, &2, strategy, context))
    |> Query.after_action(&generate_new_tokens(&1, &2, strategy, context))
  end

  defp verify_token(query, strategy, context) do
    token = Query.get_argument(query, :refresh_token)

    with {:ok, claims, _} <- Jwt.verify(token, strategy.resource, Ash.Context.to_opts(context)),
         :ok <- verify_token_purpose(claims),
         {:ok, primary_keys} <- primary_keys_from_subject(claims, strategy.resource) do

      # What we've done is verified the token, verified the token purpose and extracted
      # the id of the user. We'll now update Ash to query off of this
      query
      |> Query.filter(^primary_keys)

    else
      {:error, reason} ->
        Query.add_error(query, [:refresh_token], reason)
    end
  end

  # Do pattern matching to ensure that _only_ refresh tokens are accepted
  defp verify_token_purpose(%{"purpose" => "refresh_token"}), do: :ok
  defp verify_token_purpose(_), do: {:error, "The token purpose is not valid"}

  # Our Jwt provides a claim such as `user?id=myId` so let's parse that to
  # get the primary key for the user owning this token
  # This is taken from the existing AshAuthentication library
  defp primary_keys_from_subject(%{"sub" => sub}, resource) do
    primary_key_fields =
      resource
      |> Resource.Info.primary_key()
      |> Enum.map(&to_string/1)
      |> MapSet.new()

    key_parts =
      sub
      |> URI.parse()
      |> Map.get(:query, "")
      |> URI.decode_query()

    provided_key_fields =
      key_parts
      |> Map.keys()
      |> MapSet.new()

    if MapSet.equal?(primary_key_fields, provided_key_fields) do
      {:ok, Enum.to_list(key_parts)}
    else
      {:error, "The token subject does not contain the required primary key fields" }
    end
  end

  defp primary_keys_from_subject(_, _), do: {:error, "The token does not contain a subject"}
end

This is looking good. So far, our preparation is taking the refresh_token argument, verifying it and extracting the subject details out of it, and telling Ash.Query to only query for users with that primary key.

Next, we’ll want to implement our two after_action hooks to actually revoke the tokens and generate new ones. Let’s implement those now.

The first thing we’ll want to do is revoke the refresh token. This is important because we want to make sure our long-lived refresh tokens aren’t easily compromised.

defp revoke_refresh_token(query, [user], strategy, context) do
  token_resource = Info.authentication_tokens_token_resource!(strategy.resource)
  token = Query.get_argument(query, :refresh_token)

  # Here we asked Ash to tell us what the token resource was, so we can
  # easily call the action to revoke it.

  case TokenResource.revoke(token_resource, token, Ash.Context.to_opts(context)) do
    :ok ->
      {:ok, [user]}

    {:error, reason} ->
      {:error, reason}
  end
end

Now, we’ll want to actually generate the new tokens:

defp generate_new_tokens(query, [user], strategy, context) do
  with {:ok, refresh_token, _claims} <- generate_token(user, context),
       {:ok, token, _claims} <- Jwt.token_for_user(user, %{"purpose" => :user}, Ash.Context.to_opts(context)) do
    user =
      user
      |> Resource.put_metadata(:refresh_token, refresh_token)
      |> Resource.put_metadata(:token, token)

    {:ok, [user]}
  else
    {:error, reason} ->
      {:error, reason }
  end
end

# Same helper method as in our sign in to generate preparation. It might be worth extracting
# this out to a helper method in the future
defp generate_token(user, context) do
  opts = Ash.Context.to_opts(context) |> Keyword.put(:token_lifetime, {30, :days})

  Jwt.token_for_user(user, %{"purpose" => "refresh_token"}, opts)
end

Similar to our sign-in action, we are generating new tokens and placing them on the user metadata. This allows the action to expose them to our API. Once we expose this method in our GraphQL schema, we should be able to call it to generate a new access token and refresh token.

query RefreshToken() {
  refreshToken(refreshToken: "my-refresh-token") {
    token
    refreshToken
  }
}

If we call this with a valid refresh token, we should get the following response:

{
  "data": {
    "refreshToken": {
      "refreshToken": "eyJh...Ms_M",
      "token": "eyJhb...wNe0"
    }
  }
}

If we call that query again with our old refresh token, we’ll get an error, as the previous token was revoked.

Next Steps

This provides us with some pretty basic support for access and refresh tokens, and thanks to existing Ash Authentication functionality, implements several security best practices for us:

Prevents token replay attacks thanks to revoking refresh tokens
Reduces attack window as any leaked access tokens are short lived, and refresh tokens are only valid once

A nice enhancement to the above implementation might be to also return the expiration time of the access token. This would allow the client to not have to decode the JWT token themselves to determine the expiration time. That can be achieved by adding an additional metadata field on both actions, and extracting the expiration time from the generated token claim and setting it on the user metadata.

  {:ok, claims} <- Jwt.peek(token)
  expires_in = Map.get(claims, "exp")

  user = user |> Resource.put_metadata(:expires_in, expires_in)

An even better next step, which we might explore in a future post, is to extract some of this out to an add-on, so some of the configuration (such as refresh token expiration) can be more easily configured. In addition, I didn’t provide robust error-handling for all of the edge cases in order to keep the post short, and it’d also be a best practice to return more specific AshAuthentication errors throughout. For example:

{:error, AshAuthentication.Errors.AuthenticationFailed.exception(
  strategy: strategy,
  query: query,
  caused_by: %{
    module: __MODULE__,
    strategy: strategy,
    action: :verify_token,
    message: "Unable to verify token"
  }
)}

Stimulus and RxJS for an SPA Like Experience

Tue, 11 Jun 2019 00:00:00 GMT

I really enjoy using Stimulus as a lightweight Javascript framework. With only a handful of attributes in your HTML and a few lines of Javascript, it’s possible to create some fairly advanced UI interactions. Lately, I’ve been combining Stimulus with RxJS to provide some protections around those interactions and improve the user experience with minimal code. Combining Stimulus and a few operators from RxJS, it’s possible to provide a fluid, SPA-like experience for your users.

I find this to be a great mix of clean code and improved usability, and was a technique I used quite a bit when building the new booking experience on Kwikcal.com.

The Experience

For this post, we’ll pretend to create a single page where a user can select from different movies in a list and have the details of that movie loaded dynamically through an XHR request, and display the details in a bottom panel below. This is a fairly straight forward interaction but can have a few gotcha’s that are easily overlooked.

What we want is that when a user clicks on a thumbnail for a movie, we’ll dynamically load the details of that movie. We also want some loading indicators so the user knows that something is taking place, but only if the user is on a slow connection. Also, if the user is on a slow connection and clicks through on different movies, we want to make sure that we always display the movie the user last clicked on - regardless of which request finished last.

Basic Interaction

To start with, we’ll want to setup Stimulus so that our user can click on a thumbnail and load the content. In our case, we’re using Rails as a backend to return a partial, but this should work with any backend framework that can render HTML.

<div class="movies" data-controller="movies">
  <div class="movie-cards">
    <% @movies.each do |movie| %>
      <div class="movie-card" data-target="movies.movieItem"
           data-action="click->movies#loadMovie"
           data-movie-url="<%= movie_path(movie[:slug]) %>">
        <div class="movie-item-content">
          <%= image_tag(movie[:thumb]) %>

          <div class="movie-item-detail text-center">
            <%= movie[:title] %>
          </div>
        </div>
      </div>
    <% end %>
  </div>

  <div class="movie-detail">
    Movie detail goes here...
  </div>

</div>

Here is what our index page looks like, with some Stimulus attributes set up to define what our controller is, the targets for our movie item, and the URL for the partial that we will eventually load. This is what I love about Stimulus - all of our code set up is in HTML, and we’re able to even leverage things such as our route helpers so that our Javascript doesn’t even care about how our routes are structured. All of that logic lives in a single source - our backend app.

Up above, we set up an action data-action="click->movies#loadMovie". This tells Stimulus what action on our controller to call when a user clicks on that element. Let’s hook that up in our Controller.

import { Controller } from "stimulus";

export default class extends Controller {
  loadMovie(event) {
    let target = event.currentTarget;
    let movieSlug = target.getAttribute("data-movie-url");
    console.log(`User clicked on ${movieSlug}`);
  }
}

So far we haven’t done much. We’ve added a method for our click event, and right now we’re just logging to the console what the user loaded. To get the data for the movie, we’ll pull in RxJS which has a lot of utility methods we’ll take advantage of.

A sprinkling of reactivity

RxJS is a library for doing reactive programming. If you’re coming from the Angular world, like I am, you’re probably familiar with it already. RxJS is a “library for composing asynchronous and event-based programs by using observable sequences”.

It’s easier to see it in action, and the official docs can explain the basics better than I could. Let’s add RxJS to our project and get going.

yarn add rxjs

Fortunately, RxJS as a library is broken down into smaller parts that we can use. The first thing we’ll want to do is set up some Subject’s to observe for when a user clicks on a movie.

First, we’ll want to import a few things from the rxjs library. Specifically, ajax, Subject and map as an operator.

import { Controller } from "stimulus";
import { Subject } from "rxjs";
import { map } from "rxjs/operators";

Next, we want to set up a new Subject which we’ll observe. We’ll use the connect lifecycle callback from Stimulus to set this up every time a new controller is created. This subscription will be used to listen to changes in the selected movie, and then output the URL to load. We’ll expand on this later on, but let’s take baby steps to get our observables in order.

import { Controller } from "stimulus";
import { Subject } from "rxjs";
import { map } from "rxjs/operators";

export default class extends Controller {
  movieItem$ = new Subject();

  connect() {
    this.setupMovieClick();
  }

  disconnect() {
    // We need to make sure that we unsubscribe to the stream,
    // otherwise we could have memory leaks
    this.movieItem$.unsubscribe();
  }

  loadMovie(event) {
    let target = event.currentTarget;
    let movieSlug = target.getAttribute("data-movie-url");
    this.movieItem$.next(movieSlug);
  }

  setupMovieClick() {
    this.movieItem$
      .pipe(
        map((movieUrl) => {
          return movieUrl;
        }),
      )
      .subscribe((response) => {
        console.log(`Displaying: ${response}`);
      });
  }
}

Every time you subscribe to an Observable, it’s important to remember that you must always unsubscribe, in order to prevent a memory leak.

If you’re new to RxJS this probably looks a bit crazy - so let’s go through it one section at a time.

The first thing we want to do is set up an observable that we’ll listen to and react to when a user event takes place. This is what our Subject is - the movieItem$. It’s common practice in RxJS to name our streams ending in a dollar sign, to further clarify what they are.

Second, we create a private method to set up the movie click. Here, we use pipe to set up a series of operations that take place every time a new item is added to the stream. In this initial example, we just want to map and return the URL. Later on, we’ll expand that logic a bit.

Finally, we call .subscribe on that stream and specify a callback to take place after all of the pipe operations have completed. It’s important to know that nothing takes place until we actually subscribe to a stream. So if you had native events or XHR requests, they wouldn’t actually fire until we subscribe to the stream.

Finally, we take our old loadMovie method and change it up a bit. We tell the stream that there is a new value, by calling .next with the path to the partial. This is what triggers our subscription callback to fire, which calls our console.log statement.

Now that this is done, if we refresh the page and click on a thumbnail we should see the URL of the movie to load in our console.

Loading the movie details

Now that we know our button clicks are all wired up and reactive, let’s go and retrieve the data for the movie details.

The first thing we’ll want to do is import the ajax command from RxJS. We do that by adding the following to the top of our file:

import { ajax } from "rxjs/ajax";

We’ll also want to import switchMap from rxjs/operators, as we’ll want to use this for the XHR requests instead of a simple map operation.

Here is what our pipe should now look like:

setupMovieClick() {
  this.movieItem$
    .pipe(
      switchMap((movieUrl) => {
        return ajax({
          method: 'GET',
          url: movieUrl,
          responseType: 'text'
        });
      }),
      map((response) => {
        return response.response;
      })
    )
    .subscribe((response) => {
      console.log(response);
    });
}

What we’re doing is instead of doing a map to output the URL, we do a switchMap and return our ajax call to load our partial.

switchMap is similar to a regular map but has the added benefit of only returning the latest request. This means that if the user is on a less than ideal connection and is quickly clicking on many movie thumbnails, switchMap will do all the dirty work of making sure that only the last click will be processed, instead of the last request result.

What this means in practice is that our clicks don’t get out of sync. Say, for example, the user clicks on movie 1, and that takes 450ms to respond, but before that happens, the user clicks on movie 2, and now that only takes 100ms to respond. Even though the last response is for movie 1, the last requested item is movie 2, and that is what the map will return.

In fact, switchMap is even smart enough to cancel any of the old HTTP requests for us!

Now what we want to do after our switchMap, which returns the results of our XHR request, is return a map which takes the text response from our request and maps that to any subscriber.

If we run this now, we’ll get the movie details for the last item the user clicked on, regardless of the completion order of the network requests.

Displaying the details

Now that we have the movie details as a string from our partial, we can use some Stimulus targets to inject that content into the DOM. We’ll want to take our old placeholder div and tell Stimulus about it, by specifying it as a target.

<div class="movie-detail" data-target="movies.movieDetails">
  Movie detail goes here...
</div>

Then, at the top of our controller, we tell Stimulus about it, so we can access it from our controller.

static targets = ['movieDetails'];

Finally, we’ll modify our subscription callback to update the innerHTML of this element:

.subscribe((response) => {
  this.movieDetailsTarget.innerHTML = response;
});

With this, we should now see the movie details as we click around on the screen. Nice!

Loading Indicator

So far, this is looking pretty good. The user can click on a movie card and see the details of the movie. Even better, with our reactive programming approach, even users on a less than ideal connection don’t get any state out of sync by having XHR requests returned out of order. They always see the last item they clicked on. One challenge left is to add a loading indicator, so users on a slower connection can see a visual indicator that we’re fetching their data.

To keep things simple, we’ll use an animated gif from loader.io, and put it in our template. We could also just have easily used an SVG and some CSS, but that’s out of scope for this article.

The first thing we’ll want to do is to put the loading state in our template and tell our Stimulus controller about it.

<div class="loading-indicator hidden"
     data-target="movies.movieDetailsLoading">
  <%= image_tag("loading.gif") %>
</div>

static targets = ['movieDetails', 'movieDetailsLoading'];

Now that Stimulus knows about it, we can do some simple CSS to hide and show the movie details content and the loading content. Our code is getting a bit complex, so we should probably take the opportunity to refactor the displaying of the loading state and displaying of the movie content into separate methods.

So how do we hook into our subscription to know when a movie is loading? Fortunately, RxJS has our back, and we can simply tap into the pipe to call our loading code without affecting anything that gets returned from the pipe. Let’s see what that looks like, along with our refactored code.

setupMovieClick() {
  this.movieItem$
    .pipe(
      tap(() => {
        this.displayLoadingState();
      }),
      switchMap((movieUrl) => {
        return ajax({
          method: 'GET',
          url: movieUrl,
          responseType: 'text'
        });
      }),
      map((response) => {
        return response.response;
      })
    )
    .subscribe((response) => {
      this.displayMovieContent(response);
    });
}

displayLoadingState() {
  this.movieDetailsLoadingTarget.classList.remove('hidden');
  this.movieDetailsTarget.classList.add('hidden');
}

displayMovieContent(movieContent) {
  this.movieDetailsTarget.innerHTML = movieContent;

  this.movieDetailsLoadingTarget.classList.add('hidden');
  this.movieDetailsTarget.classList.remove('hidden');
}

Here what we do is we call tap with a function that gets called in our event stream, after an item is clicked, and before the ajax request is fired off. Then, we target the elements through Stimulus and add some utility classes to hide the different elements.

Now, when we click on a movie, we’ll see a little spinner display before the movie details are displayed. Great!

The only downside here is that if a user is on a fast connection, then they’ll see a quick flash of the loading spinner before that gets displayed.

Loading Indicator Timeout

One way to work around the loading indicator for users on a fast connection is to put the code to display the spinner on a timeout. If it’s been 250 milliseconds and we haven’t gotten data from the server back, we should display a spinner. As soon as we get data back, let’s cancel the timeout. This has the benefit of only displaying the spinner for users on a slow connection.

setupMovieClick() {
  let loadingIndicatorTimeout;

  this.movieItem$
    .pipe(
      tap(() => {
        loadingIndicatorTimeout = setTimeout(() => {
          this.displayLoadingState();
        }, 250);
      }),
      switchMap((movieUrl) => {
        return ajax({
          method: 'GET',
          url: movieUrl,
          responseType: 'text'
        });
      }),
      tap(() => {
        clearTimeout(loadingIndicatorTimeout);
      }),
      map((response) => {
        return response.response;
      })
    )
    .subscribe((response) => {
      this.displayMovieContent(response);
    });
}

What we’re doing is taking our initial tap function, and wrapping it in a setTimeout to run after 250ms. Then, in a new tap operation, we cancel the timeout, as that means we’ve retrieved the data from the server. If the timeout never reached 250, such as a user on a fast connection, then the loading spinner never fires. If it’s already been displayed, then nothing happens, as the callback already took place.

Final Touches

Wow - we’ve achieved a lot, with only a handful of code in our Stimulus controller. There’s one final touch that we should add. Currently, if a user clicks on a movie, we display that movie in the details panel below. However, if a user continually clicks on the same movie tile, we keep making the same request over and over again.

Once again, RxJS has our back - this time with the distinctUntilChanged operator. Add this operator as the first operator in our pipeline, and the rest will only fire when the stream item has changed - which in our case is the movie detail URL to load.

this.movieItem$
  .pipe(
    distinctUntilChanged(),
    tap(() => {
      loadingIndicatorTimeout = setTimeout(() => {
        this.displayLoadingState();
      }, 250);
    }),
    // etc etc.

Another behavior we should add is to highlight the selected movie. This is something we can do using Stimulus in our click handler.

Since we’ve already added a data-target for our movie items in our template, we just need to add those as a static target in our controller. From there, we can use basic CSS and DOM manipulation to identify the selected card.

static targets = ['movieItem', 'movieDetails', 'movieDetailsLoading'];

loadMovie(event) {
  let target = event.currentTarget;
  let movieSlug = target.getAttribute('data-movie-url');

  this.movieItemTargets.forEach((movieItem) => {
    movieItem.classList.remove('selected');
  });

  target.classList.add('selected');

  this.movieItem$.next(movieSlug);
}

Now our final product is looking pretty good. As the user clicks around the movies, they get visual indicators if they are loading, visual indicators of their selected movie and any slow or untimely requests are easily handled for us by RxJS.

Not bad for around 75 lines of Javascript!

If you’d like to see the final code, please feel free to browse the mike1o1/stimulus-rxjs-example repository.

Stimulus and RxJS For Improved Loading States

Fri, 15 May 2020 00:00:00 GMT

I’ve written before about using Stimulus and RxJS, but I wanted to write again about an improved way of handling loading states using RxJS and Stimulus.

Displaying a loading state is a great way to indicate to the user that there is something happening in response to a button click, but sometimes if the user is on a fast connection or machine, displaying that loading state too quickly can have a negative impact.

For example, if a user action takes ~100ms to process something, displaying and then quickly hiding a loading state will just show a flash of content and could leave the user a little bit confused.

Fortunately, RxJS makes handling this extremely simple to implement. In the previous post we implemented this using setTimeout and clearTimeout, but now we’ll see how this can be improved by using RxJS primitives.

Loading State

A loading state is something we want to display when the user clicks an action and the application needs to retrieve data from a remote source. Since we don’t know how long that data retrieval will take place, we display a loading state letting the user know something is happening.

Here is an example of how this could look in response to a button click

setupClickEvent() {
  this.newClick
    .pipe(
      tap(() => {
        this.displayLoadingState();
      }),
      delay(500)  // Fake delay
    )
    .subscribe(() => {
      this.displayContent();
    });
}

displayLoadingState() {
  this.loadingTarget.classList.remove('hidden');
}

displayContent(content) {
  this.loadingState.classList.add('hidden');

  // display actual content
}

If you’ve used RxJS before (or read the previous post), this should be pretty familiar. When a new click is observed, we immediately display the loading state. Once the data is retrieved from the remote source, we hide the loading state.

Adding a Loading Delay

To improve the experience, so we don’t get a flash of a loading indicator for users on a fast connection, we should add a delay between the time that the loading takes place and when we actually modify the DOM to do display it. Basically, we separate the loading state from the logic of actually displaying the loading state.

To do this, we first want to add a new Subject for handling the loading state.

import { Controller } from "stimulus";
import { Subject } from "rxjs";
import { tap, delay, filter, debounceTime } from "rxjs/operators";

export default class extends Controller {
  static targets = ["loading", "delay"];

  newClick = new Subject();
  isLoading = new Subject();

  loadingDelay = 350;

  connect() {
    this.setupClickEvent();
    this.setupLoadingState();
  }

  myClick(event) {
    this.newClick.next();
  }

  setupClickEvent() {
    this.newClick
      .pipe(
        tap(() => {
          this.delayTarget.innerText = "";
          this.isLoading.next(true);
        }),
        delay(150),
      )
      .subscribe(() => {
        this.isLoading.next(false);
        this.delayTarget.innerText = `Data available`;
        // Display content
      });
  }

  setupLoadingState() {
    // Subscribe to when loading state is enabled
    // but wait 250ms before updating the DOM and displaying it
    this.isLoading
      .pipe(
        debounceTime(this.loadingDelay),
        filter((value) => value === true),
      )
      .subscribe(() => {
        this.loadingTarget.classList.remove("hidden");
      });

    // Subscribe to when loading state is disabled
    // and hide it immediately
    this.isLoading.pipe(filter((value) => !value)).subscribe(() => {
      this.loadingTarget.classList.add("hidden");
    });
  }
}

The bulk of the work takes place in the handleLoadingState method and is done completely with RxJS primitives filter and debounceTime. What we do is create two subscriptions - the first for when loading state is enabled, and the second for when the loading state is turned off.

The difference between the two is that we add a debounce between the time the loading state is turned on and the time that we actually display it. If the loading state is disabled between that time, it will fail the filter check and the loading state stays hidden.

We also updated our button click code to simply call next on the isLoading subject with the appropriate state (true or false). This further decouples the displaying of the loading state from the retrieving of the data. All the retrieving of the data needs to do is tell RxJS that something is loading or is done loading. Everything else happens by subscribing to that Subject.

If we change the fake delay on our button click action to be higher than 350, we’ll see the loading indicator display. If we change the fake delay to less than 350, we won’t show the loading indicator at all.

Conclusion

With just a few more lines of code, we’ve improved our loading state logic quite a bit. We’ve decoupled the loading state itself from the logic that handles the display of the loading state.

If you’d like to see the final code, please feel free to browse the mike1o1/stimulus-rxjs-loading-state repository.

Using Hotwire with Rails for a SPA like experience

Thu, 05 Aug 2021 00:00:00 GMT

In a previous post I wrote about using Rails and Stimulus to create a SPA like experience with page navigation. Since then, the Basecamp team has released Hotwire to allow for similar functionality but with little-to-no Javascript.

We’ll take a look at updating the experience from the previous post to use Turbo Frames to provide inter-page navigation. Later, we’ll sprinkle in some Stimulus to provide some visual feedback to the user with loading states.

To recap, here is what we’ll be building.

First Steps

With Hotwire/Turbo, we have a concept of a Turbo Frame. A Turbo Frame is similar to frames of old, but can be thought of as a tool to break-down a page into separate areas of content. In our case, we’ll have two frames - one for the list of movies, and another for where we display the details about the selected movie.

Thinking in frames takes some getting used to, but it can be powerful once it clicks. The documentation has some good examples, but it still took a bit for it to click with me. In short, if you’re navigating within a frame, then if the response coming back also has that same frame id within it, Turbo will replace it for you automatically. If we don’t want that, we can set the turbo frame target, either to “_top”, or to a specific turbo frame elsewhere on the page.

Let’s see what our page looks like if we break it down into frames - one for the index, another for the content.

<div class="movies">
  <%= turbo_frame_tag :index, class: "movie-cards" do %>
    <% @movies.each do |movie| %>
      <%= link_to movie_path(movie[:slug], class: "movie-card" do %>
        <%= image_tag(movie[:thumb]) %>
        <div class="movie-item-detail text-center">
          <%= movie[:title] %>
        </div>
      <% end %>
    <% end %>
  <% end %>

  <%= turbo_frame_tag :details, class: "movie-detail" do %>
    Select a movie for more details...
  <% end %>
</div>

As a refresher, let’s see what our old “show” view looked like. Pretty barebones, just some details about the movie.

<p>
  Title: <%= @movie[:title] %>
</p>

<p>
  Summary: <%= @movie[:summary] %>
</p>

<p>
  Director: <%= @movie[:director] %>
</p>

<p>
  Length: <%= @movie[:length] %>
</p>

<p>
  Genre: <%= @movie[:genre] %>
</p>

<p>
  Year: <%= @movie[:year] %>
</p>

This setup will get us our frames. If we were to click on one of the movie cards, we’d see our index disappear and an error in the console.

Response has no matching <turbo-frame id="index"> element

As mentioned above, since our link was within a turbo-frame element, Turbo is expecting the html response to contain a matching turbo-frame element, and Turbo will swap out the content for us. Cool, let’s just wrap the show view in a turbo-frame element with an id of “index”, right? That won’t quite work because then we’d be replacing the index.

Since we’re deviating from the default navigation behavior, we need to do two things to instruct Turbo how to handle our navigation.

First, we need to wrap our response in a turbo frame, but with an id of “details”. This should be straight forward, let’s update our show template and wrap the response in a turbo-frame.

<%= turbo_frame_tag :details do %>
  <p>
    Title: <%= @movie[:title] %>
  </p>

  ...
<% end %>

Second, we need to tell Turbo that when a user clicks on a link inside the index frame, to target the details frame. Let’s update our index template and add a data-turbo-frame attribute, and tell Turbo to update the details frame when navigation is completed.

<%= link_to movie_path(movie[:slug], class: "movie-card", "data-turbo-frame": "details" do %>
  <%= image_tag(movie[:thumb]) %>
  <div class="movie-item-detail text-center">
    <%= movie[:title] %>
  </div>
<% end %>

With these changes made, if we refresh the page and click on a movie card, we’ll see the details update. Very cool! We’re about 80% of the way towards a SPA like experience, and we haven’t even written a single line of Javascript/Typescript - not bad!

If we pay close attention, we’ll see that there is some visual feedback that’s missing. There’s nothing to indicate to the user that an action is taking place. If they’re on a slow connection, or the details takes awhile to load, they won’t know that anything happened as there is no loading state. Second, the index frame never gets updated to show which movie is selected.

In the SPA example in the previous post, we were able to address both concerns through Javascript and using loading states. Fortunately, we can still implement both of those with a simple Stimulus controller.

Stimulus For Visual Feedback

In the old previous post, we used Stimulus to implement our own click handlers for when a user clicked on a movie, and we used RxJs to handle fetching of the html content, and we updated the DOM ourselves. All of that is now taken care of by Turbo, but we can still use Stimulus to handle some of the visual feedback. Let’s first create our Stimulus controller and tackle the issue of loading states.

// We'll name this "navigation_controller", for lack of a better term right now.
export default class extends Controller {
  static targets = ["content", "loading"];

  displayLoading(event) {
    this.loadingTarget.classList.remove("hidden");
    this.contentTarget.classList.add("hidden");
  }

  displayContent() {
    this.loadingTarget.classList.add("hidden");
    this.contentTarget.classList.remove("hidden");
  }
}

We’ve added two targets - the content of the item, and some loading content. When we want to display the loading state, we hide the content target and show the loading target, and do the opposite when we want to display the content.

How do we incorporate the controller into our template? Let’s first add our targets and use the controller.

<div class="movies" data-controller="navigation">
  <%= turbo_frame_tag :index, class: "movie-cards" do %>
    <!-- ... -->
  <% end %>

  <%= turbo_frame_tag :details, class: "movie-detail", "data-navigation-target": "content" do %>
    Select a movie for more details...
  <% end %>

  <div class="loading-indicator hidden"
       data-navigation-target="loading">
    <%= image_tag("loading.gif") %>
  </div>
</div>

With this update we’ve done two things. First, we added our loading spinner to the DOM, in an initial state of hidden, and we flagged our turbo-frame as the content target for our navigation controller.

If we reload and click around, though, we’ll see that nothing has happened. That shouldn’t be too surprising, because we haven’t told Stimulus how to actually invoke our two method for displaying the loading or content state.

Taking a look at the Turbo documentation, there are a few events that stand-out as something we might be able to hook into. The first is the turbo:before-fetch-request event, which is fired before Turbo issues a request to load the page. This sounds like it would be a good time to update the DOM to display a loading state. Let’s wire that up.

The documentation states that these events are fired on the document, and fortunately Stimulus provides an easy way to hook into those.

<div
  class="movies"
  data-controller="navigation"
  data-action="turbo:before-fetch-request@document->navigation#displayLoading"
>
  <!-- ... -->
</div>

What we’re doing now, is anytime Turbo begins a request, we trigger the displayLoading action on our Stimulus controller. If we were to reload the page now, we’d see the loading state display. However, we are not notified when the navigation is complete, so we don’t really know when to then show the content.

Turbo fires another event when the request is completed, the turbo:before-fetch-response. This is confusing, because it has the term “before” in it, but it basically means that the response for the content is available, which means the http request completed, so we can hide our loading state, and unhide our content. Let’s wire that up the same way we did our loading state.

<div
  class="movies"
  data-controller="navigation"
  data-action="
     turbo:before-fetch-request@document->navigation#displayLoading
     turbo:before-fetch-response@document->navigation#displayContent
"
>
  <!-- ... -->
</div>

If we were to refresh the page and click around (and set the Network speed to slow), we’d see a flash of the loading state, followed by the details of the movie.

If we wanted to really spice things up, we can incorporate RxJs to better handle the loading state and not show the loading state unless the request takes a certain amount of time. Check out my previous post to see how to do that.

Selected Item

Now that we have a loading state implemented, we want to let the user know in the index frame which item in the detail frame is being used. Unfortunately, there doesn’t seem to be an easy way to do this using the before-fetch-request event, as we don’t know the specific item being clicked. However, there’s another event which might be even better for us: turbo:click.

The turbo:click event is fired on the element that was clicked to trigger navigation. Let’s update our template to use this instead:

<div class="movies" data-controller="navigation"
     data-action="turbo:before-fetch-response@document->navigation#displayContent"
>
  <%= turbo_frame_tag :index, class: "movie-cards" do %>
    <% @movies.each do |movie| %>
      <%= link_to movie_path(movie[:slug]),
        data: {
          turbo_frame: "details",
          action: "turbo:click->navigation#displayLoading",
          navigation_target: "link"
        },
        class: "movie-card" do %>
        <!-- ... -->
      <% end %>
    <% end %>
  <% end %>

We’ve done a few things here. We removed one of our document level listeners, added a turbo:click action handler on the actual link itself and also added a data-navigation-target to tell the Stimuls controller about our link elements. We can now update our Stimulus controller to handle the event and new target.

export default class extends Controller {
  static targets = ["content", "loading", "link"];

  displayLoading(event) {
    this.loadingTarget.classList.remove("hidden");
    this.contentTarget.classList.add("hidden");

    let value = event.detail.url;

    this.updateLinks(value);
  }

  displayContent() {
    // ...
  }

  // Iterate all of our links, remove the selected class, but then add
  // if the link href matches the url we're navigating to.
  updateLinks(item) {
    this.linkTargets.forEach((link) => {
      link.classList.remove("selected");
      if (link.href === item) {
        link.classList.add("selected");
      }
    });
  }
}

When the turbo:click event is fired, the url that we’re navigating to is included as part of the CustomEvent detail. We can use that to then iterate through our list of movie links, and set the selected class on that particular item. With this in place, if we refresh the page and start navigating around we’ll see that the movie being displayed is now highlighted in the index.

With the Hotwire tools, such as Turbo and Stimulus, it’s really impressive how far we can get with such little Javascript. As DHH would say, “look at all the code I’m not writing”.

If you’d like to see the final code, please feel free to browse the mike1o1/hotwired-spa-experience repository.