CableReady

Appearance

Return to top
On this page

DOM Mutations

append

Inserts HTML into the DOM, inside the target element, after its last child.

ruby
append(
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  html:           String,  # [null]   - the HTML to assign
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-append
  • cable-ready:after-append

Reference

graft

Reparent the target element and its children to a new parent element in the DOM.

Grafted elements are moved, not recreated. This means that any Stimulus controllers attached to an element will disconnect and then immediatelyconnect again, but their internal state remains intact.

ruby
graft(  
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  parent:         String,  # [null]   - string containing a CSS selector
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-graft
  • cable-ready:after-graft

Reference

inner_html

Sets the innerHTML of a DOM element.

ruby
inner_html(  
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  html:           String,  # [null]   - the HTML to assign
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-inner-html
  • cable-ready:after-inner-html

Reference

insert_adjacent_html

Inserts HTML into the DOM relative to an element. Positions are as follows, defaulting to beforeend:

  • beforebegin: Before the target element itself
  • afterbegin: Inside the target element, before its first child
  • beforeend: Inside the target element, after its last child
  • afterend: After the target element itself
ruby
insert_adjacent_html(
  batch:          String,  # [null]      - add the operation to a named batch
  cancel:         Boolean, # [false]     - cancel the operation (for use on client)
  delay:          Integer, # [0]         - wait for n milliseconds before running
  focus_selector: String,  # [null]      - string containing a CSS selector
  html:           String,  # [null]      - the HTML to insert
  position:       String,  # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
  select_all:     Boolean, # [false]     - operate on list of elements returned from selector
  selector:       String,  # required    - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]     - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-insert-adjacent-html
  • cable-ready:after-insert-adjacent-html

Reference

insert_adjacent_text

Inserts text into the DOM relative to an element. Positions are as follows, defaulting to beforeend:

  • beforebegin: Before the target element itself
  • afterbegin: Inside the target element, before its first child
  • beforeend: Inside the target element, after its last child
  • afterend: After the target element itself
ruby
insert_adjacent_text(
  batch:          String,  # [null]      - add the operation to a named batch
  cancel:         Boolean, # [false]     - cancel the operation (for use on client)
  delay:          Integer, # [0]         - wait for n milliseconds before running
  focus_selector: String,  # [null]      - string containing a CSS selector
  position:       String,  # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
  select_all:     Boolean, # [false]     - operate on list of elements returned from selector
  selector:       String,  # required    - string containing a CSS selector or XPath expression
  text:           String,  # [null]      - the text to insert
  xpath:          Boolean  # [false]     - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-insert-adjacent-text
  • cable-ready:after-insert-adjacent-text

Reference

morph

Fast lightweight DOM diffing/patching without a virtual DOM.

ruby
morph(
  batch:                    String,  # [null]    - add the operation to a named batch
  cancel:                   Boolean, # [false]   - cancel the operation (for use on client)
  children_only:            Boolean, # [false]   - indicates if only child nodes should be morphed... skipping the parent element
  content:                  String,  # reference - the content that is going to be used to morph
  delay:                    Integer, # [0]       - wait for n milliseconds before running
  focus_selector:           String,  # [null]    - string containing a CSS selector
  html:                     String,  # [null]    - the HTML to assign  
  permanent_attribute_name: String,  # [null]    - an attribute name that prevents elements from being updated i.e. "data-permanent"
  select_all:               Boolean, # [false]   - operate on list of elements returned from selector
  selector:                 String,  # required  - string containing a CSS selector or XPath expression
  xpath:                    Boolean  # [false]   - process the selector as an XPath expression
)

When morphing an element with children_only: true you need to make sure that the content you're providing to the html value will result in a successful operation:

  • it must have a single top-level container element with the same CSS selector as the target
  • inside that container element is another element node, not a text node

Consider the following example of #foo, a successful morphing candidate:

html
<div>
  <%= render partial: "foo", locals: {message: "Am I the medium or the massage?"} %>
</div>
html
<div id="foo">
  <span><%= message %></span>
</div>

If the <div id="foo"> was located in show.html.erb the morph would not succeed because the top-level container that you're replacing would not be present in the replacement HTML.

If you need to render a collection of partials, you'll have to wrap the render method in a container because you cannot have the top-level container in each partial:

html
<div id="bar">
  <%= render collection: @bars %>
</div>
html
<span><%= bar.message %></span>
ruby
morph(
  children_only: true,
  selector: "#bar",
  html: "<div id=\"bar\">" + render(Bar.all) + "</div>"
)

Life-cycle Callback Events

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

As with all operations, you can modify the items in the event.detail object inside of a before-morph to change the parameters of how the operation will be executed.

The morph operation's event.detail object has a special key called content which is a direct reference to the internal template element's content accessor holding the document fragment that will be morphed into your DOM.

This means that you can change the content which will soon be morphed into your page, but you cannot assign the content to a new value. Doing so would remove the reference!

Instead, use the DOM API and mutate children inside of the content:

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

Reference

outer_html

Replaces a DOM element with new HTML.

ruby
outer_html(
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  html:           String,  # [null]   - the HTML to use as replacement
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-outer-html
  • cable-ready:after-outer-html

Reference

prepend

Inserts HTML into the DOM, inside the target element, before its first child.

ruby
prepend(  
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  html:           String,  # [null]   - the HTML to assign
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-prepend
  • cable-ready:after-prepend

Reference

remove

Removes an element from the DOM.

ruby
remove(
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-remove
  • cable-ready:after-remove

Reference

replace

Replaces a DOM element with new HTML. This operation is an alias of outer_html and has the same implementation.

ruby
replace(
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  html:           String,  # [null]   - the HTML to use as replacement
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-replace
  • cable-ready:after-replace

Reference

text_content

Sets the text content of a DOM element.

INFO

CableReady sets textContent instead of innerText. You can learn more here, or just move on with your day. ☀️

ruby
text_content(
  batch:          String,  # [null]   - add the operation to a named batch
  cancel:         Boolean, # [false]  - cancel the operation (for use on client)
  delay:          Integer, # [0]      - wait for n milliseconds before running
  focus_selector: String,  # [null]   - string containing a CSS selector
  select_all:     Boolean, # [false]  - operate on list of elements returned from selector
  selector:       String,  # required - string containing a CSS selector or XPath expression
  text:           String,  # [null]   - the text to assign
  xpath:          Boolean  # [false]  - process the selector as an XPath expression
)

Life-cycle Callback Events

  • cable-ready:before-text-content
  • cable-ready:after-text-content

Reference

Released under the MIT License.

Copyright © 2023