cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stev...@outerthought.org
Subject [WIKI-UPDATE] Main Apples WoodyIntro WoodyWidgetReference LeftMenu Thu Nov 6 21:00:07 2003
Date Thu, 06 Nov 2003 20:00:08 GMT
Page: http://wiki.cocoondev.org/Wiki.jsp?page=Main , version: 273 on Thu Nov  6 19:45:18 2003
by 24.202.243.89

- !! What for you have opened access for editing this page?
- !! What will be, if somebody here will write junk?
- !! Here it is possible to write anything you like?
- !! I do not understand something?
- !! And there still below someone already has attached a file...
- !! You should forbid editing!!!
- 
- 
- 
- 


Page: http://wiki.cocoondev.org/Wiki.jsp?page=Apples , version: 2 on Thu Nov  6 19:12:03 2003
by 212.48.41.50

- tratata
+ 


Page: http://wiki.cocoondev.org/Wiki.jsp?page=WoodyIntro , version: 8 on Thu Nov  6 19:39:58
2003 by BrunoDumon

- Woody is the new form framework for Cocoon.
+ Three important aspects of web application development are publishing, flow control and
form handling. Traditionally, Cocoon has been very strong in the publishing aspect with is
XML-transforming pipelines. With the advent of flowscript and its continuations concept, handling
transitions between pages has become dead easy. And now Woody ("Cocoon Forms") fills the form
handling gap.
- Previously, Cocoon already provided a number of form-handling solutions (XMLForm, FormValidatorAction
and SimpleFormTransformer, Precept) so you may wonder what makes Woody different.
+ In Woody, the model of a form is defined by a __form definition__. This is an XML file describing
the structure of the form, by declaring the widgets it consists of. This file doesn't contain
any presentational information. Based on the form definition, a __form instance__ can be created.
This is a specific instance of the form that will hold actual data. The form defintion is
to the form instance what a Java class is to a Java object, or what an XML Schema is to an
XML document.
- Woody combines the ease of use of the FormValidatorAction and the power of XMLForm. Forms
can be created without any programming. Of course you'll need some controller code that passes
on the request to the form, but using Cocoon's flowscript this is very easy. You can also
use the provided actions to handle basic forms without any programming. And of course, if
you need additional power, all the necessary hooks are there to extends or customise Woody.
+ Since the form definition is simply described in an XML file, this means you can create
forms without any knowledge of Java. On the other hand, hardcore Java programmers do not have
to fear that Woody is not for them.
- Woody takes a widget-oriented approach to forms. A form is defined by specifying the widgets
that should appear on the form. Woody contains a set of standard widgets that should cover
most needs, but it is possible to add your own ones. Each widget knows how to read its state
from a Request object, how to validate itself, and can generate an XML representation of itself.
A widget can remember its state itself, so unlike XMLForm or Struts, you do not have to write
a form bean for that purpose. A widget can hold strongly typed data. For example, you can
indicate that a field should contain a date. If you do this, you can be assured that after
the form is successfully validated, and you retrieve its value, you will get a Date object.
So your own business logic doesn't need to care about converting strings to other types (and
all the locale and formatting related issues of this).
? ^^^^^^^^^^   --  ^ -----------------------   ^^^ ^         ^  ----------------------   
    -------------------------------  ^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^           ------------------------------------------------------------------------------
                                                                                         
                                                                                     -----------
                                                                                         
                                                                                         
                                                                                         
                                                                                         
                                  -                                                      
 -

+ As said before, a form consists of a number of widgets. A __widget__ is an object that knows
how to read its state from a Request object, how to validate itself, and can generate an XML
representation of itself. A widget can remember its state itself, so unlike Struts, you do
not have to write a form bean for that purpose. A widget can hold strongly typed data. For
example, you can indicate that a field should contain a date. If you do this, you can be assured
that after the form is successfully validated, and you retrieve its value, you will get a
Date object. So your own business logic doesn't need to care about converting strings to other
types, and all the locale and formatting related issues of this.
? ^  +   ^^    ^^ ^      ++++  ++ ^^^^^^^^^ +++           ^ ^^      ++++ ++++++++++      
                                                                                         
                                                                                         
                                                                                         
                                                                                         
                                                                                         
                                                                                         
                           +

