Events API
Overview
Besides adding event listeners, "data-*" attributes can be used to directly bind events and components to DOM elements in the HTML markup.
"data-*" attributes can accept various formats, including string, JSON, object, array, partial object, and partial array:
<div data-click="component_1"></div>
<div data-click="component_1, component_2"></div>
<div data-click="[component_1, component_2]"></div>
<div data-click="component_1: 'book', component_2: 'cat'"></div>
<div data-click="{component_1: 'book', component_2: 'cat'}"></div>
<div data-click='{"component_1": "book", "component_2": "cat"}'></div>
When events are triggered via "data-*" attributes, standard event objects will be passed to the specified components, with the following additional properties:
Property
Type
Description
it
DOM element
The element the event was assigned to.
While "target" points to the specific element that triggered the event, "it" references the assigned element.
If an event is bound to a <div> and triggered on a child <span>, "target" will be <span>, and "it" will be <div>.
While "target" points to the specific element that triggered the event, "it" references the assigned element.
If an event is bound to a <div> and triggered on a child <span>, "target" will be <span>, and "it" will be <div>.
itType
string
The actual type of the event.
For example, for a "click-out" event, the "type" property will be "click", while the "itType" property will represent "click-out".
For example, for a "click-out" event, the "type" property will be "click", while the "itType" property will represent "click-out".
calls
number
The number of times the current event type is triggered on the assigned element.
To trigger events, they must be enabled in the "events" property of the "config.js" configuration file, e.g., "click: true".
Example of HTML markup with a "click" event bound to a button:
<!-- Executes the "component_1" component when a button or any of its child elements is clicked. -->
<button data-click="component_1">
<span></span>
</button>
When an event is triggered, multiple components can be run at once:
<!-- Executes the components "component_1" and "component_2" on click. -->
<button data-click="component_1, component_2"></button>
Pass the necessary data to make the components universal and multifunctional:
<!-- Executes the component "component_1" with the specified data when clicked. -->
<button data-click="component_1: null"></button>
<button data-click="component_1: 'book'"></button>
<button data-click="component_1: {'book': [1, 2]}"></button>
<!-- Executes the components "component_1" and "component_2" with the specified data when clicked. -->
<button data-click="
component_1: null,
component_2: true
"></button>
<button data-click="
component_1: 'book',
component_2: 'cat'
"></button>
<button data-click="
component_1: {'book': [1, 2]},
component_2: null
"></button>
This data will serve as the second argument within the components.
The necessary DOM elements can also be passed directly to the components:
<!-- Pass the first <div> element found. -->
<button data-click="component_1: $('div')"></button>
<!-- Pass all the <div> elements found. -->
<button data-click="component_1: $('div ?')"></button>
<!-- Pass the parent element <div>. -->
<button data-click="component_1: $('.. div')"></button>
<!-- Pass the first <span> element found inside the current element. -->
<button data-click="component_1: $('@ span')">
<span></span>
</button>
<!-- Pass an array of elements. -->
<button data-click="
component_1: [
$('div ? 0'),
$('div ? 2')
]
"></button>
<!-- Pass an object of elements. -->
<button data-click="
component_1: {
book: $('<<'),
cat: $('@ span')
}
"></button>
The "@" symbol can be placed at the beginning of a selector, which indicates starting from the current element.
If just "@" is specified, it will return the current element itself.
Additionally, if a selector starts with "..", "<<", ">>", "~~", "::", or "~~", it specifies starting from the current element.
More details about selectors can be found in the DOM Elements API documentation.
If just "@" is specified, it will return the current element itself.
Additionally, if a selector starts with "..", "<<", ">>", "~~", "::", or "~~", it specifies starting from the current element.
More details about selectors can be found in the DOM Elements API documentation.
The necessary DOM elements can also be passed directly to the components using the "data-use" attribute:
<!--
An object with the "block" property, containing an array of <div> elements,
will be passed to the "component_1" component.
An object with the "blockSecond" property, containing a <span> element,
will be passed to the components "component_2" and "component_3".
-->
<button data-click="component_1, component_2"></button>
<button data-click="component_3"></button>
<div data-use="component_1" data-name="block"></div>
<div data-use="component_1" data-name="block"></div>
<span data-use="component_2, component_3" data-name="blockSecond"></span>
A single DOM element can be passed to multiple components at once, separated by commas.
The property name in the object is determined by the "data-name" attribute.
If "data-name" attribute is not specified, the property name will default to "use".
If multiple DOM elements with "data-use" attributes share the same "data-name" value, an array of these DOM elements will be passed to the component.
DOM elements with "data-use" attributes can be placed anywhere in the document.
The property name in the object is determined by the "data-name" attribute.
If "data-name" attribute is not specified, the property name will default to "use".
If multiple DOM elements with "data-use" attributes share the same "data-name" value, an array of these DOM elements will be passed to the component.
DOM elements with "data-use" attributes can be placed anywhere in the document.
Waiting for components to complete before executing the next, with unlimited nesting, is supported via the "await" property:
<!-- The component "component_2" executes only after the component "component_1" has completed. -->
<button data-click="
component_1: {
await: {
component_2: null
}
}
"></button>
<!--
The components "component_2" and "component_3" execute only after the component "component_1" has completed.
The component "component_4" executes only after the component "component_3" has completed.
-->
<button data-click="
component_1: {
name: 'cat',
secondName: 'book',
await: {
component_2: null,
component_3: {
name: 'cat',
secondName: 'book',
await: {
component_4: $('div')
}
}
}
}
"></button>
The "await" property uses the component name as the key and the data passed to it as the value.
Binding multiple events to a single DOM element is supported:
<button data-click="component_1" data-contextmenu="component_1, component_2"></button>
<textarea data-input="component_1" data-resize="component_2" data-visible="component_3"></textarea>
<button
data-click="
component_1: {
name: 'cat',
secondName: 'book',
await: {
component_2: null
}
}
"
data-contextmenu="
component_1: {
name: 'cat 2',
secondName: 'book 2',
await: {
component_2: null
}
}
"
></button>
The "-in" modifier allows binding events to a DOM element's direct descendants:
<!-- The event triggers only when <li> elements are clicked. -->
<ul data-click-in="component_1">
<li></li>
<li></li>
<li></li>
</ul>
Since events are tied to a DOM element's descendants using the "-in" modifier, the "it" property of the event object refers to the direct descendant that triggered the event.
The "-out" modifier triggers events on the DOM element when the current DOM element is not the target of the event:
<!--
The event will be triggered on the <div> element
only if the click occurs outside of it or its child elements.
-->
<div data-click-out="component_1">
<span></span>
</div>
The maximum number of event triggers can be limited using the "data-call-*" attribute:
<!--
The "click" event will be triggered every time the <button> is clicked.
The "visible" event will only trigger once, the first time it is called.
-->
<button data-click="component_1" data-visible="component_2" data-call-visible="1"></button>
The frequency of event triggers can be controlled using the "data-debounce-*" and "data-throttle-*" attributes:
<!-- Executes the component "component_1" after a 500ms input delay. -->
<input type="text" data-input="component_1" data-debounce-input="500">
<!-- Executes the component "component_1" no more than once every 500ms during input. -->
<input type="text" data-input="component_1" data-throttle-input="500">
<!-- Executes the component "component_1" after a 500ms scroll delay. -->
<div data-scroll="component_1" data-debounce-scroll="500"></div>
<!-- Executes the component "component_1" no more than once every 500ms during scroll. -->
<div data-scroll="component_1" data-throttle-scroll="500"></div>
The valid value for the "data-debounce-*" and "data-throttle-*" attributes is any number that specifies the delay in milliseconds.
The "data-debounce-*" attribute is used to ensure that event triggers are executed only after a specified period of inactivity.
For example, with a 500ms delay, event triggers will execute once after 500ms of inactivity.
The "data-throttle-*" attribute is used to restrict event triggers to at most once within a specified timeframe.
For example, with a 500ms delay, the event triggers can occur every 500ms but not more frequently.
The "data-debounce-*" attribute is used to ensure that event triggers are executed only after a specified period of inactivity.
For example, with a 500ms delay, event triggers will execute once after 500ms of inactivity.
The "data-throttle-*" attribute is used to restrict event triggers to at most once within a specified timeframe.
For example, with a 500ms delay, the event triggers can occur every 500ms but not more frequently.
Initially, events for specific DOM elements can be disabled using the "data-event" and "data-off" attributes:
<!-- Disables all events associated with the <div> element. -->
<div data-event="false"></div>
<!-- Disables the specified events associated with the <div> element. -->
<div data-off="click, visible"></div>
Events that support interaction with DOM elements via "data-*" attributes:
Event
Description
ready
An equivalent to the standard DOMContentLoaded event.
Triggers when the HTML document has been fully parsed.
It will not trigger again during navigation without a page reload.
Triggers when the HTML document has been fully parsed.
It will not trigger again during navigation without a page reload.
init
Triggers when the HTML document has been fully parsed and also every time during navigation without a page reload, updating content or managing templates.
The event object has the following properties:
The event object has the following properties:
Property
Type
Description
it
DOM element
The element the event was assigned to.
While "target" points to the specific element that triggered the event, "it" references the assigned element.
If an event is bound to a <div> and triggered on a child <span>, "target" will be <span>, and "it" will be <div>.
While "target" points to the specific element that triggered the event, "it" references the assigned element.
If an event is bound to a <div> and triggered on a child <span>, "target" will be <span>, and "it" will be <div>.
calls
number
The number of times the current event type is triggered on the assigned element.
raw
boolean
If true, the current DOM element has not yet been initialized.
If false, it has already been initialized.
If false, it has already been initialized.
type
string
Specifies the trigger type, such as:
Value
Description
'ready'
The event was triggered after the HTML document was fully parsed.
'load'
The event was triggered after the entire page, including all dependent resources such as stylesheets, scripts, frames, and images (except for those that are lazily loaded), had fully loaded.
'spa'
The event was triggered during navigation without a page reload.
'content'
The event was triggered when updating content with built-in methods.
'tpl'
The event was triggered when managing templates with built-in methods.
custom
The event was triggered when the init() built-in method was called.
popstate
Triggered every time browser navigation is used.
Provides a standard PopStateEvent object with an additional "previous" property that includes:
Provides a standard PopStateEvent object with an additional "previous" property that includes:
Property
Type
Description
it
DOM element
The element the event was assigned to.
calls
number
The number of times the current event type is triggered on the assigned element.
path
string
URL path of the previous page.
spa
string
The key of the object used from the "spa" property in the "config.js" configuration file for the previous page.
component
string
null
null
The name of the component used on the previous page; otherwise, it will be null.
api
object
The object that was used by the previous page to make the API request.
More details about the API object can be found in the Dynamic Application API documentation.
More details about the API object can be found in the Dynamic Application API documentation.
type
string
The event type will be "popstate".
state
Triggered every time the URL in the address bar is modified.
The event object has the following properties:
The event object has the following properties:
Property
Type
Description
it
DOM element
The element the event was assigned to.
calls
number
The number of times the current event type is triggered on the assigned element.
current
object
The object has the following properties:
Property
Type
Description
path
string
URL path of the current page.
spa
string
The key of the object used from the "spa" property in the "config.js" configuration file for the current page.
component
string
null
null
The name of a component or an object containing components dynamically used on the current page; otherwise, it is null.
api
object
The object that was used by the current page to make the API request.
More details about the API object can be found in the Dynamic Application API documentation.
More details about the API object can be found in the Dynamic Application API documentation.
previous
object
The object has the following properties:
Property
Type
Description
path
string
URL path of the previous page.
spa
string
The key of the object used from the "spa" property in the "config.js" configuration file for the previous page.
component
string
null
null
The name of a component or an object containing components dynamically used on the previous page; otherwise, it is null.
api
object
The object that was used by the previous page to make the API request.
More details about the API object can be found in the Dynamic Application API documentation.
More details about the API object can be found in the Dynamic Application API documentation.
type
string
The event type will be "state".
prestate
Triggers every time navigation occurs without a page reload or when browser navigation is used, happening before "spa" or "popstate" events.
api
Triggered every time an API request occurs.
The event object has the following properties:
The event object has the following properties:
Property
Type
Description
it
DOM element
The element the event was assigned to.
calls
number
The number of times the current event type is triggered on the assigned element.
request
object
The object used for the API request.
More details about the API object can be found in the Dynamic Application API documentation.
More details about the API object can be found in the Dynamic Application API documentation.
response
object
string
string
The response data from the API request.
type
string
The event type will be "api".
spa
Triggers every time during navigation without a page reload for a current DOM element or URL path.
If false is specified, the link will have standard behavior.
If false is specified, the link will have standard behavior.
stream
Triggered every time the stream() method is called.
The event object has the following properties:
The event object has the following properties:
Property
Type
Description
it
DOM element
The element the event was assigned to.
calls
number
The number of times the current event type is triggered on the assigned element.
request
object
The object used for the request.
More details about the object can be found in the stream() method documentation.
More details about the object can be found in the stream() method documentation.
response
object
string
string
The response data from the request.
type
string
The event type will be "stream".
resize
Triggers every time the current DOM element is resized.
Provides a standard ResizeObserverEntry event object with additional properties: "it", "itType", "type", and "calls".
Provides a standard ResizeObserverEntry event object with additional properties: "it", "itType", "type", and "calls".
visible
Triggers every time the current DOM element becomes visible in the viewport.
Provides a standard IntersectionObserverEntry event object with additional properties: "it", "itType", "type", and "calls".
The configuration can be set via the "data-config-visible" attribute, which accepts the following properties:
If an "events.visible" object is defined in the "config.js" configuration file, it will override the default values.
Provides a standard IntersectionObserverEntry event object with additional properties: "it", "itType", "type", and "calls".
The configuration can be set via the "data-config-visible" attribute, which accepts the following properties:
Option
Type
Default
Description
root
DOM element
null
The element used as the viewport for observing intersections. Defaults to the browser viewport if set to null.
rootMargin
string
0px 0px 0px 0px
Margins around the root (in CSS syntax). Expands or shrinks the effective viewport for intersection calculations.
threshold
number
array
array
0
A single number or array of numbers (0 to 1) indicating at what percentage of the target's visibility the observer's callback should be triggered.
invisible
Triggers every time the current DOM element becomes invisible in the viewport.
Provides a standard IntersectionObserverEntry event object with additional properties: "it", "itType", "type", and "calls".
The configuration can be set via the "data-config-invisible" attribute, which accepts the following properties:
If an "events.invisible" object is defined in the "config.js" configuration file, it will override the default values.
Provides a standard IntersectionObserverEntry event object with additional properties: "it", "itType", "type", and "calls".
The configuration can be set via the "data-config-invisible" attribute, which accepts the following properties:
Option
Type
Default
Description
root
DOM element
null
The element used as the viewport for observing intersections. Defaults to the browser viewport if set to null.
rootMargin
string
0px 0px 0px 0px
Margins around the root (in CSS syntax). Expands or shrinks the effective viewport for intersection calculations.
threshold
number
array
array
0
A single number or array of numbers (0 to 1) indicating at what percentage of the target's visibility the observer's callback should be triggered.
content
Triggers every time content changes in the current DOM element, either through navigation without a page reload or when the built-in content() method is called.
The event object has the following properties:
The event object has the following properties:
Property
Type
Description
it
DOM element
The element the event was assigned to.
calls
number
The number of times the current event type is triggered on the assigned element.
api
object
The object used for the API request.
More details about the API object can be found in the Dynamic Application API documentation.
More details about the API object can be found in the Dynamic Application API documentation.
update
object
array
DOM element
array
DOM element
Includes all elements whose content has been updated and matches keys with the "result" property if it is an object.
loader
DOM element
array
array
The element or an array of elements that handles the loaders.
mode
string
boolean
boolean
If the content was completely replaced, it will be false.
Otherwise, it will be one of the following values: "before", "after", "begin", or "end", indicating the place where the content was added.
Otherwise, it will be one of the following values: "before", "after", "begin", or "end", indicating the place where the content was added.
spa
string
boolean
boolean
The key of the object used from the "spa" property in the "config.js" configuration file if navigation occurred without reloading; otherwise, it is false.
result
object
string
string
The response data from the API request.
type
string
The event type will be "content".
mutation
Triggers every time changes occur to the current DOM element or its children.
Provides a standard MutationRecord event object with the additional property "it".
Configuration can be set using the "events.mutation" object in the "config.js" configuration file.
Provides a standard MutationRecord event object with the additional property "it".
Configuration can be set using the "events.mutation" object in the "config.js" configuration file.
abort
A standard event type.
animation
This event listener will handle the following events: "animationcancel", "animationend", "animationiteration", and "animationstart".
animationcancel
A standard event type.
animationend
A standard event type.
animationiteration
A standard event type.
animationstart
A standard event type.
auxclick
A standard event type.
beforecopy
A standard event type.
beforecut
A standard event type.
beforeinput
A standard event type.
beforepaste
A standard event type.
blur
A standard event type.
canplay
A standard event type.
canplaythrough
A standard event type.
change
A standard event type.
click
A standard event type.
contextmenu
A standard event type.
copy
A standard event type.
cuechange
A standard event type.
cut
A standard event type.
dblclick
A standard event type.
dragdrop
This event listener will handle the following events: "drag", "dragend", "dragenter", "dragleave", "dragover", "dragstart", and "drop".
drag
A standard event type.
dragend
A standard event type.
dragenter
A standard event type.
dragleave
A standard event type.
dragover
A standard event type.
dragstart
A standard event type.
drop
A standard event type.
durationchange
A standard event type.
emptied
A standard event type.
ended
A standard event type.
error
A standard event type.
focus
A standard event type.
focusin
A standard event type.
focusout
A standard event type.
fullscreenchange
A standard event type.
gotpointercapture
A standard event type.
input
A standard event type.
key
This event listener will handle the following events: "keydown", "keypress", and "keyup".
keydown
A standard event type.
keypress
A standard event type.
keyup
A standard event type.
load
A standard event type.
loadstart
A standard event type.
loadeddata
A standard event type.
loadedmetadata
A standard event type.
lostpointercapture
A standard event type.
mouse
This event listener will handle the following events: "mousedown", "mouseenter", "mouseleave", "mousemove", "mouseout", "mouseover", and "mouseup".
mousedown
A standard event type.
mouseenter
A standard event type.
mouseleave
A standard event type.
mousemove
A standard event type.
mouseout
A standard event type.
mouseover
A standard event type.
mouseup
A standard event type.
paste
A standard event type.
pause
A standard event type.
play
A standard event type.
playing
A standard event type.
pointer
This event listener will handle the following events: "pointercancel", "pointerdown", "pointerenter", "pointerleave", "pointerlockchange", "pointerlockerror", "pointermove", "pointerout", "pointerover", "pointerrawupdate", and "pointerup".
pointercancel
A standard event type.
pointerdown
A standard event type.
pointerenter
A standard event type.
pointerleave
A standard event type.
pointerlockchange
A standard event type.
pointerlockerror
A standard event type.
pointermove
A standard event type.
pointerout
A standard event type.
pointerover
A standard event type.
pointerrawupdate
A standard event type.
pointerup
A standard event type.
progress
A standard event type.
ratechange
A standard event type.
reset
A standard event type.
scroll
A standard event type.
seeked
A standard event type.
seeking
A standard event type.
select
A standard event type.
stalled
A standard event type.
submit
A standard event type.
suspend
A standard event type.
timeupdate
A standard event type.
touch
This event listener will handle the following events: "touchcancel", "touchend", "touchmove", and "touchstart".
touchcancel
A standard event type.
touchend
A standard event type.
touchmove
A standard event type.
touchstart
A standard event type.
transition
This event listener will handle the following events: "transitioncancel", "transitionend", "transitionrun", and "transitionstart".
transitioncancel
A standard event type.
transitionend
A standard event type.
transitionrun
A standard event type.
transitionstart
A standard event type.
volumechange
A standard event type.
waiting
A standard event type.
wheel
A standard event type.
Outside of "data-*" attributes, any available JavaScript events can be raised.
Additionally, events from "data-*" attributes can also be used globally.
Additionally, events from "data-*" attributes can also be used globally.