CableReady Documentation

The morph operation performs fast, lightweight DOM diffing/patching without a virtual DOM. It compares the current DOM with new content and applies only the necessary changes.

Using children_only: true

When morphing with children_only: true, the provided html must follow these rules to succeed:

1. It must have a single top-level container element with the same CSS selector as the target.
2. Inside that container, there must be an element node, not a text node.

Example for collections: If rendering a collection of partials, wrap the render in a container because the top-level container cannot exist inside each individual partial.

# Correct way to morph a collection
morph(
  children_only: true,
  selector: "#bar",
  html: "<div id=\"bar\">" + render(Bar.all) + "</div>"
)

Customizing morph via Lifecycle Events

You can modify operation parameters in the cable-ready:before-morph event. The event.detail.content object provides a direct reference to the internal template element's content (a DocumentFragment).

Important: You cannot assign a new value to event.detail.content. Instead, mutate the children inside the content using standard DOM APIs:

document.addEventListener('cable-ready:before-morph', event => {
  event.detail.content.querySelector('#foo').style.color = 'red'
})

Parameters:

• selector (required): CSS selector or XPath expression.
• html: The HTML to use for morphing.
• children_only: (Optional) If true, only morphs child nodes, skipping the parent.
• permanent_attribute_name: (Optional) An attribute name (e.g., data-permanent) that prevents elements from being updated.
• batch, cancel, delay, focus_selector, select_all, xpath: (See standard operation options)

Lifecycle Events:

• cable-ready:before-morph
• cable-ready:after-morph

morph(
  selector: "#content",
  html: "<div id='content'>New Content</div>",
  permanent_attribute_name: "data-permanent"
)

Instead of using string-based stream identifiers (e.g., "sailors"), you can broadcast to specific ActiveRecord models using Rails' Global ID functionality. This allows you to shift the mental model from "who are we broadcasting to?" to "what is each individual user interested in?"

To implement this:

1. In your ActionCable Channel, use stream_for (or stream_or_reject_for for sensitive data) to subscribe to a specific resource based on params.
2. On the client, subscribe to the Channel as usual, passing the resource's ID in the params.
3. Use cable_ready[ChannelClass].dispatch_event.broadcast_to(resource) to send operations to everyone subscribed to that specific resource instance.

# Server-side: Subscribe to a resource
class HelensChannel < ApplicationCable::Channel
  def subscribed
    stream_for Helen.find(params[:id])
  end
end

# Client-side: Subscribe to the channel
consumer.subscriptions.create({
  channel: 'HelensChannel',
  id: 30
}, {
  received (data) {
    if (data.cableReady) {
      CableReady.perform(data.operations)
    }
  }
})

# Server-side: Broadcast to the resource
helen = Helen.find(30)
cable_ready[HelensChannel]
  .dispatch_event
  .broadcast_to(helen)

CableReady uses a singleton instance for its identifier queues. This allows you to accumulate multiple operations for the same identifier across different parts of your code before finally dispatching them.

Key Behaviors

• Accumulation: Calling cable_ready["identifier"] multiple times adds new operations to the existing queue for that identifier.
• Method Chaining: The CableReady::Channels object returned by cable_ready["identifier"] supports chaining. Operations are broadcast in the exact order they were called.
• Clearing Queues: The .broadcast method concludes the chain and empties the queues for the dispatched operations.
• Selectors: Most operations accept a selector to target DOM elements. You can pass the selector as the first argument without a key for brevity.

Examples

Accumulating operations:

# First call adds a log
cable_ready["visitors"]
  .console_log(message: "We have more salad than we can eat.")

# Second call adds a style change to the same queue
cable_ready["visitors"]
  .set_style(selector: "body", name: "color", value: "red")

# Finally, send both
cable_ready["visitors"].broadcast

Chaining operations:

# Multiple operations in one chain
cable_ready["visitors"]
  .console_log(message: "1")
  .console_log(message: "2")
  .broadcast

Using shorthand selectors:

# Passing selector as the first positional argument
cable_ready["visitors"]
  .set_style("#foo", name: "color", value: "blue")

All CableReady operations emit DOM CustomEvents immediately before and after execution.

• Event Naming: Follows the pattern cable-ready:before-{operation} and cable-ready:after-{operation} (e.g., cable-ready:after-morph).
• Targeting: Events are emitted from the target selector if provided; otherwise, they default to document.
• Bubbling: Events bubble and can be cancelled.
• jQuery Support: If jQuery is present, matching jQuery events are triggered immediately after the DOM events.
• Exceptions: Operations like dispatch_event and console_log do not emit life-cycle events.

Note: Do not confuse these life-cycle events with ad-hoc events sent via dispatch_event operations. Life-cycle events are built-in library behaviors.

// Use named functions for callbacks to ensure they can be removed later
const afterMorphHandler = event => console.log(event.detail)

document.addEventListener('cable-ready:after-morph', afterMorphHandler)