http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a4004324/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 deleted file mode 100644 index 324910a..0000000 --- a/builds/2.3.26-nightly/xgui_imperative_formal.html +++ /dev/null @@ -1,545 +0,0 @@ -<!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/a4004324/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 deleted file mode 100644 index 05c3205..0000000 --- a/builds/2.3.26-nightly/xgui_imperative_learn.html +++ /dev/null @@ -1,656 +0,0 @@ -<!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/a4004324/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 deleted file mode 100644 index 8e1ad39..0000000 --- a/builds/2.3.26-nightly/xgui_preface.html +++ /dev/null @@ -1,74 +0,0 @@ -<!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>
