Dojo: The Definitive Guide

Chapter 3. Event Listeners and Pub/Sub Communication

Base provides extremely useful and versatile utilities for communication between JavaScript objects, DOM nodes, and any combination thereof. This chapter introduces these constructs as well as guidelines for when each of them might be most appropriate to employ. As writing portable code that involves DOM events necessarily depends on a standardized event model, you'll also learn a little bit about how Dojo works behind the scenes to smooth out some of the inconsistencies amongst mouse and keyboard events. The chapter concludes with a discussion of publish/subscribe communication, which provides a great vehicle for realizing an architecture with loosely coupled components.

Event and Keyboard Normalization

Some of the oldest code in the toolkit was written to smooth out inconsistencies with the underlying event model amongst different browsers. This section provides a brief overview of the events that you can count on being normalized when you use Dojo to develop an application. The basis of standardization is the W3C model.

Mouse and Keyboard Event Normalization

The dojo.connect machinery that you'll read about in the following section often involves a mouse event on a particular DOM node. Whenever you use Dojo, you can rest assured that the following mouse and keyboard events are supported in accordance with the W3C standard:

onclick

onmousedown

onmouseup

onmouseover

onmouseout

onmousemove

onkeydown

onkeyup

onkeypress

Tip

In addition to supporting the standardized W3C events, the nonstandard onmouseenter and onmouseleave events are also supported.

In addition to being able to count on these events firing in a standardized way, you can also rely on the event objects that are passed to event handling functions to also be normalized. In fact, if you ever have a need to normalize events yourself, you can use the following Base function:

dojo.fixEvent(/*DOMEvent*/ evt, /*DOMNode*/ sender) //Returns DOMEvent

Tip

DOMEvent is the standard convention that'll be used in the rest of the book to refer to the DOM event objects.

In other words, pass in the event and the node that should be treated as the current target, and you'll get back a normalized event that you can count on meeting the W3C specification. Table 3-1 provides a synopsis of some of the most commonly used properties on a DOMEvent.^[11]

Table 3-1. Commonly used properties on DOMEvents

Name	Type	Comment
bubbles	Boolean	Indicates whether the event can bubble up the DOM tree.
cancelable	Boolean	Indicates whether the event can have its default action prevented.
currentTarget	DOMNode	The current node whose event listeners are being processed. (Useful for when an event bubbles.)
target	DOMNode	The node that originally received the event.
type	String	The type of the event, e.g., mouseover.
ctrlKey	Boolean	Indicates if the Ctrl key was depressed when the event fired.
shiftKey	Boolean	Indicates if the Shift key was depressed when the event fired.
metaKey	Boolean	Indicates if the Meta key was depressed when the event fired. (This is the Command key on an Apple computer.)
altKey	Boolean	Indicates if the Alt key was depressed when the event fired.
screenX	Integer	The X coordinate where the event occurred on the screen.
screenY	Integer	The Y coordinate where the event occurred on the screen.
clientX	Integer	The X coordinate where the event occurred on the browser window.
clientY	Integer	The Y coordinate where the event occurred on the browser window.

Standardized Key Codes

The toolkit also exposes the following table of named key codes, which are available via dojo.keys. For example, you might detect whether a Shift + Enter key combination was processed via the following code snippet:

/* ... snip ... */
  if (evt.keyCode == dojo.keys.ENTER && evt.shiftKey) {
    /* ... */
  }
/* ... snip ... */

Table 3-2 provides a list of the constants for accessing keyboard events.

Table 3-2. A listing of the constants Dojo provides for accessing keyboard events via dojo.keys

BACKSPACE	DELETE	NUMPAD_DIVIDE
TAB	HELP	F1
CLEAR	LEFT_WINDOW	F2
ENTER	RIGHT_WINDOW	F3
SHIFT	SELECT	F4
CTRL	NUMPAD_0	F5
ALT	NUMPAD_1	F6
PAUSE	NUMPAD_2	F7
CAPS_LOCK	NUMPAD_3	F8
ESCAPE	NUMPAD_4	F9
SPACE	NUMPAD_5	F10
PAGE_UP	NUMPAD_6	F11
PAGE_DOWN	NUMPAD_7	F12
END	NUMPAD_8	F13
HOME	NUMPAD_9	F14
LEFT_ARROW	NUMPAD_MULTIPLY	F15
UP_ARROW	NUMPAD_PLUS	NUM_LOCK
RIGHT_ARROW	NUMPAD_ENTER	SCROLL_LOCK
DOWN_ARROW	NUMPAD_MINUS
INSERT	NUMPAD_PERIOD

---

^[11] Dojo currently normalizes against the DOM2 specification, which is available at http://www.w3.org/TR/DOM-Level-2-Events/events.html. See http://www.w3.org/TR/DOM-Level-3-Events/events.html for an overview of the DOM3 Event specification.