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 jxforms.xml jxtemplate.xml velocity.xml woody.xml
Date Mon, 14 Jul 2003 01:00:16 GMT
coliver     2003/07/13 18:00:16

  Modified:    src/documentation/xdocs/userdocs/flow jxforms.xml
                        jxtemplate.xml velocity.xml woody.xml
  Log:
  More docs (still incomplete though)
  
  Revision  Changes    Path
  1.3       +197 -51   cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxforms.xml
  
  Index: jxforms.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxforms.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- jxforms.xml	13 Jul 2003 19:53:14 -0000	1.2
  +++ jxforms.xml	14 Jul 2003 01:00:15 -0000	1.3
  @@ -14,8 +14,19 @@
      <link href="http://www.w3.org/DOM/">XML/DOM</link>, 
      <link href="http://www.jdom.org/">JDOM</link>,
      <link href="http://jakarta.apache.org/commons/beanutils/api/org/apache/commons/beanutils/DynaBean.html">DynaBeans</link>,
and JavaScript objects.
  +    </p>
   		
  -   </p>
  +  <s2 title="Table of Contents">
  +   <p><link href="#Overview">Overview</link></p>
  +   <p><link href="#Sitemap">Sitemap</link></p>
  +   <p><link href="#Controls">Form Controls</link></p>
  +   <p><link href="#JSAPI">JavaScript API</link></p>
  +   <p><link href="#Validation">Validation</link></p>
  +   <p><link href="#HTML">Conversion to HTML</link></p>
  +  </s2>
  +  </s1>
  +  <s1 title="Overview"><anchor id="Overview"/>
  +
   <p>W3C XForms defines a device-neutral, platform-independent set of
   form controls suitable for general-purpose use. JXForms supports a subset of these controls.
The controls are
   bound to a <em>model</em> provided by your Flowscript via <link href="http://www.w3.org/TR/xpath">XPath</link>
expressions, for example in this simple case using the <code>ref</code> attribute
  @@ -44,11 +55,11 @@
     &lt;label&gt;Expiration Date&lt;/label&gt;
   
   &lt;/input&gt;
  -&lt;submit submission="submit"&gt;
  +&lt;submit id="submit" continuation="forward"&gt;
     &lt;label&gt;Submit&lt;/label&gt;
   &lt;/submit&gt;</source>
     <p>
  -  In your Flowscript you would supply an appropriate model, for example, like this:</p>
  +  In your Flow script you would supply an appropriate model, for example, like this:</p>
      <p><source>
         var model = {
            method: "cash",
  @@ -56,8 +67,12 @@
            expiry: ""
         }
      </source></p>
  -  <p>
  -  Upon submission of the form the model will be updated accordingly, and you can take action
in your script based on its values:
  +   <p>
  +   Since JXForms uses <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>,
your model may consist of any objects that <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>
supports.
  +   </p>
  +   <p>
  +   Use the <code>setModel()</code> function of the form to associate your model
with the form. Then use the <code>sendView()</code> function of the form to display
it.
  +  Upon submission of the form, the model will be automatically updated and you can take
action in your script based on its values:
     </p>
      <p><source>
         var model = {
  @@ -76,101 +91,226 @@
             ....
         } 
      </source></p>
  -   <p>
  -   Since JXForms uses <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>,
your model may consist of any objects that <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>
supports.
  -   </p>
      <p> 
  -   JXForms also supports declarative validation of form elements using Schematron, and
automated support for back/forward navigation in multi-page forms using continuations.
  +   JXForms also supports declarative <link href="#validation">validation</link>
of form elements using Schematron, and automated <link href="#backNext">support</link>
for back/forward navigation in multi-page forms using continuations.
      </p>
     </s1>
   
  - <s1 title="Form Controls">
  + <s1 title="Sitemap"><anchor id="Sitemap"/>
  +<p>To use JXForms, you will need to add several elements to your Cocoon <link
