<!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 - FreeMarker Manual</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker Manual">
<meta property="og:title" content="Basics">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/xgui_declarative_basics.html">
<link rel="canonical" href="http://example.com/xgui_declarative_basics.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338517553">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://example.com/">
    <meta itemprop="name" content="FreeMarker Manual">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://example.com" role="banner">            <img itemprop="image" src="logo.png" alt="My Logo">
</a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="xgui.html"><span itemprop="name">XML Processing Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="xgui_declarative.html"><span itemprop="name">Declarative XML Processing</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="xgui_declarative_basics.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">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper no-toc">
  <div id="table-of-contents-wrapper" class="col-left">
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="xgui_declarative.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_declarative_details.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="xgui_declarative_basics" itemprop="headline">Basics</h1>
</div></div>  <div class="callout note">
    <strong class="callout-label">Note:</strong>

          <p>This section uses the DOM tree and the variable made in <a href="xgui_expose.html">a previous chapter</a>.</p>
          </div>
<p>With the imperative approach of XML processing -- this was shown
        in the previous chapter -- you write an FTL program that walks the
        tree to find the different kind of nodes. With the declarative
        approach, you rather define how to handle the different kind of nodes,
        and then let FreeMarker walk the tree an call the handlers you have
        defined. This approach is useful for complex XML schemas, where the
        same element can occur as the child of many other elements. Examples
        of such schemas are XHTML and XDocBook.</p><p>The directive you most often use with the declarative approach
        is the <a href="ref_directive_visit.html#ref.directive.recurse"><code>recurse</code>
        directive</a>. This directive gets a node variable as parameter,
        and ``visits&#39;&#39; all its children nodes, one after the other, starting
        with the first child. ``Visiting&#39;&#39; a node means that it calls a
        user-defined directive (like a macro) that has the same name as the
        name of the child node (<code class="inline-code">?node_name</code>). We say on
        this, that the user-defined directive <em>handles</em> the
        node. The node that the user-defined directive just handles is
        available as special variable <code class="inline-code">.node</code>. For example,
        this FTL:</p>

<div class="code-wrapper"><pre class="code-block code-template">&lt;#recurse doc&gt;

&lt;#macro book&gt;
  I&#39;m the book element handler, and the title is: ${.node.title}
&lt;/#macro&gt;</pre></div><p>will print (I have removed some disturbing white-space form the
        output):</p>

<div class="code-wrapper"><pre class="code-block code-output">I&#39;m the book element handler, and the title is: Test Book</pre></div><p>If you call <code class="inline-code">recurse</code> without parameter, then
        it uses <code class="inline-code">.node</code>, that is, it visits all children
        nodes of the node being handled currently. So this FTL:</p>

<div class="code-wrapper"><pre class="code-block code-template">&lt;#recurse doc&gt;

&lt;#macro book&gt;
  Book element with title ${.node.title}
    &lt;#recurse&gt;
  End book
&lt;/#macro&gt;

&lt;#macro title&gt;
  Title element
&lt;/#macro&gt;

&lt;#macro chapter&gt;
  Chapter element with title: ${.node.title}
&lt;/#macro&gt;</pre></div><p>will print (I have removed disturbing white-space form the
        output):</p>

<div class="code-wrapper"><pre class="code-block code-output">Book element with title Test Book
Title element
Chapter element with title: Ch1
Chapter element with title: Ch2
End book</pre></div><p>You have seen how to define handlers for element nodes, but not
        how to define handler for the text nodes. Since the name of the
        handler is the same as the node-name of nodes it handles, and as the
        node-name of all text nodes is <code class="inline-code">@text</code> (see <a href="xgui_imperative_formal.html#misc.xguiTable">the table</a>), you define handler for the
        text nodes like this:</p>

<div class="code-wrapper"><pre class="code-block code-template">
&lt;#macro @text&gt;${.node?html}&lt;/#macro&gt;</pre></div><p>Note the <code class="inline-code">?html</code>. You have to HTML-escape the
        text, since you generate output of HTML format.</p><p>Here it is the template that transforms the XML to complete
        HTML:</p><a name="misc.example.declarativeBookProcessor"></a>

<div class="code-wrapper"><pre class="code-block code-template">&lt;#recurse doc&gt;

&lt;#macro book&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;&lt;#recurse .node.title&gt;&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;h1&gt;&lt;#recurse .node.title&gt;&lt;/h1&gt;
      &lt;#recurse&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/#macro&gt;

&lt;#macro chapter&gt;
  &lt;h2&gt;&lt;#recurse .node.title&gt;&lt;/h2&gt;
  &lt;#recurse&gt;
&lt;/#macro&gt;

&lt;#macro para&gt;
  &lt;p&gt;&lt;#recurse&gt;
&lt;/#macro&gt;

&lt;#macro title&gt;
  &lt;#--
    We have handled this element imperatively,
    so we do nothing here.
  --&gt;
&lt;/#macro&gt;

&lt;#macro @text&gt;${.node?html}&lt;/#macro&gt;</pre></div><p>and the output will be (now I will honestly include the annoying
        white-space...):</p>

<div class="code-wrapper"><pre class="code-block code-output">  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;Test Book&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;h1&gt;Test Book&lt;/h1&gt;

  
    &lt;h2&gt;Ch1&lt;/h2&gt;

    
      &lt;p&gt;p1.1

      &lt;p&gt;p1.2

      &lt;p&gt;p1.3

  
    &lt;h2&gt;Ch2&lt;/h2&gt;

    
      &lt;p&gt;p2.1

      &lt;p&gt;p2.2

  
    &lt;/body&gt;
  &lt;/html&gt;

  </pre></div><p>Note that you can reduce substantially the amount of superfluous
        whitespace in the output by using the <a href="ref_directive_t.html">trim directives</a>, as
        <code class="inline-code">&lt;#t&gt;</code>. See also: <a href="dgui_misc_whitespace.html">Template Author&#39;s Guide/Miscellaneous/White-space handling</a></p><p>You may say that the FTL that did it with imperative approach
        was much shorter. That&#39;s true, but the example XML uses a very simple
        schema, and as I said, the declarative approach brings its form with
        XML schemas that are not that firm about what element can occur where.
        Say, introduce element <code class="inline-code">mark</code>, that should color text
        to red, does not mater where do you use it; in a
        <code class="inline-code">title</code>, or in a <code class="inline-code">para</code>. For this,
        with the declarative approach, you just add a macro:</p>

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro mark&gt;&lt;font color=red&gt;&lt;#recurse&gt;&lt;/font&gt;&lt;/#macro&gt;</pre></div><p>And then <code class="inline-code">&lt;mark&gt;...&lt;/mark&gt;</code> will
        automatically work everywhere. So for certain XML schemas, declarative
        XML processing will actually result in shorter, and what is even more
        important, much clearer FTL-s, than imperative XML processing. It&#39;s up
        to you to decide which approach to use when; don&#39;t forget that you can
        mix the two approaches freely. Say, in an element handler, you can use
        imperative approach to process the contents of that element.</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="xgui_declarative.html"><span>Previous</span></a><a class="paging-arrow next" href="xgui_declarative_details.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-bottom"> <p class="last-generated">
Last generated:
<time itemprop="dateModified" datetime="2020-07-09T23:48:37Z" title="Thursday, July 9, 2020 11:48:37 PM GMT">2020-07-09 23:48:37 GMT</time> </p>
<p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2020
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p>
</div></div></div></body>
</html>