Repository: incubator-freemarker-site Updated Branches: refs/heads/asf-site 127455e59 -> 52c070a95
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/xgui_imperative_formal.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/xgui_imperative_formal.html b/builds/2.3.26-nightly/xgui_imperative_formal.html new file mode 100644 index 0000000..324910a --- /dev/null +++ b/builds/2.3.26-nightly/xgui_imperative_formal.html @@ -0,0 +1,545 @@ +<!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>Details - Apache 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="Apache FreeMarker Manual"> +<meta property="og:title" content="Details"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/xgui_imperative_formal.html";> +<link rel="canonical" href="http://freemarker.org/docs/xgui_imperative_formal.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> +<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.org/";>Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html"; title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="searc h-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></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">Apache 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">Details</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> + <div class="content-wrapper"> + <div id="table-of-contents-wrapper" class="col-left"> + <script>var breadcrumb = ["Apache FreeMarker Manual","XML Processing Guide","Imperative XML processing","Details"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></script> + </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">Details</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>, <code class="inline-code">@@local_name</code>, + <code class="inline-code">@@qname</code>, <code class="inline-code">@@namespace</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">@@next_sibling_element</code>, + <code class="inline-code">@@previous_sibling_element</code>, + <code class="inline-code">@@markup</code>, <code class="inline-code">@@nested_markup</code>, + <code class="inline-code">@@text</code>, <code class="inline-code">@@local_name</code>, + <code class="inline-code">@@qname</code>, <code class="inline-code">@@namespace</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>, + <code class="inline-code">@@local_name</code>, <code class="inline-code">@@qname</code>, + <code class="inline-code">@@namespace</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>, + <code class="inline-code">@@local_name</code>, <code class="inline-code">@@qname</code>, + <code class="inline-code">@@namespace</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>, + <code class="inline-code">@@local_name</code>, <code class="inline-code">@@qname</code>, + <code class="inline-code">@@namespace</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>, <code class="inline-code">@@local_name</code>, + <code class="inline-code">@@qname</code>, <code class="inline-code">@@namespace</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>, + <code class="inline-code">@@local_name</code>, <code class="inline-code">@@qname</code>, + <code class="inline-code">@@namespace</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>These 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 registration 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 descendant) <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 + registration 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">@@local_mame</code>: The name of the node + without the namespace prefix.</p> + </li> + + <li> + <p><code class="inline-code">@@namespace</code>: The namespace URL (not the + namespace prefix) of the node.</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 output, 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> + + <li> + <p><code class="inline-code">@@next_sibling_element</code> (since 2.3.26): + The following sibling element of an element node or an empty node + sequence if there's no such element. An element counts as a + sibling of another element if they are on the same hierarchical + level, and there's no other element or non-whitespace character + data (text or CDATA) between the two elements. For example in + <code class="inline-code"><a/><!-- comment + -->#&x20;<b/></code> the two elements are + siblings, but not in <code class="inline-code"><a/>text<b/></code> + or <code class="inline-code"><a/><x/><b/></code>.</p> + </li> + + <li> + <p><code class="inline-code">@@previous_sibling_element</code> (since + 2.3.26): The previous sibling element of an element node or an + empty node sequence if there's no such element. See the last point + for the meaning of sibling.</p> + </li> + </ul> + + + + +<h2 class="content-header header-section2" id="autoid_151">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-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker";>Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/"; rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> +Last generated: +<time itemprop="dateModified" datetime="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/xgui_imperative_learn.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/xgui_imperative_learn.html b/builds/2.3.26-nightly/xgui_imperative_learn.html new file mode 100644 index 0000000..05c3205 --- /dev/null +++ b/builds/2.3.26-nightly/xgui_imperative_learn.html @@ -0,0 +1,656 @@ +<!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>Basics - Apache 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="Apache FreeMarker Manual"> +<meta property="og:title" content="Basics"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/xgui_imperative_learn.html";> +<link rel="canonical" href="http://freemarker.org/docs/xgui_imperative_learn.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> +<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.org/";>Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html"; title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="searc h-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></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">Apache 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_learn.html"><span itemprop="name">Basics</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> + <div class="content-wrapper"> + <div id="table-of-contents-wrapper" class="col-left"> + <script>var breadcrumb = ["Apache FreeMarker Manual","XML Processing Guide","Imperative XML processing","Basics"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></script> + </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.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_imperative_formal.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="xgui_imperative_learn" itemprop="headline">Basics</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_145" data-menu-target="autoid_145">Accessing elements by name</a></li><li><a class="page-menu-link" href="#autoid_146" data-menu-target="autoid_146">Accessing attributes</a></li><li><a class="page-menu-link" href="#autoid_147" data-menu-target="autoid_147">Exploring the tree</a></li><li><a class="page-menu-link" href="#autoid_148" data-menu-target="autoid_148">Using XPath expressions</a></li><li><a class="page-menu-link" href="#autoid_149" data-menu-target="autoid_149">XML namespaces</a></li><li><a class="page-menu-link" href="#autoid_150" data-menu-target="autoid_150">Don't forget escaping!</a></li></ul> </div> <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>This section uses the DOM tree and the variable made in the + <a href="xgui_expose.html">previous chapter</a>.</p> + </div> +<p>Assume that the programmer has put the XML document into the + data-model as variable <code class="inline-code">doc</code>. This variable + corresponds to the root of the <a href="xgui_expose_dom.html">DOM + tree</a>, the "document". The actual variable + structure behind <code class="inline-code">doc</code> is wily enough, and only + roughly resembles the DOM tree. So instead of getting lost in the + details, let's see how to use it by example.</p> + + + + +<h2 class="content-header header-section2" id="autoid_145">Accessing elements by name</h2> + + + <p>This FTL prints the title of the book:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><h1>${doc.book.title}</h1></pre></div> + + <p>The output will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"><h1>Test Book</h1></pre></div> + + <p>As you see, both <code class="inline-code">doc</code> and + <code class="inline-code">book</code> can be used as hashes; you get their child + nodes as sub variables. Basically, you describe the path by which + you reach the target (element <code class="inline-code">title</code>) in the DOM + tree. You may notice that there was some swindle above: with + <code class="inline-code">${doc.book.title}</code>, it seems that we instruct + FreeMarker to print the <code class="inline-code">title</code> element itself, but + we should print its child text node (check the <a href="xgui_expose_dom.html">DOM tree</a>). It still works, because + elements are not only hash variables, but string variables as well. + The scalar value of an element node is the string resulting from the + concatenation of all its text child nodes. However, trying to use an + element as scalar will cause error if the element has child + elements. For example <code class="inline-code">${doc.book}</code> would stop with + error.</p> + + <p>This FTL prints the titles of the two chapters:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><h2>${doc.book.chapter[0].title}</h2> +<h2>${doc.book.chapter[1].title}</h2></pre></div> + + <p>Here, as <code class="inline-code">book</code> has 2 + <code class="inline-code">chapter</code> element children, + <code class="inline-code">doc.book.chapter</code> is a sequence that stores the + two element nodes. Thus, we can generalize the above FTL, so it + works with any number of chapters:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.chapter as ch> + <h2>${ch.title}</h2> +</#list></pre></div> + + <p>But what's if there is only one chapter? Actually, when you + access an element as hash subvariable, it is + <em>always</em> a sequence as well (not only hash and + string), but if the sequence contains exactly 1 item, then the + variable also acts as that item itself. So, returning to the first + example, this would print the book title as well:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><h1>${doc.book[0].title[0]}</h1></pre></div> + + <p>But you know that there is exactly 1 <code class="inline-code">book</code> + element, and that a book has exactly 1 title, so you can omit the + <code class="inline-code">[0]</code>-s. + <code class="inline-code">${doc.book.chapter.title}</code> would work too, if the + book happen to have only 1 <code class="inline-code">chapter</code>-s (otherwise + it is ambiguous: how is it to know if the <code class="inline-code">title</code> + of which <code class="inline-code">chapter</code> you want? So it stops with an + error.). But since a book can have multiple chapters, you don't use + this form. If the element <code class="inline-code">book</code> has no + <code class="inline-code">chapter</code> child, then + <code class="inline-code">doc.book.chapter</code> will be a 0 length sequence, so + the FTL with <code class="inline-code"><#list ...></code> will still + work.</p> + + <p>It is important to realize the consequence that, for example, + if <code class="inline-code">book</code> has no <code class="inline-code">chapter</code>-s then + <code class="inline-code">book.chapter</code> is an empty sequence, so + <code class="inline-code">doc.book.chapter??</code> will <em>not</em> + be <code class="inline-code">false</code>, it will be always + <code class="inline-code">true</code>! Similarly, + <code class="inline-code">doc.book.somethingTotallyNonsense??</code> will not be + <code class="inline-code">false</code> either. To check if there was no children + found, use <code class="inline-code">doc.book.chapter[0]??</code> (or + <code class="inline-code">doc.book.chapter?size == 0</code>). Of course you can + use similarly all the <a href="dgui_template_exp.html#dgui_template_exp_missing">missing value handler + operators</a> (e.g. + <code class="inline-code">doc.book.author[0]!"Anonymous"</code>), just don't + forget that <code class="inline-code">[0]</code>.</p> + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>The rule with sequences of size 1 is a convenience feature + of the XML wrapper (implemented via multi-type FTL variables). It + will not work with other sequences in general.</p> + </div> + + + <p>Now we finish the example by printing all the + <code class="inline-code">para</code>-s of each chapter:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><h1>${doc.book.title}</h1> +<#list doc.book.chapter as ch> + <h2>${ch.title}</h2> + <#list ch.para as p> + <p>${p} + </#list> +</#list></pre></div> + + <p>this will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"><h1>Test</h1> + <h2>Ch1</h2> + <p>p1.1 + <p>p1.2 + <p>p1.3 + <h2>Ch2</h2> + <p>p2.1 + <p>p2.2</pre></div> + + <p>The above FTL could be written more nicely as:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#assign book = doc.book> +<h1>${book.title}</h1> +<#list book.chapter as ch> + <h2>${ch.title}</h2> + <#list ch.para as p> + <p>${p} + </#list> +</#list></pre></div> + + <p>Finally, a generalized usage of the child selector mechanism: + this template lists all <code class="inline-code">para</code>-s of the example XML + document:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.chapter.para as p> + <p>${p} +</#list></pre></div> + + <p>The output will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> <p>p1.1 + <p>p1.2 + <p>p1.3 + <p>p2.1 + <p>p2.2 + </pre></div> + + <p>This example shows that hash sub variables select the children + of a sequence of notes (just in the earlier examples that sequence + happened to be of size 1). In this concrete case, subvariable + <code class="inline-code">chapter</code> returns a sequence of size 2 (since there + are two <code class="inline-code">chapter</code>-s), and then subvariable + <code class="inline-code">para</code> selects the <code class="inline-code">para</code> child + nodes of all nodes in that sequence.</p> + + <p>A negative consequence of this mechanism is that things like + <code class="inline-code">doc.somethingNonsense.otherNonsesne.totalNonsense</code> + will just evaluate to an empty sequence, and you don't get any error + messages.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_146">Accessing attributes</h2> + + + <p>This XML is the same as the original, except that it uses + attributes for the titles, instead of elements:</p> + + + +<div class="code-wrapper"><pre class="code-block code-unspecified"><!-- THIS XML IS USED FOR THE "Accessing attributes" CHAPTER ONLY! --> +<!-- Outside this chapter examples use the XML from earlier. --> + +<book title="Test"> + <chapter title="Ch1"> + <para>p1.1</para> + <para>p1.2</para> + <para>p1.3</para> + </chapter> + <chapter title="Ch2"> + <para>p2.1</para> + <para>p2.2</para> + </chapter> +</book></pre></div> + + <p>The attributes of an element can be accessed in the same way + as the child elements of the element, except that you put an at-sign + (@) before the name of the attribute:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#assign book = doc.book> +<h1>${book.@title}</h1> +<#list book.chapter as ch> + <h2>${ch.@title}</h2> + <#list ch.para as p> + <p>${p} + </#list> +</#list></pre></div> + + <p>This will print exactly the same as the previous + example.</p> + + <p>Getting attributes follows the same logic as getting child + elements, so the result of <code class="inline-code">ch.@title</code> above is a + sequence of size 1. If there were no <code class="inline-code">title</code> + attribute, then the result would be a sequence of size 0. So be + ware, using existence built-ins is tricky here too: if you are + curious if <code class="inline-code">foo</code> has attribute + <code class="inline-code">bar</code> then you have to write + <code class="inline-code">foo.@bar[0]??</code>. (<code class="inline-code">foo.@bar??</code> is + wrong, because it always returns <code class="inline-code">true</code>.) + Similarly, if you want a default value for the + <code class="inline-code">bar</code> attribute, then you have to write + <code class="inline-code">foo.@bar[0]!"theDefaultValue"</code>.</p> + + <p>As with child elements, you can select the attributes of + multiple nodes. For example, this template prints the titles of all + chapters:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.chapter.@title as t> + ${t} +</#list></pre></div> + + + + + +<h2 class="content-header header-section2" id="autoid_147">Exploring the tree</h2> + + + <p>This FTL will enumerate all child nodes of the book + element:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc.book?children as c> +- ${c?node_type} <#if c?node_type == 'element'>${c?node_name}</#if> +</#list></pre></div> + + <p>this will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">- text +- element title +- text +- element chapter +- text +- element chapter +- text</pre></div> + + <p>The meaning of <code class="inline-code">?node_type</code> is probably clear + without explanation. There are several node types that can occur in + a DOM tree, such as <code class="inline-code">"element"</code>, + <code class="inline-code">"text"</code>, <code class="inline-code">"comment"</code>, + <code class="inline-code">"pi"</code>, ...etc.</p> + + <p>The <code class="inline-code">?node_name</code> returns the name of element + for element nodes. For other node types, it also returns something, + but that's mainly useful for declarative XML processing, which will + be discussed in a <a href="xgui_declarative.html">later + chapter</a>.</p> + + <p>If the book element had attributes, they would + <em>not</em> appear in the above list, for practical + reasons. But you can get a list that contains all attributes of the + element, with subvariable <code class="inline-code">@@</code> of the element + variable. If you modify the first line of the XML to this:</p> + + + +<div class="code-wrapper"><pre class="code-block code-unspecified"><book foo="Foo" bar="Bar" baaz="Baaz"></pre></div> + + <p>and run this FTL:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.@@ as attr> +- ${attr?node_name} = ${attr} +</#list></pre></div> + + <p>then you get this output (or something similar):</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">- baaz = Baaz +- bar = Bar +- foo = Foo</pre></div> + + <p>Returning to the listing of children, there is a convenience + subvariable to list only the element children of an element:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc.book.* as c> +- ${c?node_name} +</#list></pre></div> + + <p>This will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">- title +- chapter +- chapter</pre></div> + + <p>You get the parent of an element with the + <code class="inline-code">parent</code> built-in:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#assign e = doc.book.chapter[0].para[0]> +<#-- Now e is the first para of the first chapter --> +${e?node_name} +${e?parent?node_name} +${e?parent?parent?node_name} +${e?parent?parent?parent?node_name}</pre></div> + + <p>This will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">para +chapter +book +@document</pre></div> + + <p>In the last line you have reached the root of the DOM tree, + the document node. It's not an element, and this is why it has that + strange name; don't deal with it now. Obviously, the document node + has no parent.</p> + + <p>You can quickly go back to the document node using the + <code class="inline-code">root</code> built-in:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#assign e = doc.book.chapter[0].para[0]> +${e?root?node_name} +${e?root.book.title}</pre></div> + + <p>This will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">@document +Test Book</pre></div> + + <p>For the complete list of built-ins you can use to navigate in + the DOM tree, read the <a href="ref_builtins_node.html">reference + of node built-ins</a>.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_148">Using XPath expressions</h2> + + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>XPath expressions work only if <a href="http://jaxen.org/";>Jaxen</a> (recommended, but use + at least Jaxen 1.1-beta-8, not older) or <a href="http://xml.apache.org/xalan/";>Apache Xalan</a> + classes are available. (Apache Xalan classes are included in Sun + J2SE 1.4, 1.5 and 1.6 (and maybe later too); no separate Xalan jar + is needed.)</p> + </div> + + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>Don't use the sample XML from the previous section, where + <code class="inline-code">title</code> is an attribute; that applies only to + that section.</p> + </div> + + + <p>If a hash key used with a node variable can't be interpreted + otherwise (see the <a href="xgui_imperative_formal.html">next + section</a> for the precise definition), then it will by + interpreted as an XPath expression. For more information on XPath, + please visit <a href="http://www.w3.org/TR/xpath";>http://www.w3.org/TR/xpath</a>.</p> + + <p>For example, here we list the <code class="inline-code">para</code> elements + of the chapter with <code class="inline-code">title</code> element (not + attribute!) content "Ch1'':</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#list doc["book/chapter[title='Ch1']/para"] as p> + <p>${p} +</#list></pre></div> + + <p>It will print:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"> <p>p1.1 + <p>p1.2 + <p>p1.3</pre></div> + + <p>The rule with sequences of length 1 (explained in earlier + sections) stands for XPath results as well. That is, if the + resulting sequence contains exactly 1 node, it also acts as the node + itself. For example, print the first paragraph of chapter + "Ch1":</p> + + + +<div class="code-wrapper"><pre class="code-block code-template">${doc["book/chapter[title='Ch1']/para[1]"]}</pre></div> + + <p>which prints the same as:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template">${doc["book/chapter[title='Ch1']/para[1]"][0]}</pre></div> + + <p>The context node of the XPath expression is the node (or + sequence of nodes) whose hash subvariable is used to issue the XPath + expression. Thus, this prints the same as the previous + example:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template">${doc.book["chapter[title='Ch1']/para[1]"]}</pre></div> + + <p>Note that currently you can use a sequence of 0 or multiple + (more than 1) nodes as context only if the programmer has set up + FreeMarker to use Jaxen instead of Xalan.</p> + + <p>Also note that XPath indexes sequence items from 1, while FTL + indexes sequence items from 0. Thus, to select the first chapter, + the XPath expression is <code class="inline-code">"/book/chapter[1]"</code>, while + the FTL expression is <code class="inline-code">book.chapter[0]</code>.</p> + + <p>If the programmer has set up FreeMarker to use Jaxen instead + of Xalan, then FreeMarker variables are visible with XPath variable + references:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#assign <strong>currentTitle</strong> = "Ch1"> +<#list doc["book/chapter[title=<strong>$currentTitle</strong>]/para"] as p> +<em>...</em></pre></div> + + <p>Note that <code class="inline-code">$currentTitle</code> is not a FreeMarker + interpolation, as there are no <code class="inline-code">{</code> and + <code class="inline-code">}</code> there. That's an XPath expression.</p> + + <p>The result of some XPath expressions is not a node-set, but a + string, a number, or a boolean. For those XPath expressions, the + result is an FTL string, number, or boolean variable respectively. + For example, the following will count the total number of + <code class="inline-code">para</code> elements in the XML document, so the result + is a number:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template">${x["count(//para)"]}</pre></div> + + <p>The output will be:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output">5</pre></div> + + + + + +<h2 class="content-header header-section2" id="autoid_149">XML namespaces</h2> + + + + + <p>Be default, when you write something like + <code class="inline-code">doc.book</code>, then it will select the element with + name <code class="inline-code">book</code> that does not belongs to any XML + namespace (similarly to XPath). If you want to select an element + that is inside an XML namespace, you must register a prefix and use + that. For example, if element <code class="inline-code">book</code> is in XML + namespace <code class="inline-code">http://example.com/ebook</code>, then you have + to associate a prefix with it at the top of the template 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> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={"e":"http://example.com/ebook"}></pre></div> + + <p>And now you can write expressions as + <code class="inline-code">doc["e:book"]</code>. (The usage of square bracket + syntax was required because the colon would confuse FreeMarker + otherwise.)</p> + + <p>As the value of <code class="inline-code">ns_prefixes</code> is a hash, you + can register multiple prefixes:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={ + "e":"http://example.com/ebook", + "f":"http://example.com/form", + "vg":"http://example.com/vectorGraphics"} +></pre></div> + + <p>The <code class="inline-code">ns_prefixes</code> parameter affects the whole + <a href="dgui_misc_namespace.html">FTL namespace</a>. This means + in practice that the prefixes you have registered in the main page + template will be visible in all <code class="inline-code"><#include + ...></code>-d templates, but not in <code class="inline-code"><#imported + ...></code>-d templates (often referred as FTL libraries). Or + from another point of view, an FTL library can register XML + namespace prefixes for it's own use, without interfering with the + prefix registrations of the main template and other + libraries.</p> + + <p>Note that, if an input document is dominated by a given XML + namespace, you can set that as the default namespace for + convenience. This means that if you don't use prefix, as in + <code class="inline-code">doc.book</code>, then it selects element that belongs to + the default namespace. The setting of the default namespace happens + with reserved prefix <code class="inline-code">D</code>, for example:</p> + + + +<div class="code-wrapper"><pre class="code-block code-template"><#ftl ns_prefixes={"D":"http://example.com/ebook"}></pre></div> + + <p>Now expression <code class="inline-code">doc.book</code> select the + <code class="inline-code">book</code> element that belongs to XML namespace + <code class="inline-code">http://example.com/ebook</code>. Unfortunately, XPath + does not support this idea of a default namespace. Thus, in XPath + expressions, element names without prefixes always select the + elements that does not belong to any XML namespace. However, to + access elements in the default namespace you can directly use prefix + <code class="inline-code">D</code>, for example: + <code class="inline-code">doc["D:book/D:chapter[title='Ch1']"]</code>.</p> + + <p>Note that when you use a default namespace, then you can + select elements that does not belong to any node namespace with + reserved prefix <code class="inline-code">N</code>, for example + <code class="inline-code">doc.book["N:foo"]</code>. It doesn't go for XPath + expressions, where the above can be witten as + <code class="inline-code">doc["D:book/foo"]</code>.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_150">Don't forget escaping!</h2> + + + <p>As we generate output of HTML format in these examples, and + HTML format reserves characters as <code class="inline-code"><</code>, + <code class="inline-code">&</code>, etc., we have to ensure that those will be + escaped. For that, either FreeMarker has to be <a href="pgui_config_outputformatsautoesc.html">properly + configured</a>, or add <code class="inline-code">output_format="HTML"</code> in + the template to the <code class="inline-code">ftl</code> directive calls.</p> + + <p>So if the book title is "Romeo & Juliet", the resulting + HTML output will be correctly:</p> + + + +<div class="code-wrapper"><pre class="code-block code-output"><em>...</em> +<h1>Romeo &amp; Juliet</h1> +<em>...</em></pre></div> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="xgui_imperative.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_imperative_formal.html"><span>Next</span></a></div></div></div></div> </div> + </div> +<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker";>Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/"; rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> +Last generated: +<time itemprop="dateModified" datetime="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/xgui_preface.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/xgui_preface.html b/builds/2.3.26-nightly/xgui_preface.html new file mode 100644 index 0000000..8e1ad39 --- /dev/null +++ b/builds/2.3.26-nightly/xgui_preface.html @@ -0,0 +1,74 @@ +<!doctype html> +<!-- Generated by FreeMarker/Docgen from DocBook --> +<html lang="en" class="page-type-preface"> +<head prefix="og: http://ogp.me/ns#";> +<meta charset="utf-8"> +<title>Preface - Apache 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="Apache FreeMarker Manual"> +<meta property="og:title" content="Preface"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/xgui_preface.html";> +<link rel="canonical" href="http://freemarker.org/docs/xgui_preface.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> +<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache 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://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.org/";>Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html"; title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="searc h-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></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">Apache 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_preface.html"><span itemprop="name">Preface</span></a></li></ul><div class="bookmarks" title="B ookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> + <div class="content-wrapper"> + <div id="table-of-contents-wrapper" class="col-left"> + <script>var breadcrumb = ["Apache FreeMarker Manual","XML Processing Guide","Preface"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></script> + </div> +<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="xgui.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_expose.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-chapter" id="xgui_preface" itemprop="headline">Preface</h1> +</div></div><p>Although FreeMarker was originally designed as a web page template + engine, as of version 2.3 it also targets another application domain: + transforming XML into arbitrary textual output (e.g. HTML files). Thus, + in many cases, FreeMarker is an XSLT alternative.</p><p>Technically, there is nothing special in transforming XML + documents. It's just like when you do anything else with FreeMarker: you + drop the XML document into the data-model (and possibly other + variables), and then you merge the data-model with the FTL template(s) + that generate the output text. The extra features introduced for better + XML processing are the node FTL variable type (symbolizes a node in + generic tree structures, usable not only for XML) and the built-ins and + directives dealing with them, and the XML wrapper you get out-of-the-box + that exposes XML documents as FTL variables for the templates.</p><p>What's the difference between using FreeMarker or XSLT? The FTL + language has the usual imperative/procedural logic. On the other hand, + XSLT is a language with declarative style, designed by "too clever" + people, so it's not easy to adopt its logic, nor to use it in many + cases. Also its syntax is terribly verbose. However, XSLT's + "apply-templates" method can be very handy when you process XML + documents, thus FreeMarker supports something similar called the + "visitor pattern". So in many applications, it is much + easier to write FTL stylesheets than XSLT style-sheets. Another + fundamental difference is that FTL "transforms" the node tree to text, + while XSLT transforms the tree to another tree. So you cannot always use + FreeMarker where you can use XSLT.</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="xgui.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_expose.html"><span>Next</span></a></div></div></div></div> </div> + </div> +<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker";>Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/"; rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> +Last generated: +<time itemprop="dateModified" datetime="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html>
