Added by Anastasia Cheetham, last edited by Justin Obara on Apr 30, 2009  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Overview

The Fluid framework defines an event system which is used by many of its components. For an overview, see Infusion Event System. This page provides specific information for anyone implementing Fluid components in their user interface.

Fluid components fire events at interesting moments in their life cycle. Implementers can take advantage of this by attaching listeners to these events if they so desire. For example, the Uploader component fires an afterUploadComplete event once a file upload has completed. Implementors could choose to attach a listener to this event that displays a "Complete" message to the users.

Component Events

Each Fluid component defines its own events. Implementers must consult either the documentation for the component, or the source code, to determine what events a particular component will fire.

  • In the documentation, the events are described in the "Supported Events" section of the API page for the component in question.
  • In the source code, the default values for the supported events are defined in the events object passed to fluid.defaults().
On This Page
See Also
Still need help?

Join the infusion-users mailing list and ask your questions there.

Registering Listeners

Implementers can register listeners for events using the component creator function options parameter. A listeners object should be included in the options object defining the listener function(s) for the desired event, for example:

var opts = {
    listeners: {
        afterFileQueued: myQueueListenerFunc,
        afterUploadComplete: function (args) {
            ...
        },
        onFileProgress: [listener1, listener2]
    }
};

var myUploader = fluid.uploader(myContainer, opts);

Listeners may also be added and removed dynamically at any point in the component's lifecycle after it has been constructed, by accessing the event firers which are created under the top-level that, under the name events. For example, to achieve the same effect as the first member of the options block above, one could instead write 

    myUploader.events.afterFileQueued.addListener(myQueueListenerFunc);

Note that it is usually easier and more reliable for component users to register listeners in the options block as shown above. More advanced information on the event system, mostly suitable for component developers, can be found at Events for Component Developers.

Note that the arguments supported by each event are defined by the component itself. Implementors must consult the documentation for the component.

Event Types

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:

Type Description
unicast 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.
preventable 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.

The individual component API pages document which events are of these types.