forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r526636 - in /forrest/trunk/site-author: content/xdocs/docs_0_80/sitemap-explain.xml content/xdocs/site.xml status.xml
Date Mon, 09 Apr 2007 02:45:40 GMT
Author: crossley
Date: Sun Apr  8 19:45:40 2007
New Revision: 526636

New document to explain Cocoon sitemaps using a specific worked example.

      - copied, changed from r526538, forrest/trunk/site-author/content/xdocs/docs_0_80/index.xml

Copied: forrest/trunk/site-author/content/xdocs/docs_0_80/sitemap-explain.xml (from r526538,
--- forrest/trunk/site-author/content/xdocs/docs_0_80/index.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/sitemap-explain.xml Sun Apr  8 19:45:40
@@ -16,29 +16,170 @@
   limitations under the License.
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "">
-  <header> 
-    <title>Apache Forrest documentation</title> 
-  </header> 
+  <header>
+    <title>Cocoon sitemap explained</title>
+  </header>
-      <p>
-        A good place to get started in our docs is the <a href="your-project.html">Using
-        guide.
-      </p>
-      <p>In the <a href="howto/index.html">How-To</a> section you will
find various 
-      practical guides on how to achieve common objectives in Forrest.</p>
-      <p>We also have a <a href="faq.html">FAQ</a> list that you should
consult before posting questions to
-      our user list.</p>
-      <p>
-        The documentation <a href="site:linkmap">Table of Contents</a> provides
-        useful overview of the main documentation. <a href="site:faq/docs">This FAQ</a>
-        explains that there is other documentation at the example forrest seed
-        site and that each plugin has its own documentation.
-      </p>
-      <p>
-        There are docs for 
-        <a href="site:versions/overview">other versions</a>
-        too.
-      </p>
+    <p>
+      This document is intended to be a concise explanation of the Apache Cocoon
+      <a href="site:sitemap-ref">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>
+    <source>
+cd $FORREST_HOME/site-author
+forrest run
+    <p>
+      In a separate browser window, open
+      <a href="site:linkmap"><code>localhost:8888/linkmap.html</code></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
+      <code>linkmap.html</code> request.
+    </p>
+    <p>
+      The main sitemap is <code>$FORREST_HOME/main/webapp/sitemap.xmap</code>
+      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 <code>linkmap.html</code> is handled.
+    </p>
+    <p>
+      Open <code>$FORREST_HOME/main/webapp/sitemap.xmap</code> in another
+      window. Search for "linkmap" to find the following snippet:
+    </p>
+    <source>
+<![CDATA[<map:match pattern="linkmap.*">
+  <map:mount uri-prefix="" src="linkmap.xmap" check-reload="yes" />
+    </source>
+    <p>
+      Cocoon has passed through the other potential matches earlier in the
+      sitemap and now does further handling via the <code>linkmap.xmap</code>
+      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="">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 <code>localhost:8888/linkmap.xml</code>
+      see the internal xml format.
+    </p>
+    <p>
+      Open <code>$FORREST_HOME/main/webapp/linkmap.xmap</code> sitemap. Move
+      the "map:pipeline" section.
+    </p>
+    <p>
+      A digression: The first match is not triggered because our request is for
+      <code>linkmap.xml</code> and this match handles
+      <code>linkmap.source.xml</code> to essentially re-direct it to
+      <code>linkmap.xml</code> instead. That is what the cocoon:// means:
+      generate it via a different request within this sitemap. Try
+      <code>localhost:8888/linkmap.source.xml</code> to see the exact same
+      internal xml format.
+    </p>
+    <p>
+      The second match exactly meets our pattern <code>linkmap.xml</code>
+    </p>
+    <source>
+<![CDATA[<map:match pattern="linkmap.xml">
+  <map:generate src="cocoon://abs-linkmap" />
+  <map:transform src="{lm:transform.linkmap.document}"/>
+  <map:serialize type="xml" />
+    </source>
+    <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
+      <code>main/webapp/resources/stylesheets/linkmap-to-document.xsl</code>
+      stylesheet. See the <a href="site:locationmap">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>
+    <source>
+      <map:match pattern="linkmap.xml">
+        <map:generate src="cocoon://abs-linkmap" />
+        <map:transform src="{lm:transform.linkmap.document}"/>
+        <map:serialize type="xml" />
+      </map:match>
+    </source>
+    <p>
+      Browser <code>localhost:8888/linkmap.xml</code> 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="">Understanding
+      Apache Cocoon</a>. The Forrest <a href="site:sitemap-ref">Sitemap
+      Reference</a> will also be helpful.
+    </p>

Modified: forrest/trunk/site-author/content/xdocs/site.xml
--- forrest/trunk/site-author/content/xdocs/site.xml (original)
+++ forrest/trunk/site-author/content/xdocs/site.xml Sun Apr  8 19:45:40 2007
@@ -293,14 +293,15 @@
             <ForrestCustomize label="Customize Forrest" description="Adapt and tune Forrest
for your needs">
+                <sitemap-explain label="Sitemaps explained" href="../sitemap-explain.html"/>
+                <custom-html-source label="Custom html source" href="howto-custom-html-source.html"/>
+                <project-sitemapRef label="Project sitemap" href="site:project-sitemap"/>
                 <editcss label="Edit CSS (WYSIWYG)" href="howto-editcss.html"/>
                 <pdf-tab label="Create tab PDF" href="howto-pdf-tab.html" 
                     description="Generate one pdf-document for all pages of a tab"/>
                 <corner-css label="CSS corner SVG" href="howto-corner-images.html"/>
-                <custom-html-source label="Custom html source" href="howto-custom-html-source.html"/>
-                <project-sitemapRef label="Project sitemap" href="site:project-sitemap"/>
             <ForrestIntegrate label="Integrate Forrest with tools">

Modified: forrest/trunk/site-author/status.xml
--- forrest/trunk/site-author/status.xml (original)
+++ forrest/trunk/site-author/status.xml Sun Apr  8 19:45:40 2007
@@ -143,6 +143,9 @@
 <!-- 2007-04 -->
       <action dev="DC" type="add" context="docs">
+        New document to explain <link href="site:sitemap-explain">Cocoon sitemaps</link>
using a specific worked example.
+      </action>
+      <action dev="DC" type="add" context="docs">
         Add explanation of
         <link href="site:procedures/forrest-dev/debug-modes">Cocoon Running Modes</link>
         for setting different properties.
@@ -875,7 +878,7 @@
       <action dev="RDG" type="add" context="code" importance="high">
-        Added support for a locationmap. This enables content to be retrieved from a location
+        Added support for Locationmaps. This enables content to be retrieved from a location
         that is defined in a locationmap file. A project-based file can be located at 
         <code>PROJECT_HOME/src/documentation/content/locationmap.xml</code> while
core locationmaps
         are at <code>$FORREST_HOME/main/webapp/locationmap-*.xml</code> files.<br

View raw message