webwork/src/docs chaining.xml,NONE,1.1 index.xml,1.20,1.21

Update of /cvsroot/webwork/webwork/src/docs
In directory usw-pr-cvs1:/tmp/cvs-serv8773

Modified Files:
	index.xml 
Added Files:
	chaining.xml 
Log Message:
add action chaining doc

--- NEW FILE: chaining.xml ---
<section id="wizards">
  <title>Chaining Actions</title>
   <sectioninfo>
      <title></title>

      <abstract>
         <para>
         The ability to chain actions gives you the ability to build reusable, modular actions.
         </para>
      </abstract>

      <authorgroup>
         <author>
            <firstname>Matt</firstname>
            <surname>Baldree</surname>
         </author>
         <email>[email protected]</email>
         <author>
            <firstname></firstname>
            <surname></surname>
         </author>
      </authorgroup>

   </sectioninfo>
   <para>
   An <link linkend='action'>action</link> encapsulates a piece of functionality; e.g., you might have a login action or a sign address book action. Over time as you build projects with actions, you see common functionality that you would like to abstract out to make reusable. What you would like to do is describe a discrete piece of functionality and reuse it across applications.
   </para>
   
   <para>
   So, lets think of an action as a link in a chain. It may be the first link, last link, or a link in the middle. The ordering of this link should be abstracted but the functionality of the link should be the same. This <literal>chaining of actions</literal> is supported in WW.
   </para>

   <para>
   Lets take a simple example of an action (Foo) where its sole purpose is to capitalize a title. This action provides a setter for a title and its <literal>execute()</literal> method capitalizes the title. Next, lets say you have an action (Bar) that provides a setter for title and does nothing. 
   </para>
   
   <para>
   Now, you want to chain together these two actions to perform some work. So, you build a chain in the view map, see below.
   </para>
   
   <informalexample>Example view mapping:
      <programlisting>
<![CDATA[
# action chaining
actionchain.foo.action=Foo
actionchain.foo.success=actionchain.bar.action

actionchain.bar.action=Bar
actionchain.bar.success=bar.jsp
## Need an input view because I am explicitly add an error from the execution of Foo.
## The error will be propogated to Bar so Bar will need to handle it which will require
## an input or error view
actionchain.bar.input=bar.jsp
]]>
      </programlisting>
   </informalexample>    
  
   <para>
   Now, that your chain is built you are ready to go. So, lets take for instance a form that posts to <literal>actionchain.foo.action</literal>. WW will set all parameters on <literal>Foo</literal> and call its <literal>execute()</literal>. Upon a successful return, WW finds that the result is an <literal>action</literal> and not a view so it finds this action, loads it, sets its context which includes copying appropriate attributes from the previous action, and finally calling <literal>Bar's execute()</literal> method. If <literal>Bar</literal> returns a view, then WW will forward the request to this view.   
   </para>
   
   <para>
   Now, lets take a little deeper look. First, lets assume that both <literal>Foo and Bar</literal> extend <literal>ActionSupport</literal>. Then, assume <literal>Foo</literal> adds an error in its execution. When <literal>Foo's</literal> attributes are copied to <literal>Bar</literal> the errors will be copied as well. This means when <literal>Bar</literal> is executed, <literal>ActionSupport</literal> will return an <literal>INPUT</literal> view. WW will then search the map for an <literal>INPUT</literal> view and forward the request to this view.
   </para>
   
   <para>
   This example only demonstrated a two link chain but the their is no limit.
   </para>
</section>

Index: index.xml
===================================================================
RCS file: /cvsroot/webwork/webwork/src/docs/index.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21
--- index.xml	31 May 2002 00:42:24 -0000	1.20
+++ index.xml	17 Jun 2002 21:31:04 -0000	1.21
@@ -9,6 +9,7 @@
    <!ENTITY expr SYSTEM "expr.xml">
    <!ENTITY api SYSTEM "api.xml">
    <!ENTITY jsp SYSTEM "jsp.xml">
+   <!ENTITY chaining SYSTEM "chaining.xml">
    <!ENTITY velocity SYSTEM "velocity.xml">
    <!ENTITY xslt SYSTEM "xslt.xml">
    <!ENTITY baseclasses SYSTEM "baseclasses.xml">
@@ -134,7 +135,13 @@
          <date>2002-05-20</date>
          <authorinitials>jgh</authorinitials>
          <revremark>Added VoiceXML tag references</revremark>
-     </revision>     
+     </revision> 
+      <revision>
+         <revnumber>1.3</revnumber>
+         <date>2002-06-17</date>
+         <authorinitials>mb</authorinitials>
+         <revremark>Added documentation for chaining actions</revremark>
+     </revision>          
   </revhistory>
 </bookinfo><chapter id="fundamentals">
   <title>WebWork fundamentals</title>
@@ -169,6 +176,8 @@
    &validation;
    &errors;
    &wizards;
+   &wizards;
+   &chaining;
    &i18n;
    &intellij;
 </chapter><chapter id="about">



----------------------------------------------------------------------------------------------------
                                     Sponsor's Message
----------------------------------------------------------------------------------------------------
                      Bringing you mounds of caffeinated joy
                         >>>     http://thinkgeek.com/sf    <<<