Google Git
Sign in
apache / forrest / forrest_08_release_site / . / docs_0_80 / locationmap.html
blob: 4f0793c7b789a430bfe667fd09bc59d61114603a [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>Locationmaps (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_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div>
<div id="menu_1.1.3" class="menuitemgroup">
<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_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize Forrest</div>
<div id="menu_1.1.3.5" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_80/sitemap-explain.html">Sitemaps explained</a>
</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_selected_1.1.5', '../skin/')" id="menu_selected_1.1.5Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Background</div>
<div id="menu_selected_1.1.5" class="selectedmenuitemgroup" style="display: block;">
<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="menupage">
<div class="menupagetitle">Locationmap</div>
</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="locationmap.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>Locationmaps</h1>
<div id="motd-area">
This is documentation for development version v0.8
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#overview">About Locationmaps</a>
</li>
<li>
<a href="#namingConvention">Naming Convention</a>
</li>
<li>
<a href="#process">Explanation of Locationmap processing</a>
</li>
<li>
<a href="#selector">Multiple Location Selectors</a>
</li>
<li>
<a href="#examples">Other Locationmap examples</a>
<ul class="minitoc">
<li>
<a href="#source-via-http">Retrieving an XDoc via HTTP</a>
</li>
<li>
<a href="#source-from-remote-cms">Retrieving HTML from a CMS</a>
</li>
<li>
<a href="#sourceResolving">Source Resolving</a>
</li>
<li>
<a href="#linkrewriting">Link Rewriting</a>
</li>
<li>
<a href="#debugging">Debugging Locationmaps</a>
</li>
</ul>
</li>
</ul>
</div>
<a name="N1000D"></a><a name="overview"></a>
<h2 class="underlined_10">About Locationmaps</h2>
<div class="section">
<p>
A locationmap defines a mapping from requests to location strings.
</p>
<p>
It was conceived to:
</p>
<ul>
<li>Provide a more powerful means for semantic linking.</li>
<li>Enable Forrest with a standard configuration override mechanism.</li>
<li>Decouple the conceptual source space used by Cocoon from
the concrete source space, so that a change in the concrete sources
does not impact on the sitemap.</li>
</ul>
<p>
In other words, the locationmap enables content to be retrieved from a
location that is defined in a locationmap file (located at
<span class="codefrag">PROJECT_HOME/src/documentation/content/locationmap.xml</span>
file. The advantage of this is that the URL seen by the user need bear
no relation to the location of the source document, thus Forrest can
separate the client URL space from the source document URL space. Thus,
using the locationmap it is possible to pull together documents from
many different locations into a single uniform site.
</p>
<p>
In addition, since the user URL space is now not connected to the source
URL space it is possible to move source documents without breaking any
existing user links.
</p>
<p>
The syntax of a locationmap resembles that of the sitemap, in that it
also makes use of Matchers and Selectors to traverse a tree of nodes
towards a leaf. In the case of the locationmap however the leaf does not
identify a pipeline, but instead identifies a location string.
</p>
<p>
Apache Forrest looks in the standard location for the source file first
(by default <span class="codefrag">PROJECT_HOME/src/documentation/content/...</span>), if
a file is found in this location then the locationmap is not consulted.
However, if one is not found then the locationmap is used to resolve the
source file. The locationmap is resolved via the core sitemap, this
means that you can generate it dynamically if you so wish. Simply add a
match that looks something like this to your projects sitemap:
</p>
<pre class="code">
&lt;map:match pattern="locationmap-project.xml"&gt;
&lt;map:generate src="..."/&gt;
&lt;map:transform src="..."/&gt;
&lt;map:serialize type="xml"/&gt;
&lt;/map:match&gt;
</pre>
</div>
<a name="N1003C"></a><a name="namingConvention"></a>
<h2 class="underlined_10">Naming Convention</h2>
<div class="section">
<p>
For those that are familiar with name resolution servers or the Handles
Service, it might be easier to think of the locationmap as a name
resolution module or sort of a handle resolution module that it accepts
"names" or whatever you desire to call these "hints" and returns the
location.
</p>
<p>
The thought is that by using hints that look a little like a file name
it disguises what locationmaps are really doing for us. By using
URN-style names, we are truly disassociating the name/hint from the
physical location.
</p>
<p>
For example, here is a locationmap entry based purely on filename:
</p>
<pre class="code">
&lt;map:transform src="{lm:html-to-document.xsl}"/&gt;
</pre>
<p>
and here is that same entry using a "name" style. One implies a certain
physical location, whereas the one below is truly a name that needs to
be resolved to a physical location.
</p>
<pre class="code">
&lt;map:transform src="{lm:transform.html.document}"/&gt;
</pre>
<p>
Locationmaps are also used by plugins, and your project can also have
its own locationmap.
</p>
<p>
Where the resource is provided by a plugin rather than Forrest itself,
this is prefixed with the last part of the plugin name. For example:
</p>
<pre class="code">
&lt;map:transform src="{lm:projectInfo.transform.changes.document}"/&gt;
</pre>
<p>
The above match means look in the projectInfo plugin for a transformer
stylesheet with filename changes-to-document.xsl
</p>
<p>
The naming convention is essentially one of:
</p>
<pre class="code">
[PLUGIN_NAME.]resource-type(dot)from-format(dot)to-format
</pre>
<p>
or
</p>
<pre class="code">
[PLUGIN_NAME.]resource-type(dot)type(dot)name
</pre>
<p>
Examples of these:
</p>
<pre class="code">
transform.xthml2.html
graphic.png.project-logo
projectInfo.transform.changes.rss
</pre>
</div>
<a name="N10079"></a><a name="process"></a>
<h2 class="underlined_10">Explanation of Locationmap processing</h2>
<div class="section">
<p>
Some specific examples will explain. Please follow the relevant source
files.
</p>
<p>
The document <a href="../docs_0_80/howto/../sitemap-explain.html">Cocoon sitemaps
explained</a> (better understand that document before trying to
understand locationmaps) has two specific transformers which use
locationmap references. The first one is: <span class="codefrag">
&lt;map:transform src="{lm:transform.linkmap.document}"/&gt;
</span>
</p>
<p>
The Locationmap component first consults the primary locationmap
<span class="codefrag">$FORREST_HOME/main/webapp/locationmap.xml</span> file. This first
mounts any project locationmap if available, then the locationmaps from
plugins, then the rest of the core locationmaps in the
<span class="codefrag">$FORREST_HOME/main/webapp/</span> directory. As with sitemaps, the
first match wins. So matches in your project locationmap have
precedence, then plugins, then core.
</p>
<p>
So let us get back to our specifc example,
"<span class="codefrag">lm:transform.linkmap.document</span>". The "lm:" part means use
the locationmap protocol. There is no specific match for this in your
project locationmap, nor in any of the plugin locationmaps, so this
falls through to the core locationmaps. However, you will not find any
specific match for this in the core locationmaps, so what is happening?
</p>
<p>
See the last match in
<span class="codefrag">$FORREST_HOME/main/webapp/locationmap-transforms.xml</span> file.
This a catchall matcher for any reference starting with
"<span class="codefrag">transform.</span>"
</p>
<pre class="code">
&lt;match pattern="transform.*.*"&gt;
&lt;select&gt;
...
...
&lt;location src="{forrest:forrest.stylesheets}/{1}-to-{2}.xsl"/&gt;
&lt;/select&gt;
&lt;/match&gt;
</pre>
<p>
As you know from your understanding of Cocoon sitemaps, the first
asterisk yields "linkmap" and the second asterisk yields "document". So,
ignoring the other possible locations in this group which look in the
various skins stylesheet directories (see locationmap-transforms.xml
source), it will finally resolve to that last possible location to look
for a stylesheet called <span class="codefrag">linkmap-to-document.xsl</span> in the core
stylesheets directory
<span class="codefrag">$FORREST_HOME/main/webapp/resources/stylesheets/</span>
</p>
<p>
That explains the magic of the locationmap naming convention.
</p>
</div>
<a name="N100B5"></a><a name="selector"></a>
<h2 class="underlined_10">Multiple Location Selectors</h2>
<div class="section">
<p>
You can define multiple possble locations for a file in the locationmap
with the following code:
</p>
<pre class="code">
&lt;match pattern="tabs.xml"&gt;
&lt;select type="exists"&gt;
&lt;location src="{properties:content.xdocs}tabs1.xml"/&gt;
&lt;location src="{properties:content.xdocs}tabs2.xml"/&gt;
&lt;/select&gt;
&lt;/match&gt;
</pre>
<p>
Each location will be tested in turn, if the file exists then it will be
returned as a match, otherwise testing will continue.
</p>
</div>
<a name="N100C6"></a><a name="examples"></a>
<h2 class="underlined_10">Other Locationmap examples</h2>
<div class="section">
<a name="N100CC"></a><a name="source-via-http"></a>
<h3 class="underlined_5">Retrieving an XDoc via HTTP</h3>
<p>
Normally files are generated from
<span class="codefrag">{properties:content.xdocs}</span>. Using the Locationmap it is
possible to make these files come from elsewhere. This is useful if
you want to pull files from different directory structures, or even
remote repositories. For example, the following location match will
match any request for a document below "remote." and will retrieve the
source file from the Apache Forrest SVN repository (directly from the
ASF's SVN webserver). This is an ideal way to ensure that your
published docs are always up-to-date.
</p>
<pre class="code">
&lt;match pattern="project.remote.**.xml"&gt;
&lt;location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/{1}.xml" /&gt;
&lt;/match&gt;
</pre>
<p>
Note that because this is a wildcard matcher you can request any page
from the svn server simply by requesting
<span class="codefrag">/remote.PATH/TO/FILE/FILENAME.html</span>. In addition, we can
request any other output format available via Forrest plugins.
</p>
<p>
When including resources from remote repositories one has to be
careful about things like <span class="codefrag">site</span> and <span class="codefrag">ext</span>
linking. If the targets are not defined in the local
<span class="codefrag">site.xml</span> file then these links will be broken.
</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content">
Because of the above limitation many of the links in the page
generated from the above example are broken.
</div>
</div>
<a name="N100F2"></a><a name="source-from-remote-cms"></a>
<h3 class="underlined_5">Retrieving HTML from a CMS</h3>
<p>
Using the locationmap you can use Forrest to retrieve data from a
Content Management System (CMS), wither local or remote. As an example
we will consider Apache Lenya.
</p>
<p>
<a href="http://lenya.apache.org">Apache Lenya</a> is a Java
Open-Source Content Management System based on open standards such as
XML and XSLT and the Apache Software Stack, in particular the XML
publishing framework Apache Cocoon.
</p>
<p>
The following locationmap matcher will instruct Forrest to retrieve
content from
<span class="codefrag">http://lenya.zones.apache.org:8888/default/live/*.html?raw=true</span>,
whenever a local URL of <span class="codefrag">lenya/**</span> is encountered.
</p>
<pre class="code">
&lt;match pattern="lenya/**.xml"&gt;
&lt;location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" /&gt;
&lt;/match&gt;
</pre>
<p>
However, since the source returned by this match is HTML and not XDoc
we must convert this to our internal XDoc format before we can use it.
We do this by adding the match below to our project's
<span class="codefrag">sitemap.xmap</span> file.
</p>
<pre class="code">
&lt;map:match pattern="lenya/**.xml"&gt;
&lt;map:generate type="html" src="{lm:{0}}" /&gt;
&lt;map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl" /&gt;
&lt;map:serialize type="xml"/&gt;
&lt;/map:match&gt;
</pre>
<p>
Since this snippet uses the HTML generator you must also ensure that
your sitemap has the HTML generator component defined. That is, your
sitemap must also include:
</p>
<pre class="code">
&lt;map:components&gt;
&lt;map:generators default="file"&gt;
&lt;map:generator name="html"
src="org.apache.cocoon.generation.HTMLGenerator"&gt;
&lt;jtidy-config&gt;WEB-INF/jtidy.properties&lt;/jtidy-config&gt;
&lt;/map:generator&gt;
&lt;/map:generators&gt;
&lt;/map:components&gt;
</pre>
<p>
Since the HTML generator uses JTidy we need to make available a JTidy
configuration file. This is placed in
<span class="codefrag">PROJECT_HOME/src/documentation/WEB-INF/jtidy.properties</span>
(the location can be changed in the above sitemap snippet). A sample
config file is given below:
</p>
<pre class="code">
indent=yes
indent-spaces=8
wrap=72
markup=no
output-xml=no
input-xml=no
show-warnings=yes
numeric-entities=yes
quote-marks=yes
quote-nbsp=yes
quote-ampersand=yes
break-before-br=yes
uppercase-tags=no
uppercase-attributes=no
char-encoding=latin1
</pre>
<div class="note">
<div class="label">Note</div>
<div class="content">
This requirement to add items to your project sitemap will be removed
in a future version either by Lenya outputting XDoc, or by Forrest
switching to using XHTML as its internal format, or through the
development of a plugin for Lenya that will include the necessary
processing (whichever comes first).
</div>
</div>
<div class="warning">
<div class="label">Warning</div>
<div class="content">
This demo is an example only, it does not fully work at this time. For
example, absolute URLs in the source document need to be rewritten to
ensure that they are matched by the locationmap.
</div>
</div>
<a name="N10131"></a><a name="sourceResolving"></a>
<h3 class="underlined_5">Source Resolving</h3>
<p>
As well as being able to use the locationmap as a parameter in the
sitemap, it is also possible to use it as a psuedo-protocol within
resources processed by Forrest. For example, you can use it to import
an XSL provided by one plugin within another plugin:
</p>
<pre class="code">
&lt;xsl:import src="lm://OOo.transform.write.xdoc"/&gt;
</pre>
<a name="N1013F"></a><a name="linkrewriting"></a>
<h3 class="underlined_5">Link Rewriting</h3>
<p>
The locationmap can be used to rewrite URLs when the page is
generated. For example, when the locationmap has:
</p>
<pre class="code">
&lt;match pattern="rewriteDemo/**"&gt;
&lt;location src="http://www.domain.org/{1}.xml" /&gt;
&lt;/match&gt;
</pre>
<p>
With the above match in the locationmap, a link which has
<span class="codefrag">href="lm:rewriteDemo/index"</span> will be rewritten to an
offsite address at <span class="codefrag">domain.org</span>
</p>
<a name="N10156"></a><a name="debugging"></a>
<h3 class="underlined_5">Debugging Locationmaps</h3>
<p>
Debugging the locationmap can be difficult because Cocoons error
messages no longer provide meaningful data. We hope to improve this
over time, in the meantime we recommend that you increase the log
level of the locationmap logger. To do this edit the following line in
$FORREST_HOME/main/webapp/WEB-INF/logkit.conf:
</p>
<pre class="code">
&lt;category name="modules.mapper.lm" log-level="INFO"&gt;
</pre>
<p>
For example, you could change the log level to "DEBUG".
</p>
<p>
Output from this logger can be found in
$PROJECT_HOME/build/webapp/WEB-INF/logs/locationmap.log
</p>
<p>
You should not run production systems with this logger set higher than
"INFO as each request can generate large amounts of log information.
</p>
</div>
</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>