Formal description

Every variable that corresponds to a single node in the DOM tree is a multi-type variable of type node and type hash (for programmers: implements both TemplateNodeModel and TemplateHashModel). Thus, you can use the node built-ins with them. Hash keys are interpreted as XPath expressions, except the special keys shown in the table below. Some of the node variables also have string type, so you can use them as string variables (for programmers: they implement TemplateScalarModel).

Node type (?node_type) Node name (?node_name) String value (e.g. <p>${node}) Special hash keys
"document" "@document" No string value. (Error when you try to use it as string.) "elementName", "prefix:elementName", "*", "**", "@@markup", "@@nested_markup", "@@text"
"element" "name": the name of the element. This is the local name (i.e. name without namespace prefix). If it has no element children, the text of all text node children concatenated together. Error otherwise, when you try to use it as string. "elementName", "prefix:elementName", "*", "**", "@attrName", "@prefix:attrName", "@@", "@*", "@@start_tag", "@@end_tag", "@@attributes_markup", "@@markup", "@@nested_markup", "@@text", "@@qname"
"text" "@text" The text itself. "@@markup", "@@nested_markup", "@@text"
"pi" "@pi$target" The part between the target name and the ?>. "@@markup", "@@nested_markup", "@@text"
"comment" "@comment" The text of the comment, without the delimiters <!-- and -->. "@@markup", "@@nested_markup", "@@text"
"attribute" "name": the name of the attribute. This is the local name (i.e. name without namespace prefix). The value of the attribute. "@@markup", "@@nested_markup", "@@text", "@@qname"
"document_type" "@document_type$name": name is the name of the document element. No string value. (Error when you try to use it as string.) "@@markup", "@@nested_markup", "@@text"


Meaning of special hash keys:

Node sequences

Many of the special hash keys (indicated in the above list), and XPath expressions that result in node-sets (see the XPath recommendation) return a sequence of nodes.

These node sequences, if they store exactly 1 subvariable, will also act as the subvariable itself. For example, ${book.title[0]} will do the same as ${book.title}, if there is only one title element child of element book.

Returning an empty node sequence is a normal situation. For example, if in a concrete XML document, element book has no child element chapter, then book.chapter results in an empty node sequence. Beware! This also means, that book.chaptre (note the typo) will also return empty node sequence, and will not stop with error. Also, book.chaptre?? (note the typo) will return true because the empty sequence exists, so you have to use book.chaptre[0]?? for the check.

Node sequences that store not 1 nodes (but 0 or more than 1 nodes) also support some of the hash keys described above. Namely, the following special keys are supported:

When you apply one of the above special keys on a node sequence that contains more than 1 or 0 nodes, then for each node in the sequence (where the special key does make sense, e.g. text nodes will be skipped for key * or @foo), the special key will be applied as it was explained for single nodes, and the results will be concatenated to form the final result. The results will be concatenated in the order as the corresponding nodes occur in the node sequence. The concatenation means string or sequence concatenation depending on the type of the results. If the special key would result in a string for a single node, then for multiple nodes the result is a single string too (the results for the single nodes concatenated), and if the special key would return a sequence for a single node, then for multiple nodes the result is a single sequence too. If there are 0 nodes in the sequence you apply the special key on, the string result is an empty string or an empty sequence respectively.

XPath expressions can be used with node sequences. However, for 0 or more than 1 nodes it will work only if you use Jaxen instead of Xalan, because of the limitations of the Xalan XPath implementation.

FreeMarker Manual -- For FreeMarker 2.3.20
HTML generated: 2013-06-27 20:54:33 GMT
Edited with XMLMind XML Editor