Table of contents

Appendices

1.2 DOM event flow

The DOM event flow is the process through which the event originates from the DOM Events implementation and is dispatched into a tree. Each event has an event target, a targeted node in the case of the DOM Event flow, toward which the event is dispatched by the DOM Events implementation.

Phases[top]

The event is dispatched following a path from the root of the tree to this target node. It can then be handled locally at the target node level or from any target ancestor higher in the tree. The event dispatching (also called event propagation) occurs in three phases:

1. The capture phase: the event is dispatched on the target ancestors from the root of the tree to the direct parent of the target node.

2. The target phase: the event is dispatched on the target node.

3. The bubbling phase: the event is dispatched on the target ancestors from the direct parent of the target node to the root of the tree.

NOTE: 

An SVG 1.0 version of the representation above is also available.

The target ancestors are determined before the initial dispatch of the event. If the target node is removed during the dispatching, or a target ancestor is added or removed, the event propagation will always be based on the target node and the target ancestors determined before the dispatch.

Some events may not necessarily accomplish the three phases of the DOM event flow, e.g. the event could only be defined for one or two phases. As an example, events defined in this specification will always accomplish the capture and target phases but some will not accomplish the bubbling phase ("bubbling events" versus "non-bubbling events", see also the Event.bubbles attribute).

Event listeners[top]

Each node encountered during the dispatch of the event may contain event listeners.

Registration of event listeners[top]

Event listeners can be registered on all nodes in the tree for a specific type of event, phase, and group. If the event listener is registered on a node while an event gets processed on this node, the event listener will not be triggered during the current phase but may be triggered during a later phase in the event flow, i.e. the bubbling phase.

Event groups[top]

An event listener is always part of a group. It is either explicitly in a group if a group has been specified at the registration or implicitly in the default group if no group has been specified. Within a group, event listeners are ordered in their order of registration. If two event listeners {A1, A2}, that are part of the same group, are registered one after the other (A1, then A2) for the same phase, the DOM event flow guarantees their triggering order (A1, then A2). If the two listeners are not part of the same group, no specification is made as to the order in which they will be triggered.

NOTE: 

While this specification does not specify a full ordering (i.e. groups are still unordered), it does specify ordering within a group. This implies that if the event listeners {A1, A2, B1, B2}, with A and B being two different groups, are registered for the same phase in the following order: A1, A2, B1, and B2. The following triggering orders are possible and conform to the DOM event flow: {A1, A2, B1, B2}, {A1, B1, A2, B2}, {B1, A1, A2, B2}, {A1, B1, B2, A2}, {B1, A1, B2, A2}, {B1, B2, A1, A2}. DOM Events implementations may impose priorities on groups but DOM applications must not rely on it. Unlike this specification, [DOM2Events] did not specify any triggering order for event listeners.

Triggering an event listener[top]

When the event is dispatched through the tree, from node to node, event listeners registered on the node are triggered if:

1. they were registered for the same type of event;

2. they were registered for the same phase;

3. the event propagation has not been stopped for the group.

Removing an event listener[top]

If an event listener is removed from a node while an event is being processed on the node, it will not be triggered by the current actions. Once removed, the event listener is never invoked again (unless registered again for future processing).

Reentrance[top]

It is expected that actions taken by EventListeners may cause additional events to be dispatched. Additional events should be handled in a synchronous manner and may cause reentrance into the event model. If an event listener fires a new event using EventTarget.dispatchEvent, the event propagation that causes the event listener to be triggered will resume only after the event propagation of the new event is completed.

Since implementations may have restrictions such as stack-usage or other memory requirements, applications should not depend on how many synchronous events may be triggered.

Event propagation and event groups[top]

All event listeners are part of a group (see [Registration of event listeners]). An event listener may prevent event listeners that are part of a same group from being triggered. The effect could be:

• immediate and no more event listeners from the same group will be triggered by the event object;

• differed until all event listeners from the same group have been triggered on the current node, i.e. the event listeners of the same group attached on other nodes will not be triggered.

If two event listeners are registered for two different groups, one cannot prevent the other from being triggered.