cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sylvain Wallez <sylvain.wal...@anyware-tech.com>
Subject [RT] Revisiting Woody's form definition
Date Mon, 28 Jul 2003 20:15:18 GMT
Hi all,

One week after my first RT about Woody, after having read Marc and 
Bruno's answers and after lots of background thinking high in the 
mountain, here comes some more about Woody. I have abandoned (for now?) 
my idea of "form-defining template" which seems not so intuitive nor 
realistic, and tackled the problem of reuse and distribution of the 
various concerns between the different configuraiton files. So let's go...

 From a developper point of view, two of the main usability differences 
between Woody and XMLForm are that :
1/ XMLForm doesn't require datatypes to be declared, since it relies on 
JXPath's (limited) parsing features to parse values.
2/ Woody requires forms to be defined separately from their usage (i.e. 
the form template) while XMLForm defines forms "inline" without 
requiring a separate file.

These differences, implied by Woody's greater structuration and 
validation features introduces some usage "heaviness" (see my previous 
RT). Now isn't it possible to make Woody's more lightweight without 
sacrificing any of its features ? My opinion is yes, and this RT 
proposes some modifications towards this goal.

Please read the whole thing before replying, since after the analysis 
come some more concrete proposals !

                +---------------------------+
                | Analysis of a Woody field |
                +---------------------------+

Let's split a Woody field into its various components (repeaters are a 
special case that will be considered separately) to find out how we can 
reorganize the form definition, template and binding.

Considering all Woody files, a field is composed of :
- a base datatype (string, integer, boolean, etc) and its constraints 
(range, regexp pattern, etc)
- convertors (conversion between a typed value and its string 
representation)
- a selection list of possible values
- visual elements (label, hint, hotkey, etc)
- styling data (foreing markup inside <wt:widget> in the form template)
- a binding to application data

Base type and its constraints
-----------------------------

A field's datatype is defined by a base type (integer, date, boolean, 
etc) and some validation constraints (length, range, regexp pattern, etc).

Such datatypes are very likely to belong to the application model 
domain, and a given datatype is very likely to be used by several fields 
and in several forms. We could thus clearly benefit of having some 
form-independent datatypes catalogues, ensuring overall consistency.

Example (leaving out namespaces) :
<datatype id="email" basetype="string">
  <validation>
    <email/>
  </validation>
</datatype>

We can then define a field using :
<field id="home-email">
  <datatype ref="email"/>
</field>

or even, if no additional elements are required inside the <datatype>
<field id="home-email" datatype="email"/>

Separating the datatypes dictionary would also allow to use other type 
definition languages, such as XMLSchema datatype (i.e. <simpleType> 
declarations). When forms are used to edit XML documents, this can avoid 
the need to rewrite the existing schema into a Woody-speficic 
definition, with all the implied consistency and maintainability burdens.

Of course, there will be some fields whose datatype will not be reused. 
For these, the current definition (<datatype> inside <field>) is still 
valid, and can be considered as an anonymous inline datatype. 
Furthermore, validations can be chained : a field can define constraints 
that augment those defined on a datatype. Let's consider the password 
example :

Datatypes dictionary :
<datatype id="password" basetype="string">
  <validation>
    <length min="6">
    <valid-password/> <!-- check the presence of non-alpha characters -->
  </validation>
</datatype>

Form definition :
<field id="password">
  <datatype ref="password">
    <validation>
      <assert test="password = confirmPassword">
        <failmessage>The passwords must be equal</failmessage>
      </assert>
    </validation>
  </datatype>
</field>
<field id="confirmPassword" datatype="password"/>

Convertors
----------

Convertors (or should it be "converters" ?) define the locale-dependent 
conversions between a value and its string representation. This is where 
e.g. date formats are defined. Currently, Woody defines converters 
inside <datatype> which is inside <field>. But if we separate datatypes 
as suggested above, do converters belong to fields or to datatypes ?

In my opinion, to neither and to both :
- to neither, because just as datatypes are independent from fields, 
convertors act on a particular base type (double, date, etc) and have no 
relationships with the particular constraints defined by a datatype nor 
with any particular form field. So just as for datatypes, we can thus 
have a format catalogue reused by several forms and/or datatypes.
- to both, because a datatype may have a "default" or "preferred" 
converter, but still leave room for a particular field to use a special 
custom format.

The format catalogue could then be composed of formats as in the 
following example :
<format id="short-date" basetype="date" converter="formatting">
  <pattern locale="en">MM/dd/yyyy</pattern>
  <pattern locale="fr">dd/MM/yyyy</pattern>
<format>

