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 (
bookin 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
chapterelement nodes are the children of the
bookelement node, but the
paraelement 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
bookelement node is the parent of the two
chapterelement nodes, but it is not the parent of the
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
directives; we will show the usage of these in the further