cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ralph Goers <>
Subject Re: Changes to CForms in 2.1.11-dev
Date Wed, 03 Jan 2007 01:20:05 GMT

Does this break binary compatibility? Some of the changes sound like 
users who upgrade from 2.1.10 to 2.1.11 may have to modify their 
application?  If so, I see that as a problem.


Jeremy Quinn wrote:
> 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

View raw message