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.
cable_ready["MyChannel"].add_css_class(name: "string", # [null] - string containing the CSS class name to addselector: "string", # required - string containing a CSS selector or XPath expressionxpath: true|false # [false] - process the selector as an XPath expression)
Use an array to add multiple classes to an element.
cable_ready["MyChannel"].add_css_class(name: ["string", "string2"], # [null] - array with the CSS class names to addselector: "string", # required - string containing a CSS selector or XPath expressionxpath: true|false # [false] - process the selector as an XPath expression)
cable-ready:before-add-css-class
cable-ready:after-add-css-class
Removes an attribute from an element.
cable_ready["MyChannel"].remove_attribute(name: "string", # required - the attribute to removeselector: "string", # required - string containing a CSS selector or XPath expressionxpath: true|false # [false] - process the selector as an XPath expression)
cable-ready:before-remove-attribute
cable-ready:after-remove-attribute
Removes a CSS class from an element.
cable_ready["MyChannel"].remove_css_class(name: "string", # [null] - string containing the CSS class name to removeselector: "string", # required - string containing a CSS selector or XPath expressionxpath: true|false # [false] - process the selector as an XPath expression)
Use an array to removes multiple classes from an element.
cable_ready["MyChannel"].remove_css_class(name: ["string", "string2"], # [null] - array with the CSS class names to removeselector: "string", # required - string containing a CSS selector or XPath expressionxpath: true|false # [false] - process the selector as an XPath expression)
cable-ready:before-remove-css-class
cable-ready:after-remove-css-class
Sets an attribute on an element.
cable_ready["MyChannel"].set_attribute(name: "string", # required - the attribute to setselector: "string", # required - string containing a CSS selector or XPath expressionvalue: "string", # [null] - the value to assign to the attributexpath: true|false # [false] - process the selector as an XPath expression)
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.
cable-ready:before-set-attribute
cable-ready:after-set-attribute
Sets an dataset property (data-* attribute) on an element.
cable_ready["MyChannel"].set_dataset_property(name: "string", # required - the property to setselector: "string", # required - string containing a CSS selector or XPath expressionvalue: "string", # [null] - the value to assign to the datasetxpath: true|false # [false] - process the selector as an XPath expression)
This method pairs extremely well with the new Values and Classes APIs coming in Stimulus v2, 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:
export default class extends Controller {static values = { index: Number }indexValueChanged() {this.showSlide(this.indexValue)}// ...}
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.
cable-ready:before-set-dataset-property
cable-ready:after-set-dataset-property
Sets a valid property on an element to a new value.
cable_ready["MyChannel"].set_property(name: "string", # required - string containing a valid propertyselector: "string", # required - string containing a CSS selector or XPath expressionvalue: "string", # [null] - the value to assign to the propertyxpath: true|false # [false] - process the selector as an XPath expression)
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.
cable-ready:before-set-property
cable-ready:after-set-property
Sets a single style on an element.
cable_ready["MyChannel"].set_style(name: "string", # required - the style to setselector: "string", # required - string containing a CSS selector or XPath expressionvalue: "string", # [null] - the value to assign to the stylexpath: true|false # [false] - process the selector as an XPath expression)
cable-ready:before-set-style
cable-ready:after-set-style
Sets multiple styles on an element.
cable_ready["MyChannel"].set_styles(selector: "string", # required - string containing a CSS selector or XPath expressionstyles: {background: "red",color: "white"},xpath: true|false # [false] - process the selector as an XPath expression)
cable-ready:before-set-styles
cable-ready:after-set-styles
Sets the value of an element.
cable_ready["MyChannel"].set_value(selector: "string", # required - string containing a CSS selector or XPath expressionvalue: "string", # [null] - the value to assign to the attributexpath: true|false # [false] - process the selector as an XPath expression)
Remember, setting the value
property of a DOM element will not add or modify any value
attribute on the element.
cable-ready:before-set-value
cable-ready:after-set-value