You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Ferdinand Soethe <fe...@apache.org> on 2007/03/27 19:54:35 UTC
Re: svn commit: r523017 - /forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
I'd appreciate sbdy checking this for accuracy since I had to change
quite a bit in this document.
Regards,
Ferdinand Soethe
ferdinand@apache.org wrote:
> 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>
>
>
>
>
Re: svn commit: r523017 - /forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> Ferdinand Soethe wrote:
> >David Crossley wrote:
> >
> >>and to add a Requirement to read our "Sitemap Reference".
> >
> >Ah, good one. Thanks.
> >
> >>Does this re-working now mean that we can remove the old linked
> >>docs? ...
> >>docs_0_80/howto/forrest.xmap.html
> >>docs_0_80/howto/project_sitemap.xmap.html
> >>docs_0_80/howto/sitemap.xmap.html
> >
> >As far as this doc is concerned yes. But since I didn't know who else
> >uses it, I haven't done it. (I really miss a function in Forrest that
> >give you all the links to a given document).
>
> grep (or your friendly text editor) provides that facility.
No mentions in site.xml and cannot find any with grep,
so removing those out-of-date docs.
> (yes I know you meant a plugin that would give you that content, so get
> writing after the 0,8 release ;-)
We have a Jira Component for "Plugins: Potential new".
Would someone please add an entry. This would be a very
useful tool.
-David
Re: svn commit: r523017 - /forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> David Crossley wrote:
>
>> and to add a Requirement to read our "Sitemap Reference".
>
> Ah, good one. Thanks.
>
>> Does this re-working now mean that we can remove the old linked
>> docs? ...
>> docs_0_80/howto/forrest.xmap.html
>> docs_0_80/howto/project_sitemap.xmap.html
>> docs_0_80/howto/sitemap.xmap.html
>
> As far as this doc is concerned yes. But since I didn't know who else
> uses it, I haven't done it. (I really miss a function in Forrest that
> give you all the links to a given document).
grep (or your friendly text editor) provides that facility.
(yes I know you meant a plugin that would give you that content, so get
writing after the 0,8 release ;-)
Ross
Re: svn commit: r523017 - /forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
Posted by Ferdinand Soethe <ma...@soethe.net>.
David Crossley wrote:
> and to add a Requirement to read our "Sitemap Reference".
Ah, good one. Thanks.
> Does this re-working now mean that we can remove the old linked
> docs? ...
> docs_0_80/howto/forrest.xmap.html
> docs_0_80/howto/project_sitemap.xmap.html
> docs_0_80/howto/sitemap.xmap.html
As far as this doc is concerned yes. But since I didn't know who else
uses it, I haven't done it. (I really miss a function in Forrest that
give you all the links to a given document).
Regards,
Ferdinand Soethe
Re: svn commit: r523017 - /forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-custom-html-source.xml
Posted by David Crossley <cr...@apache.org>.
Ferdinand Soethe wrote:
> I'd appreciate sbdy checking this for accuracy since I had to change
> quite a bit in this document.
Thanks a million for doing this important job.
I haven't had time to review it yet, other than a quick glance
and to add a Requirement to read our "Sitemap Reference".
Does this re-working now mean that we can remove the old linked
docs? ...
docs_0_80/howto/forrest.xmap.html
docs_0_80/howto/project_sitemap.xmap.html
docs_0_80/howto/sitemap.xmap.html
-David