One of the first thing a browser does when the user navigates to a website, is to download its HTML and parse it into a DOM, a representation of this document as in-memory objects.
This API is the bread and butter of every front-end web developers. They might abstract it away with libraries such as JQuery, but in the end JQuery itself will use it.
The DOM API contains numerous interfaces and method such as « getElementById », « getElementByClassName », which allows the developer to manipulate the structure of the document through script.
The DOM in cocktail is (surprisingly) implemented in the « dom » package, itself located in the « core » package. One important distinction to make is that the DOM API is not the HTML API. The HTML api is located in the « html » package and we’ll look at it another time.
The HTML API derives from the DOM API, and thus depends on it but the way the DOM API is specified, it can be used to represent any document format based on XML. For instance, browser implementing the SVG format for vector graphics, also use a derived DOM to represent those SVG documents. This explain why the DOM specification is separate from the HTML specification.
A Tree of Node
To best represent the structure of an XML document, the DOM is constructed as a tree of node where each node can be a branch (have child nodes of its own) or a leaf.
There are a few different types of nodes in the DOM, less than 10 (I don’t give the exact number as the next version of the DOM spec seems to remove and add some), the most common are the element and text nodes. An element node is created for each tag that you have in your XML/HTML, for instance for each <div> or <img>. As for text nodes, they represent the text between each tag, the actual content that people browsing your site will read.
The document itself is a type of node, and is the parent of the first element node of the document. For instance, for an HTML document, it will be the parent of the <html> element.
Each attribute on element nodes (for instance « src » on <img>) is also represented as an Attr node, though it seems that in future version it will be replaced by a lighter key/value paire.
Node types also include comment nodes, and weird types of node, like entities reference that nobody ever used and are bound to die of loneliness at some point.
In the « dom » package you can see Haxe files matching the standard node names, such as Element and Text. All nodes derive from the standard « Node » interface, in the corresponding files, which is an abstract base type for all DOM nodes. In this class you can find familiar methods such as « appendChild » or « removeChild » and their default implementation. Each type of node might override those method for their own particular behaviour.
The Node base class itself derives from the EventTarget class which is the standard class managing event dispatching in the DOM. This makes every node capable of listening and dispachting event (even comments node !). We’ll talk more about DOM events in another article.
That’s about all there is to know about the DOM in Cocktail. The implementation of DOM is simple and helped by the fact that it is specified by standard. Some type of nodes, such as DocType are missing for now as well as some standard Node method. When they get implemented, that’s where they will go.