We can then have a field defined using :
<field id="birth-date">
  <datatype ref="past-date"/>
  <format ref="short-date"/>
</field>

Or even <field id="birth-date" datatype="past-date" format="short-date"/>

With "past-date" being defined as
<datatype id="past-date" basetype="date">
  <validation>
    <past-date/> <!-- ensure value is in the past -->
  </validation>
</datatype>

As for datatypes, formats for which reuse is not envisioned can be 
inlined inside the datatype or field definition.

Selection list
--------------

Selection lists define an enumeration in which the user has to choose a 
value.

Selection lists currently can be defined in datatypes, but it may make 
sense for fields to also allow selection lists, thus restricting the 
values allowed by their datatypes. If both the datatype and the field 
define selection lists, the field's list must be a restriction of the 
datatype's list (note that this can be enforced automatically since the 
datatype will check it's list before the field does the same).

Visual elements
---------------

These are the widget's label, hint, help, hotkey, and any other 
information that will come around the widget in the produced page. This 
information is field-specific (doesn't make sense for a datatype).

But this information can also be considered as template-specific, since 
visual elements belong to the view. So what about allowing them in the 
template also, e.g. :
<wt:widget id="foo">
  <wt:label>My label</wt:label>
</wt:label>

Of course, one may consider that the label content should simply replace 
a <wi:widget-label>, but I'm considering here the case where the 
template totally delegates the form layout (including label placement) 
to the formatting stylesheets (like XMLForm does).

Styling data
------------

A Woody template can contain foreign markup inside <wt:field>, which is 
copied as is by the WoodyTransformer, encapsulated in a <wi:styling>.

This clearly belongs to the view. Or do we want to be able to specify a 
default rendering style in the field definition ?

Binding
-------

Binding defines the process or filling a form with application data and 
later writing the form data back to application data. This is currently 
a separate file that maps every widget of the form to the application.

What's currently missing is a way for the binding to enforce more 
validation controls related to data not present in the form. A kind of 
Schematron mixing form data and application data. This would require the 
ability to set widgets violations externally, but Bruno already talked 
about adding this.

Of course, there's still the possibility to open the "java code box", 
but XPath expressions mixing form and application data can fill most of 
the needs.

Also wouldn't it be less verbose if the binding was written in the form 
definition itself ? This mixing would only cause problems if we want to 
have several bindings on a single form, but I'm not sure this case will 
arise often.

                +---------------------------+
                |     Change proposals      |
                +---------------------------+


Datatypes and format dictionaries
---------------------------------

Allowing separation of datatypes and formats from form definitions will 
reduce their verbosity and increase reusability and consistency. Adding 
these two files may be though of as increased complexity, but they will 
in fact greatly simplify form definition.

The problem is how these files should be referenced from the sitemap 
and/or the form. IMO, such catalogues can be considered as 
application-wide, and therefore be declared in the Woody component 
configuration, thus avoiding some more parameters in the sitemap itself.

Identification of concerns
--------------------------

The above analysis contains some "micro-proposals" for each item, which 
may seem like a big mixing of all concerns. I think this reorganisation 
is important to ensure minimal verbosity and hassle when writing forms, 
while still allowing people to choose their preferred way of working 
(most often, a single person is in charge of many of the concerns).

Now the question is : are element's concerns identified by the file 
they're written in or by their namespace ? I found somewhat confusing 
when I discovered Woody that a given data (e.g. a <label>) is copied 
unchanged from the form definition to the form instance but has its 
namespace changed from "wd:" to "wi:". IMO, the label being a concern of 
the form instance, it should be written <wi:label> whatever file it is 
in. So why don't we use the namespace to identify the concerns and allow 
mixing these namespaces in configuration files ?

This would give e.g.
<wd:field id="foo">
  <wi:label>The label for foo</wi:label>
</wd:field>

We can then define which concern is allowed in which file and define the 
various configuration files as an "overriding chain" :
   format dictionary < datatype dictionary < form definition < form template

Format dictionary contains : named formats
Datatype dictionary contains : named datatypes composed of base type, 
optional validations, optional (format reference or inline format)
Form definition contains : widget definitions composed of (datatype 
reference or inline datatype), optional format, optional visual items, 
optional styling items,
Form template contains : widget references including optional visual 
items, optional styling items

The binding is not mentioned here as it is orthogonal to this chain (can 
be either in a separate file on in the form definition file, but not in 
other files).

                +---------------------------+
                |          The end          |
                +---------------------------+


Thanks for reading so far. I hope I was able to explain all this clearly 
and that most of this makes sense.

Traditional question : what do you think ?

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Orixo, the opensource XML business alliance  -  http://www.orixo.com



Mime
View raw message