The DOM tree

We will use this XML document for the examples:

<book>
  <title>Test Book</title>
  <chapter>
    <title>Ch1</title>
    <para>p1.1</para>
    <para>p1.2</para>
    <para>p1.3</para>
  </chapter>
  <chapter>
    <title>Ch2</title>
    <para>p2.1</para>
    <para>p2.2</para>
  </chapter>
</book>

W3C DOM models an XML document as a tree of nodes. The node tree of the above XML can be visualized as:

document
 |
 +- element book
     |
     +- text "\n  "
     |
     +- element title
     |   |
     |   +- text "Test Book"
     |
     +- text "\n  "
     |
     +- element chapter
     |   |
     |   +- text "\n    "
     |   |
     |   +- element title
     |   |   |
     |   |   +- text "Ch1"
     |   |
     |   +- text "\n    "
     |   |
     |   +- element para
     |   |   |
     |   |   +- text "p1.1"
     |   |
     |   +- text "\n    "
     |   |
     |   +- element para
     |   |   |
     |   |   +- text "p1.2"
     |   |
     |   +- text "\n    "
     |   |
     |   +- element para
     |      |
     |      +- text "p1.3"
     |
     +- element
         |
         +- text "\n    "
         |
         +- element title
         |   |
         |   +- text "Ch2"
         |
         +- text "\n    "
         |
         +- element para
         |   |
         |   +- text "p2.1"
         |
         +- text "\n    "
         |
         +- element para
             |
             +- text "p2.2"

Note that the disturbing "\n  "-s are the line-breaks (indicated here with \n, an escape sequence used in FTL string literals) and the indentation spaces between the tags.

Notes on the DOM related terminology:

• The topmost node of a tree is called the root. In the case of XML documents, it is always the "document" node, and not the top-most element (book in this example).

• We say that node B is the child of node A, if B is the immediate descendant of A. For example, the two chapter element nodes are the children of the book element node, but the para element nodes are not.

• We say that node A is the parent of node B, if A is the immediate ascendant of node B, that is, if B is the children of A. For example, the book element node is the parent of the two chapter element nodes, but it is not the parent of the para element nodes.

• There are several kind of components that can occur in XML documents, such as elements, text, comments, processing instructions, etc. All such components are nodes in the DOM tree, so there are element nodes, text nodes, comment nodes, etc. In principle, the attributes of elements are also nodes in the tree -- they are the children of the element --, but still, usually we (and other XML related technologies) exclude them of element children. So basically they don't count as children nodes.

The programmer drops the document node of the DOM tree into the FreeMarker data-model, and then the template author can walk the DOM tree using that variable as the starting-point.

The DOM nodes in FTL correspond to node variables. This is a variable type, similarly to type string, number, hash, etc. Node variable type makes it possible for FreeMarker to get the parent node and the child nodes of a node. This is technically required to allow the template author to navigate between the nodes, say, to use the node built-ins or the visit and recurse directives; we will show the usage of these in the further chapters.