Refresh when Visible

by Julian Rubisch

To install this controller, run this command in your Rails app directory in the terminal:

bin/rails app:template LOCATION=https://betterstimulus.com/templates/client-server/visible-refresh

Usage

Configuration

Rationale

I developed this controller when I wrote my first “real” PWA and ran into an issue:

Out of the box, you can’t just refresh a page if you need to update the page contents. Now this might not be a problem for the majority of apps, but at the moment you’ve got some real-time data streams coming in (e.g. a metrics dashboard, or from a third-party API), this becomes annoying.

The solution I came up with makes use of the Page Visibility API, which provides events that indicate whether a document is hidden or not. Hidden, in this case can mean things like:

• the user switched to another browser tab,
• she minimized the window,
• the browser window is covered by another window,
• the PWA (as in our case) has been put into the background,
• etc.

So, conversely, this controller uses the visibilitychange event to trigger a refresh when the page becomes visible again.

Implementation

As a modern Rails take on polling, this controller uses a lambda, appendRefresh, to trigger a Turbo refresh. If your Turbo refresh method is set to morphing, it will morph instead of replace the whole document.

So, by wiring up the trigger action to the visibilitychange event in your DOM, a refresh will happen whenever the page becomes visible:

<section data-controller="visible-refresh"
         data-action="visibilitychange@document->visible-refresh#trigger">

Bonus

Optionally (hence commented out), this controller includes a configurable setInterval to trigger a recurring refresh. This might be helpful if you’re dealing with a dashboard being fed by external data, for example.