blob: 84687912210eabf14b3237bc625438416f69589c [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Cocoon sitemap explained (v0.8-dev)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="../favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="../index.html">Welcome</a>
</li>
<li>
<a class="unselected" href="../contrib.html">Developers</a>
</li>
<li class="current">
<a class="selected" href="../versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="../tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs">
<a class="unselected" href="../docs_0_70/index.html">0.70 (current)</a><a class="selected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
</div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.80-dev</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_80/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/your-project.html">Using Forrest</a>
</div>
<div onclick="SwitchMenu('menu_selected_1.1.3', '../skin/')" id="menu_selected_1.1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">How-To</div>
<div id="menu_selected_1.1.3" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_80/howto/index.html">Overview</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
<div id="menu_1.1.3.2" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/upgrading_08.html">Upgrading to 0.8</a>
</div>
<div class="menuitem">
<a href="">Use Forrest</a>
</div>
<div onclick="SwitchMenu('menu_selected_1.1.3.5', '../skin/')" id="menu_selected_1.1.3.5Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Customize Forrest</div>
<div id="menu_selected_1.1.3.5" class="selectedmenuitemgroup" style="display: block;">
<div class="menupage">
<div class="menupagetitle">Sitemaps explained</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-custom-html-source.html">Custom html source</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-corner-images.html">CSS corner SVG</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate Forrest with tools</div>
<div id="menu_1.1.3.6" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/howto/howto-forrest-from-maven.html">Maven Integration</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/catalog.html">Using DTD Catalogs</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend Forrest</div>
<div id="menu_1.1.3.7" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/howto/howto-buildPlugin.html">Build a Plugin</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/skin-package.html">Package new Skins</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-asf-mirror.html">Download mirror</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding Documentation</div>
<div id="menu_1.1.3.9" class="menuitemgroup">
<div class="menuitem">
<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage HowTo</div>
<div id="menu_1.1.3.9.2" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/howto/multi/howto-multi.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step3.html">Step 3</a>
</div>
</div>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/faq.html">FAQs</a>
</div>
<div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
<div id="menu_1.1.5" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/searching.html">Search Options in Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/locationmap.html">Locationmap</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/skins.html" title="About default skins, their naming and features">Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/status-themes.html">Dispatcher versus Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/cap.html">Sourcetype Action</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/validation.html">XML validation and entity resolution</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/glossary.html">Glossary</a>
</div>
<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
<div id="menu_1.1.8" class="menuitemgroup">
<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
<div id="menu_1.1.8.1" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/dtd-docs.html">Overview</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
<div id="menu_1.1.8.2" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/document-v13.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.html">document-v20</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
<div id="menu_1.1.9" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/primer.html">Forrest Primer</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/libre-intro.html">Libre</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/dreams.html">Dream list</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
</div>
</div>
</div>
<div id="credit">
<hr>
This is documentation for development version v0.8
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="sitemap-explain.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>Cocoon sitemap explained</h1>
<div id="motd-area">
This is documentation for development version v0.8
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<p>
This document is intended to be a concise explanation of the Apache Cocoon
<a href="../docs_0_80/sitemap-ref.html">Sitemap</a> and its use in Apache Forrest. This
is a worked example showing the automatically generated Table of Contents.
Please follow the various sitemaps as we explain.
</p>
<pre class="code">
cd $FORREST_HOME/site-author
forrest run
</pre>
<p>
In a separate browser window, open
<a href="../linkmap.html"><span class="codefrag">localhost:8888/linkmap.html</span></a> to see
the generated Table of Contents. This has been transformed from the
site.xml navigation configuration to show the layout of the whole site as
a ToC.
</p>
<p>
Cocoon consults the sitemaps to find out how to process the
<span class="codefrag">linkmap.html</span> request.
</p>
<p>
The main sitemap is <span class="codefrag">$FORREST_HOME/main/webapp/sitemap.xmap</span>
and if the match is not found there then other sitemaps are consulted. The
first match wins. Various sitemaps are responsible for different types of
processing and there are also sitemaps in the many plugins.
</p>
<p>
So let us see how <span class="codefrag">linkmap.html</span> is handled.
</p>
<p>
Open <span class="codefrag">$FORREST_HOME/main/webapp/sitemap.xmap</span> in another
window. Search for "linkmap" to find the following snippet:
</p>
<pre class="code">
&lt;map:match pattern="linkmap.*"&gt;
&lt;map:mount uri-prefix="" src="linkmap.xmap" check-reload="yes" /&gt;
&lt;/map:match&gt;
</pre>
<p>
Cocoon has passed through the other potential matches earlier in the
sitemap and now does further handling via the <span class="codefrag">linkmap.xmap</span>
sitemap.
</p>
<p>
Before going any further, it is necessary to understand the "**" and "*"
pattern matching and replacements. See the email thread: "Re: explain
sitemap matches and pass parameters to transformers"
<a href="http://issues.apache.org/jira/browse/FOR-874">FOR-874</a>.
</p>
<p>
Okay we will skip some explanation of processing. At this stage we are
only concerned with generating the internal xml. Later steps of processing
will transform that into the final html output and adorn it with
navigation menus and headers, etc. This is your main aim for most of your
sitemap work for input formats: handle the incoming requests, and
transform into the standard internal xml format. Then Forrest
automatically does the rest.
</p>
<p>
In another browser window, open <span class="codefrag">localhost:8888/linkmap.xml</span> to
see the internal xml format.
</p>
<p>
Open <span class="codefrag">$FORREST_HOME/main/webapp/linkmap.xmap</span> sitemap. Move to
the "map:pipeline" section.
</p>
<p>
A digression: The first match is not triggered because our request is for
<span class="codefrag">linkmap.xml</span> and this match handles
<span class="codefrag">linkmap.source.xml</span> to essentially re-direct it to
<span class="codefrag">linkmap.xml</span> instead. That is what the cocoon:// means:
generate it via a different request within this sitemap. Try
<span class="codefrag">localhost:8888/linkmap.source.xml</span> to see the exact same
internal xml format.
</p>
<p>
The second match exactly meets our pattern <span class="codefrag">linkmap.xml</span>
</p>
<pre class="code">
&lt;map:match pattern="linkmap.xml"&gt;
&lt;map:generate src="cocoon://abs-linkmap" /&gt;
&lt;map:transform src="{lm:transform.linkmap.document}"/&gt;
&lt;map:serialize type="xml" /&gt;
&lt;/map:match&gt;
</pre>
<p>
As with all pipelines, it starts with a generator to commence the xml
stream, then transforms it with a single transformer (there could be
multiple sequential transformers) and finally the serializer component.
Here it is:
</p>
<p>
The generator is not simply reading an xml file. It produces the xml via a
different part of this sitemap. Let us explain that later and assume for
now that it produces the xml from your site.xml file.
</p>
<p>
Move on to the transformer. It transforms the xml obtained from the
site.xml into the internal document xml format using an XSLT stylesheet.
The locationmap reference defines the source for that stylesheet:
"lm:transform.linkmap.document" is evaluated by the Locationmap to be the
<span class="codefrag">main/webapp/resources/stylesheets/linkmap-to-document.xsl</span>
stylesheet. See the <a href="../docs_0_80/locationmap.html">Locationmap</a>
documentation for explanation.
</p>
<p>
Now let us get back to that new request for "abs-linkmap". This is used a
number of times within this sitemap, hence it is its own pipeline. As
usual it starts with a generator, then a transformer, then a serializer.
</p>
<p>
Again the generator is sent to some other part of the sitemap hierarchy,
because this request is needed by many other parts of the system beyond
just this linkmap handling. You see that it is not matched within this
linkmap.xmap sitemap. Go to the main sitemap.xmap and search for
"site.navigation.links.xml" where you find the match that handles this by
looking for various Locationmap definitions to find and transform the
site.xml file.
</p>
<p>
Don't get lost, come back to the linkmap.xmap sitemap.
</p>
<p>
Following this generator, the transformer turns the links into absolute
references. This is then serialized as xml to finish this "abs-linkmap"
match which is the end of the generator in our main match.
</p>
<p>
A developer's trick will help to understand what is happening. Edit the
linkmap.xmap to comment-out the transformer ...
</p>
<pre class="code">
&lt;map:match pattern="linkmap.xml"&gt;
&lt;map:generate src="cocoon://abs-linkmap" /&gt;
&lt;!--
&lt;map:transform src="{lm:transform.linkmap.document}"/&gt;
--&gt;
&lt;map:serialize type="xml" /&gt;
&lt;/map:match&gt;
</pre>
<p>
Browser <span class="codefrag">localhost:8888/linkmap.xml</span> to see the result of the
"abs-linkmap" generation before it is transformed into the internal
document xml.
</p>
<p>
So now you understand some of the power of sitemaps.
</p>
<p>
A basic understanding of Cocoon's pipelines and their components will help
you to realise the true power. You should know about matchers, generators,
transformers and serializers and have a rough idea how they work together
in a pipeline. A good place to start learning about Cocoon is
<a href="http://cocoon.apache.org/2.1/userdocs/concepts/">Understanding
Apache Cocoon</a>. The Forrest <a href="../docs_0_80/sitemap-ref.html">Sitemap
Reference</a> will also be helpful.
</p>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>