FLUID-5082 "Soft namespaces"

[Antranig Basman]

An incomplete version of this facility got committed on Friday, but it was found to immediately conflict 
with the refactored pager from FLUID-4035. A corrected version has been committed today.

The purpose of this facility is to help 3rd (and higher) parties to override particular listeners that 
appear in configuration. The more our component configuration becomes declarative, we tend to accumulate 
long lists of listeners, especially to "onCreate" functions - whilst these are better than their equivalents 
written in code in the former "init functions" (to be deprecated), given that they are out in the open and 
can be inspected by tools, etc. they are still inadequate in that unless the original author gave a 
namespace to the listeners, it would be impossible for someone adapting the component to single out just 
that one listener for overriding.

http://wiki.fluidproject.org/display/Infusion14/Infusion+Event+System

Rather than force the original author to think up fresh namespaces for every listener attached to a 
component, it seemed desirable for FLUID-5082 to implement a "soft namespaces" system where a namespace was 
invented for every listener which did not have one. These namespaces are "soft" because of the crucial rule 
that "no listener assigned with a soft namespace can override another one with a soft namespace". In order 
to override a soft-namespaced listener, one must supply a listener with a "hard namespace" (that is, a 
traditional event namespace supplied with the "namespace" key, argument to "addListener" or else a string 
following the event name with "." as with the jQuery convention for event namespaces) that agrees exactly 
with the soft namespace assigned by the framework.

http://www.learningjquery.com/2007/09/namespace-your-events

Last week's implementation of FLUID-5082 was defective because the namespaces chosen were too short and led 
to unanticipated collisions - three listeners were discovered in the new Pager design which had all been 
assigned a namespace of "onModelChange".

Under the new rules, the fully-qualified name of the component (defaults record) holding the listener record 
forms the start of every soft namespace. The rest of the namespace is derived from either the 
"func"/"funcName"/"listener" element of the listener record, or in the case of a "this-ist" record, from the 
"this" and "method" elements.


For a traditional listener record, the last soft namespace segment is taken from the last path segment of 
the "func"/"funcName"/"listener" entry. For a "this-ist" record, it is taken by adding the "method" entry to 
the end of the last path segment of the "this" entry.

For example, in the following listener block:

     fluid.defaults("fluid.tests.FLUID5082Parent", {
...
         listeners: {
             testEvent: [{
                 funcName: "fluid.tests.FLUID5082func",
                 args: ["{that}", 1]
             }, {
                 func: "{that}.FLUID5082invoker",
                 args: ["{that}", 2]
             }, {
                 "this": "{that}.self",
                 method: "FLUID5082invoker2",
                 args: ["{that}", 3]
             }

the first listener gets a soft namespace of "fluid.tests.FLUID5082Parent.FLUID5082func", the 2nd listener 
gets a soft namespace of "fluid.tests.FLUID5082Parent.FLUID5082invoker" and the 3rd gets 
"fluid.tests.FLUID5082Parent.self.FLUID5082invoker2" under the special "this-ist" rules.


Right now, this framework facility is expected to be mainly "ideological" rather than practical - our chain 
of users and integrators don't stretch far enough away from the core community to cause this kind of 
adaptation to be happening very frequently, but as, for example, the UIOptions family of components comes 
into wider and wider use, we expect the requirement to provide this kind of fine-scaled customisation to 
arise. In the meantime, we expect existing work to be unaffected by it - in fact, an important criterion for 
this patch was that all the code (configuration) written so far could continue to be accepted without a 
change of meaning.

As a side-note, with the "new renderer" delivered with FLUID-5047, we expect these very long lists of 
listeners attached in "onCreate" to go away in favour of a dedicated "decorators" system, but this is still 
some months off.

Those interested in the details of how soft namespaced listeners override might like to work through the 
test case for this facility at

https://github.com/fluid-project/infusion/blob/master/src/webapp/tests/framework-tests/core/js/FluidIoCTests.js#L866-L930

Cheers,
Antranig.