>> Articles >> Web Technology >> API Documentation for Custom Javascript Events

API Documentation for Custom Javascript Events

This page documents the core of the Custom Events code. Docs for the rest of the code (the tracer and broker) will be added as time permits.

Event.Publisher

Mix Event.Publisher into your class or object if it needs to publish custom events for Event.Listeners. Allows your objects to use the same event features as DOM elements, because it uses hidden DOM elements to implement the custom events.

Found in event_mixins.js (and the version without debugging, event_mixins_notrace.js).

.getEventTarget( event_name ): Private. Finds the secret <A> element that this publisher will use to publish the event event_name through the DOM.
.addEventListener( event_name, callback_func, capturing ): Adds the observer function callback_func for the event event_name (optionally capturing) to the current event publisher. Called by Event.Listeners.
.removeEventListener( event_name, callback_func, capturing ): Removes the observer function callback_func (where capturing must match) from the event publisher.
.dispatchEvent( event_name, data, can_bubble, cancelable ): Creates a new event_name event, attaches a custom object for the event data (see "passing data", below), and dispatches the event to the listeners via the browser's standard event distribution mechanisms. Generally called by the publisher itself.

Event.Listener

Mix Event.Listener into your class if it needs to act on the event notifications sent by any publishers.

Found in event_mixins.js (and the version without debugging, event_mixins_notrace.js).

.getEventHandlerName( event_name )

Private. If a call to listenForEvent or stopListeningForEvent omits the name of the listener function, getEventHandlerName is used to find the "correct" name of the listener function.

The "correct" name of the handler function is determined by upper-casing the first character of the event name, replacing all /[ _]/ with -, camelizing the result, and then prepending "on". So if the event's name is "i just did_something", this function would return "onIJustDidSomething", and the listener code would then assume that was the name of the listener function.

.listenForEvent( event_source, event_name, use_capture, onEvent_name )

Causes the listener to "subscribe" for events of type event_name which are published by event_source, assuming that event_source is an Event.Publisher.

.stopListeningForEvent( event_source, event_name, use_capture, onEvent_name )

Unsubscribe the current listener from the events of type event_name published by event_source.

Event (two new methods)

Adds the methods create and dispatch to Prototype's Event object.

Found in event_mixins.js (and the version without debugging, event_mixins_notrace.js).

.create( event_data, can_bubble, cancelable, fl_dispatch, target )

Browser-agnostic method for creating new click events.

Could/should be generalized for creating events of any type, but this will be difficult because the browsers all do this so very differently (createEvent versus createEventObject, and HTMLEvents versus MouseEvents...). For now, this method is only usable for click events.

event_data is any data the Publisher wants attached to the event for use by the Listeners, can_bubble and cancelable are straight out of the DOM event api, fl_dispatch is a boolean which (if true) causes the event to be dispatched to target as soon as it is created, and target is the DOM element which is to receive the event (as in, "pretend I clicked on [target]"). target is only used if fl_dispatch is true.

.dispatch( target, event )

Sends the event to the specified target DOM object. This is just a browser-agnostic wrapper for target.dispatchEvent (from the DOM) and target.fireEvent (from MSIE).

Event.Broker

The broker allows your publishers and listeners (subscribers) to remain unaware of each other. Publishers register their events (by name) with the broker. Listeners subscribe only to the broker, rather than to the publishers (the broker takes care of subscribing the listeners to the publishers, automatically).

Use of Event.Broker changes the events model so that listeners just need to know what events they care to receive, and don't need to know anything about which objects on the page will actually produce those events.

Event.Broker is especially useful in three situations:

when you have a 'pluggable' interface (meaning Listeners may not know in advance about all of the available Publishers).
when there are numerous (or even "many") publishers that can produce the same events
when the available event publishers change regularly (for example, if you have a list of items, and the list is updated in response to changes on the server side)

In all of those cases, the benefit of the broker is that the listeners only need to know about the one, central Event.Broker object.

.registerEventsPublisher( event_types, publisher )

Public. Called by a Publisher, usually when it is first created/initialized.

event_types is an array of strings, where each string is the name (type) of one event produced by this publisher. publisher is the Publisher object which is being registered (usually 'this').

window.eventBroker.registerEventsPublisher( ['new msg arrived', 'msg deleted'], this )

Any Listeners which have already registered with the Broker for any of the events in event_types will be automatically subscribed to this publisher, immediately. New Listeners (for events of the types produced by this Publisher) will be subscribed to this publisher as soon as they register with the Broker.

.unregisterEventsPublisher( event_types, publisher )

Public. Called by a Publisher, usually when the Publisher object is about to be destroyed.

This is the opposite of .registerEventsPublisher().

event_types is an array of strings, where each string is the name (type) of one event produced by this publisher. publisher is the Publisher object which is being un-registered with the Broker (usually 'this').

All of the Listeners which have subscribed to this Publisher's events will be automatically unsubscribed by the Broker, and then the Broker will remove the Publisher from its internal lists of Publishers so that it will no longer receive any new subscribers.

addEventListener( event_type, event_listener, useCapture )

Public. Called by a Listener, usually when it is first created/initialized. However, you do not call this method directly. It's called by the Event.Listener interface. (See example, below.)

event_type is the name/type of the event that the Listener wants to receive. event_listener is the Listener object itself (usually 'this'). useCapture is the DOM-standard parameter to indicate at which phase the event should be sent to the Listener.

After registering with the Broker, the Broker will make sure that the Listener is subscribed to all Publishers which produce the events for which the Listener has subscribed. (This includes Publishers which which register before or after the Listener registered.)

this.listenForEvent( window.eventBroker, 'new msg arrived', false );

this.listenForEvent( window.eventBroker, 'msg deleted', false, 'onMsgDeleted' );

removeEventListener( event_type, event_listener, useCapture )

Public. Called by a Listener when it is no longer interested in receiving a given type of event (such as when it is being destroyed!) You do not call this method directly. It's called by the Event.Listener interface. (See example, below.)

event_type is the name/type of event that the Listener is no longer interested in receiving. event_listener is a reference to the Listener instance itself (usually 'this'). useCapture is the DOM-standard parameter that indicated at which phase the event was to be sent to the Listener: the boolean value of this param must match the original call to addEventListener.

Unregistering with the broker will cause the Listener to be unsubscribed from all Publishers of events of type event_type.

this.stopListeningForEvent( window.eventBroker, 'new msg arrived', false );

this.stopListeningForEvent( window.eventBroker, 'msg deleted', false, 'onMsgDeleted' );

Passing Data with Custom Events

Calls to an event publisher's .dispatchEvent() method may include an optional data param, which can be of any type. This data (or null if not provided) can be accessed by the listeners via event.event_data.data.

The event_data object that is attached to every custom event includes three properties:

event_name: the name (or type) of the custom event
event_target: the Event.Publisher which generated the event
data: the data param which was included when the publisher's .dispatchEvent() method was called

Previous: Creating Custom Events with JavaScript: Decoupling | Next: MetaWeblog.getRecentPosts: Conflict and Confusion

Page last updated: 9/6/2006

Search TruerWords

API Documentation for Custom Javascript Events

Event.Publisher

Event.Listener

Event (two new methods)

Event.Broker

Passing Data with Custom Events