CableReady
Search…
v4.5.0
Welcome
Installation
Setup
CableReady 101
Working with CableReady
CableReady Everywhere
Leveraging Stimulus
Stream Identifiers
Broadcasting to Resources
Customization
Troubleshooting
Advocating for "Reactive Rails"
Release History
Reference
Methods
Operations
DOM Mutations
Element Property Mutations
DOM Events
Browser Manipulations
Notifications
Powered By GitBook
Element Property Mutations

add_css_class

Adds a CSS class to an element. If the class already exists on the element, callback events will be emitted but no change will occur on the element itself.
1
cable_ready["MyChannel"].add_css_class(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # [null] - string containing the CSS class name to add
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
xpath: true|false # [false] - process the selector as an XPath expression
7
)
Copied!
Use an array to add multiple classes to an element.
1
cable_ready["MyChannel"].add_css_class(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: ["string", "string2"], # [null] - array with the CSS class names to add
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
xpath: true|false # [false] - process the selector as an XPath expression
7
)
Copied!

Life-cycle Callback Events

  • cable-ready:before-add-css-class
  • cable-ready:after-add-css-class

Reference

remove_attribute

Removes an attribute from an element.
1
cable_ready["MyChannel"].remove_attribute(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # required - the attribute to remove
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
xpath: true|false # [false] - process the selector as an XPath expression
7
)
Copied!

Life-cycle Callback Events

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

Reference

remove_css_class

Removes a CSS class from an element.
1
cable_ready["MyChannel"].remove_css_class(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # [null] - string containing the CSS class name to remove
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
xpath: true|false # [false] - process the selector as an XPath expression
7
)
Copied!
Use an array to removes multiple classes from an element.
1
cable_ready["MyChannel"].remove_css_class(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: ["string", "string2"], # [null] - array with the CSS class names to remove
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
xpath: true|false # [false] - process the selector as an XPath expression
7
)
Copied!

Life-cycle Callback Events

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

Reference

set_attribute

Sets an attribute on an element.
1
cable_ready["MyChannel"].set_attribute(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # required - the attribute to set
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
value: "string", # [null] - the value to assign to the attribute
7
xpath: true|false # [false] - process the selector as an XPath expression
8
)
Copied!
Setting an attribute changes the element's HTML, and you will see it reflected in your browser's element inspector. Conversely, properties reflect the live state of the DOM element created by interpreting the HTML.
While there is frequently a 1:1 mapping between attributes and properties, there is a long list of gotchas. For example, changing the value attribute of a text input element does not change the current value property, or vice versa. Many debugging sessions conclude with frustration over the many attribute vs property gotchas.
To set the value of a Boolean attribute, such as disabled, you can specify any value. An empty string or the name of the attribute are recommended values. All that matters is that if the attribute is present at all, regardless of its actual value, its value is considered to be true. The absence of the attribute means its value is false. By setting the value of the disabled attribute to the empty string (""), we are setting disabled to true, which results in the button being disabled.

Life-cycle Callback Events

  • cable-ready:before-set-attribute
  • cable-ready:after-set-attribute

Reference

set_dataset_property

Sets an dataset property (data-* attribute) on an element.
1
cable_ready["MyChannel"].set_dataset_property(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # required - the property to set, camelCased
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
value: "string", # [null] - the value to assign to the dataset
7
xpath: true|false # [false] - process the selector as an XPath expression
8
)
Copied!
The name parameter must be passed as camelCase and without the data- prefix. If you have an index value defined on a Stimulus controller called slide-show, you will need to set:
1
name: "slideShowIndexValue"
Copied!
This method pairs extremely well with the new Values API in Stimulus 2, which allows you to specify certain dataset properties to monitor for changes. In addition to providing an excellent way to pass initialization settings to a controller, Stimulus will also execute a special callback if the dataset value is changed:
1
export default class extends Controller {
2
static values = { index: Number }
3
​
4
indexValueChanged() {
5
this.showSlide(this.indexValue)
6
}
7
​
8
// ...
9
}
Copied!
This technique can be seen in action in the stimulus-hotkeys package. CableReady can be used to dynamically upset the user's keyboard shortcuts based on personal preferences in real-time, which is pretty damn cool.

Life-cycle Callback Events

  • cable-ready:before-set-dataset-property
  • cable-ready:after-set-dataset-property

Reference

set_property

Sets a valid property on an element to a new value.
1
cable_ready["MyChannel"].set_property(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # required - string containing a valid property
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
value: "string", # [null] - the value to assign to the property
7
xpath: true|false # [false] - process the selector as an XPath expression
8
)
Copied!
As discussed in the set_attribute description above, properties are the run-time characteristics of HTML that has been parsed and converted to a DOM element.
There are many concepts from the HTML markup that don't map cleanly to the JS representation - such as class vs. className for CSS classes - since class is a reserved word in Javascript.
While DOM elements have many standard properties, you can assign additional properties arbitrarily so long as you don't conflict with an existing property. This technique is known as "hanging" variables on DOM elements, and can be a very powerful tool. Remember: it's possible to hang variables off document and window if need be.

Life-cycle Callback Events

  • cable-ready:before-set-property
  • cable-ready:after-set-property

Reference

set_style

Sets a single style on an element.
1
cable_ready["MyChannel"].set_style(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
name: "string", # required - the style to set
4
select_all: true|false, # [false] - operate on list of elements returned from selector
5
selector: "string", # required - string containing a CSS selector or XPath expression
6
value: "string", # [null] - the value to assign to the style
7
xpath: true|false # [false] - process the selector as an XPath expression
8
)
Copied!

Life-cycle Callback Events

  • cable-ready:before-set-style
  • cable-ready:after-set-style

Reference

set_styles

Sets multiple styles on an element.
1
cable_ready["MyChannel"].set_styles(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
select_all: true|false, # [false] - operate on list of elements returned from selector
4
selector: "string", # required - string containing a CSS selector or XPath expression
5
styles: {
6
background: "red",
7
color: "white"
8
},
9
xpath: true|false # [false] - process the selector as an XPath expression
10
)
Copied!

Life-cycle Callback Events

  • cable-ready:before-set-styles
  • cable-ready:after-set-styles

Reference

set_value

Sets the value of an element.
1
cable_ready["MyChannel"].set_value(
2
cancel: true|false, # [false] - cancel the operation (for use on client)
3
select_all: true|false, # [false] - operate on list of elements returned from selector
4
selector: "string", # required - string containing a CSS selector or XPath expression
5
value: "string", # [null] - the value to assign to the attribute
6
xpath: true|false # [false] - process the selector as an XPath expression
7
)
Copied!
Remember, setting the value property of a DOM element will not add or modify any value attribute on the element.

Life-cycle Callback Events

  • cable-ready:before-set-value
  • cable-ready:after-set-value

Reference

Previous
DOM Mutations
Next
DOM Events
Last modified 6mo ago
Export as PDF
Copy link
Contents
add_css_class
remove_attribute
remove_css_class
set_attribute
set_dataset_property
set_property
set_style
set_styles
set_value