# How to use Cocoon WebMail Site

0.9
Technical document

This document describes Cocoon WebMail.

Cocoon WebMail Site

This document describes the Cocoon WebMail Site. The overview section describes the URI space, layout and resource mapping used by Cocoon WebMail Site.

The next sections describes the Cocoon sitemap components used in the Cocoon WebMail Site.

The target audience of this document are sitemap designer, and developers interested in setting up a Cocoon WebMail Site.

Overview

URI Space

The URI space has following structure, root denotes the root of this URI space.

URI space

As you may figure out `*.html` 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 `asciiart/*.jpg` are jpg resource created from simple ascii art text.

The document pages all have the format `*.html`, eg. `index.html`, or `howto-cocoon-webmail.html`. The dynamic Cocoon Webmail pages all have the format `mail/*.html`, eg. `mail/maill.html`, or `mail/logout.html`.

Layout

The visible layout of Cocoon Webmail Site is a simple multi column layout.

Layout

The sections contain following piece of information

- 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.
- The col1 section presents auxilliary information.
- 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.
- The col3 section presents additional links.
- Finally the bottom section displays the Cocoon Webmail footer.

Implementing the Layout

For the sake of flexibilty a page requested by an URI is aggregated. The aggregation parts are located in the resource section directories.

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.

Resource Mapping

The Cocoon Webmail Site uses following directory structure on the filesystem:

Directory structure

As you can figure out each layout section is mapped to a directory. Each of these directories contains the documents of one section.

Thus for example the request URI of this page is `howto-cocoon-webmail.html`. The `mid-col-2` section of this page expects an xml document in the filesystem as `docs/mid-col-2/howto-cocoon-webmail.xml`.

By design dynamic pages of the Cocoon Webmail application are requested by an URI of the format `mail/*.html`, the resource mapping of these pages maps to the same directories as the static pages. Thus `mail/mail.html` maps for the section `mid-col-2` to `docs/mid-col-2/mail.xsp`.

Cocoon's Sitemap Elements

Beside the usage of the sitemap `MailAction` there are several sitemap components, and sitemap constructs used in sitemap of the Cocoon Webmail.

The following sections detail most important Cocoon's sitemap components of Cocoon WebMail. All of these components are listed in the sitemap componts section.

Actions

- resource-exists - Checks existance of a resource
- link-translator - Defines link rewriting patterns
- mail - action of the Cocoon Webmail application, executes commands, manages http session, and javamail session.

Generators

- file - generates XML from an XML file
- serverpages - generates XML from an XSP file
- asciiart-svg - generates SVG from a TXT file

Matchers

- wildcard - matches simple wildcard of the format `*`, and `**`
- 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.

Readers

- resource - simple resource reader for serving images, and CSS files

Selectors

- 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.

Transformers

- xslt - XSLT transformer for transforming aggregated site document to html, transforming javamail documents to a document.
- paginator - Paginator transformer for splitting up long pages, separating document pages by `pagesheets/htmlpages.xml`, and separating dynamic pages by `pagesheets/mailhtmlpages.xml`,

Views

- content - defines a view requesting the 'pure' content of a page.
- links - defines a view for requesting all outbounding links of a page.

Resources

- 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.
- 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.
- 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 `load-page`.

Serving a Document Page

Each requested document URI uses following sitemap data flow:

serving document page

Each aggregate part follows in principal following sitemap data flow:

serving document detail

Serving a Dynamic Page

Each requested dynamic URI uses following sitemap data flow:

serving dynamic page

Each aggregate part follows in principal following sitemap data flow:

serving dynamic page detail

MailAction Dataflow

As `MailAction` access a lot of parameters the following diagram gives an overview of all parameters involved for processing a request.

MailAction Dataflow

Summary

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.