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

 <?xml version="1.0" encoding="UTF-8"?>
 <!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"?>
	<!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>