CableReady
Search…
v5.0 pre-release
DOM Events
dispatch_event
Create a custom DOM event in the browser for the purpose of implementing custom functionality.
dispatch_event immediately dispatches a DOM CustomEvent in the browser. These events bubble up through the DOM and are cancelable.If jQuery is in use (and available in the global
window scope) dispatch_event will also trigger a jQuery event with the same name.1
dispatch_event(
2
batch: String, # [null] - add the operation to a named batch
3
cancel: Boolean, # [false] - cancel the operation (for use on client)
4
delay: Integer, # [0] - wait for n milliseconds before running
5
detail: Object, # [null] - assigned to event.detail
6
name: String, # required - the name of the DOM event to dispatch (can be custom)
7
select_all: Boolean, # [false] - operate on list of elements returned from selector
8
selector: String, # [document] - string containing a CSS selector or XPath expression
9
xpath: Boolean # [false] - process the selector as an XPath expression
10
)
Copied!
While the event itself is frequently the payload, you can build very powerful functionality by passing a Hash of metadata to the
detail parameter.The
detail parameter will convert user_id to userId - snake_case to camelCase - for JS consumption on the client.Developers frequently use
dispatch_event to notify the client when long-running server processes are completed. You can see an example in Leveraging Stimulus.Life-cycle Callback Events
cable-ready:before-dispatch-eventcable-ready:after-dispatch-event
Life-cycle events for
dispatch_event are raised on document.Reference
set_meta
Add a
meta tag to your document head. If a meta tag with the same name already exists, update the content to a new value.1
set_meta(
2
batch: String, # [null] - add the operation to a named batch
3
cancel: Boolean, # [false] - cancel the operation (for use on client)
4
content: String, # required - the content attribute of the meta tag
5
delay: Integer, # [0] - wait for n milliseconds before running
6
name: String # required - the name attribute of the meta tag
7
)
Copied!
meta tags are under-appreciated as a semantically-appropriate place to place data that can be consumed by multiple components on a page. It's even less common to see scenarios where a meta tag is updated after the page has been rendered. This is a shame, because there's absolutely no good reason not to do so.Example
Here is a Stimulus controller that watches a
meta tag for content changes, which update the attached element. In this example, imagine a notification "pill" component that is not displayed if there is no text value.1
import { Controller } from 'stimulus'
2
3
export default class extends Controller {
4
static values = { tag: String }
5
6
initialize () {
7
this.metaTag = document.head.querySelector(
8
`meta[name=pill-${this.tagValue}]`
9
)
10
this.element.textContent = this.metaTag.content
11
this.observer = new MutationObserver(this.meta)
12
}
13
14
connect () {
15
this.observer.observe(this.metaTag, {
16
attributeFilter: ['content']
17
})
18
}
19
20
disconnect () {
21
this.observer.disconnect()
22
}
23
24
meta = mutation => {
25
this.element.textContent = mutation[0].target.content || ''
26
}
27
}
Copied!
1
<head>
2
<meta name="pill-messages" content="4" />
3
</head>
4
5
<span class="badge text-danger" data-controller="pill" data-pill-tag-value="messages"></span>
Copied!
This technique allows the developer to update data that concerns the page without a potentially brittle expectation that the server knows the
id of every component that needs to be updated.Life-cycle Callback Events
cable-ready:before-set-metacable-ready:after-set-meta
Life-cycle events for
set_meta are raised on document.Reference
Last modified 5mo ago
Export as PDF
Copy link