The ElementTraversal Specification

Abstract

This specification defines the ElementTraversal interface, which allow script navigation of the elements of a DOM tree, excluding all other nodes in the DOM, such as text nodes. It also provides a property to expose the number of child elements of an element. It is intended to provide a more convenient alternative to existing DOM navigation interfaces, with a low implementation footprint.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is produced by the Web API WG (part of the Rich Web Clients Activity). This document has no formal standing within the W3C. Please send comments to public-webapi@w3.org, the public email list for issues related to Web APIs.

The patent policy for this document is the 5 February 2004 W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Web API Working Group's patent disclosure page. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of contents

• 1. Introduction
• • 1.1. Not in This Specification
  • 1.2. Conformance
• 2. ElementTraversal Interface
• • 2.1. firstElementChild
  • 2.2. lastElementChild
  • 3.3. previousElementSibling
  • 2.4. nextElementSibling
  • 2.5. childElementCount
• 3. Examples of usage
• 4. Relationship to other DOM specifications
• • 4.1. DOM Level 1 Core
  • 4.2. DOM Level 2 Range & Traversal
  • 4.3. DOM Level 3 Core
• 5. Security Considerations

• A. IDL Definitions
• B. ECMAScript Language Binding
• C. Java Language Binding
• D. Change History
• E. References
• F. Acknowledgements

1. Introduction

The Node interface defines 11 node types, but most commonly authors wish to operate solely on nodeType 1, the element node. Other node types include the document element and text nodes, which include whitespace and linebreaks. DOM 1 node traversal includes all of these node types, which is often a source of confusion for authors and which requires an extra step for authors to confirm that the expected element node interfaces are available. This introduces an additional performance constraint.

ElementTraversal is an interface that allows the author to restrict navigation to element nodes. It permits navigation from an element to its first element child, its last element child, and to its next or previous element siblings. Because the implementation exposes only the element nodes, the memory and computational footprint of the DOM representation can be optimized for contrained devices.

The DOM 1 Node interface also defines the childNodes attribute, which is a live list of all child nodes of the node, and which has a length property to exposes the total number of child nodes. The length property is useful for preprocessing operations and calculations before, or instead of, looping through the child nodes. ElementTraversal's childElementCount provides similar functionality, but only reports the number of element nodes, which is often what is desired for such operations.

2. ElementTraversal Interface

This section is normative.

The ElementTraversal interface is a set of properties on the Element object, which allow an author to easily navigate between elements. Four of the properties, firstElementChild, lastElementChild, previousElementSibling, and nextElementSibling, each provide a live reference to another element with the defined relationship to the current element, if the related element exists. The fifth property, childElementCount, exposes the number of child elements of an element, for preprocessing before navigation. A conforming User Agent must implement all five methods. A User Agent may implement similar interfaces in other specifications, but such implementation is not required for conformnce to this specification, if the User Agent is designed for a minimal code footprint.

This interface must be implemented on all elements, regardless of their namespace. For the purpose of ElementTraversal, an entity reference node which represents an element must be treated as an element node. Navigation must be irrespective of namespace, e.g. if an element in the HTML namespace is followed by element in the SVG namespace, nextElementSibling will allow you to navigate from the HTML element to the SVG element.

2.1. firstElementChild

Accessing this property of an element must return a reference to the first child node of that element which is of nodeType 1, as an Element object. If the element on which this property is accessed does not have any child nodes, or if none of those child nodes are element nodes, then this property must return null.

2.2. lastElementChild

Accessing this property of an element must return a reference to the last child node of that element which is of nodeType 1, as an Element object. If the element on which this property is accessed does not have any child nodes, or if none of those child nodes are element nodes, then this property must return null.

2.3. previousElementSibling

Accessing this property of an element must return a reference to the sibling node of that element which most immediately precedes that element in document order, and which is of nodeType 1, as an Element object. If the element on which this property is accessed does not have any preceding sibling nodes, or if none of those preceding sibling nodes are element nodes, then this property must return null.

2.4. nextElementSibling

Accessing this property of an element must return a reference to the sibling node of that element which most immediately follows that element in document order, and which is of nodeType 1, as an Element object. If the element on which this property is accessed does not have any following sibling nodes, or if none of those following sibling nodes are element nodes, then this property must return null.

2.5. childElementCount

Accessing this property of an element must return the current number of child nodes of that element which are of nodeType 1. An implementation may store this number, or it may calculate it upon evocation of this property, but the number must always represent the number of child element nodes at the time the property is accessed. Only immediate child nodes must counted, e.g. elements which are child nodes of one of the child nodes of the element on which the property is accessed are not included in this count. If the element on which this property is accessed does not have any child nodes, or if none of those child nodes are element nodes, then this property must return 0.

3. Examples of usage

This section is informative.

This section illustrates several ECMAScript [ECMA262] examples using ElementTraversal.

3.1. Example of previousElementSibling

The following code takes an element as a parameter, and returns the element's position in document order within its parent:

function findPosition( el ) {
   var pos = 0;

   // step through child elements in reverse order
   while ( null != el ) {
      //navigate to previous sibling
      el = el.previousElementSibling;
      pos++;
   }
   
   return pos;
}

3.2. Example of Precalculating Values and Looping Through Elements

