Google Earth API (Deprecated)

DOM Part I: An Introduction to the Earth API Document Object Model

Roman Nurik, Google Geo APIs Team
August 2009


Objective & Prerequisites

In the article An Overview of Using KML in the Earth API, I briefly discuss the idea of the Earth API's KML Document Object Model (DOM) and its similarities to the HTML DOM specification adopted by modern web browsers. In this article, we'll discuss these similarities and analogies in more detail.

This article assumes you are familiar with JavaScript and know the basics of the Earth API. Make sure you have read the Developer's Guide and have tried the Hello, Earth Demo before you continue.

What is the W3C DOM?

As defined by the World Wide Web Consortium (W3C), the leading standards body in web and related technologies, the Document Object Model (DOM) is:

"a platform- and language-neutral interface that will allow programs and scripts to dynamically access and update the content, structure and style of documents. The document can be further processed and the results of that processing can be incorporated back into the presented page."

In short, the W3C Document Object Model is a recommendation for interfaces for accessing, updating, and reading documents—with an emphasis on hierarchically structured documents. It defines concepts such as nodes, elements and attributes, and recommends constructs for node access like firstChild, parentNode, appendChild, etc.

For a more in-depth tutorial on the W3C DOM recommendation, see this article on QuirksMode.

Web browser DOMs (HTML)

Modern web browsers implement the DOM specification to expose a web page's HTML document tree via native classes in their JavaScript interpreters, such as HTMLDivElement. Developers can thus write JavaScript code to access and manipulate HTML programmatically.

If you've done any JavaScript web development before, then chances are you've already used a web browser's implementation of the DOM spec. For example, commonly used code like the following HTML and JavaScript:

<div id="mydiv">...</div>
var myDiv = document.getElementById('mydiv');

uses the standard getElementById method, defined in the DOM Level 2 specification, to search through a web page's current HTML document for the element with the given ID.

Google Earth Plugin DOMs (KML)

Much like web browsers expose DOM interfaces for HTML documents in their JavaScript implementations, Google Earth Plugin instances expose W3C DOM-like interfaces for the KML content they contain via the Earth API.

So, while web browsers expose interfaces for accessing a <div> and its subtree via mydiv.childNodes, the Google Earth Plugin exposes Earth API interfaces for accessing <Placemark> objects and their tree via placemark.getGeometry and interfaces for accessing a <Folder> and its children via folder.getFeatures().getChildNodes().

The next sections highlight several key analogies between the HTML and KML DOMs discussed in the past two sections.

DOM analogies between web browsers and the Google Earth Plugin

Conceptual analogies

  Web browsers Google Earth Plugin
Exposed document type HTML KML
Exposed via the web browser's native JavaScript implementation the Google Earth API (JavaScript based)
Root interface HTMLDocument GEPlugin
Example interfaces HTMLHtmlElement, HTMLDivElement, HTMLImageElement, etc. KmlDocument, KmlPlacemark, KmlGroundOverlay, etc.
Example elements <html>, <div>, <img>, etc. <Document>, <Placemark>, <GroundOverlay>, etc.

Document access code

  Web browsers Google Earth Plugin
Get the nth child mydiv.childNodes[4] folder.getFeatures().getChildNodes().item(4)
Get a node's next sibling mydiv.nextSibling placemark.getNextSibling()
Get a node's parent mydiv.parentNode placemark.getParentNode()

Document manipulation code

  Web browsers Google Earth Plugin
Creating an element document.createElement('DIV') ge.createPlacemark('')
Inserting an element mydiv.insertBefore(newdiv, otherdiv) folder.getFeatures().insertBefore(placemark, otherplacemark)
Removing an element mydiv.parentNode.removeChild(mydiv) placemark.getParentNode().getFeatures().removeChild(placemark)

Next steps

To see how these concepts can be used to implement common patterns for for traversing KML document hierarchies, read the next article in this series: Part II: Using the GEarthExtensions Utility Library for Easy DOM Manipulation.

To learn more about the W3C DOM spec., check out the W3C Document Object Model documentation or the W3C DOM Technical Reports.

To learn more about DOM methods in the Earth API, visit the Object Containers section of the Developer's Guide.