Class jabberwerx.EventNotifier (MINIMAL)

Extends JWBase.
Manages notifying listeners for a given event name.

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.EventNotifier(dispatcher, name) Constructs a new EventNotifier with the given dispatcher and event name.

Field Summary
Field Attributes	Field Name and Description
	dispatcher The owning dispatcher
	name The event name

Method Summary
Method Attributes	Method Name and Description
	bind(cb) Registers the given callback with this EventNotifier.
	bindWhen(selector, cb) Registers the given callback, filtering via the given selector.
	shouldBeSavedWithGraph() Marks this type for inline serialization.
	trigger(data, delegated, cb) Fires an event on all registered callbacks, with the given data.
	unbind(cb) Unregisters the given callback from this EventNotifier.
	wasUnserialized() serialize the original string selectors passed to bindWhen.

Class Detail

jabberwerx.EventNotifier(dispatcher, name)

Constructs a new EventNotifier with the given dispatcher and event name. This constructor should not be called directly. Instead, it is constructed by the jabberwerx.EventDispatcher as part of its constructor, or internally as needed.

Parameters:
{jabberwerx.EventDispatcher} dispatcher: The owning dispatcher
{String} name: The event name

Field Detail

{jabberwerx.EventDispatcher} dispatcher

The owning dispatcher

{String} name

The event name

Method Detail

bind(cb)

Registers the given callback with this EventNotifier.

The callback is expected to have the following signature:

 cb = function(evt) {
     // evt is the jabberwerx.EventObject instance describing
     // the current triggering

     // return true to indicate this event is "handled"
     // This return value may have special meaning for some
     // event notifiers
 }

Callbacks are remember by their object reference, and are considered to be unique. Registering the same function multiple times removes any previous registration, and applies {cb} to the current position and with the supplied additional arguments.

Parameters:
{Function} cb: The callback to register or update

Throws:
{TypeError}: If {cb} is not a function

bindWhen(selector, cb)

Registers the given callback, filtering via the given selector. The registered callback is only executed if the given selector indicates the data passed to #trigger matches.

A selector may be either undefined, a jQuery selector string or a function. If {selector} is undefined, then this method performs the same registration as #bind.

If {selector} is a string, it is used as the selector in jabberwerx.$(), with data (coerced into a DOM Node) as the context. If there are any results from the jQuery selection, they are added to the event object's 'selected' property, and {cb} is executed. Note that 'selected' is 'unwrapped' if the selection is a single node; otherwise it is an array of the selected nodes.

If {selector} is a function, it is passed the event data, and is expected to return a value (that does not evaluate as false) if the data matches. For example, the following selector function would match any events where the data is a Room:

var selector = function(data) {
    if (data instanceof jabberwerx.Room) {
        return data; //non-null object is "true"
    }
    return false; //prevents matching
}

The result of {selector} is stored in the {@link jabberwerx.EventObject#selected} property.

 cb = function(evt) {
     // evt is the jabberwerx.EventObject instance describing
     // the current triggering

     // return true to indicate this event is "handled"
     // This return value may have special meaning for some
     // event notifiers
 }

Parameters:
{String|Function|undefined} selector: The selector, as either a jQuery selector string or a function
{Function} cb: The callback to register or update

Throws:
{TypeError}: If {cb} is not a function, or if {selector} is not of the expected types

{Boolean} shouldBeSavedWithGraph()

Marks this type for inline serialization.

Returns:: {Boolean} always true

trigger(data, delegated, cb)

Fires an event on all registered callbacks, with the given data. This method creates a jabberwerx.EventObject, then calls all of the registered callbacks. Once all of this notifier's callbacks have been notified, all callbacks registered on {@link jabberwerx#.globalEvents} for this event are notified. If provided, the {cb} callback's signature is expected to be:

 cb = function(results) {
     // results is true if any event callback returned true,
     // false otherwise
 }

Parameters:
data Optional: data specific to this event triggering
{jabberwerx.EventNotifier} delegated Optional: the notifier to delegate event triggering to after calling this notifier's registered callbacks.
{Function} cb Optional: function to execute when all of this event notifier's callbacks have been notified

Throws:
{TypeError}: If {delegated} is defined and is not an instance

unbind(cb)

Unregisters the given callback from this EventNotifier.

Parameters:
{Function} cb: The callbck to unregister

wasUnserialized()

serialize the original string selectors passed to bindWhen. While callbacks are invocations, the selector functions created in bindWhen are anonymous and are not serialized. Serialize original string as needed, selecgor functions to be recreated after graph is restored.

Classes

Class jabberwerx.EventNotifier (MINIMAL)