[WIKI-UPDATE] WoodyTODO WoodyNotes Woody WoodyReference Tue Apr 22 17:00:04 2003

[st...@outerthought.org]

Page: http://wiki.cocoondev.org/Wiki.jsp?page=WoodyTODO , version: 1 on Tue Apr 22 14:56:47 2003 by BrunoDumon

New page created:
+ !!!The Woody TODO list
+ 
+ !Implementation-level things
+ * (high) caching of FormDefinitions by the DefaultFormManager
+ * The types of widgets, datatypes and validation rules should be taken from external configuration files. Currently they are hardcoded.
+ * variable fields: fields which are not editable by the user
+ * calculated fields
+ * default values for fields
+ * checking validity of id's (should not contain spaces or dots, or characters not allowed in request parameters)
+ * extend supported datatypes (most notably with date and decimal), and add more validation rules (regexp check for strings, ...)
+ * Including one form in another form (subforms)
+ * The "action" and "method" attributes on the html form element should be set by the WoodyTemplateTransformer, which gets them as parameter from the sitemap (because this is not a concern of the template designer, but of the sitemap designer)
+ * It should be possible to set SelectionLists on widget-instance level (currently they are read once on widget-definition level).
+ * think about the design of the various XML formats
+ * make an utility that checks that all (required) fields defined in the form definition are present in the form layout template
+ * (low) allow src attribute on selection-list to be a class that implements a certain interface, for higher performance than executing a pipeline and interpreting its XML output.
+ * validation widget: a widget that has no value of its own, but just serves to perform validation on or between other widgets (for validation rules that don't belong to a specific widget).
+ * it should be possible to run over the widget tree without knowing what widgets are in there (getChildren on ContainerWidget interface or something)
+ * for fields with a selection list, it should be checked that the submitted value is effectively in the selection list (to avoid problems with people playing with request parameters). Since this could potentially be expensive (if the selection list is dynamically generated), maybe do this as a seperate validation rule.
+ *...
+ 
+ !Design-level things
+ * Eventhandling (more written-out ideas to come)
+ * Generic mechanism for storing hidden form state (e.g. value of hidden fields, properties that are defined on a widget instance level instead of widget definition level), or maybe decide to just require to store the form instance in the session in that case
+ 


Page: http://wiki.cocoondev.org/Wiki.jsp?page=WoodyNotes , version: 1 on Tue Apr 22 14:11:58 2003 by BrunoDumon

New page created:
+ !!!Various Woody notes
+ 
+ Various nice-to-knows that don't fit somewhere else yet.
+ 
+ !Referencing other fields in expressions
+ 
+ Many of Woody's validation rules support using expressions. For example, the "registration form" example uses this to check that the two provided passwords are the same:
+ 
+ {{{
+ <wd:datatype base="string">
+   <wd:validation>
+     <wd:assert test="password = confirmPassword">
+       <wd:failmessage>The two passwords are not equal.</wd:failmessage>
+     </wd:assert>
+   </wd:validation>
+ </wd:datatype>
+ }}}
+ 
+ In the expression, "password" and "confirmPassword" are variables that refer to other widgets. There is a potential problem when one or both these fields don't have a value yet, thus if they are "null". If the referenced widgets are required, then Woody is smart enough to wait with the evaluation of the validation rule until all these widgets have a value. So in that case, there are no problems. If on the other hand the widgets are not required, and the widgets have no value yet, the variables will be replaced with null. If the expression doesn't check on this explicitely, the evaluation of the expression could fail (e.g. with a NullPointerException). [[TODO: we need to provide a way to check in expressions if something is null -- for now its best to only refer to required widgets].
+ 
+ !Form instances
+ 
+ This is an implementation detail, but may be interesting to know: internally each widget in Woody has a "definition" and an "instance". The definition holds all configuration details for a specific widget on a certain form. The instance holds the data for one specific use (instance) of the form. The definition is shared by all instances. This makes the instances very light since they only contain what's absolutely necessary.  This distinction between "definition" and "instance" is in fact very similar to Java's classes and objects.
+ 
+ 
+ !Mappings or bindings for connecting forms to your data
+ 
+ In the future, we envisage that there will be mapping (binding) mechanisms to handle the loading and storage of form data based on an XML description.  These mappings could allow loading of data from a database record, a business bean or an XML document into the form. After the form validation cyclus has ended, it could then apply the users' changes back to the database record, business bean or XML document. But for now, you need to write some Java code to load data into the form and get the data from the form, but this is fortunately very easy (see examples further on).  [[TODO] we could also provide an action that returns the value of all widgets as parameters to the sitemap, or provide an XSP taglib to retrieve them. Let us know if you would find this useful (or even better, provide a patch).
+ 


Page: http://wiki.cocoondev.org/Wiki.jsp?page=Woody , version: 2 on Tue Apr 22 14:58:19 2003 by BrunoDumon

+ None of these pages are my private property. Feel free to edit them, to add comments, questions, new content, ...
+ 


Page: http://wiki.cocoondev.org/Wiki.jsp?page=WoodyReference , version: 1 on Tue Apr 22 14:01:45 2003 by BrunoDumon

New page created:
+ !!!Woody reference
+ 
+ Work in progress.
+ 
+ !!Widget reference
+ 
+ Not yet documented:
+ * XML output formats of the widgets
+ * widget-specific API's
+ * default XSLT presentation parameters
+ 
+ !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
+ such as string, long or date to ask for different types of data.
+ 
+ Configuration example:
+ 
+ {{{
+ <wd:field id="..." required="true|false">
+   <wd:label>...</wd:label>
+   <wd:datatype base="...">
+      [...]
+   </wd:datatype>
+ </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 __required attribute__ is optional, by default it is false. It indicates whether this field is required.
+ 
+ The __wd:label__ element contains the label for this widget. This element is optional. It can contain mixed content. 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 in a seperate section.
+ 
+ !multivaluefield widget
+ 
+ The multivaluefield is similar to the field widget but can take multiple values. A multivaluefield should always have a datatype with a selection list, since the user will have to select values from this list. The multivaluefield could be rendered as a list of checkboxes or as a listbox in which the user can select multiple items.
+ 
+ Configuration example:
+ 
+ {{{
+ <wd:multivaluefield id="...">
+   <wd:label>...</wd:label>
+   <wd:datatype base="...">
+     <wd:selection-list>
+       <wd:item value="...">
+         <wd:label>...</wd:label>
+       </wd:item>
+       [...]
+     </wd:selection-list>
+   </wd:datatype>
+ </wd:multivaluefield>
+ }}}
+ 
+ Most of the elements and attributes have the same meaning as for the
+ field widget.
+ 
+ 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.
+ 
+ !booleanfield widget
+ 
+ A 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:booleanfield>
+ }}}
+ 
+ !repeater widget
+ 
+ A repeater widget is a widget that repeats a number of other widgets.
+ It can be used to create e.g. tables.
+ 
+ Configuration example:
+ 
+ {{{
+ <wd:repeater id="...">
+   [...]
+ </wd:repeater>
+ }}}
+ 
+ The repeater 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.
+ 
+ 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" example of Woody for an example on how to use this.
+ 
+ !!Datatype reference
+ 
+ !General
+ 
+ In its most basic form a datatype is declared as follows:
+ 
+ {{{
+ <wd:datatype base="...">
+ }}}
+ 
+ The base attribute refers to one of the built-in datatypes such as string or long.
+ 
+ A datatype can have a number of validation rules, for example:
+ 
+ {{{
+ <wd:datatype base="string">
+   <wd:validation>
+     <wd:length exact='4'/>
+   </wd:validation>
+ </wd:datatype>
+ }}}
+ 
+ The validation element contains a number of child elements, each child element signifies a validation rule. The supported validation rules are documented in a seperate section.
+ 
+ A datatype can also have a selection list. The selection list can be defined inline or read from an external source. Example of inline declaration:
+ 
+ {{{
+ <wd:datatype base="long">
+   <wd:selection-list>
+     <wd:item value="1"/>
+     <wd:item value="2"/>
+     <wd:item value="3">
+       <wd:label>three</wd:label>
+     </wd:item>
+     <wd:item value="4"/>
+     <wd:item value="5"/>
+   </wd:selection-list>
+ </wd:datatype>
+ }}}
+ 
+ Each item in the selection-list can have a value (specified in the value attribute) and optionally a label (specified in the wd:label element). If no label is specified, the value is used as label. The wd:label element can contain mixed content.
+ 
+ Example of getting a selection list from an external source:
+ {{{
+ <wd:datatype base="string">
+   <wd:selection-list src="cocoon:/mychoices.xml"/>
+ </wd:datatype>
+ }}}
+ 
+ All Cocoon-supported protocols can be used. The format of the XML produced by the source should be the same as in case of inline specification of the selection list, thus the root element should be a wd:selection-list element.
+ 
+ !string datatype
+ 
+ [[Nothing here yet]
+ 
+ !long datatype
+ 
+ [[Nothing here yet]
+ 
+ !!Validation rule reference
+ 
+ !General
+ 
+ For each validation rule, the "failmessage" (i.e. the message displayed to the user in case the validation failed) can be overridden by specifying a child wd:failmessage element inside the validation rule element. The failmessage can contain mixed content. Example:
+ 
+ {{{
+ <wd:datatype base="string">
+   <wd:validation>
+     <wd:email>
+       <wd:failmessage>Not a valid email address!</wd:failmessage>
+     </wd:email>
+   </wd:validation>
+ </wd:datatype>
+ }}}
+ 
+ To provide locale-dependent messages, use i18n tags in combination with the I18nTransformer.
+ 
+ Often the values that validation rules will check are specified as expressions. The expression interpreter used is the one from xReporter, general information about it can be found [here|http://xreporter.cocoondev.org/en/expressions.html]
+ 
+ !length
+ 
+ Can be used in combination with these datatypes: string.
+ 
+ Checks the length of strings. This validation rule can take 3 attributes: min, max and exact. You can use either of these three seperately or min and max together. The values of these attributes are expressions.
+ 
+ !email
+ 
+ Can be used in combination with these datatypes: string.
+ 
+ Checks that a value is a valid email address.
+ 
+ !range
+ 
+ Can be used in combination with these datatypes: long.
+ 
+ Checks the numeric range. This validation rule can take 3 attributes: min, max and exact. You can use either of these three seperately or min and max together. The values of these attributes are expressions.
+ 
+ !assert
+ 
+ Can be used in combination with these datatypes: all datatypes.
+ 
+ Evaluates the expression specified in the "test" attribute. This expression should have a boolean result, it should evaluate to either true or false.
+ 
+ !value-count
+ 
+ Can be used in combination with these datatypes: all datatypes as part of multivaluefield.
+ 
+ Checks the number of items selected in a multivaluefield. Again works with min, max and exact attributes.
+