This documentation is currently being moved to our new documentation site.

Please view or edit the documentation there, instead.

If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Event injection and boiling

Owned by Antranig Basman
Last updated: Apr 16, 2014Version comment
9 min read
On This Page

The Infusion Event System explains how to declare events of various types attached to a single component. Within a larger design, sometimes it is necessary to

  1. collaborate between multiple components in a component tree on "sharing" references to event firers ("event injection")
  2. present an event with a particular signature fired by a component as one with a different signature in a listener ("event boiling")

Both of these capabilities rely on the IoC - Inversion of Control system and on the tree of components in question being an IoC-driven tree.

Event injection

Event injection is the wholesale injection of an event belonging to one component, to appear as an event belonging to another. These events will share a single set of listeners which will be fired when any sharing component fires the event, and any sharing component may add and remove listeners. This is achieved by simply referencing the source event to be injected on the right hand side of the standard events block on the component. For example:

Example 1
fluid.defaults("fluid.tests.parentComponent", {
    gradeNames: ["fluid.eventedComponent", "autoInit"],
    events: {
        parentEvent: null
    },
    components: {
        childComponent: {
            type: "fluid.tests.childComponent"
        }
    }
});

fluid.defaults("fluid.tests.childComponent", {
    gradeNames: ["fluid.eventedComponent", "autoInit"],
    events: {
        parentEvent: "{parentComponent}.events.parentEvent"
    }
});

The first defaults block in this example defines a standard eventedComponent which defines one concrete event, named parentEvent, and one child component, with options unspecified.

The second defaults block defines defaults for childComponent. Here, the reference to the event parentEvent becomes shared between the two components. childComponent will appear to have a event firer named parentEvent which behaves exactly as if it were defined locally (as it is in the parent component) and will share listeners with the parent component.

Alternative choice of scoping for event binding

Note that the defaults we have written in the examples above for childComponent prevent it from being used in contexts where the reference {parentComponent} cannot be resolved. This may or may not be desirable depending on the purpose for childComponent. Its purpose may only comprise being reused together with {parentComponent}, or it may be intended to be more generally reusable - since this is only test/example code, this intention can't be made clear. For completeness, we present another style of writing this configuration which expresses the other intention, that childComponent should be generally reusable: this moves the reference to parentComponent into the tree for parentComponent itself, ensuring that childComponent is independently reusable.

 

Example 2
fluid.defaults("fluid.tests.parentComponent", {
    gradeNames: ["fluid.eventedComponent", "autoInit"],
    events: {
        parentEvent: null
    },
    components: {
        childComponent: {
            type: "fluid.tests.childComponent",
			options: {
				events:{
    	    		parentEvent: "{parentComponent}.events.parentEvent"
    			}
			}
	   }
    }
});

fluid.defaults("fluid.tests.childComponent", {
    gradeNames: ["fluid.eventedComponent", "autoInit"],
    events: {
        parentEvent: null
    }
}); 

Here, the base component childComponent contains a standard local definition of an event named parentEvent which satisfies the component's own requirements to fire this event when in isolation. The event binding on parentEvent is defined in the defaults block of parentComponent. At the instantiation of parentComponent, the bound event overwrites the definition of the local event parentEvent .

Event boiling

A "boiled" event is derived from another event (a "base event") but allows the signature of the event to be adjusted. A listener to a boiled event receives a call at the same point in time as a standard listener, but can receive a different set of arguments than the ones which were supplied in the original call to fire() which triggered the event. This modified argument set can draw values from IoC-resolved contextual values around the component tree, as well as from the original argument set which the firer of the event supplied.

Boiled events are useful in wiring together consumers and producers of events who have different expectations - these differences can arise, for example, through the development of the codebases being in different lifecycles - perhaps the producer of the event is part of framework code which is not going to be updated for a long time, but has been written with a poorly planned API which does not expose crucial information which the event consumer requires.

Suggestions are still welcomed for more a suitable name than "boiled events".

Boiling one single event

A boiled event is defined in just the same place as a standard event - in the events block of a component's defaults. The configuration ("right-hand side") value is more complex than that for a simple event - it needs to specify not only the base event, but also the transformation performed on the argument list. The configured value must contain two elements, the event property, which references the event to be boiled, and the args which specifies the argument list which will be received by listeners to the boiled event. This uses the standard {context}.pathName format for contextualised EL values which is used in IoC, with the addition that one extra context object is in scope - the context {arguments} allows the argument list to refer to the original argument list that was presented when the base event was fired. For example:

