Overview

The Fluid framework defines a event system which is used by many of its components. For an overview, see Infusion Event System. This page provides specific information for developers who are creating Fluid components.

  • Component developers must decide what events their component will fire, based on what it does, and what they think that component users would be interested in being notified of.
  • Component developers declare their events in the defaults for the component.
  • The component initialization process will instantiate firers for the declared events and attached them to the component's that object.
  • Component developers must fire the events at the appropriate times.
  • Component developers may add listeners to the firers, if desired.

The rest of this page discusses these points in more detail.


Declaring Events

Naming

The general convention for naming events is to use on and after prefixes for events that happen before and after certain things, such as onBeginEdit or afterTransferComplete.

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

Event Types

Events may optionally be declared as one of two possible special types:

Declaring events

Component developers declare the events their component will fire using the events object in the defaults for their component, for example:

fluid.defaults("fluid.myComponentName", {
    events: {
        onBeginEdit: null;
        afterTransferComplete: null;
    }
});


The events object's keys correspond to the event types that this component wishes to support, and the values are either null or the string values "unicast" or "preventable."


Instantiating Event Firers in a Component

A component's creator function must call fluid.initView() to initialize the component's view:

fluid.myComponent = function (container, options) {
    var that = fluid.initView("fluid.myComponent", container, options);
    ...
};

The fluid.initView() function automatically instantiates event firers for all of the events declared in the defaults, and attaches them to the returned that object.


Adding Listeners

After fluid.initView() has instantiated the event firers, the component itself may wish to attach listeners to events using the event firer's addListener() function, for example:

var bindEvents = function (that) {
    that.events.onBeginEdit.addListener(function() {
        ...
    });

    that.events.afterTransferComplete.addListener(transferCompleteHandlerFunc);
};

Firing Events

The component is responsible for firing the events at the right time, using the event firer's fire() function, for example:

var edit = function () {
    that.events.onBeginEdit.fire(args);
    ... (handle editing) ...
};

var transfer = function () {
    ... (handle transfer) ...
    that.events.afterTransferComplete.fire(args);
};

The arguments passed to fire() are arbitrary, and component developers are free to determine what information should be passed on to event listeners by the event firer.