cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From br...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/forms api_java.xml api_javascript.xml book.xml eventhandling.xml formsgenerator.xml sample.xml templategenerator.xml templatetransformer.xml validation.xml widget_action.xml widget_aggregatefield.xml widget_booleanfield.xml widget_messages.xml widget_repeater_action.xml widget_row_action.xml widget_submit.xml widget_upload.xml xslt.xml
Date Sat, 24 Apr 2004 12:09:03 GMT
bruno       2004/04/24 05:09:03

  Modified:    src/documentation/xdocs/userdocs/forms book.xml
                        eventhandling.xml formsgenerator.xml sample.xml
                        templategenerator.xml templatetransformer.xml
                        validation.xml widget_action.xml
                        widget_aggregatefield.xml widget_booleanfield.xml
                        widget_messages.xml widget_repeater_action.xml
                        widget_row_action.xml widget_submit.xml
                        widget_upload.xml xslt.xml
  Added:       src/documentation/xdocs/userdocs/forms api_java.xml
                        api_javascript.xml
  Log:
  forms documentation updates
  
  Revision  Changes    Path
  1.4       +11 -1     cocoon-2.1/src/documentation/xdocs/userdocs/forms/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/book.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- book.xml	21 Apr 2004 01:28:58 -0000	1.3
  +++ book.xml	24 Apr 2004 12:09:03 -0000	1.4
  @@ -36,8 +36,8 @@
       <menu-item label="booleanfield" href="widget_booleanfield.html"/>
       <menu-item label="repeater" href="widget_repeater.html"/>
       <menu-item label="output" href="widget_output.html"/>
  -    <menu-item label="action" href="widget_action.html"/>
       <menu-item label="submit" href="widget_submit.html"/>
  +    <menu-item label="action" href="widget_action.html"/>
       <menu-item label="repeater-action" href="widget_repeater_action.html"/>
       <menu-item label="row-action" href="widget_row_action.html"/>
       <menu-item label="aggregatefield" href="widget_aggregatefield.html"/>
  @@ -47,6 +47,7 @@
     
     <menu label="Widget concepts">
       <menu-item label="Validation" href="validation.html"/>
  +    <menu-item label="Event Handling" href="eventhandling.html"/>
       <menu-item label="Datatypes" href="datatypes.html"/>
     </menu>
   
  @@ -59,5 +60,14 @@
   
     <menu label="Binding">
       <menu-item label="Binding Framework" href="binding.html"/>
  +  </menu>
  +
  +  <menu label="API">
  +    <menu-item label="Java" href="api_java.html"/>
  +    <menu-item label="Javascript (Flowscript)" href="api_javascript.html"/>
  +  </menu>
  +
  +  <menu label="Other resources">
  +    <menu-item label="Forms @ Wiki" href="http://wiki.cocoondev.org/Wiki.jsp?page=Forms"/>
     </menu>
   </book>
  
  
  
  1.2       +117 -2    cocoon-2.1/src/documentation/xdocs/userdocs/forms/eventhandling.xml
  
  Index: eventhandling.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/eventhandling.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- eventhandling.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ eventhandling.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,8 +24,123 @@
       </authors>
     </header>
     <body>
  -    <s1 title="coming soon">
  -      <p>coming soon</p>
  +    <s1 title="Intro">
  +      <p>Some types of widgets can emit events. For example, the
  +      action widget produces ActionEvents and the field widget
  +      produces ValueChangedEvents. Next to these events, there are
  +      also processing phase events, fired in between the various
  +      phases of the processing of a request.</p>
  +
  +      <p>Handling events can be done in two ways:</p>
  +
  +      <ul>
  +        <li>by defining event listeners in the form definition (as child
  +        of wd:on-action for the action widget, or wd:on-value-changed for
  +        the field widget, ...). These event listeners will be triggered when
  +        the widget on which they're defined fires an event.</li>
  +        <li>by registering a org.apache.cocoon.woody.event.FormHandler on the
  +        Form object. This FormHandler will receive all events from all widgets.</li>
  +      </ul>
  +
  +      <p>Note that higher-level API's like the flowscript integration might
  +      provide other ways which might be more comfortable to work with in
  +      those environments.</p>
  +    </s1>
  +
  +    <s1 title="When are events processed? (Request processing phases)">
  +      <p>To answer the question "When are events processed?", we have to
  +      look a bit deeper into how a form request is handled. This is separated
  +      in a couple of phases, more specifically the following ones:</p>
  +
  +      <ul>
  +        <li>Any outstanding events are broadcasted to the event listeners.<br/>
  +        The reason this is done is because events might have been collected while
  +        the form was loaded with values by the binding framework.</li>
  +        <li>ProcessingPhaseListeners are informed that the <code>LOAD_MODEL</code>
