static
Class 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.
Properties
DOMReady
- static boolean
True when the document is initially usable
addListener/removeListener can throw errors in unexpected scenarios.
These errors are suppressed, the method returns false, and this property
is set
The poll interval in milliseconds
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).
Methods
static
EventHandle
attach
(
type
,
fn
,
el
,
context
,
args
)
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
static
boolean
detach
(
type
,
fn
,
el
)
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.
static
void
Event.define
(
type
,
cfg
)
Static method to register a synthetic event definition and implementation
in the DOM Event subsystem.
Pass either a string type
and configuration object as
separate parameters or a configuration object that includes a
type
property as a single parameter.
The configuration object should include implementation methods for
on
and detach
. This is the full list of
configuration properties:
type
- Required if using the
Y.Event.define( config )
signature. The name of the synthetic event. What goes
node.on(HERE, callback )
.
on
function ( node, subscription, fireEvent )
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
information on the subscription
object. When the
criteria have been met to fire the synthetic event, call
fireEvent.fire()
.
detach
function ( node, subscription, fireEvent )
The
implementation logic for cleaning up a detached subscription. E.g.
detach any DOM subscriptions done in on
.
publishConfig
- (Object) The configuration object that will be used to instantiate
the underlying CustomEvent. By default, the event is defined with
emitFacade: true
so subscribers will receive a DOM-like
event object.
processArgs
function ( argArray )
Optional method to extract any
additional arguments from the subscription signature. Using this
allows on
signatures like node.on(
"hover", overCallback, outCallback )
. Be sure that
the args passed in is pruned of any additional arguments using, for
example, argArray.splice(2,1);
. Data returned from the
function will be stored on the subscription
object passed
to on
and detach
under
subscription._extra
.
-
- Parameters:
-
type
<String>
Name given to the synthetic event
-
cfg
<Object>
configuration object. Pass this as the first
parameter if it includes the type
property.
static
string
generateId
(
el
)
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
static
Event
getEvent
(
e
,
el
)
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
static
Y.Custom.Event
getListeners
(
el
,
type
)
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:
Y.Custom.Event
- the custom event wrapper for the DOM event(s)
static
void
onAvailable
(
id
,
fn
,
p_obj
,
p_override
,
checkContent
)
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)
Deprecated Use Y.on("available")
static
void
onContentReady
(
id
,
fn
,
p_obj
,
p_override
)
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.
-
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 an object, fn will
exectute in the context of that object
Deprecated Use Y.on("contentready")
static
void
purgeElement
(
el
,
recurse
,
type
)
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