Hi All

A lot of work is being done on CForms for the 2.1.11 release.
It may be a bit disruptive temporarily to users' projects, but IMHO it will be worth it.


What if all you do is write a few simple forms and use the standard form-processing pipelines and xslt? There will be very little to do to move to cocoon 2.1.11 as most of the changes are handled by those built-in resources.


A list of the changes :

1. Update the Dojo Libraries to 0.4.1, the latest release (with a few fixes).

Dojo 0.4.1 seems faster, more stable and more compatible across browsers. It brings many benefits, the main one IMHO was the ability to do item (2).


2. Switch to using namespaces for Dojo Widgets.

The switch to Dojo 0.4.1 allows us to use namespaces for Widgets.
Although in the short-term it may feel that replacing stuff like dojoType="CFormsSuggest" with dojoType="forms:CFormsSuggest" is a PIA, it brings great advantages.

The client-side code now consists of 3 namespaces :
    dojo  : all of dojo, the default (no need for a prefix)
    forms : widgets from the cocoon.forms module
    ajax  : widgets from the cocoon.ajax module

These namespace modules are registered with dojo and a manifest is provided so their widgets can be auto-loaded. What this means is that instead of for example, our XSLT adding dojo.require(some.package) because something might possibly be wanted from it, we can leave the dojo.require declarations out, libraries in the modules load because their module path is registered, widgets load automatically because they have a resolver in their manifest. The hack of dojo.require in cocoon.js is no longer required, or used (or compatible).

It now becomes far easier for you to develop dojo widgets in your own namespace and have them auto-loaded as well.

If you have custom dojo-savvy js libraries to load you'd do something like this : dojo.registerModulePath("myorg.modulename", "../myorg/modulename/ js");
    dojo.require("myorg.modulename.mybrilliantlibrary");
    . . .
// do something with my library after everything has safely loaded : dojo.addOnLoad(function() { myorg.modulename.mybrilliantlibrary.doSomethingAstonishing(); });

Dojo would load : _cocoon/resources/myorg/modulename/js/ mybrilliantlibrary.js
This could be served from either :
    build/webapp/resources/myorg/modulename/js/mybrilliantlibrary.js
or from a jar file in build/webapp/WEB-INF/libs/ with a package path like : org/apache/cocoon/myorg/resources/modulename/js/ mybrilliantlibrary.js

Your library must at least say :
    dojo.provide(myorg.modulename.mybrilliantlibrary);

Say your project required you to extend some of CForm's or Dojo's widgets, the cleanest and simplest thing to do will be to do that in your own namespace.

Say you were writing Widgets in the same registered module as above, you would provide a manifest file which dojo would try to load from here : _cocoon/resources/myorg/modulename/manifest.js (NB. it is in modulename/ not modulename/js/).

Your manifest would typically register a namespace like this :
dojo.registerNamespace("mystuff", "myorg.modulename", resolverFunction);

Then it would provide a resolverFunction that maps between lowercase widget names and a full packagename.
See the manifests in the forms and ajax blocks for an example.

You would use your widgets like this :
    <div dojoType="mystuff:FunkyMonkey"/>
and dojo would attempt to load : _cocoon/resources/myorg/modulename/ js/FunkyMonkey.js

As we move more of our CForms widget implementations to dojo, this will lead to a dramatic reduction of unnecessary code being loaded by the browser (a big problem in previous versions imho).



3. Cleanup of the client-side code.

Apart from a general push to convert all of cocoon's javascript (clientside and serverside) into namespaced javascript as a general best practise, I felt that the existing implementation of the clientside code was more complex/opaque than it needed to be.

forms_lib.js and cocoon.forms.common have been refactored.
forms_* functions in forms_lib.js have been deprecated and are replaced by nearly equivalent functions in cocoon.forms.* the old functions can still be called (temporarily) they do their best to pass the calls on to the new implementation.

One issue dealt with by this update, is removing barriers to having multiple cforms per page. This required changing some of the parameters passed to functions like adding onSubmit handlers, we now need a reference to the form as well as the handler. Another side effect of this is that forms now need id attributes. If you do not have one in your template, one is added for you in the standard CForms rendering pipelines.

If you are not writing your own CForms Widgets, you are unlikely to be effected.



4. Dojo widgets for ajax and non-ajax forms.

CFormForm.js which used to be the Dojo Widget used for ajax-enabled CForms has been deprecated and replaced by two Dojo Widgets : SimpleForm (handles non-ajax forms) and AjaxForm (does what CFormForm did).

From this you can see that now a Dojo Widget is always used on the form tag of CForms. This helped with item (3), simplification, and I think it will help us maintain a more similar environment between ajax and non-ajax forms.

If you are using standard rendering pipelines, you are unlikely to be effected.



5. Dojo debug turned on and off via a sitemap parameter.

2.1.9 introduced a new CForms tag <fi:init/>. It was inserted into html/head before dojo was loaded. AFAICS it was only being used to turn on dojo debugging. It would be far more useful being inserted after dojo has loaded, then it can be used from templates that want to do initialisation of dojo-savvy code.

Debug messages for Dojo on the browser can now be turned on via a sitemap parameter, passed to the standard cforms rendering xslt. See forms/samples/sitemap.xmap for an example.

Logging in dojo 0.4.1 has been much improved. Debug messages are no longer written to the page, but to either FireBug (if you use FireFox) or to the browser's JavaScript Console. There are also new functions that can display navigable tree-views of your objects even if you are not using FireBug.



6. CForms no longer alters the form's onsubmit attribute.
CForms used to prepend a call to forms_onsubmit() to the onsubmit attribute of forms, to call it's own onSubmit handlers. If you had added your own call to an onSubmit handler, I suspect that CForms ones ability to cancel the form submission would have been lost. CForm's onSubmit handlers are now called as part of the refactoring in item (3).

CForms should still work without dojo being loaded. If you refactor the XSLT to avoid dojo, then please read the notes in forms-field- styling.xsl. CForms without interactive widgets should require only : _cocoon/ resources/forms/js/common.js Legacy CForms Widgets still currently require : _cocoon/resources/ forms/js/forms-lib.js


Your feedback is very welcome.

Please test, test, test ! :)



best regards

Jeremy





Attachment: smime.p7s
Description: S/MIME cryptographic signature

Reply via email to