cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From coli...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/flow api.xml jpath.xml jxtemplate.xml sitemap.xml using.xml velocity.xml views.xml book.xml continuations.xml how-does-it-work.xml
Date Sat, 24 May 2003 18:51:26 GMT
coliver     2003/05/24 11:51:26

  Modified:    src/documentation/xdocs/userdocs/flow book.xml
                        continuations.xml how-does-it-work.xml
  Added:       src/documentation/xdocs/userdocs/flow api.xml jpath.xml
                        jxtemplate.xml sitemap.xml using.xml velocity.xml
                        views.xml
  Log:
  improve flowscript docs (still sucks though, unfortunately)
  
  Revision  Changes    Path
  1.3       +7 -0      cocoon-2.1/src/documentation/xdocs/userdocs/flow/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/book.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- book.xml	25 Mar 2003 13:53:56 -0000	1.2
  +++ book.xml	24 May 2003 18:51:26 -0000	1.3
  @@ -14,5 +14,12 @@
       <menu-item label="Introduction" href="index.html"/>
       <menu-item label="Continuations" href="continuations.html"/>
       <menu-item label="How does it work?" href="how-does-it-work.html"/>
  +    <menu-item label="Usage" href="using.html"/>
  +    <menu-item label="Sitemap" href="sitemap.html"/>
  +    <menu-item label="JavaScript API" href="api.html"/>
  +    <menu-item label="Generators" href="views.html"/>
  +    <menu-item label="JXTemplate" href="jxtemplate.html"/>
  +    <menu-item label="JPath" href="jpath.html"/>
  +    <menu-item label="Velocity" href="velocity.html"/>
     </menu>
   </book>
  
  
  
  1.2       +3 -3      cocoon-2.1/src/documentation/xdocs/userdocs/flow/continuations.xml
  
  Index: continuations.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/continuations.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- continuations.xml	25 Mar 2003 13:43:33 -0000	1.1
  +++ continuations.xml	24 May 2003 18:51:26 -0000	1.2
  @@ -35,13 +35,13 @@
     var a, b, operator;
   
     sendPageAndWait("getA.html");
  -  a = request.getParameter("a");
  +  a = cocoon.request.get("a");
   
     sendPageAndWait("getB.html");
  -  b = request.getParameter("b");
  +  b = cocoon.request.get("b");
   
     sendPageAndWait("getOperator.html");
  -  operator = request.getParameter("op");
  +  operator = cocoon.request.get("op");
   
     try {
       if (operator == "plus")
  
  
  
  1.2       +1 -1      cocoon-2.1/src/documentation/xdocs/userdocs/flow/how-does-it-work.xml
  
  Index: how-does-it-work.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/how-does-it-work.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- how-does-it-work.xml	25 Mar 2003 13:43:33 -0000	1.1
  +++ how-does-it-work.xml	24 May 2003 18:51:26 -0000	1.2
  @@ -35,7 +35,7 @@
   	<p>Since continuations are objects, you can also store them in
   	a database, for really long-lived session, just like you do
   	with session beans.</p>
  -    </s1>
  +  </s1>
   
     </body>
   </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/api.xml
  
  Index: api.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Advanced Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
        <person name="Christopher Oliver" email="coliver@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="JavaScript API">
  	<p>Cocoon provides a JavaScript API to manage control flow based on an <link href="http://cvs.cocoondev.org/cgi-bin/viewcvs.cgi/?cvsroot=rhino">extended</link>
version of <link href="http://www.mozilla.org/rhino">Mozilla Rhino</link> that
supports continuations.</p>
      </s1>
      <s1 title="Functions">
      <s2 title = "sendPage">
        <p>
        <code>void sendPage([String] uri, [Object] bean)</code>
        </p>
        <p>
        Passes control to the Cocoon sitemap to generate the output page.
        </p>
        <p>
        <code>uri</code> is the relative URL of the page to be sent back to the
client.
        </p>
        <p>
         <code>bean</code> is a context object which can be accessed inside this
page toextract various values and place them in the generated page.
        </p>
      </s2>
      <s2 title = "sendPageAndWait">
      <p>
      <code>WebContinuation sendPageAndWait([String] uri, [Object] bean, [Number] timeToLive)</code>
      </p>
       <p>
       Passes control to the Cocoon sitemap to generate the output page.
       </p>
        <p>The flow script is suspended after the page is generated and the whole execution
stack saved in a the WebContinuation object returned from this function. </p>
       <p> <code>uri</code> is the relative URL of the page to be sent back
to the client. <code>bean</code> is a context object which can be accessed inside
this page to extract various values and place them in the generated page.</p>
       <p><code>timeToLive</code> is the time to live for the continuation
created.</p>
       <p>The return value is the continuation object.</p>
      </s2>
    </s1>
      <s1 title="Objects">
      <s2 title = "cocoon">
      </s2>
      <p>The <code>cocoon</code> object represents the current Cocoon sitemap
and provides the following readonly properties:</p> 
      <p>The current Cocoon request:</p>
      <p>
      <code>[org.apache.cocoon.environment.Request] request</code>
      </p>
      <p>The current Cocoon response:</p>
      <p>
      <code>[org.apache.cocoon.environment.Response] response</code>
      </p>
      <p>The current Cocoon session:</p>
      <p>
      <code>[org.apache.cocoon.environment.Session] session</code>
      </p>
      <p>The current Cocoon application context:</p>
      <p>
      <code>[org.apache.cocoon.environment.Context] context</code>
      </p>
      <p>The current Cocoon environment:</p>
      <p>
      <code>[org.apache.cocoon.environment.Environment] environment</code>
      </p>
      <p>The current Sitemap's component manager:</p>
      <p>
      <code>[org.apache.avalon.framework.component.ComponentManager] componentManager</code>
      </p>
      <p>Any parameters passed to the script by the Sitemap:</p>
      <p>
      <code>[Array] parameters</code>
      </p>
      <p>The <code>cocoon</code> object also provides the following functions:</p>
      <p>
      <code>[Boolean] process([String] uri, [Object] bizData, [java.io.OutputStream]
stream)</code></p>
      <p>
       Call the Cocoon sitemap for the given URI, sending the output of the
       eventually matched pipeline to the specified outputstream.</p>
      <p><code>uri</code> is the URI for which the request should be generated.</p>
      <p><code>bizData</code> is the business data object
       to be made available to the forwarded pipeline</p>
       <p><code>stream</code> is an <code>OutputStream</code>
where the output should be written to.</p>
       <p>Returns the result from the Cocoon processor.
       </p>
      
      <p><code>void createSession()</code></p>
      <p>  
         Associate the current set of JavaScript global variables with the user's session.
This means that all invocations from the
         sitemap of a JavaScript function (using the &lt;map:call
         function="..."&gt;), will share global JavaScript variables.
      </p> 
  
      <p>
      <code>void removeSession()</code>
      </p>
      <p>
         Dissociate global JavaScript variables from the user's session.
      </p>
  
      <p><code>void load([String] uri)</code></p>
      <p>
        Load the JavaScript script specified by <code>uri</code>. The Cocoon
       source resolver is used to resolve <code>uri</code>. 
      </p>
  
      </s1>
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/jpath.xml
  
  Index: jpath.xml
  ===================================================================
  <?xml version='1.0' encoding='ISO-8859-1'?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
  "../dtd/document-v10.dtd">
  <document>
  	<header>
  		<title>Advanced Control Flow</title> 
  		<authors>
  			<person name="Christopher Oliver" email="coliver@apache.org" />
  			<person name="Ovidiu Predescu" email="ovidiu@apache.org" />
  		</authors>
  	</header>
  <body>
  	<s1 title="JPath Logic Sheet">
    <p>
  The JPath Logic Sheet is an XSP logic sheet that allows you to access data from a Cocoon
Flowscript in an XSP page and inject it into a Cocoon pipeline. It provides a set of tags
(similar to the those defined by <link href="http://www.w3.org/TR/xslt">XSLT</link>)
that allow you to iterate over Java collections (and Java or JavaScript arrays) and to test
for the presence of optional or alternate bean properties. It is based on <link href="http://jakarta.apache.org/commons/jxpath">Apache
JXPath</link>.
    </p>
  </s1>
  <s1 title ="Tags">
  <p>The JPath tags are defined in the namespace</p>
  <source>
  http://apache.org/xsp/jpath/1.0
  </source>
  <s2 title ="if">
  <p>The <code>if</code> tag allows the conditional execution of its body

  according to value of a <code>test</code> attribute:</p>
  <source>
    &lt;if test="XPathExpression"&gt;
        body
    &lt;/if&gt;
  </source>
  <p>Example:
  <source>
  &lt;jpath:if test="cart/numberOfItems = 0"&gt;
    Your cart is empty
  &lt;/jpath:if&gt;
  </source>
  </p>
  </s2>
  <s2 title ="choose">
  <p>The <code>choose</code> tag performs conditional block execution by
the 
  embedded <code>when</code> sub tags. It renders the body of the first 
  <code>when</code> tag whose <code>test</code> condition evaluates
to true. 
  If none of the <code>test</code> conditions of nested <code>when</code>
tags
  evaluate to <code>true</code>, then the body of an <code>otherwise</code>

  tag is evaluated, if present:</p>
  <source>
   &lt;choose&gt;
     &lt;when test="XPathExpression"&gt;
        body
     &lt;/when&gt;
     &lt;otherwise&gt;
        body
     &lt;/otherwise&gt;
   &lt;/choose&gt;
  </source>
  <p>Example:
  <source>
  &lt;choose&gt;
    &lt;when test="not(user/loggedIn)"&gt;
       You're not logged in
    &lt;/when&gt;
    &lt;otherwise&gt;
       You're already logged in
    &lt;/otherwise&gt;
  &lt;/choose&gt;
  </source>
  </p>
  </s2>
  <s2 title="value-of">
  <p>The <code>value-of</code> tag evaluates an expression and outputs 
  the result of the evaluation:</p>
  <source>
  &lt;value-of select="XPathExpression"/&gt;
  </source>
  <p>Example:
  <source>
  &lt;value-of select="cart/numberOfItems"&gt;
  </source>
  </p>
  </s2>
  <s2 title="for-each">
  <p>The <code>forEach</code> tag allows you to iterate over a collection

  of objects:</p><p>
  <source>
    &lt;forEach select="XPathExpression"&gt;
      body
   &lt;/forEach&gt;
  </source>
  <p>When using XPath expressions within <code>for-each</code> the current
element is the context node and can be referenced with:</p>
  <source>.</source></p>
  <p>Example:
  <source>
  &lt;for-each select="cart/cartItems[position() &lt;= $count]"&gt;
     &lt;td&gt;&lt;value-of select="./productId"&gt;&lt;/td&gt;
  &lt;/forEach&gt;
  </source>
  </p>
  </s2>
  <s2 title="continuation">
  <p>The <code>continuation</code> tag returns the id of the current web
continuation of your Flowscript. You can refer to previous continuations by supplying the
<code>level</code> attribute. Zero is the current level, <code>-1</code>
refers to the previous continuation, and so on.</p>
  <source>
  &lt;continuation [level="Number"]/&gt;
  </source>
  <p>Example:
  <source>
  &lt;xsp:attribute name="action"&gt;"kont/"+&lt;jpath:continuation&gt;&lt;xsp:attribute&gt;
  </source>
  </p>
  </s2>
  </s1>
  </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxtemplate.xml
  
  Index: jxtemplate.xml
  ===================================================================
  <?xml version='1.0' encoding='ISO-8859-1'?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
  "../dtd/document-v10.dtd">
  <document>
  	<header>
  		<title>Advanced Control Flow</title> 
  		<authors>
  			<person name="Christopher Oliver" email="coliver@apache.org" />
  		</authors>
  	</header>
  <body>
  	<s1 title="JXTemplate Generator">
    <p>
  The JXTemplate Generator is a page template processor that allows you to inject data from
Java and JavaScript objects passed by a Cocoon Flowscript into a Cocoon pipeline. It provides
a set of tags (similar to the <link href="http://java.sun.com/products/jsp/jstl/">JSTL</link>
core tags) that allow you to iterate over Java collections (and Java or JavaScript arrays)
and to test for the presence of optional or alternate bean properties, as well as embedded
expressions to specify conditions and to access the properties of objects. The <em>JX</em>Template
Generator gets its name from the embedded expression languages it supports, namely <link
href="http://jakarta.apache.org/commons/jxpath">Apache <em>JX</em>Path</link>
and <link href="http://jakarta.apache.org/commons/jxpath">Apache <em>J</em>e<em>X</em>l</link>.

    </p>
           </s1>
           <s1 title="Expression Languages">
    <p>
  The JXTemplateGenerator supports two embedded expression languages: <link href="http://jakarta.apache.org/commons/jxpath">Jexl</link>
and <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>. Apache
<link href="http://jakarta.apache.org/commons/jxpath">Jexl</link> provides an
extended version of the expression language of the <link href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/JSTL.html">JSTL</link>.
Apache <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link> provides
an interpreter of the <link href="http://www.w3.org/TR/xpath">XPath</link> expression
language that can apply XPath expressions to graphs of Java objects of all kinds: JavaBeans,
Maps, Servlet contexts, DOM etc, including mixtures thereof.
   </p>
    <p>
   Having an embedded expression language allows a page author to access an object using a
simple syntax such as
   </p>
  <source>
   &lt;site signOn="${accountForm.signOn}"&gt;
   </source>
  <p>Embedded Jexl expressions are contained in <source>${}</source></p>
  <p>Embedded JXPath expressions are contained in <source>#{}</source></p>
  <p>The referenced objects may be Java Beans, DOM, JDOM, or JavaScript objects 
  from a Flowscript. In addition the following implicit objects are available as
  both JXPath and Jexl variables in a template:</p>
  <p>
  <dl>
  <dt><code>request</code></dt>
  <dd>The Cocoon current request</dd>
   
  <dt><code>response</code></dt>
  <dd>The Cocoon response associated with the current request</dd>
   
  <dt><code>session</code> </dt>
  <dd>The Cocoon session associated with the current request</dd>
   
  <dt><code>context</code> </dt>
  <dd>The Cocoon context associated with the current request</dd>
   
  <dt><code>parameters</code></dt>
  <dd>Any parameters passed to the generator in the pipeline</dd>
  </dl>
  </p>
  <p>
  Jexl Example:
  <source>
    The content type of the current request is ${request.contentType}
  </source>
  </p>
  <p>
  JXPath Example:
  <source>
    The content type of the current request is #{request/contentType}
  </source>
  </p>
  <p> 
  The current Web Continuation from the Flowscript 
  is also available as a variable named <code>continuation</code>. You would 
  typically access its <code>id</code>:
  <source>
     &lt;form action="${continuation.id}"&gt;
  </source>
  </p>
  <p>You can also reach previous continuations by using the <code>getContinuation()</code>
function:</p>
  <source>
      &lt;form action="${continuation.getContinuation(1).id}" >
  </source>
  <p>or using an XPath expression:</p><p>
  <source>
      &lt;form action="#{getContinuation($continuation)/id}" >
  </source></p>
  </s1>
  <s1 title ="Tags">
  <p>The JXTemplateGenerator tags are defined in the namespace</p>
  <source>
  http://apache.org/cocoon/templates/jx/1.0
  </source>
  <s2 title ="template">
  <p>The <code>template</code> tag defines a new template:</p><source>
     &lt;t:template xmlns:t="http://apache.org/cocoon/templates/jx/1.0"&gt;
         body
     &lt;/t:template&gt;
  </source>
  </s2>
  <s2 title ="import"/>
  <p>The <code>import</code> tag allows you to include another template
within the current template. The content of the imported template is compiled and will be
executed in place of the <code>import</code> tag:</p><source>
     &lt;import uri="URI" [context="Expression"]/&gt;
  </source><p>The Cocoon source resolver is used to resolve <code>uri</code>.
If <code>context</code> is present, then its value is used as the context for
evaluating the imported template, otherwise the current context is used.</p>
  <s2 title ="set">
  <p>The <code>set</code> tag creates a local alias of an object. The <code>var</code>
attribute specifies the name of a variable to assign the object to. The <code>value</code>
attribute specifies the object (defaults to <code>body</code> if not present):</p><source>
     &lt;set var="Name" [value="Value"]&gt;
         [body]
     &lt;/set&gt;
  </source><p>If used within a <code>macro</code> definition (see
below) variables created by <code>set</code> are only visible within the body
of the <code>macro</code>.</p>
  <p>Jexl Example:
  <source>
  &lt;set var="greeting" value="Hello ${user}"/&gt;
  ${greeting}
  </source>
  </p>
  <p>JXPath Example:
  <source>
  &lt;set var="greeting" value="Hello #{user}"/&gt;
  #{$greeting}
  </source>
  </p>
  </s2>
  <s2 title ="if">
  <p>The <code>if</code> tag allows the conditional execution of its body

  according to value of a <code>test</code> attribute:</p>
  <source>
    &lt;if test="Expression"&gt;
        body
    &lt;/if&gt;
  </source>
  <p>Jexl Example:
  <source>
  &lt;if test="${cart.numberOfItems == 0}"&gt;
    Your cart is empty
  &lt;/if&gt;
  </source>
  </p>
  <p>JXPath Example:
  <source>
  &lt;if test="#{cart/numberOfItems = 0}"&gt;
    Your cart is empty
  &lt;/if&gt;
  </source>
  </p>
  </s2>
  <s2 title ="choose">
  <p>The <code>choose</code> tag performs conditional block execution by
the 
  embedded <code>when</code> sub tags. It renders the body of the first 
  <code>when</code> tag whose <code>test</code> condition evaluates
to true. 
  If none of the <code>test</code> conditions of nested <code>when</code>
tags
  evaluate to <code>true</code>, then the body of an <code>otherwise</code>

  tag is evaluated, if present:</p>
  <source>
   &lt;choose&gt;
     &lt;when test="Expression"&gt;
        body
     &lt;/when&gt;
     &lt;otherwise&gt;
        body
     &lt;/otherwise&gt;
   &lt;/choose&gt;
  </source>
  <p>Jexl Example:
  <source>
  &lt;choose&gt;
    &lt;when test="${!user.loggedIn}"&gt;
      &lt;set var="label" value="Log in"&gt;
    &lt;/when&gt;
    &lt;otherwise&gt;
      &lt;set var="label" value="Log out"&gt;
    &lt;/otherwise&gt;
  &lt;/choose&gt;
  </source>
  </p>
  <p>JXPath Example:
  <source>
  &lt;choose&gt;
    &lt;when test="#{not(user/loggedIn)}"&gt;
      &lt;set var="label" value="Log in"&gt;
    &lt;/when&gt;
    &lt;otherwise&gt;
      &lt;set var="label" value="Log out"&gt;
    &lt;/otherwise&gt;
  &lt;/choose&gt;
  </source>
  </p>
  </s2>
  <s2 title="out">
  <p>The <code>out</code> tag evaluates an expression and outputs 
  the result of the evaluation:</p>
  <source>
  &lt;out value="Expression"/&gt;
  </source>
  <p>Jexl Example:
  <source>
  &lt;out value="${cart.numberOfItems}"&gt;
  </source>
  </p>
  <p>JXPath Example:
  <source>
  &lt;out value="#{cart/numberOfItems}"&gt;
  </source>
  </p>
  </s2>
  <s2 title="forEach">
  <p>The <code>forEach</code> tag allows you to iterate over a collection

  of objects:</p><p>
  <source>
    &lt;forEach [var="Name"] [items="Expression"] [begin="NumExpr"] [end="NumExpr"] [step="NumExpr"]&gt;
      body
   &lt;/forEach&gt;
  </source></p>
  <p>The <code>items</code> attribute specifies the list of items to iterate
over. The <code>var</code> attribute specifies the name of a variable to hold
the current item. The <code>begin</code> attribute specifies the element to start
with 
  (<code>0</code> = first item, <code>1</code> = second item, ...).

  If unspecified it defaults to <code>0</code>. The <code>end</code>

  attribute specifies the item to end with (<code>0</code> = first item, 
  <code>1</code> = second item, ...). If unspecified it defaults to the last item
in the list. Every <code>step</code> items are
  processed (defaults to <code>1</code> if <code>step</code> is absent).
Either <code>items</code> or both <code>begin</code> and <code>end</code>
must be present.</p>
  <p>An alternate form of <code>forEach</code> is supported for convenience
when using XPath (since you can specify the selection criteria for the collection using XPath
itself):</p>
  <source>
  &lt;forEach select="XPathExpression"&gt;
    body
  &lt;/forEach&gt;
  </source>
  <p>When using XPath expressions within <code>forEach</code> the current
element is the context node and can be referenced with:</p>
  <source>#{.}</source>
  <p>Jexl Example:
  <source>
  &lt;forEach var="item" items="${cart.cartItems} begin="${start}" end="${count-start}"
step="1""&gt;
     &lt;td&gt;${item.productId}&lt;/td&gt;
  &lt;/forEach&gt;
  </source>
  </p>
  <p>JXPath Example:
  <source>
  &lt;forEach items="#{cart/cartItems[position() &lt;=$count]}}&gt;
     &lt;td&gt;#{./productId}&lt;/td&gt;
  &lt;/forEach&gt;
  </source>
  </p>
  </s2>
  <s2 title="macro"> 
  <p>The <code>macro</code> tag allows you define a new custom tag.</p><source>
  &lt;macro name="Name" [targetNamespace="Namespace"]&gt;
    &lt;parameter name="Name" [optional="Boolean"] [default="Value"]/&gt;
    body
  
  &lt;/macro&gt;
  </source>
   <p> For example:</p><source>
  &lt;c:macro name="d"&gt;
    &lt;tr&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;
  &lt;/c:macro&gt;
  </source>
  <p>The tag being defined in this example is <code>&lt;d&gt;</code>
and it 
  can be used like any other tag:</p><source>
    &lt;d/&gt;
  </source>
  <p>However, when this tag is used it will be replaced with a row containing a single
empty data cell.</p>
  <p> When such a tag is used, the attributes and content of the tag become available
as variables in the body of the <code>macro</code>'s definition, for example:</p><source>
  &lt;c:macro name="tablerows"&gt;
    &lt;c:parameter name="list"/&gt;
    &lt;c:parameter name="color"/&gt;
    &lt;c:forEach var="item" items="${list}"&gt;
      &lt;tr&gt;&lt;td bgcolor="${color}"&gt;${item}&lt;/td&gt;&lt;/tr&gt;
    &lt;/c:forEach&gt;
  &lt;/c:macro&gt;
  </source>
  <p>The <code>parameter</code> tags in the macro definition define formal
parameters, which are replaced with the actual attribute values of the tag when it is used.
The content of the tag is also available as a special variable <code>${content}</code>.</p><p>Assuming
you had this code in your flowscript:</p><p>
     <code>var greatlakes = ["Superior", "Michigan", "Huron", "Erie", "Ontario"];</code></p><p><code>
sendPage(uri, {greatlakes: greatlakes});</code>
  </p><p>and a template like this:</p><source>
  &lt;table&gt;
     &lt;tablerows list="${greatlakes}" color="blue"/&gt;
  &lt;/table&gt;
  </source>
  <p>When the <code>tablerows</code> tag is used in this situation the following
output would be generated:
  </p>
   <source>
  &lt;table&gt;
    &lt;tr&gt;&lt;td bgcolor="blue"&gt;Superior&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor="blue"&gt;Michigan&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor="blue"&gt;Huron&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor="blue"&gt;Erie&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor="blue"&gt;Ontario&lt;/td&gt;&lt;/tr&gt;
  &lt;/table&gt;
  </source>
  </s2>
  </s1>
  </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/sitemap.xml
  
  Index: sitemap.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Advanced Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
        <person name="Christopher Oliver" email="coliver@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="Sitemap">
      <p>The Cocoon sitemap includes several elements to specify interactions with your
Flowscripts</p>
        <s2 title="flow">
       <p>The <code>flow</code> element defines a Flowscript interpreter
for a sitemap. The <code>language</code> attribute specifies the target programming
language. Currently the only supported language is <code>"JavaScript"</code>.
Its embedded <code>script</code> elements allow you to specify the files that
make up the flow for this sitemap. Each <code>script</code> element specifies
the URI of a script that will be compiled and executed when this Sitemap is created. The <code>src</code>
attribute specifies the URI of the script.</p><p>
        <source><![CDATA[
          <map:flow language="Language">
             <map:script src="URI"/>+
          </map:flow>
        ]]></source>
      </p>
        </s2>
        <s2 title="call">
       <p>The <code>call</code> element allows you to call a top-level function
in your Flowscript or to invoke an existing continuation.</p>
        <p>If the <code>function</code> attribute is present, then the Sitemap
will invoke a top-level function defined in your Flowscript. The <code>function</code>
attribute specifies the name of the function. Zero or more nested <code>parameter</code>
elements may be provided to pass arguments to the function.</p>
        <p>
        <source><![CDATA[
          <map:call function="FunctionName">
             <map:parameter name="Name" value="Value"/>*
          </map:call>
        ]]></source>
        </p>
        <p>If the <code>continuation</code> attribute is present, then the
Sitemap will invoke an existing continuation of your Flowscript. The <code>continuation</code>
attribute specifies the unique id of the continuation.</p>
        <p>
        <source><![CDATA[
          <map:call continuation="Id"/>
        ]]></source>
        </p>
        </s2>
      </s1>
  
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/using.xml
  
  Index: using.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Advanced Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
      </authors>
    </header>
  
    <body>
    <s1 title="Using Cocoon's Control Flow">
    <p>
      The general flow of actions in an application which uses the control flow
      is as described below.
    </p>
   
    <p>
      The request is received by Cocoon and passed to the sitemap for
      processing. In the sitemap, you can do two things to pass the control to
      the Control Flow layer:
      <ul>
        <li>
          You can invoke a JavaScript top-level function to start processing a
          logically grouped sequences of pages. Each time a response page is
          being sent back to the client browser from this function, the
          processing of the JavaScript  code stops at the point the page is
          sent back, and the HTTP request finishes. Through the magic of
          continuations, the execution state is saved in a continuation object.
          Each continuation is given a unique string id, which could be embedded
          in generated page, so that you can restart the saved computation later
          on.
        </li>
        <li>
          To invoke a top level JavaScript function in the Control Flow, you use
          the <code>&lt;map:call&nbsp;function="function-name"/&gt;</code>
          construction.
        </li>
        <li>
          To restart the computation of a previously stopped function, you use
          the <code>&lt;map:continue&nbsp;with="..."/&gt;</code> construction.
          This restarts the computation saved in a continuation object
          identified by the string value of the <code>with</code> attribute.
          This value could be extracted in the sitemap from the requested URL,
          from a POST or GET parameter etc. When the computation stored in the
          continuation object is restarted, it appears as if nothing happened,
          all the local and global variables have exactly the same values as
          they had when the computation was stopped.
        </li>
      </ul>
    </p>
   
    <p>
      Once the JavaScript function in the control layer is restarted, you're
      effectively inside the Control Flow. Here you have access to the request
      parameters, and to the business logic objects. The controller script
      takes the appropriate actions to invoke the business logic, usually
      written in Java, creating objects, setting various values on them etc...
    </p>
   
    <p>
      When the business logic is invoked, you're inside the Model. The business
      logic takes whatever actions are needed, accessing a database, making a
      SOAP request to a Web service etc. When this logic finishes, the program
      control goes back to the Control Flow.
    </p>
   
    <p>
      Once here, the Control Flow has to decide which page needs to be sent back
      to the client browser. To do this, the script can invoke either the
      <code>sendPage</code> or the <code>sendPageAndContinue</code>
functions.
      These functions take two parameters, the relative URL of the page to be
      sent back to the client, and a context object which can be accessed
      inside this page to extract various values and place them in the
      generated page.
    </p>
   
    <p>
      The second argument to <code>sendPage</code> and
      <code>sendPageAndContinue</code> is a context object, which can be a
      simple dictionary with values that need to be displayed by the View. More
      generally any Java or JavaScript object can be passed here, as long as
      the necessary get methods for the important values are provided.
    </p>
   
    <p>
      The page specified by the URL is processed by the sitemap, using the
      normal sitemap rules. The simplest case is an XSP generator followed by
      an XSLT transformation and a serializer. This page generation is part of
      the View layer. If an XSP page is processed, you can make use of several
      Cocoon generators to retrieve values from the context objects passed by the
      Control Flow.
    </p>
   
    <p>
      Going back to the <code>sendPage</code> and
      <code>sendPageAndContinue</code> functions, there is a big difference
      between them. The first function will send the response back to the
      client browser, and will stop the processing of the JavaScript script by
      saving it into a continuation object. The other function,
      <code>sendPageAndContinue</code> will send the response, but it will not
      stop the computation. This is useful for example when you need to exit a
      top-level JavaScript function invoked with
      <code>&lt;map:call&nbsp;function="..."/&gt;</code>.
    </p>
   
    <p>
      The above explains how MVC could be really achieved in Cocoon with the
      control flow layer. Note that there is no direct communication between
      Model and View, everything is directed by the Control Flow by passing to
      View a context object constructed from Model data. In a perfect world,
      XSP should have only one logicsheet, the JXPath logicsheet. There should
      be no other things in an XSP page that put logic in the page (read View),
      instead of the Model. If you don't like XSP, and prefer to use JSP or
      Velocity, the JXPath logicsheet equivalents should be implemented.
    </p>
   
    <h4>Basic usage</h4>
   
    <p>
      As hinted in the previous section, an application using Cocoon's MVC
      approach is composed of three layers:
      <ul>
        <li>
          A JavaScript controller which implements the interaction with the
          client
        </li>
        <li>
         The business logic model which implements your application
        </li>
        <li>
          The XSP pages, which describe the content of the pages, and XSLT
          stylesheets which describe the look of the content.
        </li>
      </ul>
    </p>
   
    <p>
      In more complex applications, the flow of pages can be thought of smaller
      sequences of pages which are composed together. The natural analogy is to
      describe these sequences in separate JavaScript functions, which can then
      be called either from the sitemap, can call each other freely.
    </p>
   
    <p>
      An example of such an application is the user login and preferences
      sample 
    </p>
   
    <p>
      This application is composed of four top-level JavaScript functions:
      <ul>
        <li><code>login</code>,</li>
        <li><code>registerUser</code>,</li>
        <li><code>edit</code> and</li>
        <li><code>logout</code>.</li>
      </ul>
    </p>
   
    <p>
      The entry level point in the application can be any of these functions,
      but in order for a user to use the application, (s)he must login first.
      Once the user logs in, we want to maintain the Java User object which
      represents the user between top-level function invocations.
    </p>
   
    <p>
      If the script does nothing, each invocation of a top-level function
      starts with fresh values for the global variables, no global state is
      preserved between top-level function invocations from the sitemap. In
      this sample for example, the <code>login</code> function assigns to the
      global variable <em>user</em> the Java User object representing the
      logged in user. The <code>edit</code> function trying to operate on this
      object would get a null value instead, because the value is not shared by
      default between these top-level function invocations.
    </p>
   
    <p>
      To solve the problem, the <code>login</code> and
      <code>registerUser</code> functions have to call the
      <code>cocoon.createSession()</code> method, which creates a servlet
      session and saves the global scope containing the global variables' value
      in it. Next time the user invokes one of the four top-level functions,
      the values of the global variables is restored, making sharing very easy.
    </p>
   
    <p>
      Even if you don't need complex control flow in your application, you may
      still choose to use the MVC pattern described above. You can have top-
      level JavaScript functions which obtain the request parameters, invoke
      the business logic and then call <code>sendPageAndContinue</code> to
      generate a response page and return from the computation. Since there's
      no continuation object being created by this function, and no global
      scope being saved, there's no memory resource being eaten. The approach
      provides a clean way of separating logic and content, and makes things
      easy to follow, since you have to look at a single script to understand
      what's going on.
    </p>
      </s1>
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/velocity.xml
  
  Index: velocity.xml
  ===================================================================
  <?xml version='1.0' encoding='ISO-8859-1'?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
  "../dtd/document-v10.dtd">
  <document>
  	<header>
  		<title>Advanced Control Flow</title> 
  		<authors>
  			<person name="Christopher Oliver" email="coliver@apache.org" />
  			<person name="Ovidiu Predescu" email="ovidiu@apache.org" />
  		</authors>
  	</header>
  <body>
  	<s1 title="Velocity Generator">
    <p>
  If called from a Flowscript, the Cocoon <link href="http://jakarta.apache.org/velocity">Velocity</link>
Generator provides access to the immediate properties of the context object passed to <code>sendPage</code>
and <code>sendPageAndWait</code>. In that case, the current <code>WebContinuation</code>
is also available as a variable named <code>$continuation</code>
   You would 
  typically access its <code>id</code>:
  <source>
  <p><pre>
     &lt;form action="$continuation.id"&gt;
  </pre></p>
  </source>
  <p>You can also reach previous continuations by using the <code>getContinuation()</code>
function:</p>
  <source>
  <p><pre>
      &lt;form action="$continuation.getContinuation(1).id" &gt;
  </pre></p>
  </source>
  
  In addition the following implicit objects are always available in
  the Velocity context:
  <p>
  <dl>
  <dt><code>request</code> (<code>org.apache.cocoon.environment.Request</code>)</dt>
  <dd>The current Cocoon request</dd>
  
  <dt><code>response</code> (<code>org.apache.cocoon.environment.Response</code>)</dt>
  <dd>The Cocoon response associated with the current request</dd>
  
  <dt><code>session</code> (<code>org.apache.cocoon.environment.Session</code>)</dt>
  <dd>The Cocoon session associated with the current request</dd>
  
  <dt><code>context</code> (<code>org.apache.cocoon.environment.Context</code>)</dt>
  <dd>The Cocoon context associated with the current request</dd>
  
  <dt><code>parameters</code> (<code>org.apache.avalon.framework.parameters.Parameters</code>)</dt>
  <dd>Any parameters passed to the generator in the pipeline</dd>
  </dl>
  </p>
    </p>
  </s1>
  </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/views.xml
  
  Index: views.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Advanced Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
        <person name="Christopher Oliver" email="coliver@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="Flowscript-aware Generators">
  <p>
  The second argument to <code>sendPage</code> and <code>sendPageAndWait</code>
is a context object, which can be a simple dictionary with values that need to be displayed
by the View. More generally any Java or JavaScript object can be passed here, as long as the
necessary get methods for the important values are provided.
  </p>
  <p>
  The page specified by the URL is processed by the sitemap, using the normal sitemap rules.
  </p>
  <p>
  Several generators are provided that allow you to access the context object and inject its
values into a pipeline.
  </p>
      </s1>
  
    </body>
  </document>
  
  
  

Mime
View raw message