Methods
fire(targets, events, payloadopt, nullable) → {Number}
Fires event handlers of all matched targets for given events.
This function does not actually dispatch events, but identifies matches in the internal event map, based on previously registered handlers using "on" and "once" and executes the attached handlers, providing them a synthetic CustomEvent as first parameter, carrying the event name as well as a potential payload. So this, function is using the event map as an event bus, instead of the DOM, so these events also will never bubble, but just hit the currently present handlers identified exactly by the provided parameters.
The definition of targets and events works exactly as in "on" and "once", the only difference being, that we have no handler, since if we'd have the handler already, we could just call it.
Since we do not use the DOM in this function, we also do not have native events, and therefore we do not have normal event targets we can work with. Instead, this implementation adds the "syntheticTarget" and the "syntheticTargetElements" event properties to the event that is given to the handler. "syntheticTarget" contains the defined event map target, either as a EventTarget or an array of an EventTarget and a corresponding delegation selector (just as you defined them before), while "syntheticTargetElements" returns the actual elements as an iterable array. So, in case of a delegation, this gives you the power to actually work with the current delegation targets, without having to write own logic for this.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
targets |
EventTarget | Array.<EventTarget> | the target(s) to execute event handlers on |
||
events |
String | Array.<String> | the event name(s) to fire, can be either a single name or a list of names, each name may also have a namespace, separated by a dot, to target all events/namespaces, you may use ""/".*" |
||
payload |
Object |
<optional> <nullable> |
null | a plain object payload to relay to the event handlers via the detail of the CustomEvent given to the handler as first parameter |
Throws:
-
error in case no targets are defined
-
error in case no events are defined
-
error in case targets are not all usable event targets
-
error in case delegations are missing viable ancestor targets
Returns:
- Type
- Number
Example
fire(buttonElement, 'click');
fire(linkElement, '*.__default', {importantFlag : true});
fire(divElement, 'crash');
fire([ancestorElement, 'a'], 'click', {linkWasClicked : true});
fire([ancestorElement, '.btn[data-foobar="test"]'], '*.delegated');
fire(linkElement, '*');
fire([ancestorElement, 'a', ancestorElement, '.btn[data-foobar="test"]'], '*.*');
fire(buttonElement, 'click.*', {price : 666});