CableReady

Out-of-Band Server Triggered DOM Operations

CableReady provides a simple interface for triggering client-side DOM operations from the server via ActionCable.

Quick Start

Please read the official ActionCable docs to learn more about ActionCable before proceeding.

// app/assets/javascripts/application.js
/*
 *= require cable_ready
 */

// app/assets/javascripts/channels/user.js
App.cable.subscriptions.create({ channel: "UserChannel" }, {
  received: function (data) {
    if (data.cableReady) {
      CableReady.perform(data.operations);
    }
  }
});

# app/models/user.rb
class User < ApplicationRecord
  include CableReady::Broadcaster

  def broadcast_name_change
    cable_ready["UserChannel"].text_content selector: "#user-name", text: name
    cable_ready.broadcast
  end
end

See CableReady TodoMVC for a more complete reference implementation.

The selector options use Document.querySelector() to find elements.

It's possible to invoke multiple DOM operations with a single ActionCable broadcast.

DOM Events

dispatchEvent

Dispatches a DOM event in the browser.

cable_ready["MyChannel"].dispatch_event(
  name:     "string", # required - the name of the DOM event to dispatch (can be custom)
  detail:   "object", # [null]   - assigned to event.detail
  selector: "string"  # [window] - string containing one or more CSS selectors separated by commas
)

Element Mutations

morph

Fast lightweight DOM diffing/patching without a virtual DOM.

cable_ready["MyChannel"].morph(
  selector:      "string", # required - string containing one or more CSS selectors separated by commas
  focusSelector: "string", # [null]   - string containing one or more CSS selectors separated by commas
  html:          "string"  # [null]   - the HTML to assign
)

innerHTML

Sets the innerHTML of a DOM element.

cable_ready["MyChannel"].inner_html(
  selector:      "string", # required - string containing one or more CSS selectors separated by commas
  focusSelector: "string", # [null]   - string containing one or more CSS selectors separated by commas
  html:          "string"  # [null]   - the HTML to assign
)

textContent

Sets the text content of a DOM element.

cable_ready["MyChannel"].text_content(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  text:     "string"  # [null]   - the text to assign
)

insertAdjacentHTML

Inserts HTML into the DOM relative to an element. Supports behavior akin to prepend & append.

cable_ready["MyChannel"].insert_adjacent_html(
  selector:      "string", # required    - string containing one or more CSS selectors separated by commas
  focusSelector: "string", # [null]      - string containing one or more CSS selectors separated by commas
  position:      "string", # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
  html:          "string"  # [null]      - the HTML to insert
)

insertAdjacentText

Inserts text into the DOM relative to an element. Supports behavior akin to prepend & append.

cable_ready["MyChannel"].insert_adjacent_text(
  selector: "string", # required    - string containing one or more CSS selectors separated by commas
  position: "string", # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
  text:     "string"  # [null]      - the text to insert
)

remove

Removes an element from the DOM.

cable_ready["MyChannel"].remove(
  selector:      "string", # required - string containing one or more CSS selectors separated by commas
  focusSelector: "string"  # [null]   - string containing one or more CSS selectors separated by commas
)

replace

Replaces a DOM element with new HTML.

cable_ready["MyChannel"].replace(
  selector:      "string", # required - string containing one or more CSS selectors separated by commas
  focusSelector: "string", # [null]   - string containing one or more CSS selectors separated by commas
  html:          "string"  # [null]   - the HTML to use as replacement
)

setValue

Sets the value of an element.

cable_ready["MyChannel"].set_value(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  value:    "string"  # [null]   - the value to assign to the attribute
)

Attribute Mutations

setAttribute

Sets an attribute on an element.

cable_ready["MyChannel"].set_attribute(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  name:     "string", # required - the attribute to set
  value:    "string"  # [null]   - the value to assign to the attribute
)

removeAttribute

Removes an attribute from an element.

cable_ready["MyChannel"].remove_attribute(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  name:     "string"  # required - the attribute to remove
)

CSS Class Mutations

addCssClass

Adds a css class to an element. This is a noop if the css class is already assigned.

cable_ready["MyChannel"].add_css_class(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  name:     "string"  # [null]   - the CSS class to add
)

removeCssClass

Removes a css class from an element.

cable_ready["MyChannel"].add_css_class(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  name:     "string"  # [null]   - the CSS class to remove
)

Dataset Mutations

setDatasetProperty

Sets an dataset property (data-* attribute) on an element.

cable_ready["MyChannel"].set_dataset_property(
  selector: "string", # required - string containing one or more CSS selectors separated by commas
  name:     "string", # required - the property to set
  value:    "string"  # [null]   - the value to assign to the dataset
)

JavaScript Development

The JavaScript source is located in vendor/assets/javascripts/cable_ready/src & transpiles to vendor/assets/javascripts/cable_ready/cable_ready.js via Webpack.

cd vendor/assets/javascripts/cable_ready/src
webpack