previous   next   contents   index


3. DOM Core: The SMIL DOM Foundation

Table of contents

The SMIL DOM has as its foundation the Core DOM. The SMIL DOM includes the support defined in the DOM Level 2 Core, and the DOM Level 2 Events.

3.1. DOM Level 2 Core

The DOM Level 2 Core describes the general functionality needed to manipulate hierarchical document structures, elements and attributes. The SMIL DOM describes functionality that is associated with or depends upon SMIL elements and attributes. Where practical, we would like to simply inherit functionality that is already defined in the DOM Level 2 Core. Nevertheless, we want to present an API that is easy to use, and familiar to script authors that work with the HTML DOM definitions.

Following the pattern of the HTML DOM, the SMIL DOM defines a naming convention for properties, methods, events, collections and data types. All names are defined as one or more English words concatenated together to form a single string. The property or method name starts with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a method that converts a time on an element local timeline to global document time might be called "localToGlobalTime". The attribute "xml:link" will be called "xmlLink" in DOM.

3.1.1. Properties and methods

In the ECMAScript binding, properties are exposed as properties of a given object. In Java, properties are exposed with get and set methods.

Most of the properties are directly associated with attributes defined in the SMIL syntax. By the same token, most

(ED: (or all?))
of the attributes defined in the SMIL syntax are reflected as properties in the SMIL DOM. There are also additional properties in the DOM that present aspects of SMIL semantics (such as the current position on a timeline).

The SMIL DOM methods support functionality that is directly associated with SMIL functionality (such as control of an element timeline).

3.1.2. Constraints on Core interfaces

In some instances, the SMIL DOM defines constraints on the Level 2 Core interfaces. These are introduced to simplify the SMIL associated runtime engines. The constraints include:

  • Read-only properties, precluding arbitrary manipulation of the SMIL element properties at runtime.
  • Disallowed structural changes, precluding certain changes to the structure of the document (and the associated time graph) at runtime.
(ED: This section will need to be reworked once we have a better handle on the approach we take (w.r.t. modality, etc.) and the details of the interfaces. )
(ED: We probably also want to include notes on the recent discussion of a presentation or runtime object model as distinct from the DOM. )

3.2. DOM Level 2 Event Model

One of the goals of the DOM Level 2 Event Model is the design of a generic event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. The SMIL event model includes the definition of a standard set of events for synchronization control and presentation change notifications, a means of defining new events dynamically, and the defined contextual information for these events.

3.2.1. SMIL and DOM Level 2 events

The DOM Level 2 Events specification currently defines a base Event interface and three broad event classifications:

  • UI events
  • UI Logical events
  • Mutation events

In HTML documents, elements generally behave in a passive (or sometimes reactive) manner, with most events being user-driven (mouse and keyboard events). In SMIL, all timed elements behave in a more active manner, with many events being content-driven. Events are generated for key points or state on the element timeline (at the beginning, at the end and when the element repeats). Media elements generate additional events associated with the synchronization management of the media itself.

The SMIL DOM makes use of the general UI and mutation events, and also defines new event types, including:

  • Object Temporal Events
  • Logical Temporal Events
  • Synchronization Events
  • Media-delivery Events

Some runtime platforms will also define new UI events, e.g. associated with a control unit for web-enhanced television (e.g. channel change and simple focus navigation events). In addition, media players within a runtime may also define specific events related to the media player (e.g. low memory).

The SMIL events are grouped into four classifications:

Static SMIL events
This is a group of events that are required for SMIL functionality. Some of the events have more general utility, while others are specific to SMIL modules and associated documents (SMIL documents as well as HTML and XML documents that integrate SMIL modules).
Platform and environment specific events
These events are not defined in the specification, but may be created and raised by the runtime environment, and may be referenced by the SMIL syntax.
Author-defined events
This is a very important class of events that are not specifically defined in the DOM, but that must be supported for some common use-case scenarios. A common example is that of broadcast or streaming media with embedded triggers. Currently, a media player exposes these triggers by calling script on the page. To support purely declarative content, and to support a cleaner model for script integration, we allow elements to raise events associated with these stream triggers. The events are identified by names defined by the author (e.g. "onBillWaves" or "onScene2"). Declarative syntax can bind to these events, so that some content can begin (or simply appear) when the event is raised. This is very important for things like Enhanced Television profiles, Enhanced DVD profiles, etc.
This functionality is built upon the DOM Level 2 Events specification.
Property mutation events
These are mutation events as defined in the DOM Level 2 Events specification. These events are raised when a particular property is changed (either externally via the API, or via internal mechanisms).
Note that SMIL Animation does not "change properties" in the manner referenced above, and so does not generate property mutation events. For details, see the SMIL Animation specification.

3.3. Event propagation support

In addition to defining the basic event types, the DOM Level 2 Events specification describes event flow and mechanisms to manipulate the event flow, including:

The SMIL DOM defines the behavior of Event capture, bubbling and cancellation in the context of SMIL and SMIL-integrated Documents.

In the HTML DOM, events originate from within the DOM implementation, in response to user interaction (e.g. mouse actions), to document changes or to some runtime state (e.g. document parsing). The DOM provides methods to register interest in an event, and to control event capture and bubbling. In particular, events can be handled locally at the target node or centrally at a particular node. This support is included in the SMIL DOM. Thus, for example, synchronization or media events can be handled locally on an element, or re-routed (via the bubbling mechanisms) to a parent element or even the document root. Event registrants can handle events locally or centrally.

Note: It is currently not resolved precisely how event flow (dispatch, bubbling, etc.) will be defined for SMIL timing events. Especially when the timing containment graph is orthogonal to the content structure (e.g. in XML/SMIL integrated documents), it may make more sense to define timing event flow relative to the timing containment graph, rather than the content containment graph. This may also cause problems, as different event types will behave in very different ways within the same document.

Note: In Documents using SMIL Layout, it is currently not resolved precisely how certain user interface events (e.g. onmouseover, onmouseout) will be defined and will behave. It may make more sense to define these events relative to the regions and layout model, rather than the timing graph.

previous   next   contents   index