RELEASE_2_1_13/src/blocks/mail/samples/mail/docs/mid-col-2/howto-cocoon-webmail.xml - cocoon - Git at Google

 <?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>
	<?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 <div> 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>