Futurism
Lazy-load Rails partials via CableReady
Install / Use
/learn @stimulusreflex/FuturismREADME
Futurism
Lazy-load Rails partials via CableReady
:rotating_light: BREAKING CHANGE: With v1.0, futurism has been transferred to the stimulusreflex organization. Please update your npm package to @stimulus_reflex/futurism accordingly :rotating_light:
Table of Contents
- Table of Contents
- Facts
- Usage
- API
- Events
- Instrumentation
- Installation
- Authentication
- Testing
- Gotchas
- Contributing
- License
- Contributors
Facts
- only one dependency: CableReady
- bundle size (without CableReady) is around ~2.46kB
Browser Support
- Chrome v67+ (v54+ via Polyfill)
- Firefox v63+
- Edge v79+
- Safari v10.1+ via Polyfill
- iOS Safari & Chrome v10.3+ via Polyfill
Usage
with a helper in your template
<%= futurize @posts, extends: :div do %>
<!-- placeholder -->
<% end %>
custom <futurism-element>s (in the form of a <div> or a <tr is="futurism-table-row"> are rendered. Those custom elements have an IntersectionObserver attached that will send a signed global id to an ActionCable channel (FuturismChannel) which will then replace the placeholders with the actual resource partial.
With that method, you could lazy load every class that has to_partial_path defined (ActiveModel has by default).
You can pass the placeholder as a block:
<%= futurize @posts, extends: :tr do %>
<td class="placeholder"></td>
<% end %>
You can also omit the placeholder, which falls back to eager loading.
API
Currently there are two ways to call futurize, designed to wrap render's behavior:
Resource
You can pass a single ActiveRecord or an ActiveRecord::Relation to futurize, just as you would call render:
<%= futurize @posts, extends: :tr do %>
<td class="placeholder"></td>
<% end %>
Partial Path
Remember that you can override the partial path in you models, like so:
class Post < ApplicationRecord
def to_partial_path
"home/post"
end
end
That way you get maximal flexibility when just specifying a single resource.
Explicit Partial
Call futurize with a partial keyword:
<%= futurize partial: "items/card", locals: {card: @card}, extends: :div do %>
<div class="spinner"></div>
<% end %>
You can also use the shorthand syntax:
<%= futurize "items/card", card: @card, extends: :div do %>
<div class="spinner"></div>
<% end %>
Collections
Collection rendering is also possible:
<%= futurize partial: "items/card", collection: @cards, extends: :div do %>
<div class="spinner"></div>
<% end %>
Specifying Controller to Render
You can also pass in the controller that will be used to render the partial.
<%= futurize partial: "items/card", collection: @cards, controller: MyController, extends: :div do %>
<div class="spinner"></div>
<% end %>
By default (i.e. not passing in a value), futurize will use ApplicationController, but you may override by setting the Futurism default controller in an initializer, for example config/initializers/futurism.rb.
Futurism.default_controller = "MyController" # to avoid the controller from trying to autoload at boot, provide as a string
HTML Options
You can pass a hash of attribute/value pairs which will be mixed into the HTML markup for the placeholder element. This is important for layouts that require elements to have dimensionality. For example, many scripts calculate size based on element height and width. This option ensures that your elements have integrity, even if they are gone before you see them.
<%= futurize @posts, extends: :tr, html_options: {style: "width: 50px; height: 50px;"} do %>
<td class="placeholder"></td>
<% end %>
This will output the following:
<tr style="width: 50px; height: 50px;">
<td class="placeholder"></td>
</tr>
Eager Loading
It may sound surprising to support eager loading in a lazy loading library :joy:, but there's a quite simple use case:
Suppose you have some hidden interactive portion of your page, like a tab or dropdown. You don't want its content to block the initial page load, but once that is done, you occasionally don't want to wait for the element to become visible and trigger the IntersectionObserver, you want to lazy load its contents right after it's added to the DOM.
Futurism makes that dead simple:
<%= futurize 'some_tab', eager: true, extends: :tr do %>
<div class="placeholder"</td>
<% end %>
Bypassing
In some rare cases, e.g. when combined with CableReady's async updates_for mechanism, you'll want to bypass futurism entirely and fall back to native rendering. You can do this by passing an unless option:
<%= futurize 'some_tab', unless: bypass_futurism?, extends: :tr do %>
<div class="placeholder"</td>
<% end %>
Internally, this works the same as bypassing futurism in tests
Broadcast Partials Individually
Futurism's default behavior is to broadcast partials as they are generated in batches:
On the client side, IntersectionObserver events are triggered in a debounced fashion, so several renders are performed on the server for each of those events. By default, futurism will group those to a single broadcast call (to save server CPU time).
For collections, however, you can opt into individual broadcasts by specifying broadcast_each: true in your helper usage:
<%= futurize @posts, broadcast_each: true, extends: :tr do %>
<div class="placeholder"</td>
<% end %>
Contextual Placeholder Arguments
For individual models or arbitrary collections, you can pass record and index to the placeholder block as arguments:
<%= futurize @post, extends: :div do |post| %>
<div><%= post.title %></div>
<% end %>
<%= futurize @posts, extends: :tr do |post, index| %>
<td><%= index + 1 %></td><td><%= post.title %></td>
<% end %>
<%= futurize partial: "users/user", collection: users, extends: "tr" do |user, index| %>
<td><%= index + 1 %></td><td><%= user.name %></td>
<% end >
Events
Once your futurize element has been rendered, the futurism:appeared custom event will be called.
Instrumentation
Futurism includes support for instrumenting rendering events.
To enable ActiveSupport notifications, use the instrumentation option:
Futurism.instrumentation = true
Then subscribe to the render.futurism event:
ActiveSupport::Notifications.subscribe("render.futurism") do |*args|
event = ActiveSupport::Notifications::Event.new(*args)
event.name # => "render.futurism"
event.payload[:channel] # => "Futurism::Channel" # ActionCable channel to broadcast
event.payload[:controller] # => "posts" # The controller that invokes `futurize` call
event.payload[:action] # => "show" # The action that invokes `futurize` call
event.payload[:partial] # => "posts/card" # The partial that was rendered
end
This is useful for performance monitoring, specifically for tracking the source of futurize calls.
Installation
Add this line to your application's Gemfile:
gem 'futurism'
And then execute:
$ bundle
To copy over the javascript files to your application, run
$ bin/rails futurism:install
! Note that the installer will run yarn add @stimulus_reflex/futurism for you !
Manual Installation
After bundle, install the Javascript library:
There are a few ways to install the Futurism JavaScript client, depending on your application setup.
ESBuild / Webpacker
yarn add @stimulus_reflex/futurism
Import maps:
# config/importmap.rb
# ...
pin '@stimulus_reflex/futurism', to: 'futurism.min.js', preload: true
Rails Asset pipeline (Sprockets):
<!-- app/views/layouts/application.html.erb -->
<%= javascript_include_tag "futurism.umd.min.js", "data-turbo-track": "reload" %>
In your app/javascript/channels/index.js, add the following
import * as Futurism from '@stimulus_reflex/futurism'
import consumer from './consumer'
Futurism.initializeElements()
Futurism.createSubscript
