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><javascript></code> and/or
+ <code><java></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><fi:styling submit-on-change="true"/></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><