Basics
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.
The directive you most often use with the declarative approach
is the recurse
directive. This directive gets a node variable as parameter,
and ``visits'' all its children nodes, one after the other, starting
with the first child. ``Visiting'' 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 (?node_name). We say on
this, that the user-defined directive handles the
node. The node that the user-defined directive just handles is
available as special variable .node. For example,
this FTL:
 | | |
|
<#recurse doc>
<#macro book>
I'm the book element handler, and the title is: ${.node.title}
</#macro> |
| |
| | |
will print (I have removed some disturbing white-space form the
output):
| | |
|
I'm the book element handler, and the title is: Test Book |
| |
| | |
If you call recurse without parameter, then
it uses .node, that is, it visits all children
nodes of the node currently handled. So this FTL:
| | |
|
<#recurse doc>
<#macro book>
Book element with title ${.node.title}
<#recurse>
End book
</#macro>
<#macro title>
Title element
</#macro>
<#macro chapter>
Chapter element with title: ${.node.title}
</#macro> |
| |
| | |
will print (I have removed disturbing white-space form the
output):
| | |
|
Book element with title Test Book
Title element
Chapter element with title: Ch1
Chapter element with title: Ch2
End book |
| |
| | |
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 @text (see the table), you define handler for the
text nodes like this:
| | |
|
<#macro @text>${.node?html}</#macro> |
| |
| | |
Note the ?html. You have to HTML-escape the
text, since you generate output of HTML format.
Here it is the template that transforms the XML to complete
HTML:
| | |
|
<#recurse doc>
<#macro book>
<html>
<head>
<title><#recurse .node.title></title>
</head>
<body>
<h1><#recurse .node.title></h1>
<#recurse>
</body>
</html>
</#macro>
<#macro chapter>
<h2><#recurse .node.title></h2>
<#recurse>
</#macro>
<#macro para>
<p><#recurse>
</#macro>
<#macro title>
<#--
We have handled this element imperatively,
so we do nothing here.
-->
</#macro>
<#macro @text>${.node?html}</#macro> |
| |
| | |
and the output will be (now I will honestly include the annoying
white-space...):
| | |
|
<html>
<head>
<title>Test Book</title>
</head>
<body>
<h1>Test Book</h1>
<h2>Ch1</h2>
<p>p1.1
<p>p1.2
<p>p1.3
<h2>Ch2</h2>
<p>p2.1
<p>p2.2
</body>
</html>
|
| |
| | |
Note that you can reduce substantially the amount of superfluous
whitespace in the output by using the trim directives, as
<#t>. See also: Template Author's Guide/Miscellaneous/White-space handling
You may say that the FTL that did it with imperative approach
was much shorter. That'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 mark, that should color text
to red, does not mater where do you use it; in a
title, or in a para. For this,
with the declarative approach, you just add a macro:
| | |
|
<#macro mark><font color=red><#recurse></font></#macro> |
| |
| | |
And then <mark>...</mark> 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's up
to you to decide which approach to use when; don'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.
