Built-ins for nodes (for XML)

Note that the variables returned by these built-ins are generated by the node variable implementation it is used with. This means that the returned variables can have extra features in additional to what it stated here, for example, with the XML DOM nodes the sequence retuned by the children built-in also can be used as hash and maybe as string, as it is described in the part about XML processing.

ancestors

A sequence that contains all the node's ancestors, starting with the immediate parent and ending with the root node. The result of this built-in is also a method, by which you can filter the result with the full-qualified name of the node. For example as node?ancestors("section") to get the sequence of all ancestors with name section.

children

A sequence that contains all of this node's child nodes (i.e. immediate descendant nodes).

XML: This is almost the same as special hash key *, except that it returns all nodes, not only elements. So the possible children are element nodes, text nodes, comment nodes, processing instruction nodes, etc. but not attribute nodes. Attribute nodes are excluded from the sequence.

node_name

Returns the string that is used to determine what user-defined directive to invoke to handle this node when it is ``visited''. See: the visit and recurse directives.

XML: If the node is an element or attribute, then the string will be the local (prefix free) name of the element or attribute. Otherwise the name usually starts with @ followed by the node type. See this table. Note that this node name is not the same as the node name returned in the DOM API; the goal of FreeMarker node names is to give the name of the used-defined directive that will process the node.

node_namespace

Returns the namespace string of the node. FreeMarker does not define the exact meaning of node namespace; it depends on what your node variables are modeling. It's possible that a node doesn't have any node namespace defined. In this case, the built-in should evaluate to undefined variable (i.e. node?node_namespace?? is false), so you can't use the returned value.

XML: In the case of XML, it's the XML namespace URI (such as "http://www.w3.org/1999/xhtml"). If an element or attribute node does not use XML namespace, then this built-in evaluates to an empty string. For other XML nodes this built-in always return undefined variable.

node_type

A string that describes the type of node this is. FreeMarker does not define the exact meaning of node type; it depends on what your variables are modeling. It's possible that a node doesn't support node type at all. In this case, the built-in evaluates to an undefined value, so you can't use the returned value. (You can still check if a node supports the type property with node?node_type??.)

XML: The possible values are: "attribute", "text", "comment", "document_fragment", "document", "document_type", "element", "entity", "entity_reference", "notation", "pi". Note that a there is no "cdata" type, because CDATA is considered as plain text node.

parent

The node that is this node's immediate parent in the node tree. The root node has no parent node, so for the root node, the expression node?parent?? evaluates to false.

XML: Note that the value returned by this built-in is also a sequence (same as the result of XPath expression .., when you write someNode[".."]). Also note that for attribute nodes, it returns the element the attribute belongs to, despite that attribute nodes are not counted as children of the element.

root

The node that is the root of the tree of nodes to which this node belongs.

XML: According to W3C, the root of an XML document is not the topmost element node, but the document itself, which is the parent of the topmost element. For example, if you want to get the topmost element of the XML (the so called ``document element''; do not mix it with the ``document''), which is called foo, then you have to write someNode?root.foo. If you write just someNode?root, then you get the document itself, and not the document element.