So here it is. Your comments much appreciated before I format it for inclusion in the Forrest documention?
I've moved to the dev list rather than the user list. The devs want to see this develop, the users want the final document.
I was going to use document.dtd and write a second shorter and more to the point how-to on the specifics of processing your own legacy html. OK?
That would be brilliant (don't forget we have a HowTo DTD).
So this tries to explain what happens internally when a clients asks Forrest to serve "mytests/mybad.html", a legacy html-file with lots of junk in it.
junk = things like legacy navigation?
0. Clients asks Forrest to serve ".../xdocs/mytests/mybad.html"
"http://some.domain.org/mystest/mybad.html";
1. Forrest looks for a matching pipeline in "...\forrest\main\webapp\sitemap.xmap".
2. This Pattern would in fact match the request but generates no xml since the map:parts match no cocoon pipeline and thus no xml is generated.
Actually this does not match because *.html will only match something like "mybad.html". Here you have a directory structure so you need "**" in order to match it. "*" means a single part of an URL, "**" means any number of parts to an URL.
3. This pattern also matches the request and is used to continue
processing
<map:match pattern="**/*.html">
{0}= mytests/mybad.html
{1}= mytests
{2}= mybad
<map:aggregate element="site">
<map:part src="cocoon:/skinconf.xml"/> adds skin info
<map:part src="cocoon:/build-info"/> adds meta data
<map:part src="cocoon:/{1}/tab-{2}.html"/> creates tabs
=>cocoon:/mytests/tab-mybad.html
<map:part src="cocoon:/{1}/menu-{2}.html"/> creates menus
=>cocoon:/mytests/menu-mybad.html
Below a cocoon pipeline is called to generate the body <map:part src="cocoon:/{1}/body-{2}.html"/>
=>cocoon:/mytests/body-mybad.html
return here for the rest of this pipeline in step 9
4. This is the pipeline called in step 3
Check if there is an ehtml-file (deprecated embedded html)
<map:match pattern="**body-*.html">
{0}= mytests/body-mybad.html
{1}= mytests/
{2}= mybad
<map:select type="exists">
<map:when test="{project:content.xdocs}{1}{2}.ehtml">
=>.../xdocs/mytests/mybad.ehtml
The value of {project:content.xdocs} depends on the settings in forrest.properties
<map:generate src="{project:content.xdocs}{1}{2}.ehtml" />
=>.../xdocs/mytests/mybad.ehtml <map:transform src="{forrest:stylesheets}/html2htmlbody.xsl" />
<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
=>cocoon://mytests/linkmap-mybad.html <map:transform src="resources/stylesheets/declare-broken-site-links.xsl" />
<map:serialize type="xml" />
</map:when>
</map:select>
</map:match>
Since file does not exist, pipeline generates nothing so Forrest keeps looking for next matching pipeline ...
Yes, a pipeline is only considered as having executed when it generates some content, the test for the *.ehtml file fails so no processing is done.
5. ... and finds another pipeline for the same matches
<!-- Default matches -->
<!-- (HTML rendered from doc-v11 intermediate format -->
<map:match pattern="**body-*.html">
{0}= mytests/body-mybad.html
{1}= mytests/
{2}= mybad
In the following step we ask Forrest to call the pipeline for mybad.xml.
This triggers a new matching attempt starting from the top of the pipeline section.
<map:generate src="cocoon:/{1}{2}.xml"/>
=>cocoon:/mytests/mybad.xml
Return here for the rest of this pipeline in step
The number of slashes is significant. "cocoon:/" means look for a pipeline in the current sitemap, "cocoon://" means look for a match in any xmap. This is not significant a this point but will be later.
6. This below is relevant now as it loads the project sitemap and inserts it right at this position of the main sitemap. (This project sitemap was also loaded before, but was irrelevant since there were no matches in the project sitemap)
Probably best, in the documentation to describe what happens *without* a project sitemap first since this will be the default behaviour. Then your howto can describe how the project sitemap intercepts this request.
<!-- This is the user pipeline, that can answer requests instead
of the Forrest one, or let requests pass through.
To take over the rendering of a file it must match the file name and path.
To take over the generation of the intermediate format, it must give
Forrest the same filename but ending with xml, and a DTD that Forrest
recognizes.
-->
<map:pipeline internal-only="false"> 4t!!!h step patterns above first
<map:select type="exists">
<map:when test="{project:sitemap}">
<map:mount uri-prefix="" src="{project:sitemap}" check-reload="yes" pass-through="true"/>
</map:when> </map:select>
</map:pipeline>
7. In the project sitemap we find this match for our call for an XML-file!
<map:match pattern="**/mybad.xml">
{0}= mytests/mybad.xml
{1}= mytests
Load my file with the html-generator. This generator
internally uses jtidy to clean up the html and make it xhtml.
<map:generate src="{project:content.xdocs}{1}/mybad.html" type="html"/>
Now we call my special stylesheet to remove all
elements that I don't want in the forrest page.
I place it in the same directory as the source document as it
is very specific.
<map:transform src="{project:content.xdocs}{1}/mybadHTMLfixer.xsl"/>
Stylesheets should be placed in the {project:resources.stylesheets} directory, only displayable content should be in the xdocs directory.
Finally call the existing stylesheet to convert html to document1.1
<map:transform src="{forrest:stylesheets}/html2document.xsl" />
Serialize result as xml (it is now the body of my Forrest page
and uses in document.dtd)
<map:serialize type="xml"/>
</map:match>
8. Return to calling routine in step 5 and execute the rest of the pipeline
to finalize the body of my Forrest page.
{0}= mytests/body-mybad.html
{1}= mytests/
{2}= mybad
???
<map:transform type="idgen"/>
generates ID attributes for elements that are used for internal linking (i.e. <a href="thispage.html#thatPosition">Go to thatPosition</a>)
??? <map:transform type="xinclude"/>
XInclude content from other files (see http://www.w3.org/TR/xinclude/)
Adjust links
<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
=> cocoon:/mytests/linkmap-mybad.html
<map:transform src="resources/stylesheets/declare-broken-site-links.xsl" />
<map:call resource="skinit">
<map:parameter name="type" value="document2html"/>
<map:parameter name="path" value="{1}{2}.html"/>
=> mytests/mybad.html <map:parameter name="notoc" value="false"/>
</map:call>
</map:match>
At the end of the pipeline this is the page body in Html with all
links adjusted.
Yes, to see it you can type http://localhost:8888/mytest/body-mybad.html into your browser.
9. Return to the calling routine in step 3 and finish processing
{0}= mytests/mybad.html {1}= mytests {2}= mybad
</map:aggregate>
At this point the body (as html) is aggregated with the menus and tabs
and the next part just adds the final touches to the presentation.
<map:call resource="skinit">
<map:parameter name="type" value="site2xhtml"/>
<map:parameter name="path" value="{0}"/>
=> mytests/mybad.html
</map:call>
</map:match>
At the end, the result is delivered to the browser.
Looks good to me.
Ross
