#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# SyntheticEvent Class

Defined in: `event/js/synthetic.js:196`
Module: event-synthetic
Parent Module: event

Available since 3.1.0

Wrapper class for the integration of new events into the YUI event infrastructure. Don't instantiate this object directly, use `Y.Event.define(type, config)`. See that method for details.

Properties that MAY or SHOULD be specified in the configuration are noted below and in the description of `Y.Event.define`.

## Constructor

### `SyntheticEvent`

(

- `cfg`

)

Defined in `event/js/synthetic.js:196`

Available since 3.1.0

#### Parameters:

- `cfg` Object

  Implementation pieces and configuration

- Index
- Methods
- Properties

## Item Index

### Methods

- _deleteSub
- _detach
- _init
- _on
- _subscribe
- applyArgExtras
- delegate
- detach
- detachDelegate
- getRegistry static
- getSubs
- on
- processArgs
- subMatch

### Properties

- preventDups

## Methods

### `_deleteSub`

(

- `sub`

)
private

Defined in `event/js/synthetic.js:251`

Available since 3.2.0

Alternate `_delete()` method for the CustomEvent object created to manage SyntheticEvent subscriptions.

#### Parameters:

- `sub` Subscription

  the subscription to clean up

### `_detach`

(

- `args`

)
private

Defined in `event/js/synthetic.js:569`

Available since 3.2.0

Removes the subscription(s) from the internal subscription dispatch mechanism. See `SyntheticEvent._deleteSub`.

#### Parameters:

- `args` Array

  The arguments passed to `node.detach(...)`

### `_init`

() protected

Defined in `event/js/synthetic.js:283`

Construction logic for the event.

### `_on`

(

- `args`
- `delegate`

)
EventHandle private

Defined in `event/js/synthetic.js:431`

Sets up the boilerplate for detaching the event and facilitating the execution of subscriber callbacks.

#### Parameters:

- `args` Array

  array of arguments passed to `Y.on(...)` or `Y.delegate(...)`

- `delegate` Boolean

  true if called from `Y.delegate(...)`

#### Returns:

EventHandle: the detach handle for this subscription

### `_subscribe`

(

- `node`
- `method`
- `args`
- `extra`
- `filter`

)
EventHandle private

Defined in `event/js/synthetic.js:492`

Available since 3.2.0

Creates a new Notifier object for use by this event's `on(...)` or `delegate(...)` implementation and register the custom event proxy in the DOM system for cleanup.

#### Parameters:

- `node` Node

  the Node hosting the event

- `method` String

  "on" or "delegate"

- `args` Array

  the subscription arguments passed to either `Y.on(...)` or `Y.delegate(...)` after running through `processArgs(args)` to normalize the argument signature

- `extra` Any

  Extra data parsed from `processArgs(args)`

- `filter` String | Function

  the selector string or function filter passed to `Y.delegate(...)` (not present when called from `Y.on(...)`)

#### Returns:

EventHandle:

### `applyArgExtras`

(

- `extra`
- `sub`

)

Defined in `event/js/synthetic.js:547`

Implementers MAY provide this method definition.

Implement this function if you want extra data extracted during processArgs to be propagated to subscriptions on a per-node basis. That is to say, if you call `Y.on('xyz', fn, xtra, 'div')` the data returned from processArgs will be shared across the subscription objects for all the divs. If you want each subscription to receive unique information, do that processing here.

The default implementation adds the data extracted by processArgs to the subscription object as `sub._extra`.

#### Parameters:

- `extra` Any

  Any extra data extracted from processArgs

- `sub` Subscription

  the individual subscription

### `delegate`

(

- `node`
- `sub`
- `notifier`
- `filter`

)

Defined in `event/js/synthetic.js:381`

Available since 3.2.0

Implementers SHOULD provide this method definition.

Implementation logic for subscriptions done via `node.delegate(type, fn, filter)` or `Y.delegate(type, fn, container, filter)`. Like with `on()` above, this function should monitor the environment for the event being fired, and trigger subscription execution by calling `notifier.fire(e)`.

This function receives a fourth argument, which is the filter used to identify which Node's are of interest to the subscription. The filter will be either a boolean function that accepts a target Node for each hierarchy level as the event bubbles, or a selector string. To translate selector strings into filter functions, use `Y.delegate.compileFilter(filter)`.

#### Parameters:

- `node` Node

  the node the subscription is being applied to

- `sub` Subscription

  the object to track this subscription

- `notifier` SyntheticEvent.Notifier

  call notifier.fire(..) to trigger the execution of the subscribers

- `filter` String | Function

  Selector string or function that accepts an event object and returns null, a Node, or an array of Nodes matching the criteria for processing.

### `detach`

(

- `node`
- `sub`
- `notifier`

)

Defined in `event/js/synthetic.js:366`