phase has ended.</li>
  +        <li>All widgets in the widget tree read their value from the request.
  +        If a widget decides it has to produce an event, it is added to a global
  +        (i.e. form-level) list (but not yet executed).</li>
  +        <li>Once all widgets had the opportunity to read their value from the request,
  +        the events are broadcasted to the event listeners. This assures that event
  +        listeners have access to the values of all widgets in the tree.</li>
  +        <li>ProcessingPhaseListeners are informed that the <code>READ_FROM_REQUEST</code>
phase has ended.</li>
  +        <li>It is possible that processing ends now. This usually happens when
  +        an action widget has caused an event.</li>
  +        <li>All widgets in the widget tree validate themselves.</li>
  +        <li>ProcessingPhaseListeners are informed that the <code>VALIDATE</code>
phase has ended.</li>
  +      </ul>
  +    </s1>
  +
  +    <s1 title="Recursive event loops">
  +      <p>Event listeners themselves might call methods on widgets which cause
  +      new events to be generated. You have to be careful not to cause recursive
  +      event loops by doing this.</p>
  +
  +      <p>For example, calling setValue on a widget
  +      in a ValueChangedEvent caused by that widget will schedule a new ValueChangedEvent,
  +      which will then again cause the execution of the event listener
  +      which will then again call setValue and thus again cause a new event
  +      to be generated, and so on.</p>
  +    </s1>
  +
  +    <s1 title="Defining event handlers in the form definition">
  +      <p>Event handlers can be specified as part of the form definition, as child
  +      of the various wd:on-xxx elements, such as wd:on-action for the action widget.</p>
  +
  +      <p>Event handlers can be written in either javascript or java.
  +      The form definition syntax is as follows:</p>
  +
  +      <source><![CDATA[<fd:on-xxxx>
  +  <javascript>
  +    ... some inline javascript code ...
  +  </javascript>
  +  <java class="..."/>
  +</fd:on-xxxx>]]></source>
  +
  +      <p>You can specify as many <code>&lt;javascript&gt;</code>
and/or
  +      <code>&lt;java&gt;</code> event listeners as you want.</p>
  +
  +      <s2 title="Javascript event listeners">
  +        <p>Objects available in the Javascript snippet:</p>
  +        <ul>
  +          <li><code>event</code>: a subclass of WidgetEvent. The reference
documentation
  +          of the individual widgets mentions which WidgetEvent subclass they provide
  +          in their events. You can then check the javadoc for those classes to see
  +          what they provide.</li>
  +          <li><code>viewData</code>: any data that is normally passed
from the flowlayer
  +          to the view (pipeline). Exact contents depends on which flowscript API version
you use.</li>
  +          <li>if the form processing was started from a flowscript, then everything
  +          available from the scope of that flowscript, such as global variables,
  +          functions and the <code>cocoon</code> object (see also
  +          <link href="../flow/api.html">Flow Object Model</link>).</li>
  +        </ul>
  +
  +        <note>It does not make sense to create continuations from the Javascript
event
  +        handler. In other words, do not call cocoon.sendPageAndWait or form.showForm
  +        from there.</note>
  +      </s2>
  +
  +      <s2 title="Java event listeners">
  +        <p>The Java class specified in the class attribute on the java element should
  +        implement a certain event listener interface. Which interface depends on the type
of widget.
  +        See the documentation of the individual widgets for more information.</p>
  +      </s2>
  +    </s1>
  +
  +    <s1 title="Handling events using the FormHandler">
  +      <p>To handle events using a FormHandler, write a class implementing the following
