Author: ferdinand
Date: Tue Mar 27 10:49:34 2007
New Revision: 523017
URL: http://svn.apache.org/viewvc?view=rev&rev=523017
Log:
FOR-922: Adjusted sitemap-examples in this howto to the changes in Forrest
Modified:
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
Modified:
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml?view=diff&rev=523017&r1=523016&r2=523017
==============================================================================
---
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
(original)
+++
forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
Tue Mar 27 10:49:34 2007
@@ -73,14 +73,7 @@
<steps title="Understanding the HTML-Pipeline">
- <warning>
- The example sitemap fragments are out-of-date because since this
- document was written, the core sitemaps in main/webapp/ have changed and
- some of the specialised processing has moved to plugins.
- View your source sitemaps when reading this document.
- (See <a
href="https://issues.apache.org/jira/browse/FOR-922";>FOR-922</a>.)
- </warning>
-
+
<p>
The first part of this howto explains the html pipeline, so as to
provide the background to enable you to add additional processing
@@ -100,7 +93,7 @@
So let's see what happens, when a client asks Forrest to
serve the document
<br />
- 'http://some.domain.org/mytest/mybad.html'.
+ 'http://my.domain.org/mytest/mybad.html'.
</p>
</section>
@@ -126,20 +119,18 @@
<p>
To help you to easily follow the next steps, we have added
- comments and anchors to 'sitemap.xmap',
+ comments and markers to 'sitemap.xmap',
so that you can quickly jump to all relevant sections
and read them more easily.
</p>
<p class="instruction">
- Follow this link to the
- <a href="sitemap.xmap.html#Start+of+Sitemap">
+ Search for <code><![CDATA[map:sitemap]]></code> to find the
start of the Sitemap.
- </a>
</p>
<p>
- As the comment explains, this sitemap is the starting point
+ This sitemap is the starting point
for all requests. So even if there are other sitemaps
(which we will see later on), we always start looking for a
matching pattern right here.
@@ -157,11 +148,7 @@
</p>
<p class="instruction">
So let's skip right to the start of the
- Pipelines-Section. Search for <map:pipelines> or
- follow this link to the
- <a href="sitemap.xmap.html#Start+of+Pipelines">
- beginning of the pipelines-element
- </a>
+ Pipelines-Section. Search for <code><![CDATA[map:pipelines]]></code>
</p>
<p>
@@ -184,35 +171,42 @@
Like all Cocoon applications, Forrest knows which
pipeline to use for processing a certain request by
looking at the entry criteria for each pipeline it comes
- across. These can be a match against a given pattern,
+ across. This can be a match against a given pattern,
the test if a certain files exists or one of many other
possible tests that Cocoon supports.
</p>
- <p class="instruction">
+ <p>
To better know what we are talking about, let's follow
- Forrest down the list to the
- <a href="sitemap.xmap.html#Test+for+First+Pipeline">
- Test for the First Pipeline
- </a>.
+ Forrest down the list to the Test for the First Pipeline:
+ </p>
+
+ <p class="instruction">
+ Scroll down to the line
+ <code><![CDATA[<map:match pattern="cprofile.*">]]></code>
</p>
<p>
Here you can see that very specialized matches need to occur
early in the sitemap. The
requested file (and pathname) is compared to a pattern
- '*.xlex' that would match if our request ended with
- '.xlex' and had no pathname. Since it doesn't, we don't
+ 'cprofile.*' that would match if our request started with
+ 'cprofile', endet with any kind of extension and had no pathname.
Since it doesn't, we don't
have a match and need to keep looking.
</p>
<p class="instruction">
- Skip forward until we find the
- <a href="sitemap.xmap.html#First+Match+for+%22**%2F*.html%22">
- First Match for "**/*.html"
- </a>
- (<map:match pattern="**/*.html">).
+ Skip forward until you find
+ <code><![CDATA[<map:match pattern="**/*.html">]]></code>.
+
</p>
+
+ <note>While scrolling down you may have noticed the match-pattern
+ <code><![CDATA[<map:match pattern="*.html">]]></code> a couple of
+ lines earlier. This will not match our request since *.something
in Cocoon matches only
+ files in the root directory.
+ </note>
+
</section>
<section id="html-pipeline">
@@ -223,18 +217,18 @@
</p>
<source><![CDATA[
<map:match pattern="**/*.html">
- <map:aggregate element="site">
- <map:part src="cocoon:/skinconf.xml"/>
- <map:part src="cocoon:/build-info"/>
- <map:part src="cocoon:/{1}/tab-{2}.html"/>
- <map:part src="cocoon:/{1}/menu-{2}.html"/>
- <map:part src="cocoon:/{1}/body-{2}.html"/>
- </map:aggregate>
- <map:call resource="skinit">
- <map:parameter name="type" value="site2xhtml"/>
- <map:parameter name="path" value="{0}"/>
- </map:call>
-</map:match>]]></source>
+ <map:aggregate element="site">
+ <map:part src="cocoon:/skinconf.xml"/>
+ <map:part src="cocoon:/build-info"/>
+ <map:part src="cocoon:/{1}/tab-{2}.html"/>
+ <map:part src="cocoon:/{1}/menu-{2}.html"/>
+ <map:part src="cocoon:/{1}/body-{2}.html"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="transform.site.xhtml"/>
+ <map:parameter name="path" value="{0}"/>
+ </map:call>
+ </map:match>]]></source>
<p>
In the first part of this pipeline, the
aggregate-element assembles information required to build
@@ -259,7 +253,7 @@
back into our pipeline.
(The 'pseudo' goes back to the fact that unlike
'http' or 'ftp', which are real protocols, you can use cocoon:
- only within the cocoon environments as only they will know what to
+ only within the cocoon environments as only Cocoon will know what to
do with it.)
</p>
<p>
@@ -330,10 +324,8 @@
</p>
<p class="instruction">
- Search for '**body-*.html' from the beginning of the
- sitemap or jump to the
- <a href="sitemap.xmap.html#First+Match+for+%27**body-*.html%27">First
Match for '**body-*.html'</a>
- to see where we find our next match.
+ Search for <code><![CDATA[**body-*.html]]></code> from the beginning
of the
+ sitemap to see where we find our next match.
</p>
</section>
<section id="match-1">
@@ -345,12 +337,12 @@
</p>
<source><![CDATA[
<map:select type="exists">
- <map:when test="{properties:content.xdocs}mytests/mybad.ehtml">]]></source>
+ <map:when test="{lm:project.{1}{2}.ehtml}">]]></source>
<p>
we quickly discover that there can't be a file of
that name in the project-directory.
<br />
- (The variable '{properties:content.xdocs}' is always replaced with
+ (The variable '{lm:project.}' is always replaced with
the name of your project directory that you can change
in the 'forrest.properties'-file.)
</p>
@@ -364,8 +356,7 @@
<title>Second Match for '**body-*.html'</title>
<p class="instruction">
Continue searching downwards for '**body-*.html' in the
- sitemap-file or jump directly to the
- <a
href="sitemap.xmap.html#Second+Match+for+%27**body-*.html%27">Second Match for
'**body-*.html'</a>.
+ sitemap-file.
</p>
<p>
Looking at the pipeline that handles the request, we see that
@@ -418,8 +409,7 @@
'/mytests/mybad.xml'.
</p>
<p>
- We find it in the pattern
- <a href="sitemap.xmap.html#First+Match+for+%27**.xml%27">'**.xml'></a>,
+ We find it in the pattern <code><![CDATA[<map:match
pattern="**.xml">]]></code>,
which is the standard handling for all xml-requests.
</p>
<p>
@@ -427,7 +417,7 @@
this pipeline, it falls right through to the map:mount-element
at the end:
</p>
- <source><![CDATA[<map:mount uri-prefix="" src="forrest.xmap"
check-reload="yes" />]]></source>
+ <source><![CDATA[<map:mount uri-prefix="" src="forrest.xmap"
check-reload="yes" />]]></source>
<p>
which makes Forrest load and process a secondary sitemap,
the file 'forrest.xmap' in the same directory.
@@ -437,33 +427,23 @@
matching pattern.
</p>
<p>
- Our search leads us to the
- <a href="forrest.xmap.html#Second+Match+for+%27**.xml%27">
- Second Match for '**.xml'
- </a>,
- a pipeline designed to handle internationalisation if that
- feature is configured. Since it is not, all it does is
- call the file-resolver-resource with the full pathname of
- our file but no extension.
+ Our search first leads us to the matcher <code><![CDATA[<map:match
type="wildcard" pattern="**.xml">]]></code>
+ with a number of submatchers embedded into it.
</p>
-<source><![CDATA[
-<map:call resource="file-resolver">
- <map:parameter name="uri" value="mytests/mybad"/>
-</map:call>]]></source>
- </section>
- <section id="file">
- <title>Introducing the File-Resolver</title>
- <p class="instruction">
- To find out more about the working of the file-resolver,
- search for the definition of the
- <a href="forrest.xmap.html#Definition+of+File-Resolver-Resource">
- <map:resource name="file-resolver">
- </a>
- higher up in the file.
+ <p>The first one, <code><![CDATA[<map:match type="wildcard"
pattern="**.xml">]]></code>, would handle input coming from Forrest plugins.
+ We won't go into details here.</p>
+ <p>
+ All further matchers <code><![CDATA[<map:match type="i18n"
pattern="{properties:content.xdocs}{1}.*.xml"> ]]></code>.
+ implement what we call a cascade of matchers. By testing for the
existence of one source file after another Forrest will use and process the
+ first of the tested source-formats found.
</p>
+
+ <note>Using the i18n-matcher here, Forrest will do a lot more than just
finding content in one of many possible source formats.
+ It will also make sure that the the proper language version of the
conent (if there are several) is used.
+ Read more about this matcher <a
href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/matching/LocaleMatcher.html";>http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/matching/LocaleMatcher.html</a></note>
<p>
- Here you will find a pipeline that tests for the existence of
- the file with different extensions. '.html' is second in this
+ Checking each matcher in turn you will find that a pipeline that tests
for the existence of
+ the file with different extensions. '.html' is third in this
list and leads to the processing steps shown below:
</p>
</section>
@@ -471,28 +451,25 @@
<section id="process-html">
<title>html-Default Processing</title>
<p>
- The default processing of html-files consists of four
+ The default processing of html-files consists of three
processing steps:
</p>
<ol>
<li>
- <code><map:generate src="{properties:content.xdocs}{uri}.html"
type="html"/></code><br/>
- Using the html-generator, Forrest reads the html-document
+ <code><![CDATA[<map:generate src="{source}" type="html"
/>]]></code><br/>
+ Using Cocoons html-generator, Forrest reads the html-document
from file and uses JTidy to clean up and convert it to xml
- (which is required for all processing in cocoon pipelines).
+ (which is required for all processing in Cocoon pipelines).
At the output of this transformer we will have a valid
XHTML-document althought it might still contain some unwanted
elements. We'll deal with those later (see
<a href="#custom">When to customize</a>).
</li>
<li>
- <code><map:transform
src="{forrest:forrest.stylesheets}/html2document.xsl"/></code><br/>
- Using the standard stylesheet 'html2document.xsl', this XHTML is
- transformed into Forrest standard document format.
- </li>
- <li>
- <code><map:transform type="idgen"/></code><br/>
- This step generates IDs required for navigation within the page.
+ <code><![CDATA[<map:transform src="{lm:transform.html.document}"
/>]]></code><br/>
+ Using the standard stylesheet 'html-to-document.xsl', this XHTML is
+ transformed into Forrest's <a href="site:glossary">Standard
Document Format</a>. (refer to a detailed <a
href="site:locationmap">explanation of locationsmaps</a>
+ to understand exactly how and where that stylesheet is found!)
</li>
<li>
<code><map:serialize type="xml-document"/></code><br/>
@@ -515,8 +492,8 @@
<title>Returning to the '**body-*.html'-Pipeline</title>
<p>
On returning into the
- <a
href="sitemap.xmap.html#Returning+to+the+%27**body-*.html%27+Pipeline">'**body-*.html'
pipeline</a>,
- procesing continues with the next components in this pipeline:
+ '**body-*.html'-Pipeline (in sitemap.xmap),
+ processing continues with the next components in this pipeline:
</p>
<ul>
<li>
@@ -535,7 +512,7 @@
directory structure. It also resolves any special Forrest links.
</li>
<li>
- The final transformation, as the name suggests, will take
+ The final transformation, <code><![CDATA[<map:transform
src="{lm:transform.html.broken-links}" />]]></code> as the name suggests, will
take
care of reporting broken site-links.
</li>
<li>
@@ -598,24 +575,20 @@
<title>How to customize?</title>
<p>
To add your own custom processing for a group of pages, you will
- create a project sitemap with pipelines that process documents
+ enhance the project sitemap with pipelines that process your
documents
according to your specifications.
</p>
<p>
This project sitemap is located in the file
'src/documentation/sitemap.xmap' in your Forrest project directory
- and will be created automatically when you seed a new project.
- At this point it contains only one
- <a
href="project_sitemap.xmap.html#Example+pipeline+for+%27**custom.xml%27">
- pipeline for handling the '**custom.xml'-pattern</a> as an example.
+ and is created automatically whenever you seed a new project.
+ At this point it already contains a few examples for custom
pipelines.
</p>
<p>
To add your own custom processing, edit the file and add a new
pipeline to the project sitemap. Since the project sitemap is
- loaded into the main sitemap
- <a href="sitemap.xmap.html#Insertion+Point+for+Project+Sitemap">
- right at the top</a>, your pipeline intercepts practically all
- of Forrest's standard pipelines.
+ loaded into the main sitemap right at the top (search for 'This is
the user pipeline'),
+ your pipeline intercepts practically all of Forrest's standard
pipelines.
</p>
</section>
@@ -668,24 +641,22 @@
</map:match>
</map:pipeline>]]></source>
<p class="instruction">
- Open the 'forrest.xmap', navigate to the file-resolver-section,
- copy the four lines for handling *.html files and paste them into
- your new pipeline.
+ Open the 'forrest.xmap', search for <code><![CDATA[<map:match
type="i18n" pattern="{properties:content.xdocs}{1}.*.html">]]></code>,
+ copy the three lines for handling *.html files and paste them into
your new pipeline.
</p>
<source><![CDATA[
<!--Custom Pipeline for my bad html-pages-->
<map:pipeline>
<map:match pattern="mytest/*.xml">
- <map:generate src="{properties:content.xdocs}{uri}.html" type="html"/>
- <map:transform src="{forrest:forrest.stylesheets}/html2document.xsl"/>
- <map:transform type="idgen"/>
+ <map:generate src="mytest/{1}.html" type="html" />
+ <map:transform src="{lm:transform.html.document}" />
<map:serialize type="xml-document"/>
</map:match>
</map:pipeline>]]></source>
<p>
Your custom pipeline will now behave exactly like the standard
- html-handler. Now all that is left to be done is creating the
+ html-handler. All that is left to be done is creating the
custom transformation and adding it the pipeline.
</p>
<p class="instruction">
@@ -703,12 +674,11 @@
<!--Custom Pipeline for my bad html-pages-->
<map:pipeline>
<map:match pattern="mytest/*.xml">
- <map:generate src="{properties:content.xdocs}{uri}.html" type="html"
/>]]>
- <strong><![CDATA[
+ <map:generate src="mytest/{1}.html" type="html" />]]>
+ <strong><![CDATA[
<map:transform
src="{properties:resources.stylesheets}/fixMyBadHTML.xsl"/>]]>
- </strong><![CDATA[
- <map:transform src="{forrest:forrest.stylesheets}/html2document.xsl" />
- <map:transform type="idgen" />
+ </strong><![CDATA[
+ <map:transform src="{lm:transform.html.document}" />
<map:serialize type="xml-document"/>
</map:match>
</map:pipeline>]]></source>
