apache > cocoon

- Home

# Example sitemap snippets

## Overview

The following explanations describe how some sections of the sitemaps operate. For overview, see the general Sitemap document and the specific userdocs.

## C2 documentation

The Cocoon documentation XML files are located at `documentation/xdocs/*.xml` and sub-directories. The sitemap at `documentation/sitemap.xmap` does most of the work. It is used by `build docs` and it also mounted by the main sitemap to handle requests for documentation as a servlet.

Each match is presented and described in turn.

    Match #1 ...
       <!-- ================  C2 documentation  ================= -->
       <map:match pattern="">
        <map:redirect-to uri="index.html"/>
       </map:match>

Just a convenience for redirecting the null pattern to the home page.

    Match #2 ...
       <map:match pattern="*.html">
        <map:aggregate element="site">
         <map:part src="cocoon:/book-{1}.xml"/>
         <map:part src="cocoon:/body-{1}.xml"/>
        </map:aggregate>
        <map:transform src="stylesheets/site2xhtml.xsl">
         <map:parameter name="use-request-parameters" value="true"/>
         <map:parameter name="header" value="graphics/{1}-header.jpg"/>
        </map:transform>
        <map:serialize/>
       </map:match>

Generates the response for a top-level page (e.g. index.html). Note that lower-level pages (e.g. userdocs/index.html) do not match here and are processed in a similar way by Match #3.

Each document is composed of two separate parts: the side-panel menu and the actual page content. Each part is build separately and then aggregated. Consider the example of the home page (index.html). The side-panel content comes from `documentation/xdocs/book.xml` (and is handled by the pipeline `book-index.xml`). The actual page content comes from `documentation/xdocs/index.xml` (and is handled by the pipeline `body-index.xml`).

So Match #2 generates an intermediate XML file by aggregating the XML output from the two pipelines and wrapping it with a `<site>` element. (The `cocoon:/` protocol means "Use the relevant pipeline from the current sitemap".) The output stream is then transformed to XHTML and serialized.

    Match #3 ...
       <map:match pattern="**/*.html">
        <map:aggregate element="site">
         <map:part src="cocoon:/{1}/book-{1}/{2}.xml"/>
         <map:part src="cocoon:/body-{1}/{2}.xml"/>
        </map:aggregate>
        <map:transform src="stylesheets/site2xhtml.xsl">
           <map:parameter name="use-request-parameters" value="true"/>
           <map:parameter name="header" value="graphics/{2}-header.jpg"/>
         </map:transform>
        <map:serialize/>
       </map:match>

This is similar to Match #2, except that it deals with documents in sub-directories. For the side-panel, this uses the `book.xml` found in each relevant directory.

    Match #4 ...
       <map:match pattern="**book-**.xml">
         <map:generate src="xdocs/{1}book.xml"/>
           <map:transform src="stylesheets/book2menu.xsl">
             <map:parameter name="use-request-parameters" value="true"/>
             <map:parameter name="resource" value="{2}.html"/>
           </map:transform>
         <map:serialize type="xml"/>
       </map:match>

This produces the additional structured content for the relevant side-panel menu. Note that this is the only match that serializes to XML (the others have the default HTML).

In essence, this Match #4 is called from Match #2 via the `cocoon:/` protocol and is aggregated with the output of Match #6

    Match #5 ...
       <map:match pattern="body-todo.xml">
         <map:generate src="xdocs/todo.xml"/>
         <map:transform src="stylesheets/todo2document.xsl"/>
         <map:transform src="stylesheets/document2html.xsl"/>
         <map:serialize/>
       </map:match>

       <map:match pattern="body-changes.xml">
         <map:generate src="xdocs/changes.xml"/>
         <map:transform src="stylesheets/changes2document.xsl"/>
         <map:transform src="stylesheets/document2html.xsl"/>
         <map:serialize/>
       </map:match>

       <map:match pattern="body-faq.xml">
         <map:generate src="xdocs/faq.xml"/>
         <map:transform src="stylesheets/faq2document.xsl"/>
         <map:transform src="stylesheets/document2html.xsl"/>
         <map:serialize/>
       </map:match>

These matches are for special cases. Note that they are defined before the general body-*.xml match. Remember that the sitemap reads from top to bottom and the first encountered match is used.

These special-cases need to transform the content into XML files that conform to document-v10.dtd first.

    Match #6 ...
       <map:match pattern="body-**.xml">
         <map:generate src="xdocs/{1}.xml"/>
         <map:transform src="stylesheets/document2html.xsl"/>
         <map:serialize/>
       </map:match>

This match handles the bodies of all other the other documents (which are natively conforming to document-v10.dtd).

In essence, this Match #6 is called from Match #2 via the `cocoon:/` protocol and is aggregated with the output of Match #4

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).