Cubism

Lightweight Resource-Based Presence Solution with CableReady.

Cubism provides real-time updates of who is viewing or interacting with whatever resources you need. Whether you want Slack's "X is typing..." indicator or an e-commerce "5 other customers are viewing this item" notice, Cubism gives you everything you need "under the hood" so that you can focus on what really matters—end-user functionality.

Table of Contents
Usage
Installation
API
Limitations
Gotchas
Contributing
License
Contributors

Usage

Prepare your User Model

In your app's User model, include Cubism::User:

class User < ApplicationRecord
  include Cubism::User

  # ...
end

Track Present Users in your Models

In the models you'd like to track presence for, include the Cubism::Presence concern:

class Project < ApplicationRecord
  include Cubism::Presence

  # ...
end

Set Up the Cubicle Template

Using the cubicle_for helper, you can set up a presence indicator. It will

subscribe to the respective resource, and
render a block which is passed the list of present users:

<%= cubicle_for @project, current_user do |users| %>
  <%= users.map(&:username).join(", ")
<% end %>

Important! due to technical limitations the cubism block does not act as a closure, i.e. it has only access to the users variable passed to it - think of it more as a self-contained component.

Installation

Add this line to your application's Gemfile:

gem 'cubism'

And then execute:

$ bundle

There are a few ways to install the Cubism JavaScript client, depending on your application setup.

ESBuild / Webpacker

yarn add @minthesize/cubism

Import maps:

# config/importmap.rb
# ...
pin '@minthesize/cubism', to: 'cubism.min.js', preload: true

Rails Asset pipeline (Sprockets):

<!-- app/views/layouts/application.html.erb -->
<%= javascript_include_tag "cubism.umd.min.js", "data-turbo-track": "reload" %>

Kredis

This gem uses kredis under the hood, so be sure to follow their installation instructions. In other words, provide a Redis instance and configure it in config/redis/shared.yml.

Javascript

In your app's Javascript entrypoint (e.g. app/javascript/packs/application.js) import and initialize CableReady (cubism will make use of the injected ActionCable consumer):

import CableReady from "cable_ready";
import "@minthesize/cubism";

CableReady.initialize({ consumer });

API

The cubicle_for helper accepts the following options as keyword arguments:

scope: declare a scope in which presence indicators should appear. For example, if you want to divide between index and show views, do scope: :index and scope: :show respectively (default: "").
exclude_current_user (true|false): Whether or not to exclude the current user from the list of present users broadcasted to the view. Useful e.g. for "typing..." indicators (default: true).
appear_trigger: JavaScript event names (e.g. ["focus", "debounced:input]) to use. (Can also be a singular string, which will be converted to an array). The default is :connect, i.e. register a user as "appeared"/"present" when the element connects to the DOM. Another special value is :intersect, which fires when the trigger_root comes into the viewport.
disappear_trigger: a JavaScript event name (e.g. :blur) to use. (Can also be a singular string, which will be converted to an array). The default is :disconnect, i.e. remove a user form the present users list when the element disconnects from the DOM. Analoguous to above, :intersect means that disappear will fire when the trigger_root is scrolled out of the viewport.
trigger_root: a CSS selector to attach the appear/disappear events to. Defaults to the cubicle-element itself.
html_options are passed to the TagBuilder.

Limitations

Supported Template Handlers

Gotchas

Usage with ViewComponent

Currently there's a bug in VC resulting in the capture helper not working correctly (https://github.com/github/view_component/pull/974). The current workaround is to assign a slot in your component and render the presence list from outside:

class MyComponent < ViewComponent::Base
  renders_one :presence_list

  # ...
end

<%= render MyComponent.new do |c| %>
  <% c.presence_list do %>
    <%= cubicle_for @project, current_user do |users| %>
      ...
    <% end %>
  <% end %>
<% end %>

Contributing

Get local environment setup

Below are a set of instructions that may help you get a local development environment working

# Get the gem/npm package source locally
git clone https://github.com/julianrubisch/cubism
yarn install # install all of the npm package's dependencies
yarn link # set the local machine's cubism npm package's lookup to this local path

# Setup a sample project and edit Gemfile to point to local gem
# (e.g. `gem "cubism", path: "../cubism"`)
# yarn link @minthesize/cubism


# Do your work, Submit PR, Profit!


# To stop using your local version of cubism
# change your Gemfile back to the published (e.g. `gem "cubism"`)
cd path/to/cubism/javascript
# Stop using the local npm package
yarn unlink

# Instruct your project to reinstall the published version of the npm package
cd path/to/project
yarn install --force

📦 Releasing

Make sure that you run yarn and bundle to pick up the latest.
Bump version number at lib/cubism/version.rb. Pre-release versions use .preN
Run rake build and yarn build
Commit and push changes to github git commit -m "Bump version to x.x.x"
Run rake release
Run yarn publish --no-git-tag-version
Yarn will prompt you for the new version. Pre-release versions use -preN
Commit and push changes to GitHub
Create a new release on GitHub (here) and generate the changelog for the stable release for it ## License The gem is available as open source under the terms of the MIT License.

Contributors

_{Julian Rubisch}
💻