- The basic thing that Woody provides is a Form object. This Form object could be seen as
the server-side representation of a client-side form. The Form contains a number of widgets
(and is in fact itself also a widget). When a form is submitted, you can call Form.process(FormContext)
to let it (and recursively all the widgets contained in it) read its state from the request.
+ Woody contains a flexible set of widgets that should cover most needs (but, like everything
in Woody, it is extensible with your own types). One special widget is the repeater widget,
which "repeats" a number of other widgets multiple times, as is needed to generate table-like
structures. Widgets can thus have child widgets,  so a form instance is effectively a __widget
tree__.
- The Form object is something that is used by other (controller) code, such as an Action
or a flowscript, to help in handling forms.  Thus Woody will not take complete control of
how requests are handled. Woody contains some default Actions to instantiate and process a
form. Integration with flowscript is also available.
+ For presenting the form, we have a solution that's both easy and powerful. Basically, you
write a __template file__ (e.g. an XHTML file, but this could be any markup) and on the places
you want a widget to appear, you insert a special tag referencing that widget. After processing
by the Woody Template Transformer, these tags will be replaced by the XML representation of
the widget, which contains all state information of the widget (its value, validation errors,
...). These bits of XML can then be transformed to plain HTML by an XSLT. Note that this XSLT
only has to know how to style certain kinds of widgets, but not individual widget instances
itself. Thus one template in this XSLT can style all widgets of a certain type that appear
on all forms you might have. Cocoon includes a flexible, [configurable XSLT|WoodyXSLT] that
covers most needs.
- As for the presentation of the form (i.e. creating the actual HTML form), Woody provides
a [WoodyTemplateTransformer]. This mechanism allows to reuse the same XSLT to style all your
forms. Woody includes standard stylesheets which cover many needs.
+ Lets look at a typical scenario to see how things fit together:
+ [http://outerthought.net/~bruno/images/woody_overview.png]
+ * Initially, the controller logic asks the FormManager component to create a form instance
based on a form definition (form definitions are cached, so creating an instance is very fast).
+ * The controller can then optionally pre-populate this form object with some data. To fill
the form with data from a bean or XML document, a [binding framework|WoodyBinding] is available.
+ * Then the form is shown by calling a pipeline.
+ * When the form is submitted, the controller will let the form instance object process the
request, so that all widgets can read their value from the request. Some might generated events,
which will be handled by event handlers. Validation of the widget tree is also triggered,
whereby all widgets will validate themselves based on validation rules described in the form
definition. The controller can afterwards perform application-specific validation logic.
+ * If there were validation errors, the form will be redisplayed. Otherwise the controller
will decide what's the next step, for example saving the form data back to a bean or calling
some backend process using data from the form.
- ----
- !!!Illustrations
+ So to summarize some important points:
+ * by having a separate form definition and form template, strong separation of concerns
is achieved, both conceptually and skill-wise. The same form definition can be used with different
templates.
+ * it is not required to write Java classes for a form, nor do you need to be Java programmer
to benifit from Woody.
+ * strong datatyping on form definition level makes you don't have to worry about that yourself.
+ * Woody isn't concerned with page flow, this is left to other solutions such as flowscript
(for people who don't like flowscript: Woody doesn't depend on flowscript).
+ * Woody integrates nicely within the rest of Cocoon.
- The pictures below show how Woody fits into Cocoon. The first picture shows how the WoodyTemplateTransformer
is used for publishing, the second uses the WoodyGenerator.
+ __Next steps:__ run through the [sample|WoodySample] to get a feeling of form definitions
and form templates. Also have a look at the examples included with Cocoon.
- The indicated steps are those for a handling a form submit. In case the form is initially
requested, step 2 (form processes request & does validation) is not needed, but instead
in this step the form might be pre-populated with data. In case the form is successfully validated,
step 3 would not execute the publishing pipeline for the form again, but instead the data
from the form will be used for whatever purpose it is needed for, and then some other page
will be shown.
- 
- [http://outerthought.net/~bruno/images/woody_overview.png]
- 
- The WoodyTemplateTransformer inserts the XML representation of individual widgets. This
makes that the XSLT later on in the pipeline will only have to style individual widgets, and
is thus not specific for a certain form.
- 
- [http://outerthought.net/~bruno/images/woody_overview_generator.png]
- 
- The WoodyGenerator generates a complete XML representation of the form, which will then
have to be styled by an XSLT. This XSLT will be specific for that form, but could import a
library-XSLT that has templates for formatting individual widgets.
- 


Page: http://wiki.cocoondev.org/Wiki.jsp?page=WoodyWidgetReference , version: 6 on Thu Nov
 6 20:02:57 2003 by BrunoDumon

- Used to trigger an action event on the server side. Usually presented as a button the user
can press (though this is not required).
+ 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 endFormProcessing method
on the form object).
+ 
+ !!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.
+ 
+ {{{
+ <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).


Page: http://wiki.cocoondev.org/Wiki.jsp?page=LeftMenu , version: 96 on Thu Nov  6 19:17:18
2003 by BrunoDumon

- +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-



Mime
View raw message