The following code takes an element as a parameter, and place each of its children equidistantly according to the available space:

function spaceChildren( el ) {
   // get count of element nodes
   var elCount = el.childElementCount;
   
   var eachWidth = window.innerWidth / elCount;

   // get first child element 
   var childEl = el.firstElementChild;

   // set initial position
   var nextPos = eachWidth/2;
   
   // step through child elements one by one
   while ( childEl ) {
      // position child
      childEl.style.setProperty( 'position', 'absolute', '' );
      childEl.style.setProperty( 'left', nextPos + 'px', '' );
      
      //increment position by width
      nextPos += eachWidth;
      
      //then navigate to next child element
      childEl = childEl.nextElementSibling;
   }
}

3.3. Example of Comparison with Other DOM Interfaces

The following code contrasts ElementTraversal with other DOM interfaces, given the following SVG fragment:

<g id='shapeGroup'>

   <rect id='rect1' x='5' y='5' width='310' height='220' rx='15' ry='15' fill='skyblue'/>
   <rect id='rect2' x='15' y='15' width='210' height='180' rx='15' ry='15' fill='cornflowerblue'/>

   <ellipse id='ellipse1' cx='90' cy='70' rx='50' ry='30' fill='yellow' stroke='orange'/>

   <path id='path1' stroke-width='15' stroke='orange' fill='none' stroke-linecap='round' d='M25,150 C180,180 290,0 400,140 S420,100 460,90'/>  
   <text id='text1' x='0' y='0' font-size='35' fill='yellow' stroke='orange'  stroke-width='2' stroke-linejoin='round' font-weight='bold'><textPath id='textPath1' xlink:href="#path1">when life gives you lemons...</textPath></text>

</g>

function walkTest( el ) {
   // get count of all nodes
   var nodeCount = el.childNodes.length;

   // get first child node 
   var firstNode = el.firstChild;

   // get first child element 
   var childEl = el.firstElementChild;

   // step through child elements one by one
   while ( childEl ) {
      // do something useful here...
      //then navigate to next child element
      childEl = childEl.nextElementSibling;
   }
}

Where el is the 'g' element with id "shapeGroup", nodeCount will have the value 11. firstNode will be a text node (nodeType of 3), and is not equivalent to the first assigned value of childEl, which is an element node (nodeType of 1) with the 'id' "rect1". The while loop will cycle 4 more times, iterating through the sibling element nodes, respectively "rect2", "ellipse1", "path1", and "text1". The last value of childEl will be null, as "text1" does not have a next element sibling, though it does have a next node sibling.

Note that an SVG 'text' element is not the same as a text node. Note also that the SVG 'textPath' child element of the 'text' element is not included in the iteration, as it is not a sibling of childEl.

4. Relationship to other DOM specifications

This section is informative.

5. Security Considerations

This section is informative.

There are no known security considerations involved in the implementation or use of the ElementTraversal interface. This section shall be revised if future security considerations are discovered.

A. IDL Definitions

B. ECMAScript Language Binding

C. Java Language Binding

package org.w3c.dom;

public interface ElementTraversal 
{
    public Element getFirstElementChild();

    public Element getLastElementChild();

    public Element getPreviousElementSibling();

    public Element getNextElementSibling();

    public int getChildElementCount();
}

D. Change History

http://www.w3.org/TR/SVGMobile12/svgudom.html#svg__ElementTraversal

Original version in SVG Tiny 1.2 in the SVG namespace.

http://dev.w3.org/cvsweb/~checkout~/2006/webapi/ElementTraversal/publish/ElementTraversal.html?rev=1.0

First draft under WebAPI WG. Migrated to DOM and DOM namespace as a generic facility, at the request of CDF, JCP, and other groups.

http://dev.w3.org/cvsweb/~checkout~/2006/webapi/ElementTraversal/publish/ElementTraversal.html?rev=1.5

Introduced childElementCount. Added normative expository section. Added new examples. Fleshed out and cleaned up document for transition to public working draft.

http://dev.w3.org/cvsweb/~checkout~/2006/webapi/ElementTraversal/publish/ElementTraversal.html?rev=1.6

Reordered some sections for clarity of reading.

Various editorial changes and corrections and modifications to the examples are made from draft to draft.

E. References

Normative references

[RFC2119] Key words for use in RFCs to indicate Requirement Levels

S Bradner, 1997. The specification for how to use english to specify normativity, as if it were a technical language. Available at http://rfc.net/rfc2119.html

[DOM 1 Core] Document Object Model - Level 1 Core

Available at http://www.w3.org/TR/REC-DOM-Level-1/

[ECMA262] ECMAScript Language Specification, 3^rd edition

Available at http://www.ecma-international.org/publications/standards/Ecma-262.htm

Informative references

[SVGD] The proposed ElementTraversal interface in SVG

Available at http://www.w3.org/TR/SVGMobile12/svgudom.html#svg__ElementTraversal

F. Acknowledgments

The editor would like to thank the following people for contributing to this specification: Robin Berjon, Chris Lilley, Nandini Ramani, Andrew Sledd, Charles McCathieNevile, Jean-Yves Bitterlich, Bjoern Hoehrmann, and Chaals Macca. The editor would additionally like to thank the SVG WG for producing the draft [SVGD] on which this was initially based.