README.md

Futurism

Lazy-load Rails partials via CableReady

🚨 Futurism is still in pre-1.0 state. As much as I hope to keep the API backwards-compatible, I cannot guarantee it 🚨

Photo by Birmingham Museums Trust on Unsplash

Facts

• only one dependency: CableReady
• bundle size (without CableReady) is around ~1.04kB

Browser Support

• Chrome v67+ (v54+ via Polyfill)
• Firefox v63+
• Edge v79+
• Safari v10.1+ via Polyfill
• iOS Safari & Chrome v10.3+ via Polyfill

Caniuse

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 %>

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 %>

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>

Events

Once your futurize element has been rendered, the futurize:appeared custom event will be called.

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 @minthesize/futurism for you !

Manual Installation

After bundle, install the Javascript library:

$ bin/yarn add @minthesize/futurism

In your app/javascript/channels/index.js, add the following

import * as Futurism from '@minthesize/futurism''

import consumer from './consumer'

Futurism.initializeElements()
Futurism.createSubscription(consumer)

Contributing

License

The gem is available as open source under the terms of the MIT License.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Julian Rubisch 💻	darkrubyist 💻 📖	Konnor Rogers 💻	Andrew Mason 🚧	Chris Oliver 💻 👀	leastbad 💻 👀	M. E. Patterson 🐛
Stephen Margheim 💻	Hassanin Ahmed 💻	Marco Roth 💻

This project follows the all-contributors specification. Contributions of any kind welcome!