| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-section"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>Formal description - FreeMarker Manual</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="FreeMarker Manual"> |
| <meta property="og:title" content="Formal description"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="http://example.com/xgui_imperative_formal.html"> |
| <link rel="canonical" href="http://example.com/xgui_imperative_formal.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338517553"> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="http://example.com/"> |
| <meta itemprop="name" content="FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> |
| <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo"> |
| </a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="xgui.html"><span itemprop="name">XML Processing Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="xgui_imperative.html"><span itemprop="name">Imperative XML processing</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="xgui_imperative_formal.html"><span itemprop="name">Formal description</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper no-toc"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="xgui_imperative_learn.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_declarative.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="xgui_imperative_formal" itemprop="headline">Formal description</h1> |
| </div></div><p>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 <code class="inline-code">TemplateNodeModel</code> and |
| <code class="inline-code">TemplateHashModel</code>). Thus, you can use the <a href="ref_builtins_node.html">node built-ins</a> 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 |
| <code class="inline-code">TemplateScalarModel</code>).</p><a name="misc.xguiTable"></a> <div class="table-responsive"> |
| <table class="table"> |
| |
| <thead> |
| <tr> |
| <th>Node type (<code class="inline-code">?node_type</code>)</th> |
| |
| |
| <th>Node name (<code class="inline-code">?node_name</code>)</th> |
| |
| |
| <th>String value (e.g. <code class="inline-code"><p>${node}</code>)</th> |
| |
| |
| <th>Special hash keys</th> |
| |
| </tr> |
| |
| </thead> |
| |
| |
| <tbody> |
| <tr> |
| <td><code class="inline-code">"document"</code></td> |
| |
| |
| <td><code class="inline-code">"@document"</code></td> |
| |
| |
| <td>No string value. (Error when you try to use it as |
| string.)</td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"*"</code>, <code class="inline-code">"**"</code>, |
| <code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"element"</code></td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">name</em>"</code>: the |
| name of the element. This is the local name (i.e. name without |
| namespace prefix).</td> |
| |
| |
| <td>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.</td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"*"</code>, <code class="inline-code">"**"</code>, |
| <code class="inline-code">"@<em class="code-color">attrName</em>"</code>, |
| <code class="inline-code">"@<em class="code-color">prefix</em>:<em class="code-color">attrName</em>"</code>, |
| <code class="inline-code">"@@"</code>, <code class="inline-code">"@*"</code>, |
| <code class="inline-code">"@@start_tag"</code>, |
| <code class="inline-code">"@@end_tag"</code>, |
| <code class="inline-code">"@@attributes_markup"</code>, |
| <code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code>, <code class="inline-code">"@@qname"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"text"</code></td> |
| |
| |
| <td><code class="inline-code">"@text"</code></td> |
| |
| |
| <td>The text itself.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"pi"</code></td> |
| |
| |
| <td><code class="inline-code">"@pi$<em class="code-color">target</em>"</code></td> |
| |
| |
| <td>The part between the target name and the |
| <code class="inline-code">?></code>.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"comment"</code></td> |
| |
| |
| <td><code class="inline-code">"@comment"</code></td> |
| |
| |
| <td>The text of the comment, without the delimiters |
| <code class="inline-code"><!--</code> and <code class="inline-code">--></code>.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"attribute"</code></td> |
| |
| |
| <td><code class="inline-code">"<em class="code-color">name</em>"</code>: the |
| name of the attribute. This is the local name (i.e. name without |
| namespace prefix).</td> |
| |
| |
| <td>The value of the attribute.</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code>, <code class="inline-code">"@@qname"</code></td> |
| |
| </tr> |
| |
| |
| <tr> |
| <td><code class="inline-code">"document_type"</code></td> |
| |
| |
| <td><code class="inline-code">"@document_type$<em class="code-color">name</em>"</code>: |
| <code class="inline-code"><em class="code-color">name</em></code> is the name |
| of the document element.</td> |
| |
| |
| <td>No string value. (Error when you try to use it as |
| string.)</td> |
| |
| |
| <td><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code>, |
| <code class="inline-code">"@@text"</code></td> |
| |
| </tr> |
| |
| </tbody> |
| |
| </table> |
| </div> |
| <p>Notes:</p><ul> |
| <li> |
| <p>There is no CDATA type. CDATA nodes are transparently |
| considered as text nodes.</p> |
| </li> |
| |
| <li> |
| <p>Variables do <em>not</em> support |
| <code class="inline-code">?keys</code> and <code class="inline-code">?values</code>.</p> |
| </li> |
| |
| <li> |
| <p>Element and attribute node names are local names, that is, |
| they do not contain the namespace prefix. The URI of the namespace |
| the node belongs to can be queried with the |
| <code class="inline-code">?node_namespace</code> built-in.</p> |
| </li> |
| |
| <li> |
| <p>XPath expression needs Jaxen (recommended, but please use |
| 1.1-beta-8 or later; <a href="http://jaxen.org/">download |
| it here</a>) or Apache Xalan classes available, or an error |
| will stop template execution. Note, however, that as some special |
| hash keys hide the XPath expressions of the same meaning, those |
| XPath expressions will work even if there is no XPath |
| implementation available. <span class="marked-for-programmers">If both |
| Xalan and Jaxen is available, FreeMarker will use Xalan, unless |
| you choose Jaxen by calling |
| <code class="inline-code">freemarker.ext.dom.NodeModel.useJaxenXPathSupport()</code> |
| from Java.</span></p> |
| </li> |
| |
| <li> |
| <p>If Jaxen is used for the XPath support (not Xalan), then |
| FreeMarker variables are visible with XPath variable references |
| (e.g. |
| <code class="inline-code">doc["book/chapter[title=$currentTitle]"]</code>).</p> |
| </li> |
| </ul><p>Meaning of special hash keys:</p><ul> |
| <li> |
| <p><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code>: |
| Returns the sequence of child nodes that are elements of name |
| <code class="inline-code"><em class="code-color">elementName</em></code>. (Note |
| that the term ``child'' means <em>immediate</em> |
| descendant.) The selection is XML name-space aware, unless the XML |
| document was persed with an XML parser that was not in namespace |
| aware mode. In XML name-space aware mode, names without prefix |
| (<em>elementName</em>) selects only elements |
| that doesn't belong to any XML name-space (unless you have |
| registered a default XML namespace), and names with prefix |
| (<em>prefix</em>:<em>elementName</em>) |
| selects only elements that are belonging to the XML namespace |
| denoted by the prefix. The registarion of prefixes and the setting |
| of the default XML namespace is done with the |
| <code class="inline-code">ns_prefixes</code> parameter of the <a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code> |
| directive</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"*"</code>: Returns the sequence of all child |
| (direct descedant) <em>element</em> nodes. The |
| sequence will contain the elements in the ``document order'', that |
| is, in the order in which the first character of the XML |
| representation of each node occurs (after expansion of general |
| entities).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"**"</code>: Returns the sequence of all |
| descendant <em>element</em> nodes. The sequence will |
| contain the elements in the document order.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@<em class="code-color">attName</em>"</code>, |
| <code class="inline-code">"@<em class="code-color">prefix</em>:<em class="code-color">attrName</em>"</code>: |
| Returns the attribute |
| <code class="inline-code"><em class="code-color">attName</em></code> of the |
| element as a sequence of size 1 that contains the attribute node, |
| or as an empty sequence if the attribute does not exist (so to |
| check if an attribute exists use |
| <code class="inline-code">foo.@<em class="code-color">attName</em>[0]??</code>, |
| <em>not</em> |
| <code class="inline-code">foo.@<em class="code-color">attName</em>??</code>). As |
| with special key |
| <code class="inline-code">"<em class="code-color">elementName</em>"</code>, if |
| the length of the sequence is 1, then it also acts as its first |
| subvariable. If no |
| <code class="inline-code"><em class="code-color">prefix</em></code> is used, then |
| it returns only attribute that does not use XML namespace (even if |
| you have set a default XML namespace). If a |
| <code class="inline-code"><em class="code-color">prefix</em></code> is used, it |
| returns only the attribute that belongs to the XML namespace |
| associated with the |
| <code class="inline-code"><em class="code-color">prefix</em></code>. The |
| registarion of prefixes is done with the |
| <code class="inline-code">ns_prefixes</code> parameter of the <a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code> |
| directive</a>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@"</code> or <code class="inline-code">"@*"</code>: Returns |
| the sequence of attribute nodes belonging to the parent element. |
| This is the same as XPath <code class="inline-code">@*</code>.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@qname"</code>: Returns the full-qualified |
| name of the element (such as <code class="inline-code">e:book</code>, in |
| contrast to the local name returned by |
| <code class="inline-code">?node_name</code> that is <code class="inline-code">book</code>) . |
| The prefix used (as <code class="inline-code">e</code>) is chosen based on the |
| prefix registered in the current namespace with the |
| <code class="inline-code">ns_prefixes</code> parameter of the |
| <code class="inline-code">ftl</code> directive, and not influenced by the prefix |
| used in the source XML document. If you have set a default XML |
| namespace, then for nodes that use that, prefix |
| <code class="inline-code">D</code> will be used. For nodes that does not belong |
| to an XML namespace, no prefix is used (even if you have set a |
| default namespace). If there is no prefix registered for the |
| namespace of the node, the result is a non-existent variable |
| (<code class="inline-code">node.@@qname??</code> is |
| <code class="inline-code">false</code>).</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@markup"</code>: This returns the full XML |
| markup of a node, as a string. (Full XML markup means that it also |
| contains the markup of the child nodes, and the markup of the |
| children of the child nodes, and so on.) The markup you get is not |
| necessary the same as the markup in the source XML file, it's just |
| semantically identical. Especially, note that CDATA sections will |
| become to plain text. Also note that depending on how did you |
| wrapped the original XML document with FreeMarker, comment or |
| processing instruction nodes may were removed, and then they will |
| be missing from the output of course. The first outputted start |
| tag will contain |
| <code class="inline-code">xmlns:<em class="code-color">prefix</em></code> |
| attributes for each XML name-spaces used in the outputted XML |
| fragment, and those prefixes will be used in the outputted element |
| and attribute names. These prefixes will be the same as the |
| prefixes registered with the <code class="inline-code">ns_prefixes</code> |
| parameter of the <code class="inline-code">ftl</code> directive (no prefix will |
| be used for <code class="inline-code">D</code>, as it will be registered as the |
| default name-space with an <code class="inline-code">xmlns</code> attribute), or |
| if no prefix was assigned for a XML name-space with that, then an |
| arbitrary chosen unused prefix is used.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@nested_markup"</code>: This is similar to |
| <code class="inline-code">"@@markup"</code>, but it returns the XML markup of an |
| element without its opening and closing tags. For the document |
| node, it returns the same as <code class="inline-code">"@@markup"</code>. For |
| other node types (text, processing instruction, etc.), it returns |
| an empty string. Unlike with <code class="inline-code">"@@markup"</code>, no |
| <code class="inline-code">xmlns:<em class="code-color">prefix</em></code> |
| attributes will be placed into the ouput, but regarding the |
| prefixes used in element and attribute names the rules are the |
| same.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@text"</code>: This returns the value of all |
| text nodes that occur within the node (all descendant text nodes, |
| not just direct children), concatenated together into a single |
| string. If the node has no text node children, then the result is |
| an empty string.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@start_tag"</code>: Returns the markup of the |
| <a href="gloss.html#gloss.startTag">start-tag</a> of the element |
| node. As with <code class="inline-code">@@markup</code>, the output is not |
| necessary the same as in the original XML document, but it is |
| semantically equivalent with that. Regarding the XML name-spaces |
| (<code class="inline-code">xmlns:<em class="code-color">prefix</em></code> |
| attributes in the output, etc.) the rules are the same as with |
| <code class="inline-code">"@@markup"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@end_tag"</code>: Returns the markup of the |
| <a href="gloss.html#gloss.endTag">end-tag</a> of the element node. |
| As with <code class="inline-code">@@markup</code>, the output is not necessary |
| the same as in the original XML document, but it is semantically |
| equivalent with that.</p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">@@attributes_markup</code>: Returns the markup |
| of the <a href="gloss.html#gloss.attribute">attributes</a> of the |
| element node. As with <code class="inline-code">@@markup</code>, the output is |
| not necessary the same as in the original XML document, but it is |
| semantically equivalent with that.</p> |
| </li> |
| </ul> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_74">Node sequences</h2> |
| |
| |
| <p>Many of the special hash keys (indicated in the above list), |
| and XPath expressions that result in node-sets (see the <a href="http://www.w3.org/TR/xpath">XPath recommendation</a>) |
| return a sequence of nodes.</p> |
| |
| <p>These node sequences, if they store exactly 1 subvariable, |
| will also act as the subvariable itself. For example, |
| <code class="inline-code">${book.title[0]}</code> will do the same as |
| <code class="inline-code">${book.title}</code>, if there is only one |
| <code class="inline-code">title</code> element child of element |
| <code class="inline-code">book</code>.</p> |
| |
| <p>Returning an empty node sequence is a normal situation. For |
| example, if in a concrete XML document, element |
| <code class="inline-code">book</code> has no child element |
| <code class="inline-code">chapter</code>, then <code class="inline-code">book.chapter</code> |
| results in an empty node sequence. Beware! This also means, that |
| <code class="inline-code">book.chaptre</code> (note the typo) will also return |
| empty node sequence, and will not stop with error. Also, |
| <code class="inline-code">book.chaptre??</code> (note the typo) will return |
| <code class="inline-code">true</code> because the empty sequence exists, so you |
| have to use <code class="inline-code">book.chaptre[0]??</code> for the |
| check.</p> |
| |
| <p>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:</p> |
| |
| <ul> |
| <li> |
| <p><code class="inline-code">"<em class="code-color">elementName</em>"</code>, |
| <code class="inline-code">"<em class="code-color">prefix</em>:<em class="code-color">elementName</em>"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@<em class="code-color">attrName</em>"</code>, |
| <code class="inline-code">"@<em class="code-color">prefix</em>:<em class="code-color">attrName</em>"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@markup"</code>, |
| <code class="inline-code">"@@nested_markup"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@text"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"*"</code>, <code class="inline-code">"**"</code></p> |
| </li> |
| |
| <li> |
| <p><code class="inline-code">"@@"</code>, <code class="inline-code">"@*"</code></p> |
| </li> |
| </ul> |
| |
| <p>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 <code class="inline-code">*</code> or |
| <code class="inline-code">@foo</code>), 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.</p> |
| |
| <p>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.</p> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="xgui_imperative_learn.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_declarative.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2020-07-09T23:48:37Z" title="Thursday, July 9, 2020 11:48:37 PM GMT">2020-07-09 23:48:37 GMT</time> </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2020 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p> |
| </div></div></div></body> |
| </html> |