Example 3
    fluid.defaults("fluid.tests.eventBoiled", {
        gradeNames: ["fluid.eventedComponent", "autoInit"],
        events: {
            boiledLocal: {
                event: "localEvent",
                args: ["{arguments}.1", "{arguments}.0"]
            },
            localEvent: null
        }
    });

In this code block, the component defines two events - one "basic event" named localEvent, and one "boiled event" named boiledLocal which uses localEvent as a base. In this case, a listener registered to boiledLocal will receive the first two arguments which were supplied when localEvent was fired, but swapped to appear in the opposite order.

Boiling multiple events

The event boiling can be used to boil multiple events that are either from the same or a different component. The example below shows boiling from a different component, the boiled event boiledDouble in the example will be fired once both parentEvent1 and parentEvent2 from parentComponent are fired. The arguments supplied to boiledDouble would be the first argument provided by parentEvent1 and the second argument provided by parentEvent2.

Example 4
    fluid.defaults("fluid.tests.parentComponent", {
        gradeNames: ["fluid.eventedComponent", "autoInit"],
        events: {
            parentEvent1: null,
            parentEvent2: null
        },
        components: {
            child: {
                type: "fluid.tests.childComponent",
				options: {
					events: {
			            boiledDouble: {
            			    events: {
            			        event1: "{parentComponent}.events.parentEvent1",
           			            event2: "{parentComponent}.events.parentEvent2"
                			},
                			args: ["{arguments}.event1.0", "{arguments}.event2.1"]
			            }
        			}
				}
            }
        }
    });
	
	fluid.defaults("fluid.tests.eventChild3", {
        gradeNames: ["fluid.eventedComponent", "autoInit"],
		events: {
			boiledDouble: null
		}
	});

The same syntax can be used to boil events from the same component, where the references to source events can be simplified by specifying the events directly without IoC references, as shown in Example 3, since both source events and boiled event are residing on the same component.

Listener boiling

Receiving a different signature in the listener

A more lightweight alternative to injecting or fabricating new events wholesale through boiling is to apply the process to just a single listener. This most often the appropriate approach, especially when the listener enjoys a signature that is not held in common with particularly many other functions around the architecture. The syntax used for listener boiling is actually identical to that applied for defining Invokers. Here is an example of a component which defines a single event, simpleEvent - the firer for it uses a signature int value, boolean flag but we have a listener that requires a different signature Object that, int value where the first argument consists of the component itself and the 2nd argument consists of the supplied first argument:

examples.externalListener = function (that, value) {
    console.log("Received value ", value, " fired from component ", that);
};
 
fluid.defaults("examples.boiledListenerComponent", {
    gradeNames: ["fluid.eventedComponent", "autoInit"],
    events: {
        simpleEvent: null
    },
    listeners: {
        simpleEvent: { // In practice it's unlikely that this listener would be written in the same grade as the event,
                       // since this case there would be little reason for the signature to mismatch. It's more likely 
                       // this configuration would appear in another grade, or supplied as direct options, 
 // subcomponent options, or distributeOptions
            funcName: "examples.externalListener",
            args: ["{that}", "{arguments.0"]
        }
    }
});
 
var that = examples.boiledListenerComponent();
that.fire(5, true); // listener above will log 5, that

Injecting a listener to an event elsewhere in the tree

Similarly to the previous section, rather than transmitting an entire event around the component tree just so that one listener can be attached to it, it is often more efficient (although it can be more confusing for the reader) to simply inject the listener itself. Note that with this built-in syntax the listener can only be injected into (registered as a listener to) a component which is visible as a parent or a sibling of the current component, using a standard upward-matching IoC Context Selector. If you need the more powerful facility to inject a listener downwards (that is, to one or more components that may not yet be constructed) please see the section describing the use of the distributeOptions options block.

fluid.defaults("examples.injectedListenerParent", {
    gradeNames: ["fluid.eventedComponent", "autoInit"],
    events: {
        parentEvent: null,
    },
    components: {
        child: {
            type: "fluid.eventedComponent",
            options: {
                listeners: {
                    "{injectedListenerParent}.events.parentEvent", "examples.externalListener"
                }
            }
        }
    }
});
 
var that = examples.injectedListenerParent();
that.events.parentEvent.fire(that, 5); // strikes above listener through injected listener attachment

Note that both of these kinds of boiling can be applied at the same time - that is, it is possible to adjust the signature of a listener using args at the same time as resolving to it elsewhere in the tree by means of an IoC reference key. Note also that all injected listeners automatically deregistered by the framework when the component which holds their record (e.g. the child component in this example) is destroyed - there is no need for the user to call removeListener manually.