href="../concepts/sitemap.html">Sitemap</link>, namely the JXForms generator, and
several XSLT stylesheets. To use the JXForms generator, add a generator entry to your Sitemap
with the <code>src</code> attribute set to <code>org.apache.cocoon.generation.JXFormsGenerator</code>,
for example like this:</p>
  +<source>
  +&lt;map:generators&gt;
  +  &lt;map:generator label="content,data" 
  +      logger="sitemap.generator.jxforms" name="jxforms" 
  +         src="org.apache.cocoon.generation.JXFormsGenerator"/&gt;
  +&lt;/map:generators&gt;
  + </source>
  + <p>To invoke your form use the Sitemap's <code>&lt;map:call&gt;</code>
operation to invoke the <code>jxForm</code> Flowscript function, for example like
this:</p>
  +<source><![CDATA[
  +   <map:match pattern="feedBackWizard">
  +     <map:call function="jxForm">
  +        <map:parameter name="function" value="{1}"/>
  +        <map:parameter name="id" value="form-feedback"/>
  +        <map:parameter name="validator-schema-namespace" value="http://www.ascc.net/xml/schematron"/>
  +        <map:parameter name="validator-schema" value="schematron/wizard-xmlform-sch-report.xml"/>
  +     </map:call>
  +   </map:match>
  +]]></source>
  +
  +  <p>
  +  </p>
  + </s1>  
  + <s1 title="Form Controls"><anchor id="Controls"/>
    <p>The JXForms tags are defined in the following namespace:</p>
    <source>http://apache.org/cocoon/jxforms/1.0</source>
    <p>JXForms supports the following controls:</p>
    <s2 title="form">
  - <p/>
  + <p>The JXForms <code>&lt;form&gt;</code> element represents
the overall form. It also corresponds to a validation <em>phase</em> in your <link
href="#Validation">validation</link> rules. It has no direct counterpart in W3C XForms.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +  <xf:form id="form-feedback" view="userIdentity">
  +    <xf:label>Personal Information</xf:label>
  +    <error>
  +      <xf:violations class="error"/>
  +    </error>
  +    <xf:input ref="/firstName">
  +      <xf:label>First Name</xf:label>
  +      <xf:violations class="error"/>
  +    </xf:input>
  +  </xf:form>
  +      ]]></source> 
  + <p></p>
  + <p>It supports the following attributes:</p>
  + <ul>
  +   <li><code>id</code></li>
  +   <li><code>view</code></li>
  + </ul>
  + <p>
  + The <code>id</code> attribute must match the <code>id</code> Sitemap
parameter passed to the <code>jxForm</code> function in <code>&lt;map:call&gt;</code>.
The <code>view</code> attribute must match the <code>id</code> of
a <code>&lt;phase&gt;</code> element in your Schematron validation rules.
  + </p>
  + </s2>
  + <s2 title="error">
  + <p>JXForms <code>&lt;error&gt;</code> has no counterpart in
W3C XForms. If present under the <code>form</code> element it serves as a placeholder
for validation error messages associated with the entire form.
  + </p>
  + </s2>
  + <s2 title="violations">
  + <p>JXForms <code>&lt;violations&gt;</code> element has no counterpart
in W3C XForms.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  + </s2>
  + <s2 title="violation">
  + <p>JXForms <code>&lt;violation&gt;</code> element has no counterpart
in W3C XForms.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
    </s2>
    <s2 title="input">
  + <p>JXForms <code>&lt;input&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice8.html#ui-input">input</link> element.
It allows the user to do free-form data entry.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  + <p>It supports the following attributes:</p>
  + <ul>
  +   <li><code>ref</code></li>
  +   <li><code>appearance</code></li>
  +   <li><code>class</code></li>
  + </ul>
    <p/>
    </s2>
    <s2 title="secret">
  + <p>JXForms <code>&lt;secret&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice8.html#ui-secret">secret</link> element.
It is is used for entering information that is considered sensitive, and thus not echoed to
a visual or aural display as it is being entered, e.g., password entry. </p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  +<p>It supports the following attributes:</p>
  +
  + <ul>
  +   <li><code>ref</code></li>
  +   <li><code>appearance</code></li>
  +   <li><code>class</code></li>
  + </ul>
    <p/>
    </s2>
    <s2 title="textarea">
  + <p>JXForms <code>&lt;textarea&gt;</code> is based on the W3C
XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-textarea">textarea</link>
element. </p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  + <p>It supports the following attributes:</p>
  + <ul>
  +   <li><code>ref</code></li>
  +   <li><code>appearance</code></li>
  + </ul>
    <p/>
    </s2>
    <s2 title="output">
  - <p/>
  + <p>JXForms <code>&lt;output&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice8.html#ui-output">output</link> element.
It is used to display values from the model, but provides no means to enter or modify those
values.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  + <p>It supports the following attributes:</p>
  + <ul>
  +   <li><code>ref</code></li>
  +   <li><code>value</code></li>
  +   <li><code>appearance</code></li>
  +   <li><code>class</code></li>
  + </ul>
    </s2>
    <s2 title="select">
      <p>
       </p>
  - <p>JXForms <code>&lt;select&gt;</code> is modelled after the
<link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectMany">W3C XForms &lt;select&gt;</link>
element. It supports the following attributes:</p>
  + <p>JXForms <code>&lt;select&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectMany">select</link>
element. </p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  +
  +<p>It supports the following attributes:</p>
    <ul>
      <li><code>ref</code></li>
  -   <li><code>id</code></li>
      <li><code>appearance</code></li>
  +   <li><code>class</code></li>
    </ul>
    </s2>
    <s2 title="select1">
  + <p>JXForms <code>&lt;select&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectOne">select1</link>
element. It supports the following attributes:</p>
  + <ul>
  +   <li><code>ref</code></li>
  +   <li><code>appearance</code></li>
  +   <li><code>class</code></li>
  + </ul>
    <p/>
    </s2>
    <s2 title="submit">
  - <p>JXForms <code>&lt;submit&gt;</code> differs from that of
W3C XForms. It supports the following attributes:</p>
  + <p>JXForms <code>&lt;submit&gt;</code> differs from <link
href="http://www.w3.org/TR/xforms/slice8.html#ui-submit">that</link> of W3C XForms.
</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  +
  +<p>It supports the following attributes:</p>
    <ul>
      <li><code>id</code></li>
      <li><code>continuation</code></li>
      <li><code>class</code></li>
    </ul>
  - <p>Example: Submit
  - </p>
  -<source>
  -&lt;submit submission="timecard"&gt;
  -  &lt;label&gt;Submit Timecard&lt;/label&gt;
  -&lt;/submit&gt;
  -</source>
    <p>
    </p>
   </s2>
    <s2 title="group">
  - <p/>
  + <p>JXForms <code>&lt;group&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice9.html#ui-group">group</link> element.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  +
  + <p>It supports the following attributes:</p>
  + <ul>
  +   <li><code>ref</code></li>
  +   <li><code>class</code></li>
  + </ul>
  + <p>
  +  The value of the <code>ref</code> attribute of a <code>&lt;group&gt;</code>
is the context node for evaluting relative paths of the <code>ref</code> attributes
of its sub-elements.
  + </p>
    </s2>
    <s2 title="repeat">
  + <p>JXForms <code>&lt;repeat&gt;</code> is based on the W3C XForms
<link href="http://www.w3.org/TR/xforms/slice9.html#ui-repeat">repeat</link> element.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  +<p> It supports the following attributes:</p>
  + <ul>
  +   <li><code>nodeset</code></li>
  + </ul>
    <p/>
    </s2>
    <s2 title="itemset">
  + <p>JXForms <code>&lt;itemset&gt;</code> is based on the W3C
XForms <link href="http://www.w3.org/TR/xforms/slice9.html#ui-common-elements-itemset">itemset</link>
element. It is used for the dynamic creation of selections within the <code>select</code>
and <code>select1</code> elements.</p>
  + <p>Example:</p>
  +      <source><![CDATA[
  +      ]]></source> 
  + <p></p>
  +<p> It supports the following attributes:</p>
  + <ul>
  +   <li><code>nodeset</code></li>
  + </ul>
    <p/>
    </s2>
    </s1>  
  - <s1 title="Sitemap">
  -<p>To use the JXForms, you will need to add several elements to your <link href="../concepts/sitemap.html">Sitemap</link>,