interface:</p>
  +
  +      <source><![CDATA[org.apache.cocoon.woody.event.FormHandler]]></source>
  +
  +      <p>Alternatively you can extend from the following abstract class:</p>
  +
  +      <source><![CDATA[org.apache.cocoon.woody.event.AbstractFormHandler]]></source>
  +
  +      <p>which will split ActionEvents and ValueChangedEvents to two different methods.
  +      See the javadocs of these interfaces and classes for more details.</p>
  +
  +      <p>Once you created the FormHandler, register it on a form instance by calling
  +      the method setFormHandler(FormHandler formHandler) on it.</p>
       </s1>
     </body>
   </document>
  
  
  
  1.2       +3 -2      cocoon-2.1/src/documentation/xdocs/userdocs/forms/formsgenerator.xml
  
  Index: formsgenerator.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/formsgenerator.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- formsgenerator.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ formsgenerator.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,8 +24,9 @@
       </authors>
     </header>
     <body>
  -    <s1 title="Introduction">
  -      <p>TO BE DONE</p>
  +    <s1 title="Concept">
  +      <p>The FormsGenerator is a Cocoon generator that generates an XML
  +      representation of a form instance object.</p>
       </s1>
     </body>
   </document>
  
  
  
  1.3       +2 -0      cocoon-2.1/src/documentation/xdocs/userdocs/forms/sample.xml
  
  Index: sample.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/sample.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- sample.xml	17 Apr 2004 18:29:28 -0000	1.2
  +++ sample.xml	24 Apr 2004 12:09:03 -0000	1.3
  @@ -196,6 +196,8 @@
       cocoon.sendPage("registration-success-pipeline", bizdata);
   }]]></source>
   
  +      <note>This sample still shows the "old" flowscript API. Will be updated eventually.</note>
  +
         <p>The flowscript works as follows:</p>
   
         <p>First we create a Form object, specifying the form definition file to be
