You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by cz...@apache.org on 2003/10/12 15:16:32 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/advanced/authentication book.xml authentication.xml preface.xml
cziegeler 2003/10/12 06:16:32
Modified: src/documentation/xdocs/ctwig ctwig-installing.xml
src/documentation/xdocs/userdocs book.xml
Added: src/documentation/xdocs/developing/portal book.xml index.xml
portal-block.xml
src/documentation/xdocs/userdocs index.xml
src/documentation/xdocs/developing/webapps index.xml
book.xml forms.xml authentication.xml portal.xml
contexts.xml session.xml
Removed: src/documentation/xdocs/userdocs/advanced/portal
portal-fw-block.xml portal-block.xml book.xml
index.xml
src/documentation/xdocs/userdocs/advanced/session forms.xml
session.xml preface.xml book.xml contexts.xml
src/documentation/xdocs/userdocs intro.xml
src/documentation/xdocs/userdocs/advanced book.xml
preface.xml
src/documentation/xdocs/userdocs/advanced/authentication
book.xml authentication.xml preface.xml
Log:
Continue rearranging docs to the old places :(
This will take some time - so please be patient...
Revision Changes Path
1.5 +1 -1 cocoon-2.1/src/documentation/xdocs/ctwig/ctwig-installing.xml
Index: ctwig-installing.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/ctwig/ctwig-installing.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ctwig-installing.xml 2 Sep 2003 13:17:33 -0000 1.4
+++ ctwig-installing.xml 12 Oct 2003 13:16:32 -0000 1.5
@@ -27,7 +27,7 @@
<p>The latest distribution for any operating system can be found in the <fork href="http://cocoon.apache.org/mirror.cgi">Cocoon distribution folder</fork>. This file contains the Cocoon code, samples, documentation and the Java libraries that enable the Cocoon to work such as Xerces and Xalan. When you have downloaded it then extract it to somewhere. This path becomes your {COCOON_HOME}.</p>
</s2>
<s2 title="Basic Configuration">
- <p>Follow the instructions on building Cocoon as per the installation guide that comes with Cocoon. It can also be found <fork href="../userdocs/installation/index.html">here</fork> as well. Obviously since you have got the ZIP distribution you do not have to do the CVS bit thus you can start at the Building Apache Cocoon 2 section. Do each of the following steps:</p>
+ <p>Follow the instructions on building Cocoon as per the installation guide that comes with Cocoon. It can also be found <fork href="../installation/index.html">here</fork> as well. Obviously since you have got the ZIP distribution you do not have to do the CVS bit thus you can start at the Building Apache Cocoon 2 section. Do each of the following steps:</p>
<ul>
<li>Set JAVA_HOME</li>
<li>Create the WAR using
1.3 +2 -1 cocoon-2.1/src/documentation/xdocs/developing/portal/book.xml
1.9 +20 -402 cocoon-2.1/src/documentation/xdocs/developing/portal/index.xml
1.1 cocoon-2.1/src/documentation/xdocs/developing/portal/portal-block.xml
Index: portal-block.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Configuring the Cocoon Portal</title>
<authors><person email="jgreenyer@s-und-n.de" name="Joel Greenyer"></person>
</authors>
<notice>This document is under development.</notice>
<abstract>
This document describes the use and configuration
of the (new) cocoon portal block.
</abstract>
</header>
<body>
<s1 title="Introducing the Cocoon Portal">
<p>
This document describes the use and configuration
of the (new) cocoon portal that you can find in the "portal" block.
(Don't mix this with the older portal version that you can
find in the "portal-fw" block.)
</p>
<s2 title="Important parts of the Cocoon Portal">
<p>
</p>
</s2>
<s2 title="How is a portal page created by Cocoon?">
<p>
</p>
</s2>
<s2 title="I want to build my own portal! An approach">
<p>
</p>
</s2>
</s1>
<s1 title="Configuring the Portal contents">
<s2 title="Configuring Coplets">
<p>
</p>
</s2>
<s2 title="Configuring the arrangement of the defined Coplets">
<p>
</p>
</s2>
<s2 title="...">
<p>
</p>
</s2>
</s1>
<s1 title="Create a new skin for your portal">
<p>This section will explain the concepts of the portal layout,
considering the <code>skins/basic/</code> skin provided with cocoon,
and will describe how to create a new skin by extending the
existing stylesheets.</p>
<note>The skin path can be changed in the portal's sitemap. There is
a <code>global-variable</code> specifying the path to the skin folder.</note>
<p>The basic cocoon portal skin is a nice and simple example how to visualize a portal.
There are several elements that allow to customize the look and feel of the portal.
A portal with the basic skin consists of </p>
<ul>
<li>a <em>header</em></li>
<li>a <em>tab row</em></li>
<li>a <em>content section</em> containing the coplet windows</li>
<li>and a <em>footer </em></li>
</ul>
<figure alt="Parts of the portal" height="300" src="images/portal-parts.gif" width="400"></figure>
<p>The tab row is actually a part of the content section. As well, a tab row can
be provided to any coplet window.</p>
<s2 title="The skin's stylesheets">
<p>If we take a look at the <code>skins/basic/styles</code> directory, we
find a number of stylesheets:
</p>
<ul>
<li><code>portal-page.xsl</code>: Creates final HTML page</li>
<li><code>tab.xsl</code>: layout of the tab row.</li>
<li><code>window.xsl</code>: coplet window layout</li>
<li><code>column.xsl</code>: layout of a column</li>
<li><code>row.xsl</code>: layout of a row</li>
<li><code>login-page.xsl</code>: layout of the login page</li>
</ul>
<p>The <code>window.xsl</code> stylesheet determines the layout of a
coplet window. Normally, a coplet window will contain a header row with a
title and buttons like minimize, close, etc.</p>
<p>These coplet windows are arranged in rows and columns to create
the arrangement typical for portals. There can be several rows per column
and several columns in the content section. So the thinking is a little
different than in usual HTML tables.</p>
<p>The content section or content row usually has a tab row located at the top
and the coplet windows are arranged below. The layout of the tabs is
specified in the <code>tab.xsl</code> stylesheet.</p>
<p>The <code>portal-page.xsl</code> stylesheet encapsulates the content section
with the tab row and allows to define a page header and a footer.
This is probably the first stylesheet we want to take a closer look at.
</p>
<note>The <code>tab.xsl</code>, <code>column.xsl</code>,
<code>row.xsl</code> and <code>window.xsl</code> stylesheets
are used by the portal components directly and won't be found
anywhere in the sitemap. The <code>cocoon.xconf</code>
defines which stylesheets will be used by the portal.</note>
</s2>
<s2 title="The portal-page.xsl">
<p>
Here is the place to change the design of the header and footer row.
This stylesheet is used to construct the final HTML page, which displays
the portal. The code sample here displays the main template match node of the
stylesheet.
</p>
<source>
<![CDATA[...
<xsl:template match="/">
<html>
<head>
<link type="text/css" rel="stylesheet" href="page.css"/>
</head>
<body>
<table bgColor="#ffffff" border="0"
cellPadding="0" cellSpacing="0" width="100%">
<tbody>
<!-- header row -->
<tr>
<td colspan="2">
<table border="2" cellPadding="0" cellSpacing="0" width="100%">
<tbody>
<tr>
<td colspan="2" noWrap="" height="10" bgcolor="#DDDDDD">
</td>
</tr>
<tr>
<td bgcolor="#CCCCCC" height="100" align="center"
valign="middle" width="100%">
<font size="80pt">Cocoon Portal</font>
</td>
</tr>
<tr>
<td colspan="2" noWrap="" height="10" bgcolor="#DDDDDD">
</td>
</tr>
</tbody>
</table>
</td>
</tr>
<!-- content/tab row -->
<tr>
<td>
<xsl:apply-templates/>
</td>
</tr>
<!-- footer row -->
<tr>
<td colspan="2">
<table border="2" cellPadding="0" cellSpacing="0" width="100%">
<tbody>
<tr>
<td colspan="2" noWrap="" height="10" bgcolor="#DDDDDD">
<img height="1" src="sunspotdemoimg-space.gif" width="1"/>
</td>
</tr>
<tr>
<td colspan="2" noWrap="" height="30" bgcolor="#CCCCCC">
<img height="1" src="sunspotdemoimg-space.gif" width="1"/>
</td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</body>
</html>
</xsl:template>
...]]>
</source>
</s2>
<s2 title="The tab.xsl">
<p>From the <code>portal-page.xsl</code> stylesheet, we will now
move upwards in the XSL transformation steps and take a look at the
stylesheet that was processed before, the <code>tab.xsl</code>.</p>
<p>Again, this source snippet shows the main template match node of the stylesheet:</p>
<source><![CDATA[...
<!-- Process a tab -->
<xsl:template match="tab-layout">
<!-- ~~~~~ Begin body table ~~~~~ -->
<table border="2" cellpadding="0" cellspacing="0" width="100%">
<!-- ~~~~~ Begin tab row ~~~~~ -->
<tr>
<td>
<table summary="tab bar" border="2" cellpadding="0"
cellspacing="0" width="100%">
<tr vAlign="top">
<xsl:for-each select="named-item">
<xsl:choose>
<xsl:when test="@selected">
<!-- ~~~~~ begin selected tab ~~~~~ -->
<td valign="middle" bgcolor="#DDDDDD">
<b>
<a href="{@parameter}">
<font color="#000000">
<xsl:value-of select="@name"/>
</font>
</a>
</b>
</td>
<!-- ~~~~~ end selected tab ~~~~~ -->
</xsl:when>
<xsl:otherwise>
<!-- ~~~~~ begin non selected tab ~~~~~ -->
<td valign="middle" bgcolor="#CCCCCC" >
<div class="tab">
<a href="{@parameter}">
<xsl:value-of select="@name"/>
</a>
</div>
</td>
<!-- ~~~~~ end non selected tab ~~~~~ -->
</xsl:otherwise>
</xsl:choose>
</xsl:for-each>
<!-- ~~~~~ last "blank" tab ~~~~~ -->
<td width="99%" bgcolor="#CCCCCC" align="right">
</td>
</tr>
</table>
</td>
</tr>
<!-- ~~~~~ End tab row ~~~~~ -->
<!-- ~~~~~ Begin content row ~~~~~ -->
<tr>
<td bgcolor="#FFFFFF">
<xsl:apply-templates/>
</td>
</tr>
<!-- ~~~~~ End content row ~~~~~ -->
</table>
</xsl:template>
...]]></source>
<p>The first row that is created here contains the definition of the tabs.
The <code><xsl:choose></code> element differentiates between the
currently selected tab and all other tabs. The <code>@selected</code>
attribute is generated by the portal and can be accessed as shown
above. As well, the portal provides the tab's <code>@parameter</code>
(usually the tab's link) and <code>@name</code> attributes. </p>
<note>Depending on the configuration of the portal, it is possible
that tabbed areas are nested inside each other. So be careful how a tab
row might look in the middle of another content section.</note>
<p>Nice looking tabs can become pretty complex, take a look at the
<code>tab.xml</code> stylesheet in the <code>skins/common/</code>
skin to see another example.</p>
<p>Below the tabs, another table cell is defined that will be filled
with the contents of the tabbed area. This content will have been processed
by the <code>columns.xsl</code> stylesheet before - and before that by the
<code>row.xsl</code> stylesheet.</p>
</s2>
<s2 title="The column.xsl and row.xsl">
<p>The <code>column.xsl</code> and <code>row.xsl</code> stylesheets
define the look of the tables in which the coplet windows will be placed.
Usually, nothing exciting happens in these stylesheets. Here is a listing of the
important parts, just to give a complete overview.
</p>
<p>The main template match node of the <code>column.xsl</code> stylesheet:</p>
<source><![CDATA[...
<!-- Process a Column -->
<xsl:template match="column-layout">
...
<table border="{$border}" cellSpacing="0" cellpadding="0"
width="100%">
<xsl:if test="@bgcolor">
<xsl:attribute name="bgcolor">
<xsl:value-of select="@bgcolor" />
</xsl:attribute>
</xsl:if>
<tr vAlign="top">
<xsl:for-each select="item">
<td>
<xsl:if test="@bgcolor">
<xsl:attribute name="bgcolor">
<xsl:value-of select="@bgcolor" />
</xsl:attribute>
</xsl:if>
<xsl:if test="@width">
<xsl:attribute name="width">
<xsl:value-of select="@width" />
</xsl:attribute>
</xsl:if>
<xsl:apply-templates />
</td>
</xsl:for-each>
</tr>
</table>
</xsl:template>
...]]></source>
<p>The main template match node of the <code>row.xsl</code> stylesheet:</p>
<source><![CDATA[...
<!-- Process a row -->
<xsl:template match="row-layout">
...
<table border="{$border}" cellSpacing="10" width="100%">
<xsl:if test="@bgcolor">
<xsl:attribute name="bgcolor">
<xsl:value-of select="@bgcolor" />
</xsl:attribute>
</xsl:if>
<xsl:for-each select="item">
<tr vAlign="top">
<xsl:if test="@bgcolor">
<xsl:attribute name="bgcolor">
<xsl:value-of select="@bgcolor" />
</xsl:attribute>
</xsl:if>
<td>
<xsl:apply-templates />
</td>
</tr>
</xsl:for-each>
</table>
</xsl:template>
...]]></source>
</s2>
<s2 title="The window.xsl">
<p>The <code>window.xsl</code> stylesheet determines the design of the coplet
windows and probably takes the most design effort compared to the other stylesheets.
A coplet window consists of a table header with the window title and a number
of buttons like close, minimize, maximize etc. The basic skin provides some
images in the <code>images/</code> subfolder. The rest of the window will
be filled with the coplet content, depending on the configuration of
the coplet.</p>
<p>A slightly more complex example can be found in the
<code>skins/common/</code> skin.</p>
<p>The listing below shows the main template match node:</p>
<source><![CDATA[...
<xsl:template match="window">
...
<table border="2" cellSpacing="0" cellpadding="0" width="100%">
<tr vAlign="top">
<td bgColor="{$bgColor}" valign="middle">
<font>
<xsl:attribute name="color">#ffffff</xsl:attribute>
<xsl:attribute name="face">Arial</xsl:attribute>
<xsl:attribute name="size">2</xsl:attribute>
<xsl:choose>
<xsl:when test="@title">
<b><xsl:value-of select="@title"/></b>
</xsl:when>
<xsl:otherwise>
<b><xsl:value-of select="title"/></b>
</xsl:otherwise>
</xsl:choose>
</font>
</td>
<td align="right" bgColor="{$bgColor}">
<xsl:if test="fullscreen-uri">
<a href="{fullscreen-uri}">
<img src="customize.gif" border="0" alt="Full Screen"/>
</a>
</xsl:if>
<xsl:if test="maxpage-uri">
<a href="{maxpage-uri}">
<img src="show.gif" border="0" alt="Max Page"/>
</a>
</xsl:if>
<xsl:if test="maximize-uri">
<a href="{maximize-uri}">
<img src="maximize.gif" border="0" alt="Maximize"/>
</a>
</xsl:if>
<xsl:if test="minimize-uri">
<a href="{minimize-uri}">
<img src="minimize.gif" border="0" alt="Minimize"/>
</a>
</xsl:if>
<xsl:if test="remove-uri">
<a href="{remove-uri}">
<img src="delete.gif" border="0" alt="Delete"/>
</a>
</xsl:if>
</td>
</tr>
<tr>
<td colSpan="2">
<xsl:apply-templates select="content"/>
</td>
</tr>
</table>
</xsl:template>
...]]></source>
</s2>
</s1>
<s1 title="Further topics">
<p>
</p>
</s1>
</body>
</document>
1.7 +23 -13 cocoon-2.1/src/documentation/xdocs/userdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/book.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- book.xml 2 Sep 2003 12:03:18 -0000 1.6
+++ book.xml 12 Oct 2003 13:16:32 -0000 1.7
@@ -1,26 +1,36 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="Apache Cocoon"
- title="Apache Cocoon User Guide"
+ title="Apache Cocoon User Documentation"
copyright="@year@ The Apache Software Foundation">
- <menu label="User Guide">
- <menu-item label="Intro" href="intro.html"/>
+ <menu label="Navigation">
+ <menu-item label="Main" href="../index.html"/>
+ </menu>
+
+ <menu label="User Documentation">
+ <menu-item label="Concepts" href="concepts/index.html"/>
+ </menu>
- <menu-item label="1. Basics" href="user/preface.html"/>
- <menu-item label="2. Advanced" href="advanced/preface.html"/>
- <menu-item label="3. Configuration" href="config/preface.html"/>
+ <menu label="Sitemap Components">
+ <menu-item label="Generators" href="generators/generators.html"/>
+ <menu-item label="Transformers" href="transformers/transformers.html"/>
+ <menu-item label="Serializers" href="serializers/serializers.html"/>
+ <menu-item label="Matchers" href="matchers/matchers.html"/>
+ <menu-item label="Selectors" href="selectors/selectors.html"/>
+ <menu-item label="Actions" href="actions/actions.html"/>
+ <menu-item label="Readers" href="readers/readers.html"/>
</menu>
- <menu label="Developer Guide">
- <menu-item label="4. Basics" href="developer/preface.html"/>
+ <menu label="Control Flow">
+ <menu-item label="Control Flow" href="flow/index.html"/>
</menu>
- <menu label="Appendix">
- <menu-item label="A. Installation" href="installation/index.html"/>
- <menu-item label="B. Components" href="components/index.html"/>
- <menu-item label="C. Concepts" href="concepts/index.html"/>
- <external label="D. API (Javadoc)" href="../apidocs/index.html"/>
+ <menu label="XSP">
+ <menu-item label="XSP" href="xsp/index.html"/>
</menu>
+ <menu label="Offline Generation">
+ <menu-item label="Offline Generation" href="offline/index.html"/>
+ </menu>
</book>
1.7 +0 -0 cocoon-2.1/src/documentation/xdocs/userdocs/index.xml
1.3 +25 -11 cocoon-2.1/src/documentation/xdocs/developing/webapps/index.xml
1.4 +6 -8 cocoon-2.1/src/documentation/xdocs/developing/webapps/book.xml
1.1 cocoon-2.1/src/documentation/xdocs/developing/webapps/forms.xml
Index: forms.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Simple Forms</title>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@s-und-n.de"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>This chapter describes the (simple) form handling approach of
the session framework.</p>
<note>Cocoon provides several approaches for form handling. This
chapter explains one of them.</note>
</s1>
<s1 title="Form Handling">
<p>To get feedback or information from a user, forms are commonly used
to present input field in the browser. The usual approach for form handling in
web application consists of two steps. The first request presents the form to
the user. This form initiates a second request that processes the form
values.</p>
<p>Cocoon supports this two step process, in addition Cocoon offers
a single step approach.</p>
<s2 title="The common approach">
<p>The common approach consists of two steps or of creating two
resources. The first resource defines the form: All input fields are declared,
each gets a unique name. This form invokes the second resource.</p>
<p>This resource uses the session transformer to get the values
provided by the user. The values are added by the browser to the parameters of
the request. So using the request context and <em>getxml</em>, the values can
be fetched.</p>
<p>If you want to create a form with two values - forename and surname
of the user, you could generate a base xml file with the information about this
form:</p>
<source><page>
<form>
<action>form-handling-page</action>
<input name="forename" type="text"/>
<input name="surname" type="text"/>
</form>
</page></source>
<p>A stylesheet can transform this into valid html. The action tag
indicates that the "form-handling-page" should be invoked by submitting the
values.</p>
<p>The "form-handling-page" is a pipeline which is declared in the
sitemap and uses the session transformer. It could also read the following
xml:</p>
<source><page xmlns:session="http://apache.org/cocoon/session/1.0">
<forename>
<session:getxml context="request" path="/parameter/forename"/>
</forename>
<surname>
<session:getxml context="request" path="/parameter/surname"/>
</surname>
</page></source>
<p>As the form values are appended to the request, <em>getxml</em>
with specifying the path (which is the parameter name used for the input field)
inserts the value submitted by the user into the xml stream.</p>
<p>If you want to write the information in a session context, you must
wrap the whole xml inside a setxml:</p>
<source><page xmlns:session="http://apache.org/cocoon/session/1.0">
<session:setxml context="userdata" path="/user">
<forename>
<session:getxml context="request" path="/parameter/forename"/>
</forename>
<surname>
<session:getxml context="request" path="/parameter/surname"/>
</surname>
</session:setxml>
</page></source>
<p>The user data is now stored inside the session context "userdata",
so the context has the following content:</p>
<source><user>
<forename>Walter</forename>
<surname>Walterson</surname>
</user></source>
</s2>
<s2 title="The Session Framework approach">
<p>The previous chapter showed the common approach for handling form
values. It forces the user to create two resources for a single form
handling.</p>
<p>Cocoon offers an advanced approach. Only one single resource is
created. This resources contains the information about the input fields used
and in addition the information about where the submitted values should be
stored inside the session.</p>
<p>The example from the previous chapter could look like this:</p>
<source><page xmlns:session="http://apache.org/cocoon/session/1.0">
<session:form name="myform">
<session:action>the-next-page</session:action>
<session:content>
<session:inputxml name="forename" type="text" context="userdata" path="/user/forename"/>
<session:inputxml name="surname" type="text" context="userdata" path="/user/surname"/>
</session:content>
</session:form>
</page></source>
<p>The form tag starts the form definition. The name attribute is
required to distinct between different forms on the same page. The action tag
defines the url invoked by the form and the content tag describes the content
of the form: its input fields.</p>
<p>The <em>inputxml</em> tag tells Cocoon that the following request
contains form values which should be stored in the specified context under the
given path. The session transformer transforms by removing the namespace and
the context attribute:</p>
<source><page xmlns:session="http://apache.org/cocoon/session/1.0">
<form action="the-next-page">
<inputxml name="forename" type="text"/>
<inputxml name="surname" type="text"/>
</form>
</page></source>
<p>A stylesheet can now generate the appropriate html (or any other
format). The main difference is, that the resource invoked by submitting the
values has not to care about the form as Cocoon maintains the form handling.
The only prerequisit is that a session for the current user and a session
context to store the information exists.</p>
<p>The Cocoon approach allows a very easy way of form handling where
the resource which creates the form also handles the form.</p>
<p>For editing values - if the context already contains information
about the user - <em>inputxml</em> inserts the current value inside the tag. So
the xml streamed would after a second run would look like this:</p>
<source><page xmlns:session="http://apache.org/cocoon/session/1.0">
<form action="the-next-page">
<inputxml name="forename" type="text">Walter</inputxml>
<inputxml name="surname" type="text">Walterson</inputxml>
</form>
</page></source>
<p>Like <em>getxml</em> it is also possible to provide default values
for the input field, if the context does not contain any information:</p>
<source><session:inputxml name="forename" context="userdata" path="/user/forename">
Defaultname
</session:inputxml></source>
<p>But as always there is one drawback with this approach as well, you
have to put the <em>session-form-manager</em> action somewhere so
that it is called when the form values are submitted. As this
action does no harm, it can simply be put as the first action in your
main sitemap:</p>
<source>
<map:act type="session-form-manager"/>
</source>
</s2>
</s1>
</body>
</document>
1.3 +194 -106 cocoon-2.1/src/documentation/xdocs/developing/webapps/authentication.xml
1.4 +0 -0 cocoon-2.1/src/documentation/xdocs/developing/webapps/portal.xml
1.1 cocoon-2.1/src/documentation/xdocs/developing/webapps/contexts.xml
Index: contexts.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
<document>
<header>
<title>Session Contexts</title>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@s-und-n.de"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>This chapter describes the concept of the session context provided
by the session framework (session-fw block).</p>
<p>The session framework provides the concept of so called (session) contexts.
A session context is a data storage in the session that can contain
arbitrary data in XML format.</p>
<p>You can define your own contexts for your application. For example,
if you build a web shop, you can create a context called <em>shop</em>
and store the basket of the user in it.</p>
<p>The <em>session transformer</em> is the main component used for
storing and retrieving information from such a context.</p>
<note>The chapter "Special Contexts" explains some special
contexts which do not require a session. They are available everytime. These
special contexts are the request context and the
temporary context.</note>
</s1>
<s1 title="session Transformer">
<p>The <em>session transformer</em> is responsible for interpreting the tags
and performing the actions required. The session transformer is configured
in the sitemap and can be used inside a pipeline. All tags must be prefixed
with the session namespace. So the actual tag used in the document will read
<em><session:xxxx></em>. The current namespace URI for the session
transformer is <em>"http://apache.org/cocoon/session/1.0"</em>.</p>
<s2 title="Context-Tags">
<p>A context is basically an application specific block of XML data in
the users session. Each context has a unique name.</p>
<p>The command <em>createcontext</em> is used to create a new context.
A <em>name</em> attribute must be given to the context in order to identify it.
The following names may not be used: request, response, session,
context, temp, portal or authentication. If a context of the same name already exists
then this command will have no effect.</p>
<p><em><createcontext name="mycontext"/></em></p>
<p>In order to delete a context the command <em>deletecontext</em> is
provided. Again a <em>name</em> attribute must be provided.</p>
<p><em><deletecontext name="mycontext"/></em></p>
<p>Once created, XML data can then be stored inside or read from a
given context.</p>
</s2>
<s2 title="Accessing context data">
<p>The data in a context can be dynamically accessed using the
following commands.</p>
<p></p>
<p><em>getxml</em> allows data to be read out of a context. A
<em>path</em> attribute describes the source of the data inside the context and
consists of an XPath expression. All <em>path</em> values must be absolute and
only nodes and attributes can be accessed. </p>
<p>An optional default value can also be provided to allow for the
nonexistence of the requested data.</p>
<p><em><getxml context="mycontext"
path="/User/Name"/></em></p>
<p><em><getxml context="mycontext"
path="/User/Name">Matthew</getxml></em></p>
<p>Attributes can also be accessed.</p>
<p><em><getxml context="mycontext"
path="/User/Name/@Age"/></em></p>
<p><em></em></p>
<p>Data can be written into a context using the <em>setxml</em>
command. It is possible to set values or nodes as the following examples
show.</p>
<p><em><setxml context="mycontext"
path="/User/Name"/>Carsten</setxml></em></p>
<p><em><setxml context="mycontext"
path="/User/"/><Name>Carsten</Name></setxml></em></p>
<p></p>
<p>Using the <em>setxml</em> command causes all the nodes below the
target node to be deleted. If you wish to maintain the nodes and manipulate
individual branches of the XML tree - then the session transformer offers the
<em>mergexml</em> command.</p>
<p></p>
<p>Use the <em>removexml</em> command to remove nodes from the
context.</p>
<p><em><removexml context="mycontext"
path="/User/"/></em></p>
<s3 title="Example">
<p>The following example shows the use of several commands and in
particular how the <em>mergexml</em> command can be used to manipulate context
data.</p>
<source><resource xmlns:session="http://apache.org/cocoon/session/1.0">
<session:createcontext name="trackdemo"/>
<!-- build context data -->
<session:setxml context="trackdemo" path="/">
<context>
<users>
<user id="1">
<name>Carsten</name>
</user>
</users>
</context>
</session:setxml>
<session:mergexml context="trackdemo" path="/context">
<users>
<user id="1">
<name>Ziegeler</name>
<developer>true</developer>
</user>
<user id="2">
<name>Walter</name>
</user>
</users>
</session:mergexml>
<session:getxml context="trackdemo" path="/"/>
</resource></source>
<p>In the above example, a context for storing data is added. Using
the <em>setxml</em> command data is then stored into the context. The following
<em>mergexml</em> command then changes the name of user-1 and adds a further
tag. As there is no original user-2 the complete subtree is then added to the
context.</p>
</s3>
</s2>
<s2 title="Reading and writing contexts">
<p>Aside from the described means of accessing data in a context,
the session transformer also provides for the reading and writing of contexts. This can be
used to write an application context out to a database or to read an
application context in from a file.</p>
<p>The session transformer offers a very flexible way of defining the source of the
context data. It is possible to specify a resource (defined in the sitemap) or
a Java class. Using a resource allows for example the context data to be read
from a database using the SQL Transformer. As this source is a Cocoon
pipeline, the data can be generated and transformed before passing into the
context. </p>
<p>When a context is created, it can get additional save and load URIs
which are used for loading/saving to/from the context:</p>
<p><em><createcontext name="mycontext" load="cocoon://load-from-db"
save="cocoon://save-to-db"/></em></p>
<p>These URIs can then be used inside a document to load data into a
context:</p>
<p><em><loadxml context="mycontext"/></em></p>
<p>This example would then load the context data via the resource
<em>load-from-db</em> which must be defined in the sitemap.</p>
<p>Parameters can be passed to and interpreted by the uri or the Java
class. This allows the context data to be read dependent on say the current
user.</p>
<p><em><loadxml
context="mycontext"><user>ben</user></loadxml></em></p>
<p>The resource addressed by the uri will receive the parameters as
request-parameters. In addition the name of the context will always be passed
as <em>contextname</em>.</p>
<p>Writing context data works in the same manner.</p>
<p><em><savexml context="mycontext"/></em></p>
<p>Both commands can use the optional <em>path</em> attribute:</p>
<p><em><loadxml context="mycontext" path="/user"/></em></p>
<p><em><savexml context="mycotnext" path="/user"/></em></p>
<p>The first command will read xml from the uri and store it in the
context under the node <em>user</em>, the second one saves only the xml subtree
under the node <em>user</em> to the uri. The resource addressed by the uri will
be passed in addition to the <em>contextname</em> parameter the <em>path</em>
parameter with the corresponding value. If the <em>path</em> attribute is not
present the <em>path</em> parameter will get the value <em>"/"</em>.</p>
</s2>
</s1>
<s1 title="Special Contexts">
<p>Cocoon creates and maintains special contexts that allow the
applications to access the environment. This allows the read-only access
to such things as the current request using the same XPath
commands previously described. These context do not require any session, they
are always available and change on every request.</p>
<s2 title="The Request Context - Accessing the Environment, Part One">
<p>The request context is an XML description of the current
(HTTP) request. This context is a special read only context that
can be accessed with the usual commands:</p>
<p><em><getxml context="request" path="/parameter"/></em></p>
<p>For example, if you want to get the value of a parameter with the
name <em>username</em> you can include the following command in your XML and it
will be replaced with the value of the parameter:</p>
<p><em><getxml context="request"
path="/parameter/username"/></em></p>
<p>If you wish to obtain the complete querystring as it was
passed into Cocoon - without converting the data to XML - then you can use
the "/querystring" path:</p>
<p><em><getxml context="request"
path="/querystring"/></em></p>
<p>The result will be a string in the format
"?param=aaa&...".</p>
<p>The complete context you can access via these commands has the
following XML format:</p>
<source><parameter>
<!-- All parameters: parameter names build the elements with the value of the first parameter with
this name as text node child -->
<firstparameter>value of parameter</firstparameter>
<secondparameter>value of parameter</secondparameter>
</parameter>
<querystring>the querystring with a leading '?' or empty<querystring>
(The querystring contains only parameters send by the GET method)
<parametervalues>
<!-- All parameters. The tags are all inside the cinclude transformer namespace.
The generated XML can be used without modification for the
cinclude:includexml command. -->
<cinclude:parameters>
<cinclude:parameter>
<cinclude:name>1st parameter name</cinclude:name>
<cinclude:value>1st parameter value</cinclude:value>
</cinclude:parameter>
...
<cinclude:parameter>
<cinclude:name>2nd parameter name</cinclude:name>
<cinclude:value>2nd parameter value</cinclude:value>
</cinclude:parameter>
</cinclude:parameters>
<!-- If a parameter has more than one value, for each value a
<session:param> block is generated. -->
</parametervalues>
<attributes>
<!-- lists all attributes, attribute names build the elements
with the values as text node childs -->
</attributes>
<headers>
<!-- lists all headers, header names build the elements
with the values as text node childs -->
</headers>
<cookies>
<!-- lists all cookies -->
<cookie name="...">
<value>the cookie value</value>
<name>the name of the cookie</name>
<comment>value</comment>
<domain>value</domain>
<path>value</path>
<maxAge>value</maxAge>
<secure>value</secure>
<version>value</version>
</cookie>
</cookies>
<characterEncoding>value</characterEncoding>
<contentLength>value</contentLength>
<contentType>value</contentType>
<protocol>value</protocol>
<remoteAddress>value</remoteAddress>
<remoteHost>value</remoteHost>
<scheme>value</scheme>
<serverName>value</serverName>
<serverPort>value</serverPort>
<method>value</method>
<contextPath>value</contextPath>
<pathInfo>value</pathInfo>
<pathTranslated>value</pathTranslated>
<remoteUser>value</remoteUser>
<requestedSessionId>value</requestedSessionId>
<requestURI>value</requestURI>
<servletPath>value</servletPath>
<isRequestedSessionIdFromCookie>value</isRequestedSessionIdFromCookie>
<isRequestedSessionIdFromCookie>value</isRequestedSessionIdFromCookie>
<isRequestedSessionIdValid>value</isRequestedSessionIdValid></source>
</s2>
<s2 title="The Temporary Context">
<p>The temporary context with the name <em>temporary</em> is available on
each request. It is independent from the session and has no content when a new
request starts. It can be used like any other context except that the content
is lost/deleted when the current response is finished.</p>
<p>Using the tempory context it is possible to store any XML
information for processing the current request.</p>
</s2>
</s1>
<s1 title="Session-Context Input Module">
<p>In addition to the <em>session transformer</em>, the <em>session-context input module</em>
can be used directly in the sitemap to get information out of a context.</p>
<p>The information for the input module consists of two parts, the first
one being the context name and the second one the path inside the
context. Let's have a look at an example:</p>
<source>
<map:generate src="{session-context:request/method}.xml"/>
</source>
<p>
In the example above, either <em>GET.xml</em> or <em>POST.xml</em> is
read by the <em>file generator</em>, depending on the value from
the context <em>request</em> using the xpath <em>method</em>.
</p>
</s1>
</body>
</document>
1.6 +3 -387 cocoon-2.1/src/documentation/xdocs/developing/webapps/session.xml