Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.
The Infusion framework defines an event system which is used by many of its components.
By default, most Fluid component events are multi-cast (that is the event is fired to all registered listeners), but some events may be one of the following two special types:
The event will fire to only one listener.
If the implementer tries to attach multiple listeners to a unicast event, only the last registered listener will receive the event.
The event represents a "preventable" action.
The listeners may each return a boolean value of false, representing both
that further listeners should fail to be queried, and
that the operation represented by the event should be cancelled.
This is similar to the default semantics on browser events.
Registers the supplied listener with this firer. The listener is a function of a particular signature which is determined between the firer and listener of an event. The namespace parameter is an optional String which defines a key representing a particular "function" of the listener. At most one listener may be registered with a firer with a particular key. This is a similar system to that operated by the JQuery namespaced events system. For an event firer which is of type unicast, the namespace argument will be ignored and will default to a fixed value.
The use of namespaces is highly recommended.
Supplies either the same listener object which was previously supplied to addListener, or else the String representing its namespace key. The designated listener will be removed from the list of registered listeners for this fierer.
Fires an event to all the registered listeners. They will each be invoked with the exact argument list which is supplied to fireEvent itself. If this is a preventable event, fireEvent may return true indicating that a listener has requested to prevent the effect represented by this event.
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).
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:
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.