Implementers SHOULD provide this method definition.

Implementation logic for detaching subscriptions done via `node.on(type, fn)`. This function should clean up any subscriptions made in the `on()` phase.

#### Parameters:

- `node` Node

  the node the subscription was applied to

- `sub` Subscription

  the object tracking this subscription

- `notifier` SyntheticEvent.Notifier

  the Notifier used to trigger the execution of the subscribers

### `detachDelegate`

(

- `node`
- `sub`
- `notifier`
- `filter`

)

Defined in `event/js/synthetic.js:410`

Available since 3.2.0

Implementers SHOULD provide this method definition.

Implementation logic for detaching subscriptions done via `node.delegate(type, fn, filter)` or `Y.delegate(type, fn, container, filter)`. This function should clean up any subscriptions made in the `delegate()` phase.

#### Parameters:

- `node` Node

  the node the subscription was applied to

- `sub` Subscription

  the object tracking this subscription

- `notifier` SyntheticEvent.Notifier

  the Notifier used to trigger the execution of the subscribers

- `filter` String | Function

  Selector string or function that accepts an event object and returns null, a Node, or an array of Nodes matching the criteria for processing.

### `getRegistry`

(

- `node`
- `type`
- `create`

)
Array protected static

Defined in `event/js/synthetic.js:218`

Available since 3.2.0

Returns the array of subscription handles for a node for the given event type. Passing true as the third argument will create a registry entry in the event system's DOM map to host the array if one doesn't yet exist.

#### Parameters:

- `node` Node

  the node

- `type` String

  the event

- `create` Boolean

  create a registration entry to host a new array if one doesn't exist.

#### Returns:

Array:

### `getSubs`

(

- `node`
- `args`
- `filter`
- `first`

)
EventHandle[]

Defined in `event/js/synthetic.js:605`

Returns the detach handles of subscriptions on a node that satisfy a search/filter function. By default, the filter used is the `subMatch` method.

#### Parameters:

- `node` Node

  the node hosting the event

- `args` Array

  the array of original subscription args passed to `Y.on(...)` (before `processArgs`

- `filter` Function

  function used to identify a subscription for inclusion in the returned array

- `first` Boolean

  stop after the first match (used to check for duplicate subscriptions)

#### Returns:

EventHandle[]: detach handles for the matching subscriptions

### `on`

(

- `node`
- `sub`
- `notifier`

)

Defined in `event/js/synthetic.js:343`

Implementers SHOULD provide this method definition.

Implementation logic for subscriptions done via `node.on(type, fn)` or `Y.on(type, fn, target)`. This function should set up the monitor(s) that will eventually fire the event. Typically this involves subscribing to at least one DOM event. It is recommended to store detach handles from any DOM subscriptions to make for easy cleanup in the `detach` method. Typically these handles are added to the `sub` object. Also for SyntheticEvents that leverage a single DOM subscription under the hood, it is recommended to pass the DOM event object to `notifier.fire(e)`. (The event name on the object will be updated).

#### Parameters:

- `node` Node

  the node the subscription is being applied to

- `sub` Subscription

  the object to track this subscription

- `notifier` SyntheticEvent.Notifier

  call notifier.fire(..) to trigger the execution of the subscribers

### `processArgs`

(

- `args`
- `delegate`

)
Any

Defined in `event/js/synthetic.js:299`

Implementers MAY provide this method definition.

Implement this function if the event supports a different subscription signature. This function is used by both `on()` and `delegate()`. The second parameter indicates that the event is being subscribed via `delegate()`.

Implementations must remove extra arguments from the args list before returning. The required args for `on()` subscriptions are

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

The required args for `delegate()` subscriptions are

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

The return value from this function will be stored on the subscription in the '_extra' property for reference elsewhere.

#### Parameters:

- `args` Array

  parmeters passed to Y.on(..) or Y.delegate(..)

- `delegate` Boolean

  true if the subscription is from Y.delegate

#### Returns:

Any:

### `subMatch`

(

- `sub`
- `args`

)
Boolean

Defined in `event/js/synthetic.js:648`

Available since 3.2.0

Implementers MAY override this to define what constitutes a "same" subscription. Override implementations should consider the lack of a comparator as a match, so calling `getSubs()` with no arguments will return all subs.

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:

- `sub` Subscription

  the existing subscription

- `args` Array

  the calling arguments passed to `Y.on(...)` etc.

#### Returns:

Boolean: true if the sub can be described by the args present

## Properties

### `preventDups`

Boolean

Defined in `event/js/synthetic.js:328`

Implementers MAY override this property.

Whether to prevent multiple subscriptions to this event that are classified as being the same. By default, this means the subscribed callback is the same function. See the `subMatch` method. Setting this to true will impact performance for high volume events.

Default: false