Event Class

Adds an event listener

Compiles a selector string into a filter function to identify whether Nodes along the parent axis of an event's target should trigger event notification.

This function is memoized, so previously compiled filter functions are returned if the same selector string is provided.

This function may be useful when defining synthetic events for delegate handling.

Hosted as a property of the delegate method (e.g. Y.delegate.compileFilter).

Defines a new event in the DOM event system. Implementers are responsible for monitoring for a scenario whereby the event is fired. A notifier object is provided to the functions identified below. When the criteria defining the event are met, call notifier.fire( [args] ); to execute event subscribers.

The first parameter is the name of the event. The second parameter is a configuration object which define the behavior of the event system when the new event is subscribed to or detached from. The methods that should be defined in this configuration object are on, detach, delegate, and detachDelegate. You are free to define any other methods or properties needed to define your event. Be aware, however, that since the object is used to subclass SyntheticEvent, you should avoid method names used by SyntheticEvent unless your intention is to override the default behavior.

This is a list of properties and methods that you can or should specify in the configuration object:

on

function (node, subscription, notifier) The implementation logic for subscription. Any special setup you need to do to create the environment for the event being fired--E.g. native DOM event subscriptions. Store subscription related objects and state on the subscription object. When the criteria have been met to fire the synthetic event, call notifier.fire(e). See Notifier's fire() method for details about what to pass as parameters.

detach

function (node, subscription, notifier) The implementation logic for cleaning up a detached subscription. E.g. detach any DOM subscriptions added in on.

delegate

function (node, subscription, notifier, filter) The implementation logic for subscription via Y.delegate or node.delegate. The filter is typically either a selector string or a function. You can use Y.delegate.compileFilter(selectorString) to create a filter function from a selector string if needed. The filter function expects an event object as input and should output either null, a matching Node, or an array of matching Nodes. Otherwise, this acts like on DOM event subscriptions. Store subscription related objects and information on the subscription object. When the criteria have been met to fire the synthetic event, call notifier.fire(e) as noted above.

detachDelegate

function (node, subscription, notifier) The implementation logic for cleaning up a detached delegate subscription. E.g. detach any DOM delegate subscriptions added in delegate.

publishConfig

(Object) The configuration object that will be used to instantiate the underlying CustomEvent. See Notifier's fire method for details.

processArgs

function (argArray, fromDelegate) Optional method to extract any additional arguments from the subscription signature. Using this allows on or delegate signatures like node.on("hover", overCallback, outCallback).

When processing an atypical argument signature, make sure the args array is returned to the normal signature before returning from the function. For example, in the "hover" example above, the outCallback needs to be spliced out of the array. The expected signature of the args array for on() subscriptions is:

             [type, callback, target, contextOverride, argN...]
         

And for delegate():

             [type, callback, target, filter, contextOverride, argN...]
         

where target is the node the event is being subscribed for. You can see these signatures documented for Y.on() and Y.delegate() respectively.

Whatever gets returned from the function will be stored on the subscription object under subscription._extra.

subMatch

function (sub, args) Compares a set of subscription arguments against a Subscription object to determine if they match. The default implementation compares the callback function against the second argument passed to Y.on(...) or node.detach(...) etc.

Defines a new outside event to correspond with the given DOM event.

By default, the created synthetic event name will be the name of the event with "outside" appended (e.g. "click" becomes "clickoutside"). If you want a different name for the created Event, pass it as a second argument like so: Y.Event.defineOutside(eventType, "yonderclick").

Sets up event delegation on a container element. The delegated event will use a supplied selector or filtering function to test if the event references at least one node that should trigger the subscription callback.

Selector string filters will trigger the callback if the event originated from a node that matches it or is contained in a node that matches it. Function filters are called for each Node up the parent axis to the subscribing container node, and receive at each level the Node and the event object. The function should return true (or a truthy value) if that Node should trigger the subscription callback. Note, it is possible for filters to match multiple Nodes for a single event. In this case, the delegate callback will be executed for each matching Node.

For each matching Node, the callback will be executed with its 'this' object set to the Node matched by the filter (unless a specific context was provided during subscription), and the provided event's currentTarget will also be set to the matching Node. The containing Node from which the subscription was originally made can be referenced as e.container.

Removes an event listener. Supports the signature the event was bound with, but the preferred way to remove listeners is using the handle that is returned when using Y.on

Generates an unique ID for the element if it does not already have one.

Finds the event in the window object, the caller's arguments, or in the arguments of another method in the callstack. This is executed automatically for events registered through the event manager, so the implementer should not normally need to execute this function at all.

Returns all listeners attached to the given element via addListener. Optionally, you can specify a specific type of event to return.

Removes all listeners attached to the given element via addListener. Optionally, the node's children can also be purged. Optionally, you can specify a specific type of event to remove.

Simulates the event with the given name on a target.