API Docs for: 3.5.1
Show:

Event Class

Module: event-base
Parent Module: event

The event utility provides functions to add and remove event listeners, event cleansing. It also tries to automatically remove listeners it registers during the unload event.

Item Index

Methods

Properties

Methods

_applyFilter

(
  • filter
  • args
  • ce
)
Node | Node[] | Undefined protected

Provided by the event-delegate module.

Defined in event/js/delegate.js:209

Walks up the parent axis of an event's target, and tests each element against a supplied filter function. If any Nodes, including the container, satisfy the filter, the delegated callback will be triggered for each.

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

Parameters:

  • filter Function

    boolean function to test for inclusion in event notification

  • args Array

    the arguments that would be passed to subscribers

  • ce CustomEvent

    the DOM event wrapper

Returns:

Node | Node[] | Undefined: The Node or Nodes that satisfy the filter

_clean

(
  • wrapper
)
private static

Defined in event/js/event-dom.js:806

Available since 3.4.0

Removes all object references and the DOM proxy subscription for a given event for a DOM node.

Parameters:

  • wrapper CustomEvent

    Custom event proxy for the DOM subscription

_isValidCollection

(
  • o
)
Boolean deprecated private static

Defined in event/js/event-dom.js:611

Deprecated: was not meant to be used directly

We want to be able to use getElementsByTagName as a collection to attach a group of events to. Unfortunately, different browsers return different types of collections. This function tests to determine if the object is array-like. It will also fail if the object is an array, but is empty.

Parameters:

Returns:

Boolean: true if the object is array-like and populated

_load

() private static

hook up any deferred listeners

_poll

() private static

Polling function that runs before the onload event fires, attempting to attach to DOM Nodes as soon as they are available

_unload

() private static

Removes all listeners registered by pe.event. Called automatically during the unload event.

attach

(
  • type
  • fn
  • el
  • context
  • args
)
EventHandle static

Adds an event listener

Parameters:

  • type String

    The type of event to append

  • fn Function

    The method the event invokes

  • el String | HTMLElement | Array | NodeList

    An id, an element reference, or a collection of ids and/or elements to assign the listener to.

  • context Object

    optional context object

  • args Boolean | Object

    0..n arguments to pass to the callback

Returns:

EventHandle: an object to that can be used to detach the listener

compileFilter

(
  • selector
)
Function static

Provided by the event-delegate module.

Defined in event/js/delegate.js:183

Available since 3.2.0

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).

Parameters:

  • selector String

    the selector string to base the filtration on

Returns:

define

(
  • type
  • config
  • force
)
SyntheticEvent static

Provided by the event-synthetic module.

Defined in event/js/synthetic.js:670

Available since 3.1.0

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.

Parameters:

  • type String

    the name of the event

  • config Object

    the prototype definition for the new event (see above)

  • force Boolean

    override an existing event (use with caution)

Returns:

SyntheticEvent: the subclass implementation instance created to handle event subscriptions of this type

defineOutside

(
  • event
  • name
)
static

Provided by the event-outside module.

Defined in event/js/outside.js:48

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").

Parameters:

  • event String

    DOM event

  • name String

    (optional) custom outside event name

delegate

(
  • type
  • fn
  • el
  • filter
  • context
  • args
)
EventHandle static

Provided by the event-delegate module.

Defined in event/js/delegate.js:16

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.

Parameters:

  • type String

    the event type to delegate

  • fn Function

    the callback function to execute. This function will be provided the event object for the delegated event.

  • el String | Node

    the element that is the delegation container

  • filter String | Function

    a selector that must match the target of the event or a function to test target and its parents for a match

  • context Object

    optional argument that specifies what 'this' refers to.

  • args Object multiple

    0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.

Returns:

EventHandle: the detach handle

detach

(
  • type
  • fn
  • el
)
Boolean static

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

Parameters:

  • type String

    the type of event to remove.

  • fn Function

    the method the event invokes. If fn is undefined, then all event handlers for the type of event are removed.

  • el String | HTMLElement | Array | NodeList | EventHandle

    An event handle, an id, an element reference, or a collection of ids and/or elements to remove the listener from.

Returns:

Boolean: true if the unbind was successful, false otherwise.

generateId

(
  • el
)
String static

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

Parameters:

  • el Object

    the element to create the id for

Returns:

String: the resulting id of the element

getEvent

(
  • e
  • el
)
Event static

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.

Parameters:

  • e Event

    the event parameter from the handler

  • el HTMLElement

    the element the listener was attached to

Returns:

Event: the event

getListeners

(
  • el
  • type
)
CustomEvent static

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

Parameters:

  • el HTMLElement | String

    the element or element id to inspect

  • type String

    optional type of listener to return. If left out, all listeners will be returned

Returns:

