cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jo...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/concepts actions.xml
Date Sat, 19 Jul 2003 06:22:36 GMT
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="bloritsch@apache.org"/> 
  -           <person name="Giacomo Pati" email="giacomo@apache.org"/>
  -           <person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
  -           <person name="Christian Haul" email="haul@apache.org"/>
  -	 </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="bloritsch@apache.org"/>
  +      <person name="Giacomo Pati" email="giacomo@apache.org"/>
  +      <person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
  +      <person name="Christian Haul" email="haul@apache.org"/>
  +    </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>
  +
  
  
  

Mime
View raw message