Appendix A: SVG Document Object Model (DOM)

This appendix is normative.

A.1. SVG DOM overview

The SVG DOM is defined in terms of Web IDL interfaces. All IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

The SVG DOM builds upon a number of DOM specifications. In particular:

• The SVG DOM requires complete support for DOM4 [DOM4]
• The SVG DOM requires complete support for DOM Level 2 Views [DOM2VIEWS].
• The SVG DOM requires support for relevant aspects of DOM Level 3 Events [DOM3EVENTS]. (For the specific features from DOM 3 Events that are required, see see Relationship with DOM Level 3.)
• The SVG DOM requires support for relevant aspects of UI Events [UIEVENTS]. (For the specific features from DOM 3 Events that are required, see see Relationship with DOM Level 3 Events.)
• For implementations that support CSS, the SVG DOM requires complete support for DOM Level 2 Style Sheets ([DOM2STYLE], chapter 1) and relevant aspects of DOM Level 2 CSS ([DOM2STYLE], chapter 2). (For the specific features from DOM 2 CSS that are required, see Relationship with DOM Level 2 CSS.)

All SVG DOM objects that directly correspond to an attribute, e.g. the SVGAnimatedLength ry in an SVGRectElement, are live. This means that any changes made to the attribute are immediately reflected in the corresponding SVG DOM object.

A.1.1. SVG DOM object initialization

The SVG DOM allows attributes to be accessed even though they haven't been specified explicitly in the document markup. When this happens an appropriate object is created, initialized and returned. This newly constructed object does not affect rendering until it is modified for the first time. Modifications made to the corresponding attribute are immediately reflected in the object.

For example, if lineElement.x1.baseVal is accessed and the ‘x1’ attribute was not specified in the document, the returned SVG DOM object would represent the value 0 user units.

For cases where an attribute has a default value the returned SVG DOM object that must reflect that value, and for all other cases the object is initialized as described below. If a particular SVG DOM interface is not listed below that means that the object initialization shall be done using the values for the objects that the interface contains, e.g DOMString in the case of SVGAnimatedString.

SVGTextContentElement.textLength

Initialized with the return-value of getComputedTextLength on the same element.

DOMString

Initialized as the empty string ("").

float

long

short

Initialized as 0.

boolean

Initialized as false.

SVGLength

Initialized as 0 user units (SVG_LENGTHTYPE_NUMBER).

SVGLengthList

SVGNumberList

SVGPointList

SVGStringList

SVGTransformList

Initialized as the empty list.

SVGAngle

Initialized as 0 in unspecified units (SVG_ANGLETYPE_UNSPECIFIED).

SVGZoomAndPan

Initialized as 0 (SVG_ZOOMANDPAN_UNKNOWN).

SVGPreserveAspectRatio

Initialized as 'xMidYMid meet'.

A.2. Elements in the SVG DOM

Every Element object that corresponds to an SVG element (that is, an element with namespace URI "http://www.w3.org/2000/svg" and a local name that is one of the elements defined in this specification) must also implement the DOM interface identified in element definition. For example, in The ‘rect’ element, the SVGRectElement interface is identified. This means that every Element object whose namespace URI is "http://www.w3.org/2000/svg" and whose local name is "rect" must also implement SVGRectElement.

A.3. Naming conventions

The SVG DOM follows similar naming conventions to the Document Object Model HTML ([DOM1], chapter 2).

All names are defined as one or more English words concatenated together to form a single string. Property or method names start with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object.

For attributes with the CDATA data type, the case of the return value is that given in the source document.

A.4. Relationship with DOM Level 3 Events

The SVG DOM supports select all interfaces defined in, and all the event types from, DOM Level 3 Events [DOM3EVENTS].

• The following event types are triggered due to state changes in animations. (The definitions for these events can be found in the description of the TimeEvent interface.)
  • beginEvent
  • endEvent
  • repeatEvent

While event listeners can be registered using an addEventListener call on any element in the DOM, the use of event attributes on elements where those attributes are disallowed will not result in their being invoked if the relevant event is dispatched to the element. For example, if the ‘onclick’ attribute were specified on a ‘title’ element, its contents would never be run in response to a click event:

<svg xmlns="http://www.w3.org/2000/svg">
  <title onclick="alert('Hello')">Invalid event attribute</title>
  <script>
    // Find the 'title' element.
    var title = document.getElementsByTagNameNS("http://www.w3.org/2000/svg", "title")[0];

    // Create and initialize a 'click' event.
    var event = document.createEvent("MouseEvent");
    event.initMouseEvent("click", true, false, this, 1, 0, 0, 0, 0, false,
                         false, false, false, 0, null);

    // Dispatch the event to the 'title' element.  Since onclick="" is not
    // allowed on 'title', the alert will not show.
    title.dispatchEvent(event);
  </script>
</svg>

See the Attribute Index for details on which elements a given event attribute is allowed to be specified on.

Implementors may view the setting of event attributes as the creation and registration of an EventListener on the EventTarget. Such event listeners are invoked only for the "bubbling" and "at target" phases, as if false were specified for the useCapture argument to addEventListener. This EventListener behaves in the same manner as any other which may be registered on the EventTarget.

If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. Futhermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.

In ECMAScript, one way to establish an event listener is to define a function and pass that function to the addEventListener method:

function myAction1(evt) {
  // process the event
}
// ... later ...
myElement.addEventListener("click", myAction1, false)

In ECMAScript, the character data content of an event attribute becomes the definition of the ECMAScript function which gets invoked in response to the event. As with all registered ECMAScript event listener functions, this function receives an Event object as a parameter, and the name of the Event object is evt. For example, it is possible to write:

<rect onclick="MyClickHandler(evt)" .../>

which will pass the Event object evt into function MyClickHandler.

A.5. Relationship with DOM Level 2 CSS

The section describes the facilities from DOM Level 2 CSS ([DOM2STYLE], chapter 2) that are part of the SVG DOM.

A.5.1. User agents that support styling with CSS

For visual media ([CSS21], section 7.3.1), user agents must support all of the required interfaces defined in DOM Level 2 CSS. All of the interfaces that are optional for DOM Level 2 CSS are also optional for user agents implementing the SVG DOM.

A.6. Invalid values

If a script sets a DOM attribute to an invalid value (e.g., a negative number for an attribute that requires a non-negative number or an out-of-range value for an enumeration), unless this specification indicates otherwise, no exception shall be raised on setting, but the given document fragment shall become technically in error as described in Error processing.