element. If the
contained many
![]()
elements, it would be possible to add a single click handler to the
element that would get called for any click event on its descendants. Closure’s event system allows any goog.events.Event Target to specify a parent event target, achieving a uniform API that is consistent with the DOM Level 2 Events Specification. Just like built-in DOM events, both bubbling and capturing listeners are supported. In this way, a class such as Inbox may have many Message objects that belong to it. If each Message sets Inbox as its parent event target, then a client interested in Message events need only register itself as a listener of Inbox because any event dispatched by a Message object will bubble up through Inbox and get dispatched to all of its listeners: goog.provide('example.Message'); goog.provide('example.Message.EventType'); goog.require('goog.events'); goog.require('goog.events.EventTarget'); /** * @param {example.Inbox} inbox to which this message belongs. * @constructor * @extends {goog.events.EventTarget} */ example.Message = function(inbox) { goog.events.EventTarget.call(this); this.setParentEventTarget(inbox); this.dispatchEvent(example.Message.EventType.NEW_MAIL_ARRIVED); }; goog.inherits(example.Message, goog.events.EventTarget); /** @enum {string} */ example.Message.EventType = { NEW_MAIL_ARRIVED: goog.events.getUniqueId('new-mail-arrived') }; // Example of listening to Inbox to get Message events. var inbox = new example.Inbox(); inbox.addEventListener(example.Message.EventType.NEW_MAIL_ARRIVED, function(e) { alert('New mail arrived!'); }); // Because the constructor for Message dispatches an event, the alert will // occur when this Message is created. var message = new example.Message(inbox);
It is considerably easier and more efficient to manage one listener on example.Inbox than a listener for every example.Message that might pass through example.Inbox.
Closure Provides a Consistent DOM Level 2 Events API Across Browsers | 145
goog.events.Event When an event is dispatched, each registered listener function is called with the event as its only argument. The event object is a goog.events.Event, or one of its subclasses, such as goog.events.BrowserEvent. goog.events.Event implements the following subset of the W3C Event interface: /** @type {string} */ goog.events.Event.prototype.type; /** @type {Object|undefined} */ goog.events.Event.prototype.target; /** @type {Object|undefined} */ goog.events.Event.prototype.currentTarget; /** * Stops event propagation. */ goog.events.Event.prototype.stopPropagation(); /** * Prevents the default action, for example a link redirecting to a url. */ goog.events.Event.prototype.preventDefault();
The goog.events.Event constructor takes the event type as a string, and optionally, the target of the event. If the target of the event is unspecified, it will be replaced with the source of the event when dispatched via dispatchEvent(). Because the target is available to an event listener as a property of the event, it is frequently misused to package additional data along with the event. Overloading the target property in this way can lead to the following bug: var eventTarget = new goog.events.EventTarget(); var listener = function(e) { var target = e.target; if (target) { alert('the message is: ' + target.message); } else { // This code path is never exercised because dispatchEvent() replaces // the target of eventWithNullTarget with eventTarget. alert('no target'); } }; goog.events.listen(eventTarget, 'test', listener); // This will exercise the first alert in listener(). var event = new goog.events.Event('test', { message: 'hello' }); goog.events.dispatchEvent(eventTarget, event); // Although the intention is for listener() to receive an event whose "target" // property is null, the event system changes it to eventWithNullTarget upon // dispatching it.
146 | Chapter 6: Event Management
var eventWithNullTarget = new goog.events.Event('test', null); alert(eventWithNullTarget.target == null); // alerts true goog.events.dispatchEvent(eventTarget, eventWithNullTarget); alert(eventWithNullTarget.target == null); // alerts false
The correct way to pass data to an event listener is to create a custom event by subclassing goog.events.Event. Consider the Inbox example, in which an Inbox dispatches an event when it discovers new mail. Suppose the listener needs the email address of the Inbox’s owner as well as the timestamp when the event was fired. First, a new class must be created for the custom event: goog.provide('example.Inbox.NewMailEvent'); goog.require('goog.events.Event'); /** * @param {example.Inbox} inbox * @param {string} email * @param {Date} timestamp * @constructor * @extends {goog.events.Event} */ example.Inbox.NewMailEvent = function(inbox, email, timestamp) { goog.events.Event.call(this, example.Inbox.EventType.NEW_MAIL, inbox); /** * @type {string} * @private */ this.email_ = email; /** * @type {Date} * @private */ this.timestamp_ = timestamp;
}; goog.inherits(example.Inbox.NewMailEvent, goog.events.Event); /** @return {string} */ example.Inbox.NewMailEvent.prototype.getEmail = function() { return this.email_; }; /** @return {Date} */ example.Inbox.NewMailEvent.prototype.getTimestamp = function() { return this.timestamp_; };
Next, the call to dispatchEvent() will have to be changed accordingly: example.Inbox.prototype.poll = function() { var messages = this.getNewMessages();
Closure Provides a Consistent DOM Level 2 Events API Across Browsers | 147
if (messages.length) { // email_ is a private field in example.Inbox with no public accessor. this.dispatchEvent( new example.Inbox.NewMailEvent(this, this.email_, new Date())); }
};
Finally, the listener function will be amended to make use of this new information: // inbox is of type example.Inbox. inbox.addEventListener(example.Inbox.EventType.NEW_MAIL, function(e) { var inbox = /** @type {!example.Inbox} */ (e.target); var count = inbox.getUnreadCount(); goog.dom.setTextContent(goog.dom.getElement('unread-count'), count); var newMailEvent = /** @type {example.Inbox.NewMailEvent} */ (e); window.status = 'Updated at: ' + newMailEvent.getTimestamp() + ' for ' + newMailEvent.getEmail(); });
Note that the code for the listener function did not have to change; it would have continued to work if left unedited. It is common to start out by only passing a string to dispatchEvent() and later creating a richer event object as more information needs to be passed around the system.
goog.events.EventHandler An EventHandler is a single object that manages a collection of event listeners. Unlike the other types discussed in the goog.events package thus far, goog.events.Event Handler is not motivated by an object in the DOM Level 2 Event Model. One might expect the goog.events.EventHandler class to have a handleEvent() method to satisfy the EventListener interface, which it does, but its default implementation throws a “not implemented” exception, and the method is rarely overridden, in practice. (This appears to be done so that the goog.events.EventHandler can use itself as the default value of the opt_fn and opt_handler parameters in its listen() method.) As discussed in “goog.Disposable” on page 132, it is important to release resources that are no longer being used. When an object is disposed, it should de-register any listeners that it registered. One way to do this would be to store the key returned by goog.events.listen() for each registered listener, and then to call goog.events. unlistenByKey() for each key in disposeInternal(). This is effectively what goog. events.EventHandler does, though it optimizes key storage by using object pooling. A goog.events.EventHandler also allows the value that this will be bound to when invoking an EventListener to be specified as an argument to its constructor, leading to the following common pattern:
148 | Chapter 6: Event Management
/** * @param {!goog.SomeType} someType goog.SomeType must extend * goog.events.EventTarget because it is being used as the first * parameter to listen() inside the constructor. * @constructor * @extends {goog.Disposable} */ goog.SomeClass = function(someType) { goog.Disposable.call(this); /** * @type {!goog.events.EventHandler} * @protected */ this.handler = new goog.events.EventHandler(this); this.handler.listen(someType, 'suspend', this.onSuspend_); this.handler.listen(someType, 'resume', this.onResume_);
}; goog.inherits(goog.SomeClass, goog.Disposable);
/** * @param {!goog.events.Event} e * @private */ goog.SomeClass.prototype.onSuspend_ = function(e) { /* handle */ }; /** * @param {!goog.events.Event} e * @private */ goog.SomeClass.prototype.onResume_ = function(e) { /* handle */ }; /** @inheritDoc */ goog.SomeClass.prototype.disposeInternal = function() { goog.SomeClass.superClass_.disposeInternal.call(this); this.handler.dispose(); };
Any object that is going to register listeners generally does so through a goog.events. EventHandler. Often the goog.events.EventHandler is instantiated in the constructor and is stored as a protected field. Listening for events is fairly common in Closure, so it is a good idea to make the goog.events.EventHandler protected so that it can be reused by any subclasses. A common mistake is to declare the field private and name it handler_ and then to do the same in the subclass, redefining the superclass’s Event Handler (the listeners of the original EventHandler will still fire, but it will never get disposed because the reference to it is lost). Recall from “Declaring Fields in Subclasses” on page 124 that private fields are not truly private to the class in which they are defined in JavaScript. Remember that JavaScript uses prototype-based inheritance
Closure Provides a Consistent DOM Level 2 Events API Across Browsers | 149
and that the @private annotation is only a directive to the Compiler and not a built-in language feature. Note that the listeners could have been added by doing either of the following: // Supply all five arguments to listen(). this.handler.listen(someType, 'suspend', this.onSuspend_, undefined /* use default value for optional argument */, this); // Call goog.bind() rather than specifying opt_handler. this.handler.listen(someType, 'suspend', goog.bind(this.onSuspend_, this));
The five-argument form behaves the same as the three-argument form used in the example. However, the three-argument form that calls goog.bind() introduces extra overhead because listen() defaults to using the value passed to the constructor of this.handler for opt_handler, so the listener function effectively ends up being: goog.bind(goog.bind(this.onSuspend_, this), this);
The behavior will be the same when this function is called, but the extra goog.bind() is wasteful. The pattern described previously is most effective (in terms of the number of parameters that need to be specified) when the event handling functions are instance methods that take the event that is being listened for as its only parameter. However, sometimes using goog.bind() is still inevitable: // ... inside the constructor ... this.handler.listen(someType, 'expire', goog.bind(this.onExpired_, this, 'fishing license')); /** * @param {string} whatExpired * @param {goog.events.Event} e * @private */ goog.SomeClass.prototype.onExpired_ = function(whatExpired, e) { alert('It expired: ' + whatExpired); };
An astute reader will also note that goog.partial() could be used instead, as this will be bound correctly when the listener is called: this.handler.listen(someType, 'expire', goog.partial(this.onExpired_, 'fishing license'))
With the expiration handler, the string 'fishing license' is being curried to the listener function, so goog.bind() must be used. Note that for this to work, the arguments of onExpired_() cannot be transposed because the event must be the last argument in order for this setup to work. Oftentimes, the data that the listener function needs to act upon will be available in either the event or as a field on the listener object itself, so currying arguments to listener functions is not often necessary. 150 | Chapter 6: Event Management
Along those lines, be careful when introducing new optional arguments to a function that is used as a listener function. Consider the following example: // ... inside the constructor ... this.handler.listen(button, goog.events.EventType.CLICK, this.save); // Developers often omit the click event from the list of // parameters to save a byte or because they're too lazy to add an // @param tag to the JSDoc. goog.SomeClass.prototype.save = function() { // The details of the click event are unimportant; the developer // just wants save() to be called when a button is clicked. this.writeContentsTo('default.txt'); this.updateStatusMessage(); };
Generally speaking, appending a new optional argument to a list of parameters should not break any existing code, but consider the following change to the save() method: /** * @param {string=} fileName Defaults to 'default.txt'. */ goog.SomeClass.prototype.save = function(fileName) { fileName = fileName || 'default.txt'; this.writeContentsTo(fileName); this.updateStatusMessage(); };
The developer assumes that previously, no callers were passing any arguments to save(), so it should be safe to add an optional parameter. Unfortunately, this is not the case because when this.save is called as a listener of a click event, it will be invoked with a goog.events.Event as its only parameter, which save() will now treat as the optional fileName parameter, resulting in a confusing error. The solution is to separate the save logic (so it is reusable) from the event handler as follows: // ... inside the constructor ... this.handler.listen(button, goog.events.EventType.CLICK, this.onSaveClicked_); /** * @param {goog.events.BrowserEvent} e * @private */ goog.SomeClass.prototype.onSaveClicked_ = function(e) { this.save(); }; goog.SomeClass.prototype.save = function() { this.writeContentsTo('default.txt'); this.updateStatusMessage(); };
This way, save() can be modified and reused without changing the behavior of the event listener. Do not be concerned about the additional bytes introduced by breaking
Closure Provides a Consistent DOM Level 2 Events API Across Browsers | 151
a single method declaration into multiple methods—if there is only one call site for each method, then the Compiler should inline the call, eliminating the extra bytes. There is an additional advantage to this approach, which is that the return value for the listener function is independent of the return value for the function that handles the listener’s logic. This is significant because the return value of goog.events. dispatchEvent() is false if any of the handlers returns false (or if anyone called preventDefault() on the event object), so this separation helps preserve the integrity of the return value of dispatchEvent().
Handling Keyboard Events Managing the differences in how browsers deal with keyboard events is even more chaotic than managing the differences in how they dispatch events. (Once again, see QuirksMode for a summary of the browser differences.) Fortunately, the Closure Library comes to the rescue again with a straightforward, cross-browser abstraction: goog.events.KeyHandler. A goog.events.KeyHandler combines the native keyup, keydown, and keypress events dispatched by the browser and dispatches a single goog.events.KeyEvent. Generally, a key event is dispatched for every effective “key press” that the browser records. This means that when the letter “a” is held down, multiple key events will be dispatched, just as holding the “a” key down would result in the “a” character being printed to a text input multiple times. There are, of course, some exceptions (punching the shift key on Firefox does not trigger a key event, but it does on Chrome, for example), but they are generally limited to the meta keys like, shift, control, and alt. These differences are explained in great detail in the keyhandler.js file that defines goog.events.Key Handler. Another important abstraction provided by the Closure Library in this area is goog.events.KeyCodes, which is an enumeration of common key codes. (Admittedly, it violates the naming convention for enums because it is plural.) This enum is often used in conjunction with a goog.events.KeyEvent to determine which key was pressed. The keyCode property of a Closure key event is normalized so that it is consistent with the value in goog.events.KeyCodes. Because not all browsers report the same key code value for the same key on their native key event, using goog.events.KeyCodes dramatically simplifies cross-browser keyboard event handling. The pattern for listening for keyboard events on an element such as a
<span>Amazon 