cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: WoodyWidgetReference
Date Tue, 01 Jun 2004 04:06:27 GMT
   Date: 2004-05-31T21:06:26
   Editor: 142.59.177.122 <>
   Wiki: Cocoon Wiki
   Page: WoodyWidgetReference
   URL: http://wiki.apache.org/cocoon/WoodyWidgetReference

   Minor changes

Change Log:

------------------------------------------------------------------------------
@@ -15,40 +15,40 @@
 ==  field widget ==
 
 The field widget is the most common widget. It is used both for text
-boxes or selection lists. It can be associated with different datatypes
+boxes and selection lists. It can be associated with different datatypes
 such as string, long or date to ask for different types of data.
 
 [pasted the following text here from the sample, still needs some editing to fit in]
 
-A field widget can be associated with a datatype. The function of the datatype is to convert
the string value entered by the user to a more specific type like a number or a date (and
vice versa, convert them back to strings) (this part is actually delegated to a seperate object:
a Convertor). The datatype also performs the validation. (This split-up between "widget" and
"datatype" is specific for the field widget -- it is perfectly possible to make widgets that
have nothing to do with datatypes). In this way, a field widget contains strongly-typed data.
For example, if you associated a '''long''' datatype with a field widget, then you can be
sure that when you retrieve the widget's value, you will get a Long object after the form
was validated successfully.
+A field widget can be associated with a datatype. The function of the datatype is to convert
the string value entered by the user to a more specific type like a number or a date (and
vice versa, convert them back to strings) (this part is actually delegated to a seperate object:
a Convertor). The datatype also performs the validation. (This split-up between "widget" and
"datatype" is specific for the field widget -- it is perfectly possible to make widgets that
have nothing to do with datatypes). In this way, a field widget contains strongly-typed data.
For example, if you associated a '''long''' datatype with a field widget, then you can be
sure that when you retrieve the widget's value, you will get a Long object after the form
has been validated successfully.
 
-The reasoning behind the '''base''' attribute on the '''wd:datatype''' element is that you
are actually defining a new datatype, based on the built-in "string" or "long" datatype, and
customise it with validation rules (and possibly other parameters).
+The reasoning behind the '''base''' attribute on the '''wd:datatype''' element is that you
are actually defining a new datatype, based on the built-in "string" or "long" datatype, and
customising it with validation rules (and possibly other parameters).
 
 === Defining a selection list for a field ===
