cziegeler 2003/09/01 06:46:33
Modified: src/documentation/xdocs/userguide/advanced/session
session.xml book.xml
Added: src/documentation/xdocs/userguide/advanced/session
contexts.xml forms.xml
Log:
Split the session chapter
Revision Changes Path
1.2 +0 -371
cocoon-2.1/src/documentation/xdocs/userguide/advanced/session/session.xml
Index: session.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userguide/advanced/session/session.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- session.xml 1 Sep 2003 08:16:01 -0000 1.1
+++ session.xml 1 Sep 2003 13:46:33 -0000 1.2
@@ -42,376 +42,5 @@
<p>The action either creates a new session immediately (if not already
available), or terminates it (if available).</p>
</s1>
- <s1 title="Contexts">
- <s2 title="session Transformer">
- <p>The session transformer 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 document. 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>
- <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="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.2 +2 -0
cocoon-2.1/src/documentation/xdocs/userguide/advanced/session/book.xml
Index: book.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userguide/advanced/session/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 1 Sep 2003 08:16:01 -0000 1.1
+++ book.xml 1 Sep 2003 13:46:33 -0000 1.2
@@ -12,6 +12,8 @@
<menu label="2.2 Sessions">
<menu-item label="2.2.1 Intro" href="preface.html"/>
<menu-item label="2.2.2 Sessions" href="session.html"/>
+ <menu-item label="2.2.3 Contexts" href="contexts.html"/>
+ <menu-item label="2.2.4 Simple Forms" href="forms.html"/>
</menu>
</book>
1.1
cocoon-2.1/src/documentation/xdocs/userguide/advanced/session/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="[EMAIL PROTECTED]"/>
</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>
<s2 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>
<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>
</body>
</document>
1.1
cocoon-2.1/src/documentation/xdocs/userguide/advanced/session/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="[EMAIL PROTECTED]"/>
</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>