namely the JXForms generator, and several XSLT stylesheets. To use the JXForms generator add
a generator entry to your Sitemap with the <code>src</code> attribute set to <code>org.apache.cocoon.generation.JXFormsGenerator</code>,
for example like this:</p>
  -<source>
  -&lt;map:generators&gt;
  -  &lt;map:generator label="content,data" 
  -      logger="sitemap.generator.jxforms" name="jxforms" 
  -         src="org.apache.cocoon.generation.JXFormsGenerator"/&gt;
  -&lt;/map:generators&gt;
  - </source>
  - <p>To invoke your form you use the Sitemap's <code>&lt;map:call&gt;</code>
operation to invoke the <code>jxForm</code> Flowscript function, for example like
this:</p>
  -<source><![CDATA[
  -   <map:match pattern="feedBackWizard">
  -     <map:call function="jxForm">
  -        <map:parameter name="function" value="{1}"/>
  -        <map:parameter name="id" value="form-feedback"/>
  -        <map:parameter name="validator-schema-namespace" value="http://www.ascc.net/xml/schematron"/>
  -        <map:parameter name="validator-schema" value="schematron/wizard-xmlform-sch-report.xml"/>
  -     </map:call>
  -   </map:match>
  -]]></source>
  -
  -</s1>  
  - <s1 title="Flowscript">
  + <s1 title="JavaScript API"><anchor id="JSAPI"/>
     <p>
  -  JXForms provides a JavaScript <code>JXForm</code> object that provides methods
for you to manage your form's <em>model</em> and to invoke its associated <em>view</em>
and any validation you've specified.
  +  JXForms provides a JavaScript <code>JXForm</code> object that provides methods
for you to manage your form's <em>model</em> and to invoke its associated <em>view</em>
and any validation rules you've specified.
     </p>
     <p>
  -  To use JXForms in a Flowscript you must load <code>JXForm.js</code> into
your script and define a function that takes at one argument (the argument passed to your
function will be a JavaScript representation of your form), for example like this:</p>
  +  To use JXForms in a Flowscript you must load <code>resource://org/apache/cocoon/components/flow/javascript/JXForm.js</code>
into your script and define a function that takes one argument (the argument passed to your
function will be a JavaScript representation of your form), for example like this:</p>
     <source>
   
       cocoon.load("resource://org/apache/cocoon/components/flow/javascript/JXForm.js");
  @@ -178,8 +318,9 @@
       function myFormHandler(form) {
          ...
       }
  -
     </source>
  +  <p>
  +  </p>
     <s2 title="JXForm Object">
     <p>
       The <code>JXForm</code> object passed to your function has the following
properties and functions:</p>
  @@ -243,9 +384,14 @@
       </s3>
     </s2>
    </s1>  
  - <s1 title="Validation">
  + <s1 title="Validation"><anchor id="Validation"/>
  + <p>
  + JXForms provides declarative form validation using the <link href="http://www.ascc.net/xml/resource/schematron/Schematron2000.html">Schematron</link>
assertion language. Since Schematron is also based on XPath, you use the same expressions
to reference your model in your validation rules as in your forms. In addition, because JXForms
implements Schematron using <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>,
you can make assertions about Java and JavaScript objects in your validation rules as well
as about XML documents.
  + </p>
    </s1>  
  - <s1 title="Stylesheets">
  + <s1 title="Conversion to HTML"><anchor id="HTML"/>
  + <p>For conversion of JXForms controls to XHTML, JXForms provides two XSLT stylesheets
that must be applied to the output of JXFormsGenerator: <code>jxforms-default.xsl</code>
and <code>jxforms2html.xsl</code>. The former performs formatting of validation
error messages. The latter converts the result to XHTML.
  + </p>
    </s1>  
    </body>
   </document>
  
  
  
  1.16      +3 -3      cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxtemplate.xml
  
  Index: jxtemplate.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxtemplate.xml,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- jxtemplate.xml	13 Jul 2003 19:53:14 -0000	1.15
  +++ jxtemplate.xml	14 Jul 2003 01:00:15 -0000	1.16
  @@ -70,13 +70,13 @@
   <source>
      &lt;form action="${continuation.id}"&gt;
   </source>
  -<p>You can also reach previous continuations by using the <code>getContinuation()</code>