-A field widget can furthermore be associated with a selection list. This makes that the field
widget could be rendered either as a textbox or a list, depending on whether its datatype
has a selection list. For an example of selection lists, see the "Form1" example provided
with Woody. The selection-list is related with the datatype: the values in the selection-list
should be of the same type as the datatype.
+A field widget can furthermore be associated with a selection list. This allows the field
widget to be rendered either as a textbox or a list, depending on whether its datatype has
a selection list. For an example of selection lists, see the "Form1" example provided with
Woody. The selection-list is related to the datatype: the values in the selection-list should
be of the same type as the datatype.
 
 [http://outerthought.net/~bruno/images/field_datatype_relation.png]
 
-If we wouldn't make these datatype and selection list associations, we would need to create
specific widgets for each possible combination: !StringField, !LongField, !DateField, !StringSelectionList,
!LongSelectionList, ...
+If we didn't make these datatype and selection list associations, we would need to create
specific widgets for each possible combination: !StringField, !LongField, !DateField, !StringSelectionList,
!LongSelectionList, ...
 
 Configuration example:
 
-{{{
-<wd:field id="..." required="true|false">
-  <wd:label>...</wd:label>
-  <wd:hint>...</wd:hint>
-  <wd:help>...</wd:help>
-  <wd:datatype base="...">
-     [...]
-  </wd:datatype>
-  <wd:selection-list .../>
-  <wd:on-value-changed>
-    ...
-  </wd:on-value-changed>
-</wd:field>
+{{{
+<wd:field id="..." required="true|false">
+  <wd:label>...</wd:label>
+  <wd:hint>...</wd:hint>
+  <wd:help>...</wd:help>
+  <wd:datatype base="...">
+     [...]
+  </wd:datatype>
+  <wd:selection-list .../>
+  <wd:on-value-changed>
+    ...
+  </wd:on-value-changed>
+</wd:field>
 }}}
 
-The field element takes a required '''id''' attribute. This id should be unique among all
widgets in the same container (usually the form).
+The field element takes a required '''id''' attribute. This id must be unique among all widgets
in the same container (usually the form).
 
 The '''required''' attribute is optional, by default it is {{{false}}}. It indicates whether
this field is required.
 
@@ -58,13 +58,13 @@
 
 The '''wd:help''' element contains more help for the form control of this widget. This element
is optional. It can contain text help about the input control. For internationalised labels,
use i18n-tags in combination with Cocoon's I18NTransformer.
 
-The '''wd:datatype''' element indicates the datatype for this field. This element is required.
The '''base attribute''' specifies on which built-in type this datatype should be based. The
contents of the wd:datatype element can contain further configuration information for the
datatype. The possible datatypes and their configuration options are described WoodyDatatypeReference.
+The '''wd:datatype''' element indicates the datatype for this field. This element is required.
The '''base attribute''' specifies the built-in type on which this datatype should be based.
The contents of the wd:datatype element can contain further configuration information for
the datatype. The possible datatypes and their configuration options are described in WoodyDatatypeReference.
 
 The '''wd:selection-list''' element is used to associate a selection list with this field.
See WoodyDatatypeReference for more details.
 
-The '''wd:on-value-changed''' element specifies event handlers to be executed in case the
value of this field changes. See also WoodyEventHandling. The interface to be implemented
for Java event listeners is {{{org.apache.cocoon.woody.event.ValueChangedListener}}}. The
!WidgetEvent subclass is {{{org.apache.cocoon.woody.event.ValueChangedEvent}}}.
+The '''wd:on-value-changed''' element specifies event handlers to be executed when the value
of this field changes. See also WoodyEventHandling. The interface to be implemented for Java
event listeners is {{{org.apache.cocoon.woody.event.ValueChangedListener}}}. The !WidgetEvent
subclass is {{{org.apache.cocoon.woody.event.ValueChangedEvent}}}.
 
-'''Note''': ''Events used in {{{<wd:on-value-changed>}}} require that the form instance
is stored serverside (because otherwise Woody doesn't know what the previous values of the
fields were). This is automatically the case when you use flowscript. If you don't use flowscript
you could store the form instance in e.g. the session.''
+'''Note''': ''Events used in {{{<wd:on-value-changed>}}} require the form instance
to be stored serverside (because otherwise Woody doesn't know what the previous values of
the fields were). This is automatically the case when you use flowscript. If you don't use
flowscript you could store the form instance in e.g. the session.''
 
 [[Anchor(2)]]
 == multivaluefield widget ==
@@ -73,43 +73,43 @@
 
 Configuration example:
 
-{{{
-<wd:multivaluefield id="...">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-  <wd:datatype base="...">
-    [...]
-  </wd:datatype>
-  <wd:selection-list>
-    <wd:item value="...">
-      <wd:label>...</wd:label>
-    </wd:item>
-    [...]
-  </wd:selection-list>
-</wd:multivaluefield>
+{{{
+<wd:multivaluefield id="...">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+  <wd:datatype base="...">
+    [...]
+  </wd:datatype>
+  <wd:selection-list>
+    <wd:item value="...">
+      <wd:label>...</wd:label>
+    </wd:item>
+    [...]
+  </wd:selection-list>
+</wd:multivaluefield>
 }}}
 
 Most of the elements and attributes have the same meaning as for the
 field widget.
 
-'''Note''': ''A multivaluefield cannot have a {{{required}}} attribute, instead you should
+'''Note''': ''A multivaluefield cannot have a {{{required}}} attribute; instead you should
 use the {{{value-count}}} validation rule to check the number of values
 the user has selected.''
 
 [[Anchor(3)]]
 == booleanfield widget ==
 
-A '''wd:booleanfield''' is a field that has a value of true or false. Usually is rendered
as a checkbox.
+A '''wd:booleanfield''' is a field that has a value of true or false. Usually rendered as
a checkbox.
 
 Configuration example:
 
-{{{
-<wd:booleanfield id="...">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-</wd:booleanfield>
+{{{
+<wd:booleanfield id="...">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+</wd:booleanfield>
 }}}
 
 [[Anchor(4)]]
@@ -120,51 +120,51 @@
 
 Configuration example:
 
-{{{
-<wd:repeater id="..." initial-size="...">
-  <wd:widgets>
-    [...]
-  </wd:widgets>
-</wd:repeater>
+{{{
+<wd:repeater id="..." initial-size="...">
+  <wd:widgets>
+    [...]
+  </wd:widgets>
+</wd:repeater>
 }}}
 
 The '''wd:widgets''' element should contain a number of other widgets
-to repeat. This can be any of type of widget: field, multivaluefied,
-booleanfield, or even repeater itself.
+to repeat. These can be any of type of widget: field, multivaluefied,
+booleanfield, or even more repeaters.
 
-The optional '''initial-size''' attribute allows to specify how much rows should be initially
present on the repeater. It mostly avoids to display a table with only table headers. Default
value is zero.
+The optional '''initial-size''' attribute specifies how many rows should be present initially
in the repeater. It can be used to avoid displaying a table with just table headers. Default
value is zero.
 
 '''Note''': ''The WoodyTemplateTransformer has specific support for specifying a template
to use to render each of the rows of a repeater widget. See the "Form1" sample of Woody for
an example on how to use this.''
 
 [[Anchor(5)]]
 == output widget ==
-An '''wd:output''' widget is similar to a field widget, but its value is not editable. The
value of an output widget must be set programmatically (or through WoodyBinding). An output
widget does not read its value from the request, so is most useful in the case where the form
is stored accross requests (e.g. as part of a flowscript or flow-apple). An output widget
does not perform any validation, it is always considered to be valid.
+An '''wd:output''' widget is similar to a field widget, but its value is not editable. The
value of an output widget must be set programmatically (or through WoodyBinding). An output
widget does not read its value from the request, so is most useful in the case where the form
is stored across requests (e.g. as part of a flowscript or flow-apple). An output widget does
not perform any validation, it is always considered to be valid.
 
-{{{
-<wd:output id="...">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-  <wd:datatype base="...">
-     [...]
-  </wd:datatype>
-</wd:output>
+{{{
+<wd:output id="...">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+  <wd:datatype base="...">
+     [...]
+  </wd:datatype>
+</wd:output>
 }}}
 
 [[Anchor(6)]]
 == action widget ==
 
-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 button, the form will normally always be redisplayed,
unless the event handling code explicitely disables this (by using the end!FormProcessing
method on the form object).
+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 is 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 an action button has been pressed, the form will normally be
redisplayed, unless the event handling code explicitly disables this (by using the end!FormProcessing
method on the form object).
 
-{{{
-<wd:action id="..." action-command="...">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-  <wd:on-action>
-    ...
-  </wd:on-action>
-</wd:action>
+{{{
+<wd:action id="..." action-command="...">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+  <wd:on-action>
+    ...
+  </wd:on-action>
+</wd:action>
 }}}
 
 The '''action-command''' attribute specifies a name that will be part of the event generated
by this widget. It can be used to distinguish events originated from this wd:action from another
one.
@@ -173,17 +173,17 @@
 
 [[Anchor(7)]]
 == submit widget ==
-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.
+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, and therefore has the same functionality
as an action widget, but the submit widget does trigger validation and its purpose is to end
the form.
 
-{{{
-<wd:submit id="..." action-command="..." validate="true|false">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-  <wd:on-action>
-    ...
-  </wd:on-action>
-</wd:submit>
+{{{
+<wd:submit id="..." action-command="..." validate="true|false">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+  <wd:on-action>
+    ...
+  </wd:on-action>
+</wd:submit>
 }}}
 
 The optional attribute validate, which is true by default, can 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 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).
@@ -191,24 +191,24 @@
 [[Anchor(8)]]
 == repeater-action widget ==
 
-This is a specific type of action widget that handles the much needed case of adding or removing
rows from a repeater.
+This is a specific type of action widget that handles the much-needed case of adding or removing
rows from a repeater.
 
-{{{
-<wd:repeater-action id="..." action-command="delete-rows|add-row" repeater="..." select="...">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-  <wd:on-activate>
-    ...
-  </wd:on-activate>
-</wd:repeater-action>
+{{{
+<wd:repeater-action id="..." action-command="delete-rows|add-row" repeater="..." select="...">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+  <wd:on-activate>
+    ...
+  </wd:on-activate>
+</wd:repeater-action>
 }}}
 
 The '''action-command''' attribute should have either the value {{{delete-rows}}} or {{{add-row}}}.
If {{{add-row}}} is specified, the attribute repeater is required. If {{{delete-rows}}} is
specified, both the repeater and select attributes are required.
 
 The '''repeater''' attribute should contain the id of the repeater widget on which this repeater-action
should act. This must be a sibling of the repeater-action widget (see also row-action for
actions inside a row).
 
-The '''select''' attribute should contain the id of the booleanfield widget (or any type
of widget who's getValue() method returns a boolean) that is part of the repeater and used
to mark the rows to be deleted.
+The '''select''' attribute should contain the id of the booleanfield widget (or any type
of widget whose getValue() method returns a boolean) that is part of the repeater and is used
to mark the rows to be deleted.
 
 '''wd:on-activate''' allows additional event handlers to be defined, see also WoodyEventHandling.
The interface to be implemented for Java event listeners is org.apache.cocoon.woody.event.!ActionListener.
The !WidgetEvent subclass is {{{org.apache.cocoon.woody.event.ActionEvent}}}.
 
@@ -217,22 +217,22 @@
 
 This is a specific type of action widget 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.
 
-{{{
-<wd:row-action id="..." action-command="add-after|delete|move-up|move-down">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-  <wd:on-activate>
-    ...
-  </wd:on-activate>
-</wd:row-action>
+{{{
+<wd:row-action id="..." action-command="add-after|delete|move-up|move-down">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+  <wd:on-activate>
+    ...
+  </wd:on-activate>
+</wd:row-action>
 }}}
 
 The '''action-command''' attribute should have either the value {{{add-after}}}, {{{delete}}},
{{{move-up}}} or  {{{move-down}}}.
 
 '''wd:on-activate''' allows additional event handlers to be defined, see also WoodyEventHandling.
The interface to be implemented for Java event listeners is org.apache.cocoon.woody.event.!ActionListener.
The !WidgetEvent subclass is {{{org.apache.cocoon.woody.event.ActionEvent}}}.
 
-Where all you want to do is submit a specific row on a repeater, simply add a <wd:submit>
element to the widgets for the repeater.
+If all you want to do is submit a specific row on a repeater, simply add a <wd:submit>
element to the widgets for the repeater.
 
 Then, you can access the submitted row either using an event handler with {{{event.getSourceWidget().getParent()}}},
or from the flow using {{{form.getWidget().getSubmitWidget().getParent()}}}. The row itself
has a getWidget(widgetName) method that can be used to access specific widgets for the row.
 
@@ -240,26 +240,26 @@
 == aggregatefield widget ==
 
 used to edit the value of multiple fields through one textbox or to edit one
-value through multiple texboxes.
+value through multiple textboxes.
 
 ''documentation to be done''
 
 [[Anchor(11)]]
 == upload widget ==
 
-This widget allows to upload files by using Cocoon's file upload features. For this reason,
this widget won't function properly unless {{{enable-uploads}}} is set to {{{true}}} in {{{WEB-INF/web.xml}}}.
+This widget supports uploading files by using Cocoon's file upload features. For this reason,
this widget won't function properly unless {{{enable-uploads}}} is set to {{{true}}} in {{{WEB-INF/web.xml}}}.
 
 Also, don't forget to put the '''enctype''' attribute as {{{multipart/form-data}}} in the
'''wt:form-template''' element, inside the template file. 
 
-{{{
-<wd:upload id="..." mime-types="text/plain, text/xml" required="true|false">
-  <wd:label>...</wd:label>
-  <wd:help>...</wd:help>
-  <wd:hint>...</wd:hint>
-</wd:upload>
+{{{
+<wd:upload id="..." mime-types="text/plain, text/xml" required="true|false">
+  <wd:label>...</wd:label>
+  <wd:help>...</wd:help>
+  <wd:hint>...</wd:hint>
+</wd:upload>
 }}}
 
-The optional {{{mime-types}}} attribute allows to specify a comma-separated list of mime-types
which are accepted. The widget will be invalid if the uploaded type isn't of one of the specified
content types.
+The optional {{{mime-types}}} attribute specifies a comma-separated list of mime-types that
are accepted. The widget will be invalid if the uploaded type isn't one of the specified content
types.
 
 [[Anchor(12)]]
 == messages widget ==

Mime
View raw message