CableReady

CableReady provides a standard interface for invoking common client-side DOM operations from the server via ActionCable.

Learn more about CableReady by reading through & running the CableReady Test project.

Supported DOM Operations

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_broadcast "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

innerHTML

Sets the innerHTML of a DOM element.

cable_ready_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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_broadcast "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
}]

Quick Start

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

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

  def broadcast_name_change
    cable_ready_broadcast "UserChannel", text_content: [{ selector: "#user-name", text: name }]
  end
end

// 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);
    }
  }
});

Advanced Usage

Consider using CableReady in concert with a gem like SelfRenderer to create a powerful SPA style user experience with the simplicity of server side rendering.