README
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
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
After bundle
, install the Javascript library:
$ bin/yarn add @minthesize/cubism
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:
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.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.trigger_root
: a CSS selector to attach the appear/disappear events to. Defaults to thecubicle-element
itself.html_options
are passed to the TagBuilder.
Limitations
Supported Template Handlers
- ERB
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 @stimulus_reflex/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
Release
- Update the version numbers in
javascript/package.json
andlib/cubism/version.rb
git commit -m "Bump version to x.x.x"
- Run
bundle exec rake build
- Run
bundle exec rake release
- Run
npm publish --access public
License
The gem is available as open source under the terms of the MIT License.
Contributors
Julian Rubisch đź’» |