function:</p>
  +<p>You can also reach previous continuations by using the <code>getParent()</code>
function:</p>
   <source>
  -    &lt;form action="${continuation.getContinuation(1).id}" >
  +    &lt;form action="${continuation.getParent().id}" >
   </source>
   <p>or using an XPath expression:</p>
   <source>
  -    &lt;form action="#{getContinuation($continuation, 1)/id}" >
  +    &lt;form action="#{getParent($continuation)/id}" >
   </source>
   </s1>
   <s1 title ="Tags">
  
  
  
  1.16      +6 -6      cocoon-2.1/src/documentation/xdocs/userdocs/flow/velocity.xml
  
  Index: velocity.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/velocity.xml,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- velocity.xml	13 Jul 2003 19:53:14 -0000	1.15
  +++ velocity.xml	14 Jul 2003 01:00:15 -0000	1.16
  @@ -22,19 +22,19 @@
      <source>
     &lt;form action="$continuation.id"&gt;
      </source>
  -   <p>You can also reach previous continuations by using the <code>getContinuation()</code>
function:</p>
  +   <p>You can also reach previous continuations by using the <code>getParent()</code>
function:</p>
      <source>
  -  &lt;form action="$continuation.getContinuation(1).id" &gt;
  +  &lt;form action="$continuation.getParent().id" &gt;
      </source>
      <p>In addition the following implicit objects are always available in the Velocity
context:</p>
      <dl>
  -    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Request.html">org.apache.cocoon.environment.Request</link>
<code>$request</code> </dt>
  +    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Request.html">Request</link>
<code>$request</code> </dt>
       <dd>The current Cocoon request</dd>
  -    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Response.html">org.apache.cocoon.environment.Response</link>
<code>$response</code> </dt>
  +    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Response.html">Response</link>
<code>$response</code> </dt>
       <dd>The Cocoon response associated with the current request</dd>
  -    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Session.html">org.apache.cocoon.environment.Session</link>
<code>$session</code> </dt>
  +    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Session.html">Session</link>
<code>$session</code> </dt>
       <dd>The Cocoon session associated with the current request</dd>
  -    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Context.html">org.apache.cocoon.environment.Context</link>
<code>$context</code> </dt>
  +    <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Context.html">Context</link>
<code>$context</code> </dt>
       <dd>The Cocoon context associated with the current request</dd>
       <dt><code>org.apache.avalon.framework.parameters.Parameters</code>
<code>$parameters</code> </dt>
       <dd>Any parameters passed to the generator in the pipeline</dd>
  
  
  
  1.2       +5 -10     cocoon-2.1/src/documentation/xdocs/userdocs/flow/woody.xml
  
  Index: woody.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/woody.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- woody.xml	13 Jul 2003 00:48:29 -0000	1.1
  +++ woody.xml	14 Jul 2003 01:00:15 -0000	1.2
  @@ -56,6 +56,8 @@
   
   }
   ]]></source>
  +    <p>
  +    </p>
       <s2 title ="The woody function"><anchor id="woody"/>
         <p>The entry point to a Woody form is the <code>woody()</code>
function:
         <p>
  @@ -82,16 +84,9 @@
   parameter, the newly created form.
         </p>
     <p>
  -  To use Woody in a Flowscript you must load <code>woody.js</code> into your
script and define a function that takes one argument (the argument passed to your function
will be a JavaScript representation of your Woody form), for example like this:</p>
  -  <source>
  -
  -    cocoon.load("resource://org/apache/cocoon/components/woody/flow/javascript/woody.js");
  -
  -    function myFormHandler(form) {
  -       ...
  -    }
  -  </source> 
  -  </s2>
  +  To use Woody in a Flowscript you must load <code>woody.js</code> into your
script and define a function that takes one argument (<code>form1</code> in the
example at the top of this page). The argument passed to your function will be a JavaScript
representation of your Woody form.
  +  </p>
  + </s2>
    <s2 title="Form Object">
     <p>
     Woody provides a JavaScript <code>Form</code> object that provides methods
for you to manage your form's <em>model</em> and to invoke its associated <em>view</em>
and any validation you've specified.
  
  
  

Mime
View raw message