used.
  
  
  
  1.2       +22 -4     cocoon-2.1/src/documentation/xdocs/userdocs/forms/templategenerator.xml
  
  Index: templategenerator.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/templategenerator.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- templategenerator.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ templategenerator.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -18,16 +18,34 @@
   
   <document>
     <header>
  -    <title>Apache Cocoon Forms: Template Generator</title>
  +    <title>Cocoon Forms: Template Generator</title>
       <authors>
         <person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
       </authors>
     </header>
     <body>
  -    <s1 title="Introduction">
  -      <p>What: Forms Template elements implemented using JXTemplate.</p>
  +    <s1 title="Concept">
  +      <p>The same "ft:" tags as provided by the <link href="templatetransformer.html">template
  +      transformer</link> are also available as macros for the
  +      <link href="../flow/jxtemplate.html">JXTemplate</link> generator.</p>
   
  -      <p>TO BE DONE</p>
  +      <p>Before the availability of these macros, the JXTemplate generator was
  +      already often used in the form publishing pipeline. It makes it possible
  +      to dynamically include additional data on the form page and to conditionally
  +      include parts of the page (and thus conditionally show widgets).
  +      Moving the interpretation of the <code>ft:</code> tags directly into
  +      generator makes this even more powerful. Think of the possibility
  +      of not showing a repeater table if the repeater contains no rows,
  +      and this also for nested repeaters.</p>
  +    </s1>
  +
  +    <s1 title="Usage">
  +      <p>Simply remove the FormsTemplateTransformer from your publishing pipeline,
  +      and instead include the following jx statement into your template file:</p>
  +
  +      <source xml:space="preserve"><![CDATA[<jx:import uri="resource://org/apache/cocoon/forms/generation/template.jx"/>]]></source>
  +
  +      <p>Note that these macros only work when calling the pipeline from flowscript.</p>
       </s1>
     </body>
   </document>
  
  
  
  1.2       +6 -6      cocoon-2.1/src/documentation/xdocs/userdocs/forms/templatetransformer.xml
  
  Index: templatetransformer.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/templatetransformer.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- templatetransformer.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ templatetransformer.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -18,7 +18,7 @@
   
   <document>
     <header>
  -    <title>Apache Cocoon Forms: Template Transformer</title>
  +    <title>Cocoon Forms: Template Transformer</title>
       <authors>
         <person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
       </authors>
  @@ -54,7 +54,7 @@
           It looks for it in the following locations:</p>
   
           <ol>
  -          <li>if the wt:form-template element has a location attribute, then the
  +          <li>if the ft:form-template element has a location attribute, then the
             value of that attribute will be evaluated as a JXPath expression.
             The result of this expression should be the form object.</li>
             <li>if a parameter called "attribute-name" was supplied to the
  @@ -123,11 +123,11 @@
           <source><![CDATA[<ft:form-template location="getAttribute($session,
getParameter($parameters, 'sessionattr'))" ...]]></source>
   
           <p>As mentioned before, ft:form-template elements cannot be nested, but you
can
  -        have multiple wt:form-template elements on one page. Together with the location
  +        have multiple ft:form-template elements on one page. Together with the location
           attribute, this can be used to handle multiple forms occuring on one template.</p>
         </s2>
   
  -      <s2 title="wt:widget">
  +      <s2 title="ft:widget">
           <p>The ft:widget element is replaced by the forms transformer by the XML
           representation of a widget. Which widget is specified by the id attribute.
           The ft:widget element can contain a fi:styling element containing parameters
  @@ -158,7 +158,7 @@
           The label will not be wrapped in another element.</p>
         </s2>
   
  -      <s2 title="wt:continuation-id">
  +      <s2 title="ft:continuation-id">
           <p>The ft:continuation-id element will be replaced by the forms transformer
by:</p>
   
           <source><![CDATA[<fi:continuation-id>
  @@ -168,7 +168,7 @@
           <p>This might be useful for embedding the continuation ID in a hidden form
field, for example.</p>
         </s2>
   
  -      <s2 title="Working with repeaters: wt:repeater-widget, wt:repeater-widget-label,
wt:repeater-size">
  +      <s2 title="Working with repeaters: ft:repeater-widget, ft:repeater-widget-label,
ft:repeater-size">
           <p>The ft:repeater-widget element is similar to the ft:widget element but
           provides special treatment for repeaters. The content of the ft:repeater-widget
           element will be used as a template to generate each of the rows of the repeater.</p>
  
  
  
  1.3       +1 -1      cocoon-2.1/src/documentation/xdocs/userdocs/forms/validation.xml
  
  Index: validation.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/validation.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- validation.xml	17 Apr 2004 18:29:28 -0000	1.2
  +++ validation.xml	24 Apr 2004 12:09:03 -0000	1.3
  @@ -63,7 +63,7 @@
         <fd:failmessage>Not a valid email address!</fd:failmessage>
       </fd:email>
     </fd:validation>
  -</fd:datatype>]]></source>
  +</fd:field>]]></source>
   
           <p>To provide locale-dependent messages, use i18n tags in
           combination with the I18nTransformer.</p>
  
  
  
  1.2       +7 -4      cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_action.xml
  
  Index: widget_action.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_action.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_action.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_action.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,17 +24,20 @@
       </authors>
     </header>
     <body>
  -    <s1 title="action widget">
  +    <s1 title="Concept">
         <p>Used to trigger an action event on the server side. Usually presented
         as a button the user can press (though this is not required). When an
         action widget was activated, validation will not be performed. This
         is because usually it would be strange to have other fields validated
         when the user's intention wasn't really to submit the form. If you want
  -      validation to happen, use the submit widget. After pressing an action
  +      validation to happen, use the <link href="widget_submit.html">submit widget</link>.
  +      After pressing an action
         button, the form will normally always be redisplayed, unless the event
  -      handling code explicitely disables this (by using the endFormProcessing
  -      method on the form object).</p>
  +      handling code explicitely disables this (by using the method <code>endFormProcessing</code>
  +      method on the <code>Form</code> object).</p>
  +    </s1>
   
  +    <s1 title="Configuration">
         <source><![CDATA[<fd:action id="..." action-command="...">
     <fd:label>...</fd:label>
     <fd:help>...</fd:help>
  
  
  
  1.2       +5 -1      cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_aggregatefield.xml
  
  Index: widget_aggregatefield.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_aggregatefield.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_aggregatefield.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_aggregatefield.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,7 +24,11 @@
       </authors>
     </header>
     <body>
  -    <s1 title="aggregatefield widget">
  +    <s1 title="Concept">
  +      <p>TO BE DONE</p>      
  +    </s1>
  +
  +    <s1 title="Configuration">
         <p>TO BE DONE</p>
       </s1>
     </body>
  
  
  
  1.3       +4 -0      cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_booleanfield.xml
  
  Index: widget_booleanfield.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_booleanfield.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- widget_booleanfield.xml	17 Apr 2004 17:19:59 -0000	1.2
  +++ widget_booleanfield.xml	24 Apr 2004 12:09:03 -0000	1.3
  @@ -34,6 +34,10 @@
         it instead as a listbox with true and false values, you could also
         use a regular field widget. Since the styling preference might change over
         time, it is however better to use consistently the fd:booleanfield widget.</p>
  +
  +      <p>A booleanfield cannot be marked as "required", because it is
  +      always required. It is either true or false. If you want tripples
  +      (true/false/none), use a normal field widget with a selection list.</p>
       </s1>
   
       <s1 title="Configuration">
  
  
  
  1.2       +5 -1      cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_messages.xml
  
  Index: widget_messages.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_messages.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_messages.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_messages.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,7 +24,11 @@
       </authors>
     </header>
     <body>
  -    <s1 title="messages widget">
  +    <s1 title="Concept">
  +      <p>TO BE DONE</p>
  +    </s1>
  +
  +    <s1 title="Configuration">
         <p>TO BE DONE</p>
       </s1>
     </body>
  
  
  
  1.2       +6 -2      cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_repeater_action.xml
  
  Index: widget_repeater_action.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_repeater_action.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_repeater_action.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_repeater_action.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,9 +24,13 @@
       </authors>
     </header>
     <body>
  -    <s1 title="repeater-action widget">
  -      <p>This is a specific type of action widget that handles the much
  +    <s1 title="Concept">
  +      <p>This is a specific type of <link href="widget_action.html">action
widget</link>
  +      that handles the much
         needed case of adding or removing rows from a repeater.</p>
  +    </s1>
  +
  +    <s1 title="Configuration">
   
         <source><![CDATA[<fd:repeater-action id="..." action-command="delete-rows|add-row"
repeater="..." select="...">
     <fd:label>...</fd:label>
  
  
  
  1.2       +5 -2      cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_row_action.xml
  
  Index: widget_row_action.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_row_action.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_row_action.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_row_action.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,12 +24,15 @@
       </authors>
     </header>
     <body>
  -    <s1 title="row-action widget">
  -      <p>This is a specific type of action widget that handles frequent actions
  +    <s1 title="Concept">
  +      <p>This is a specific type of <link href="widget_action.html">action
widget</link>
  +      that handles frequent actions
         occuring on a repeater row, such as adding/removing a row and moving
         it up and down. These widgets should be placed inside a repeater and
         act on the current row.</p>
  +    </s1>
   
  +    <s1 title="Configuration">
         <source><![CDATA[<fd:row-action id="..." action-command="add-after|delete|move-up|move-down">
     <fd:label>...</fd:label>
     <fd:help>...</fd:help>
  
  
  
  1.2       +28 -3     cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_submit.xml
  
  Index: widget_submit.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_submit.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_submit.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_submit.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,13 +24,38 @@
       </authors>
     </header>
     <body>
  -    <s1 title="submit widget">
  +    <s1 title="Concept">
         <p>The submit widget, usually rendered as a button, is used by
         the user to submit the form. The submit widget is a special kind
         of action widget, thus also has the same functionality as an action
         widget, however the submit widget does trigger validation and its
         purpose is to end the form.</p>
   
  +      <p>You don't need to use a submit widget to submit a form. For example,
  +      in your HTML template you can simply put:</p>
  +
  +      <source><![CDATA[<input type="submit"/>]]></source>
  +
  +      <p>to be able to submit the form. Using a submit widget enables
  +      some extra functionality. You can control whether validation
  +      should be performed. You can put multiple submit widgets on
  +      a form and add different event handlers to them.</p>
  +
  +      <p>While a submit widget has the explicit purpose to submit a
  +      form, a form can also be submitted by other widgets. One example
  +      is the already mentioned <link href="widget_action.html">action
  +      widget</link>. It is however also possible to automatically submit
  +      a form when a widget changes its value, so that server-side event
  +      value-changed event listeners can be triggerd. This can be specified
  +      using <code>&lt;fi:styling submit-on-change="true"/&gt;</code>
in
  +      the form template (see <link href="xslt.html">XSLT</link> for more
  +      information on the <code>fi:styling</code> directive).</p>
  +
  +      <p>To know which widget caused the form to be submitted, use the
  +      method <code>getSubmitWidget</code> of the <code>Form</code>
object.</p>
  +    </s1>
  +
  +    <s1 title="Configuration">
         <source><![CDATA[<fd:submit id="..." action-command="..." validate="true|false">
     <fd:label>...</fd:label>
     <fd:help>...</fd:help>
  @@ -44,10 +69,10 @@
         be used to disable validation. The difference between an action
         widget and a submit widget with validate="false" is that a submit
         widget with validate="false" will end form processing, thus the form
  -      will not be redisplayed (ultimately, it is of course the controller
  +      will not be redisplayed. Ultimately, it is of course the controller
         who decides this, but the forms hint towards the controller is that
         it shouldn't be redisplayed, and this is exactly what the flowscript
  -      integration library does).</p>
  +      integration library does.</p>
       </s1>
     </body>
   </document>
  
  
  
  1.2       +14 -1     cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_upload.xml
  
  Index: widget_upload.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/widget_upload.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- widget_upload.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ widget_upload.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -24,7 +24,7 @@
       </authors>
     </header>
     <body>
  -    <s1 title="upload widget">
  +    <s1 title="Concept">
         <p>This widget allows to upload files by using Cocoon's file upload features.
         For this reason, this widget won't function properly unless <code>enable-uploads</code>
         is set to <code>true</code> in <code>WEB-INF/web.xml</code>.</p>
  @@ -33,6 +33,19 @@
         <code>multipart/form-data</code> in the <strong>ft:form-template</strong>
         element, inside the template file.</p>
   
  +      <p>To retrieve the uploaded data, simply use the <code>getValue</code>
  +      method of the widget, which will in this case return an object of the
  +      following type:</p>
  +
  +      <source>org.apache.cocoon.servlet.multipart.Part</source>
  +
  +      <p>The <code>setValue</code> method cannot be used with the upload
widget.</p>
  +
  +      <p>The uploaded data will be automatically cleaned up when the upload
  +      widget instance object is finialized by the JVM.</p>
  +    </s1>
  +
  +    <s1 title="Configuration">
         <source><![CDATA[<fd:upload id="..." mime-types="text/plain, text/xml"
required="true|false">
     <fd:label>...</fd:label>
     <fd:help>...</fd:help>
  
  
  
  1.2       +3 -1      cocoon-2.1/src/documentation/xdocs/userdocs/forms/xslt.xml
  
  Index: xslt.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/forms/xslt.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- xslt.xml	14 Apr 2004 19:04:34 -0000	1.1
  +++ xslt.xml	24 Apr 2004 12:09:03 -0000	1.2
  @@ -34,7 +34,9 @@
         <ul>
           <li><code>forms-samples-styling.xsl</code>: this stylesheet includes
two
           stylesheets: one for widget styling, one for page styling. You can choose
  -        between the basic types of it or advanced stylings.</li>
  +        between the basic types of it or advanced stylings. Usually, you will
  +        make a clone of this stylesheet for your own project, and use the other
  +        stylesheets as is.</li>
           <li><code>forms-field-styling.xsl</code>: contains templates
that style
           individual widgets, i.e. templates that translate fi:field, fi:booleanfield
           fi:action, etc. to HTML.</li>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/forms/api_java.xml
  
  Index: api_java.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 1999-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
  
  <document>
    <header>
      <title>Cocoon Forms: Java API</title>
      <authors>
        <person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="To be done">
        <p>To be done.</p>
      </s1>
    </body>
  </document>
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/forms/api_javascript.xml
  
  Index: api_javascript.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 1999-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "dtd/document-v10.dtd">
  
  <document>
    <header>
      <title>Cocoon Forms: Javascript API</title>
      <authors>
        <person name="The Apache Cocoon Team" email="dev@cocoon.apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="To be done">
        <p>To be done.</p>
      </s1>
    </body>
  </document>
  
  

Mime
View raw message