cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bruno Dumon <br...@outerthought.org>
Subject CForms flowscript API musings
Date Sun, 25 Apr 2004 11:09:41 GMT
I'm a bit annoyed by the current status of our flowscript API's for
CForms. I'll leave the intro for what it is and just jump right into it:

Form.showForm()
===============
I find that this function hides too much of how a form is processed, and
stands in the way of doing more advanced stuff.

I propose that instead of Form.showForm(), we just let the user control
it:

var form = new Form("my_form_definition.xml");
var finished = false;
while (!finished) {
    cocoon.sendPageAndWait("my-pipeline", {"form": form});
    finished = form.processSubmit();
}

In this scenario, you need to write 5 lines instead of one
form.showForm() call. However, it provides several advantages:

* You can pass multiple form objects to the sendPageAndWait call (the
FTT supports referencing different forms using the location attribute on
ft:form-template)

* allows to add custom code to be executed before the form is displayed,
and before a form submission is processed. This last one is useful for
multiple things:

        - adding checks to see if the user is allowed to submit the form
        at this moment (could be disallowed if he/she has gone
        forward/backward in the flow and changed stuff on another form)

        - if multiple forms were put on the page, allows to check using
        eg a request attribute which form submission should be
        processed.
        
        - or more generally, it allows to put other links on the page
        pointing to the same continuation but causing something else to
        be done then processing the form submission.

* allows to use sendPage instead of sendPageAndWait for stateless
applications.

For convenience we could still leave the form.showForm() function, but
make its content as simple as the one above.

Custom validation
=================
The current CForms flow API's allow to specify a javascript function
that will be called to do custom validation. However, there seems to be
a problem with this.

Normally, it is the (java) form.process() method that will handle the
different stages of a form submission, which simplified is as follows:
- widgets read values from request
- events generated by this are processed
- widgets are validated *if needed*

(see also http://cocoon.apache.org/2.1/userdocs/forms/eventhandling.html
for the full cycle description)

Note the "if needed" for the validation: it could be that validation
must not be triggered, e.g. when an action widget has been activated.
However, the additional flowscript validation function seems to be
called always.

Since we now have the generalized concept of WidgetValidators, I propose
we use those to plug in the custom validation. In this way, the custom
validation will automatically be peformed as part of the normal form
processing cycle. WidgetValidators are currently however only part of
the WidgetDefinitions, we could make it possible to define additional
ones on the instances.

The same should probably be done for event handlers. Currently the v2
API works around this limitation by using the FormHandler to allow to
add instance-specific event handlers.

Multiple bindings
=================
A simple one, but often requested on the user mailing list: it should be
possible to use multiple bindings with one form.

Currently we have the following functions:
form.createBinding(bindingURI);
form.load(object);
form.save(object);

To allow multiple bindings, we can extend the functions as follows:
form.addBinding(name, bindingURI);
form.load(name, object);
form.save(name, object);

The current functions can be left in place use "default" as the binding
name.

ScriptableWidget
================
This is a difficult issue, and touches right on the problem of how to
integrate java and javascript logic.

The ScriptableWidget makes that we have different "form" objects in the
javascript and java world (with somewhat different though equivalent
API's).

To make things more confusing, the javascript snippets that can be put
in the binding and form definition files are supplied with the original
Java widget objects, as is the validator function in the old (non-v2)
API.

There has been some discussion on pro/con ScriptableWidgets before, see:
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=107945863719119&w=2
and follow that thread.

The main pro/cons according to me are:

* pro: ScriptableWidget makes it much more natural to work with the form
in a javascript environment. Working directly with the Java objects
feels clumsy. If you look at the v2 API, it allows to easily do some 
powerful stuff like assigning javascript functions as event handlers.

* con: different objects, different API's, different documentation,
needs work when new widgets or features/concepts are added. Makes it
more difficult to do one part of logic in javascript and another part in
Java. Makes the javascript code harder to move to Java if you want to.

I'm still undecided on this topic (ScriptableWidget). I'd like to hear
what others think of this, and how they are actually working today (my
experience in using all this is rather limited). At first I was more
towards the ScriptableWidget approach, though as I'm writing this I'm
more leaning towards directly using the java objects, and creating some
convenience functions to wrap javascript functions as custom validators
and event handlers (as far as that's technically possible).

Actually, that's leading me to another random thought: do we need the
javascript Form object? (this is unrelated to the ScriptableWidget
issue) Instead we could just have some convenience functions to create a
form instance, to get a binding object, ... Currently my code always
contains a var form and a var formWidget, and when starting I was always
making the mistake of using the form instead of the formWidget var, and
now I still find it annoying.

Any input highly appreciated!

-- 
Bruno Dumon                             http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org                          bruno@apache.org


Mime
View raw message