cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeremy Quinn <jer...@apache.org>
Subject Changes to CForms in 2.1.11-dev
Date Wed, 03 Jan 2007 00:46:17 GMT
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






Mime
View raw message