joerg 2003/07/18 23:22:36
Modified: src/documentation/xdocs/userdocs/concepts actions.xml
Log:
fixed cocoon-action-ACTIONNAME vs cocoon-action=ACTIONNAME
indentation
Revision Changes Path
1.2 +122 -138 cocoon-2.1/src/documentation/xdocs/userdocs/concepts/actions.xml
Index: actions.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/concepts/actions.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- actions.xml 9 Mar 2003 00:08:17 -0000 1.1
+++ actions.xml 19 Jul 2003 06:22:36 -0000 1.2
@@ -1,53 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
-<document>
- <header>
- <title>Creating and Using Actions</title>
- <version>0.3</version>
- <type>Overview document</type>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- <person name="Giacomo Pati" email="[EMAIL PROTECTED]"/>
- <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
- <person name="Christian Haul" email="[EMAIL PROTECTED]"/>
- </authors>
- </header>
- <body>
- <s1 title="The Actions">
- <s2 title="What is an Action?">
+<document>
+ <header>
+ <title>Creating and Using Actions</title>
+ <version>0.3</version>
+ <type>Overview document</type>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ <person name="Giacomo Pati" email="[EMAIL PROTECTED]"/>
+ <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
+ <person name="Christian Haul" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </header>
+ <body>
+ <s1 title="The Actions">
+ <s2 title="What is an Action?">
<p>
Apache Cocoon has a rich set of tools for publishing web documents, and while
XSP and Generators provide alot of functionality, they still mix content
- and logic to a certain degree. The Action was created to fill that gap.
+ and logic to a certain degree. The Action was created to fill that gap.
Because the Cocoon Sitemap provides a mechanism to select the pipeline
at run time, we surmised that sometimes we need to adjust the pipeline
- based on runtime parameters, or even the contents of the Request parameter.
- Without the use of Actions this would make the sitemap almost
- incomprehensible.
+ based on runtime parameters or even the contents of the Request parameter.
+ Without the use of Actions this would make the sitemap almost incomprehensible.
</p>
<p>
The quick and dirty definition of an Action is "a Sitemap Component that
- manipulates runtime parameters". Actions must be ThreadSafe, and they
- can be as complex as you need. The Action is the proper place to handle
- form processing, and even dynamic navigation. The Action is
+ manipulates runtime parameters". Actions must be ThreadSafe and they
+ can be as complex as you need. The Action is the proper place to handle
+ form processing and even dynamic navigation. The Action is
differentiated from the other sitemap components (Generator, Transformer,
- Serializer, and Reader) primarily by the fact that it does not produce
- any display data. <link href="actions.txt">actions.txt</link> contains
- excerpts from discussions on the cocoon-dev@ mailing list regarding Actions.
+ Serializer and Reader) primarily by the fact that it does not produce
+ any display data. <link href="actions.txt">actions.txt</link> contains
+ excerpts from discussions on the cocoon-dev mailing list regarding Actions.
</p>
</s2>
<s2 title="When to use an Action instead of XSP">
<p>
Sometimes it is going to be quicker for you to create and handle
logic in XSP, because Cocoon recognizes if there have been any
- changes. However, many times it is more desirable to have a separation
- between the logic and the display. For instance, we will use a
- multipage form. In XSP the logic to handle the results for one
+ changes. However, many times it is more desirable to have a separation
+ between the logic and the display. For instance, we will use a
+ multipage form. In XSP the logic to handle the results for one
page have to be implemented in the following page.
</p>
- <source>
-<![CDATA[
+ <source><![CDATA[
<xsp:logic>
// handle the previous page's values.
String name = <xsp-request:get-parameter name="name"/>;
@@ -71,19 +69,18 @@
</esql:execute-query>
</esql:connection>
</xsp:logic>
-]]>
- </source>
+]]></source>
<p>
This can get very messy, as you will invariably have alot of processing
- for things that don't even belong in the context of this page. When
+ for things that don't even belong in the context of this page. When
you come back later to add features or someone else starts to maintain
the code, you have a mess on your hands.
</p>
<p>
- The alternative is to use Actions. Actions handle the pure logic
- handling portions of your site. This allows you to create each page
+ The alternative is to use Actions. Actions handle the pure logic
+ handling portions of your site. This allows you to create each page
in the multipage form to handle any logic it needs to for display
- purposes only. Your form handling information is kept separate, and
+ purposes only. Your form handling information is kept separate and
can even predictably change the pipeline used in the sitemap.
</p>
</s2>
@@ -91,16 +88,16 @@
<s1 title="Actions at Work">
<p>
Actions are components that allow two way communication between the
- Sitemap and the Action. This section describes how to define them
- in the sitemap, and create one in real life. We are going to write
+ Sitemap and the Action. This section describes how to define them
+ in the sitemap and create one in real life. We are going to write
an Action that is our version of "Hello World".
</p>
<p>
The problem domain is this: we "need" a component that will create
- an HTTP request parameter named "hello" with a value of "world", and
+ an HTTP request parameter named "hello" with a value of "world" and
it will create a sitemap parameter named "world" with a value of
- "hello". Why? So we can show you the two manners in which the Action
- can be used, and let your imagination go from there.
+ "hello". Why? So we can show you the two manners in which the Action
+ can be used and let your imagination go from there.
</p>
<s2 title="Creating the Action">
<p>
@@ -108,8 +105,7 @@
We are performing something very simple here, but you can get
more complex examples from the Cocoon code-base.
</p>
- <source>
-<![CDATA[
+ <source><![CDATA[
package test;
import org.apache.avalon.framework.parameters.Parameters;
@@ -138,57 +134,49 @@
return sitemapParams;
}
}
-]]>
- </source>
+]]></source>
</s2>
<s2 title="Using the Action">
<p>
- In order to use the Action we just created, we need to define it
- in the sitemap. After it has been defined, we must use it in the
- sitemap.
+ In order to use the Action we just created, we need to define it in the
+ sitemap. After it has been defined, we must use it in the sitemap.
</p>
<s3 title="Defining the Action">
- <source>
-<![CDATA[
+ <source><![CDATA[
<map:actions>
<map:action name="hello-world" src="test.HelloWorldAction"/>
</map:actions>
-]]>
- </source>
+]]></source>
</s3>
<s3 title="Using the Action">
- <source>
-<![CDATA[
+ <source><![CDATA[
<map:match pattern="file">
<map:act type="hello-world">
<map:generate type="serverpages" src="{world}_world.xsp"/>
</map:act>
<map:serialize/>
</map:match>
-]]>
- </source>
+]]></source>
<p>
- Using this approach, we will generate the file named "hello_world.xsp"
- because the value of the Sitemap parameter "{world}" is "hello". Also,
- the file "hello_world.xsp" can use the request attribute "hello" to
- produce the value "world".
+ Using this approach, we will generate the file named
+ <code>hello_world.xsp</code> because the value of the Sitemap parameter
+ <code>{world}</code> is <code>hello</code>. Also, the file
+ <code>hello_world.xsp</code> can use the request attribute
+ <code>hello</code> to produce the value <code>world</code>.
</p>
- <source>
-<![CDATA[
+ <source><![CDATA[
<para>Hello <xsp-request:get-attribute name="hello"/>.</para>
-]]>
- </source>
+]]></source>
</s3>
</s2>
<s2 title="Communication between Sitemap and Action">
- <p>
- As stated previously there is a two way communication between the
- Sitemap and the Action. The Sitemap can pass the parameters
- and the source attribute to the Action and the Action can return
- a Map object with new values which can be used in the sitemap.
- </p>
- <source>
-<![CDATA[
+ <p>
+ As stated previously there is a two way communication between the
+ Sitemap and the Action. The Sitemap can pass the parameters
+ and the source attribute to the Action and the Action can return
+ a Map object with new values which can be used in the sitemap.
+ </p>
+ <source><![CDATA[
<map:match pattern="file">
<map:act type="hello-world" src="optional src">
<!-- and here come the parameters: -->
@@ -198,66 +186,66 @@
</map:act>
<map:serialize/>
</map:match>
-]]>
- </source>
- <p>This Map object does not replace the previous Map object, but is stacked
on top
- of it. The other Map objects are still accessible through a path
expression.</p>
-<source>
-<![CDATA[
+]]></source>
+ <p>This Map object does not replace the previous Map object, but is stacked on
top
+ of it. The other Map objects are still accessible through a path
expression.</p>
+ <source><![CDATA[
<map:match pattern="*">
<map:act type="validate-session">
<map:generate type="serverpages" src="{../1}.xsp"/>
</map:act>
<map:serialize/>
</map:match>
-]]>
-</source>
- <p>The above example shows how to access the next to last map
- by prefixing the key with "<code>../</code>"</p>
+]]></source>
+ <p>
+ The above example shows how to access the next to last map
+ by prefixing the key with <code>../</code>.
+ </p>
</s2>
<s2 title="Flow Control">
- <p>
- In addition to delivering values to the Sitemap, the Action can
- also control the flow. If the action returns <code>null</code>
- all statements inside the <code>map:act</code> element are
- not executed. So, if in the example above the hello world action
- would return <code>null</code> the server page generator
- would not be activated.
- </p>
- <p> In other words: The statements within the
- <code>map:act</code> element are <em>only</em> executed if the
- action returns at least an empty Map object.</p>
+ <p>
+ In addition to delivering values to the Sitemap, the Action can
+ also control the flow. If the action returns <code>null</code>
+ all statements inside the <code>map:act</code> element are
+ not executed. So, if in the example above the hello world action
+ would return <code>null</code> the server page generator
+ would not be activated.
+ </p>
+ <p>
+ In other words: The statements within the <code>map:act</code> element
+ are <em>only</em> executed if the action returns at least an empty Map
+ object.
+ </p>
</s2>
</s1>
<s1 title="Action Sets">
<p>
You can arrange actions in an action set. The sitemap calls the
- act method of those actions in the sequence they are defined in the
+ act method of those actions in the sequence they are defined in the
action set. It is possible to signal to the sitemap to
- call an action only if the Environments getAction method returns
- a String identical to the value supplied with an action attribute.
+ call an action only if the Environment's <code>getAction</code> method
+ returns a String identical to the value supplied with an action attribute.
In the current implementation of the HttpEnvironment the value
returned by the getAction method is determined by a http request
parameter. The Environment looks for a request parameter with a
- prefix "cocoon-action-" followed by an action name.</p>
- <source>
-<![CDATA[
-<input type="submit" name="cocoon-action-ACTIONAME" value="click here to do
something">
-]]>
- </source>
- <p>Please note: the orginal "cocoon-action" syntax is deprecated but still
supported!</p>
- <p> Above we have seen that a successfully executed action
+ prefix "cocoon-action-" followed by an action name.
+ </p>
+ <source><![CDATA[
+<input type="submit" name="cocoon-action-ACTIONNAME" value="click here to do
something">
+]]></source>
+ <note>The orginal "cocoon-action" syntax is deprecated but still
supported!</note>
+ <p>Above we have seen that a successfully executed action
returns a Map object that can be used to communicate with the
sitemap. In case of an action set this is similar. With action
sets all returned Map objects are merged into a single Map. Of
course a Map can contain only one value per key so that if
multiple actions within an action set use the same key to
- communicate to the sitemap, only the last one "survives".</p>
- <p>
- So far let's have a look at at possible action set definition:
+ communicate to the sitemap, only the last one "survives".
</p>
- <source>
-<![CDATA[
+ <p>
+ So far let's have a look at at possible action set definition:
+ </p>
+ <source><![CDATA[
<map:action-sets>
<map:action-set name="shop-actions">
<map:act type="session-invalidator" action="logoff"/>
@@ -271,11 +259,9 @@
<map:act type="screen-navigator" src="{1}"/>
</map:action-set>
</map:action-sets>
-]]>
- </source>
+]]></source>
<p>And this is a possible pipeline snipped which uses this action set:</p>
- <source>
-<![CDATA[
+ <source><![CDATA[
<map:match pattern="*">
<map:act set="shop-actions"> <--- HERE -->
<map:generate type="serverpages" src="docs/xsp/{nextpage}.xsp"/>
@@ -283,41 +269,39 @@
<map:serialize type="html"/>
</map:act>
</map:match>
-]]>
- </source>
- <p>
-Let me explain some of those actions in the set first.
- </p>
+]]></source>
+ <p>Let me explain some of those actions in the set first.</p>
<p>
-The "session-invalidator" action gets called when an action of logoff is
-requested (ie. a html submit button named "cocoon-action" with the
-value "logoff" was pressed).
+ The "session-invalidator" action gets called when an action of logoff is
+ requested (ie. a html submit button named "cocoon-action-logoff" was
+ pressed).
</p>
<p>
-The "session-validator" action is called on every request. It assures that
-an http session is created and available to the other sitemap components
-(other actions and xsp pages selected for resource production).
+ The "session-validator" action is called on every request. It assures that
+ an http session is created and available to the other sitemap components
+ (other actions and xsp pages selected for resource production).
</p>
<p>
-The other actions in the set with an action attribute do specific things
-like adding an item to the cart, removing one or all items from the cart
-etc. They are called depending on the value returned by the getAction method
-of the HttpEnvironment object passed to the sitemap engine as described
-above ( see "session-invalidator" action).
+ The other actions in the set with an action attribute do specific things
+ like adding an item to the cart, removing one or all items from the cart,
+ etc. They are called depending on the value returned by the getAction
+ method of the HttpEnvironment object passed to the sitemap engine as
+ described above (see "session-invalidator" action).
</p>
<p>
-The screen-navigation action is always called because it has knowledge
-about the flow/sequence of pages and it knows how/where the preceding actions
-stores their execution status (ie. as an request attribute). Depending on those
-stati the screen-navigation action sets up a Map with an element called
-"nextpage" with the value of the page that produces the next "view".
+ The screen-navigation action is always called because it has knowledge
+ about the flow/sequence of pages and it knows how/where the preceding actions
+ stores their execution status (ie. as an request attribute). Depending on those
+ stati the screen-navigation action sets up a Map with an element called
+ "nextpage" with the value of the page that produces the next "view".
</p>
<p>
-However, one is not limited to specify distinct values at the action attribute.
-It is possible and I think useful to mark several actions with the same
-action attribute value which will then be called in sequence. This allows you
-to choose a granularity of your actions at will.
+ However, one is not limited to specify distinct values at the action attribute.
+ It is possible and I think useful to mark several actions with the same
+ action attribute value which will then be called in sequence. This allows you
+ to choose a granularity of your actions at will.
</p>
</s1>
</body>
</document>
+
