<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">

<document>
  <header>
    <title>How to use Cocoon WebMail Site</title>
    <version>0.9</version>
    <type>Technical document</type>
    <authors>
      <person name="Bernhard Huber" email="huber.at.apache.org"/>
    </authors>
    <abstract>This document describes Cocoon WebMail.</abstract>
  </header>
  <body>
    <s1 title="Cocoon WebMail Site">
      <p>
        This document describes the Cocoon WebMail Site. 
        The overview section describes the URI space, layout and
        resource mapping used by 
        Cocoon WebMail Site.
      </p>
      <p>
        The next sections describes the Cocoon sitemap components
        used in the Cocoon WebMail Site.
      </p>
      <p>
        The target audience of this document are sitemap designer, and
        developers interested in setting up a Cocoon WebMail Site.
      </p>
    </s1>
    <s1 title="Overview">
      <s2 title="URI Space">
        <p>
          The URI space has following structure, <em>root</em> denotes the root 
          of this URI space.
        </p>
        <figure alt="URI space" src="asciiart/uri-space.jpg"/>
        <p>
          As you may figure out <code>*.html</code> serves static document pages,
          mail/mail.html, and mail/logout.html serves dynamic Cocoon Webmail pages.
          All other resources are static, like images, cascaded stylesheet, and icons.
          The <code>asciiart/*.jpg</code> are jpg resource created from simple ascii art text.
        </p>
        <p>
          The document pages all have the format <code>*.html</code>, 
          eg. <code>index.html</code>, or <code>howto-cocoon-webmail.html</code>.
          The dynamic Cocoon Webmail pages all have the format <code>mail/*.html</code>,
          eg. <code>mail/maill.html</code>, or <code>mail/logout.html</code>.
        </p>
      </s2>
      <s2 title="Layout">
        <p>
          The visible layout of Cocoon Webmail Site is a simple multi column
          layout.
        </p>
        <figure alt="Layout" src="asciiart/layout.jpg"/>
        <p>
          The sections contain following piece of information
        </p>
        <ul>
          <li>
            The header section displays the Cocoon Webmail banner;
            the top section is empty for document pages, for 
            dynamic pages it contains a list of available commands.
          </li>
          <li>
            The col1 section presents auxilliary information.
          </li>
          <li>
            The col2 section contains for document pages the document content;
            for dynamic pages it presents the content of an executed command, 
            like a list of mail folders, a list of messages, the content of a message.
          </li>
          <li>
            The col3 section presents additional links.
          </li>
          <li>
            Finally the bottom section displays the Cocoon Webmail footer.
          </li>
        </ul>
        <s3 title="Implementing the Layout">
          <p>
            For the sake of flexibilty a page requested by an URI is aggregated.
            The aggregation parts are located in the resource section directories.
          </p>
          <p>
            The column layout is realized by using positioning features of CSS. Each aggregation
            part is wrapped by an &lt;div&gt; which has CSS positional settings for placing
            it some concrete page position.
          </p>
        </s3>
      </s2>
      <s2 title="Resource Mapping">
        <p>
          The Cocoon Webmail Site uses following directory structure
          on the filesystem:
        </p>
        <figure alt="Directory structure" src="asciiart/directory-hierarchy.jpg"/>
        <p>
          As you can figure out each layout section is mapped to a directory. Each of these
          directories contains the documents of one section.
        </p>
        <p>
          Thus for example the request URI of this page is <code>howto-cocoon-webmail.html</code>. 
          The <code>mid-col-2</code> section of this page expects an xml document
          in the filesystem as <code>docs/mid-col-2/howto-cocoon-webmail.xml</code>.
        </p>
        <p>
          By design dynamic pages of the Cocoon Webmail application are
          requested by an URI of the format <code>mail/*.html</code>, the resource mapping
          of these pages maps to the same directories as the static pages.
          Thus <code>mail/mail.html</code> maps for the section <code>mid-col-2</code> to
          <code>docs/mid-col-2/mail.xsp</code>.
        </p>
      </s2>
    </s1>
    <s1 title="Cocoon's Sitemap Elements">
      <p>
        Beside the usage of the sitemap <code>MailAction</code> there are several sitemap
        components, and sitemap constructs  used in sitemap of the Cocoon Webmail.
      </p>
      <p>
        The following sections detail most important Cocoon's sitemap components
        of Cocoon WebMail. All of these components are listed in the 
        sitemap componts section.
      </p>
      <s2 title="Actions">
        <ul>
          <li>resource-exists - Checks existance of a resource</li>
          <li>link-translator - Defines link rewriting patterns</li>
          <li>mail - action of the Cocoon Webmail application, executes commands, manages 
            http session, and javamail session.
          </li>
        </ul>
      </s2>
      <s2 title="Generators">
        <ul>
          <li>file - generates XML from an XML file</li>
          <li>serverpages - generates XML from an XSP file</li>
          <li>asciiart-svg - generates SVG from a TXT file</li>
        </ul>
      </s2>
      <s2 title="Matchers">
        <ul>
          <li>wildcard - matches simple wildcard of the format <code>*</code>, and <code>**</code></li>
          <li>regexp-default - extension of regexp matcher for setting default values. 
            It is used to for matching both paginated, and non-paginted URI request.
            Setting the default paginator page to 1.
          </li>
        </ul>
      </s2>
      <s2 title="Readers">
        <ul>
          <li>resource - simple resource reader for serving images, and CSS files</li>
        </ul>
      </s2>
      <s2 title="Selectors">
        <ul>
          <li>request-attribute - selects processing depending on the existance, and content
            of a request attribute, selects the suitable XSLT stylesheet for javamail object
            to document page transformation.
          </li>
        </ul>
      </s2>
      <s2 title="Transformers">
        <ul>
          <li>xslt - XSLT transformer for transforming aggregated site document to html,
            transforming javamail documents to a document.
          </li>
          <li>paginator - Paginator transformer for splitting up long pages,
            separating document pages by <code>pagesheets/htmlpages.xml</code>, and
            separating dynamic pages by <code>pagesheets/mailhtmlpages.xml</code>,
            </li>
        </ul>
      </s2>
      <s2 title="Views">
        <ul>
          <li>content - defines a view requesting the 'pure' content of a page.</li>
          <li>links - defines a view for requesting all outbounding links of a page.</li>
        </ul>
      </s2>
      <s2 title="Resources">
        <ul>
          <li>show-page - aggregates a requested URI, triggering the generation of its parts.
            The sections making up the content of a page are invoked from here.
          </li>
          <li>load-page - Decides what page file should get loaded, due to the existing
            of a resource in the filesystem, serving default pages in case of non-existance
            of a requested resource document.
          </li>
          <li>show-page-xsp - Decides what page file should get loaded, due to the existing
            of a resource in the filesystem, serving default pages in case of non-existance
            of a requested resource document. It generates from XSP instead of XML, in
            contrast to <code>load-page</code>.
          </li>
        </ul>
      </s2>
    </s1>

    <s1 title="Serving a Document Page">
      <p>
        Each requested document URI uses following sitemap data flow:
      </p>
      <figure alt="serving document page" src="asciiart/serving-document-page.jpg"/>
      <p>
        Each aggregate part follows in principal following sitemap data flow:
      </p>
      <figure alt="serving document detail" src="asciiart/serving-document-page-1.jpg"/>
    </s1>
    
    <s1 title="Serving a Dynamic Page">
      <p>
        Each requested dynamic URI uses following sitemap data flow:
      </p>
      <figure alt="serving dynamic page" src="asciiart/serving-dynamic-page.jpg"/>
      <p>
        Each aggregate part follows in principal following sitemap data flow:
      </p>
      <figure alt="serving dynamic page detail" src="asciiart/serving-dynamic-page-1.jpg"/>
    </s1>
      
    <s1 title="MailAction Dataflow">
      <p>
        As <code>MailAction</code> access a lot of parameters
        the following diagram gives an overview of all 
        parameters involved for processing a request.
      </p>
      <figure alt="MailAction Dataflow" src="asciiart/mailaction-dataflow.jpg"/>
    </s1>
    <s1 title="Summary">
      <p>
        As the basic structure of Cocoon WebMail Site has been explained,
        setting up, and maintaing a Cocoon WebMail site 
        - reusing ideas, sitemap snippets, and Cocoon's sitemap components -
        shall be easy.
      </p>
    </s1>
  </body>
</document>


