Infusion Event System

Overview

Events and options merging

In order to make it as easy as possible for Fluid component authors to define their event types and accept and manage listeners, Fluid event firers have a special status during the Fluid options merging process.

events in options

A component may declare as part of its options structure, a top-level structure named events whose keys correspond to event types that this component wishes to support, and whose values are either null or the string values "unicast" or "preventable" corresponding to the accepted arguments for getEventFirer. As part of the normal construction process of fluid.initView(), the top-level that object for the component will automatically have constructed a corresponding event firer object for each one of these events.

For example, the events section of the default options for the Reorderer component indicates that the Reorderer supports 6 events of the listed types, of which one, onBeginMove represents a "preventable" event - a listener may countermand the beginMove effect by returning true when the event is received. If the top-level that constructed by fluid.initView() is stored in a variable named thatReorderer, these events and firers will be accessible at its top level by making a call for example of the form thatReorderer.onSelect.fire(item).


events: {
    onShowKeyboardDropWarning: null,
    onSelect: null,
    onBeginMove: "preventable",
    onMove: null,
    afterMove: null,
    onHover: null
}

listeners in options

Both as part of defaults, and also as supplied instantion options, a fluid component can accept a structure named listeners, whose keys are taken from the set listed in the events structure, and whose values are either single listeners or arrays of listeners. For example, the following structure as part of an options object:


listeners: {
    onMove: function(item, requestedPosition) {
        fluid.moduleLayout.updateLayout(item, requestedPosition.element, 
                    requestedPosition.position, layout);
    }
}

indicates that the supplied listener should be registered for the event onMove.

Keys for listeners in options may also be qualified with namespaces following a period character . - this follows the jQuery convention for namespaced events.

For example,


listeners: {
    "onShowKeyboardDropWarning.setPosition": defaultOnShowKeyboardDropWarning
}

represents that the function stored in defaultOnShowKeyboardDropWarning should be attached as a listener to the event onShowKeyboardDropWarning under the namespace setPosition. The use of namespaces for event listeners is highly recommended.