I have comitted a v3 cforms flowscript API. This one combines features
from both the "v1" and "v2" API's. The "v3" should just be considered
another proposal, though I think/hope it's a good candidate to become
the basis for "the" API.
Some notes:
* you have access to both the java-object-widget-tree and its
ScriptableObject equivalent:
- getWidget() and getWidget(name) behave like in v1, thus return
the java widgets
- the javascript form object is accessible through a property
called "model", thus you can do form.model.widgetname.value
- in general, I think samples/docs should focus on the
form.model approach for most work. The main reason the java form
is accessible (IMO) is to pass it to other java components that
need to do work on it.
* custom validator functions are removed, you can now use the
WidgetValidators for this, with the added benefit that those are
executed as part of the normal validation process.
* widget validators can be assigned in a property called 'validator' of
the javascript widget object:
form.model.mywidget.validator = function(widget) { ... };
Note that while in the java api you can do addValidator/removeValidator
to add multiple validators, in the javascript API you can only assign
one function (or null to remove it). This seemed powerful enough and
provides an easier notation. (same is true for events, see next point)
* similar for events, these can be assigned like:
form.model.mywidget.onChange = function(oldValue,newValue) {...}
form.model.myWidget.onActivate = function(source,command){...}
(note that for action events I called the property onActivate instead
of onClick)
(the underlying implementation of this is not longer based on the
FormHandler but on instance-level event listeners)
* Both the validator and event functionality is of course also available
through the java API, where you can add java classes as validators or
event listeners.
* unlike v2, viewData (aka bizdata) is again a separate object that can
be given to showForm, not the form itself. This is more logical if the
form is not the only thing on the page.
* form.showForm is internally a simple while loop. If you want to
control the loop yourself, you can easily write it out instead of using
form.showForm.
* bookmark functionality from v2 dropped, a normal while loop is used
instead. To do extra stuff before displaying a form again, write out the
while loop in your own code.
* the viewData is not added 'early' to the flowcontext for the
javascript snippets specified in the definition. See an earlier mail of
me, I think this should be another object, not the viewData.
* you can define and use multiple bindings by providing an optional name
as first argument to the createBinding, load and save methods.
* the ScriptableWidget still contains the onAddRow and onRemoveRow
'events', I've left them in but we should consider migrating this
functionality to the java widget too.
Please comment on anything that you think is missing or wrong.
And last but not least, thanks to Chris for his creative work on the two
previous versions, from which I learned a lot.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org