CustomEvent: the custom event wrapper for the DOM event(s)

nativeAdd

(
  • el
  • type
  • fn
  • capture
)
private static

Adds a DOM event directly without the caching, cleanup, context adj, etc

Parameters:

  • el HTMLElement

    the element to bind the handler to

  • type String

    the type of event handler

  • fn Function

    the callback to invoke

  • capture Boolen

    capture or bubble phase

nativeRemove

(
  • el
  • type
  • fn
  • capture
)
private static

Basic remove listener

Parameters:

  • el HTMLElement

    the element to bind the handler to

  • type String

    the type of event handler

  • fn Function

    the callback to invoke

  • capture Boolen

    capture or bubble phase

notifySub

(
  • thisObj
  • args
  • ce
)
Boolean private static

Provided by the event-delegate module.

Defined in event/js/delegate.js:129

Available since 3.2.0

Overrides the _notify method on the normal DOM subscription to inject the filtering logic and only proceed in the case of a match.

This method is hosted as a private property of the delegate method (e.g. Y.delegate.notifySub)

Parameters:

  • thisObj Object

    default 'this' object for the callback

  • args Array

    arguments passed to the event's fire()

  • ce CustomEvent

    the custom event managing the DOM subscriptions for the subscribed event on the subscribing node.

Returns:

Boolean: false if the event was stopped

onAvailable

(
  • id
  • fn
  • p_obj
  • p_override
  • checkContent
)
deprecated static

Defined in event/js/event-dom.js:190

Deprecated: Use Y.on("available")

Executes the supplied callback when the item with the supplied id is found. This is meant to be used to execute behavior as soon as possible as the page loads. If you use this after the initial page load it will poll for a fixed time for the element. The number of times it will poll and the frequency are configurable. By default it will poll for 10 seconds.

The callback is executed with a single parameter: the custom object parameter, if provided.

Parameters:

  • id String | | String[]

    the id of the element, or an array of ids to look for.

  • fn Function

    what to execute when the element is found.

  • p_obj Object

    an optional object to be passed back as a parameter to fn.

  • p_override Boolean | Object

    If set to true, fn will execute in the context of p_obj, if set to an object it will execute in the context of that object

  • checkContent Boolean

    check child node readiness (onContentReady)

onContentReady

(
  • id
  • fn
  • obj
  • override
)
deprecated static

Defined in event/js/event-dom.js:263

Deprecated: Use Y.on("contentready")

Works the same way as onAvailable, but additionally checks the state of sibling elements to determine if the content of the available element is safe to modify.

The callback is executed with a single parameter: the custom object parameter, if provided.

Parameters:

  • id String

    the id of the element to look for.

  • fn Function

    what to execute when the element is ready.

  • obj Object

    an optional object to be passed back as a parameter to fn.

  • override Boolean | Object

    If set to true, fn will execute in the context of p_obj. If an object, fn will exectute in the context of that object

purgeElement

(
  • el
  • recurse
  • type
)
static

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.

Parameters:

  • el HTMLElement

    the element to purge

  • recurse Boolean

    recursively purge this element's children as well. Use with caution.

  • type String

    optional type of listener to purge. If left out, all listeners will be removed

simulate

(
  • target
  • type
  • options
)
Void static

Provided by the event-simulate module.

Defined in event-simulate/js/event-simulate.js:569

Simulates the event with the given name on a target.

Parameters:

  • target HTMLElement

    The DOM element that's the target of the event.

  • type String

    The type of event to simulate (i.e., "click").

  • options Object

    (Optional) Extra options to copy onto the event object.

Returns:

Void:

startInterval

() private static

Properties

_avail

Unknown private static

onAvailable listeners

_dri

Unknown private static

document readystate poll handle

_el_events

Unknown private static

Custom event wrapper map DOM events. Key is Element uid stamp. Each item is a hash of custom event wrappers as provided in the _wrappers collection. This provides the infrastructure for getListeners.

_interval

Unknown private static

poll handle

_loadComplete

Boolean private static

True after the onload event has fired

_retryCount

Unknown private static

The number of times to poll after window.onload. This number is increased if additional late-bound handlers are requested after the page load.

_wrappers

Y.Event.Custom private static

Custom event wrappers for DOM events. Key is 'event:' + Element uid stamp + event type

DOMReady

Boolean static

True when the document is initially usable

lastError

Error static

addListener/removeListener can throw errors in unexpected scenarios. These errors are suppressed, the method returns false, and this property is set

POLL_INTERVAL

Int final static

The poll interval in milliseconds

POLL_RETRYS

Int final static

The number of times we should look for elements that are not in the DOM at the time the event is requested after the document has been loaded. The default is 1000@amp;40 ms, so it will poll for 40 seconds or until all outstanding handlers are bound (whichever comes first).