Events for Component Developers

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.