Events are an integral part of Cloud9's plugin system. Events provide hooks that other plugins can use to add or alter functionality. Each plugin has an event emitter and you can create an instance of an EventEmitter() for other uses as well - which is discussed below.

Emitting events

Emit plugins using the emit() function. You get a reference to this function by calling getEmitter() on the plugin.

var plugin = new Plugin("Your Name", main.consumes);
var emit = plugin.getEmitter();

❗️

Only emit events from within your plugin

Events must only be emitted by your plugin itself (or any of it's sub classes). This helps keep code flows clean and prevents hacky solutions that will eventually cause spaghetti code and code paths with unexpected consequences.

The getEmitter() method is available until you call freezePublicAPI(), after which that function will no longer be provided. This secures your plugin from external plugins that might otherwise try to fire an event on your plugin.

The emit() function takes two arguments; the event name and an optional event object.

emit("beforeExample", { data: [1, 2, 3] });

Sticky Events

Sticky events are events that will call event handlers that are set immediately. One example is the ready event of the tabManager. Once the tabManager is ready, setting an event listener for the ready event will be called immediately, because the tabManager is indeed ready.

Make an event sticky by calling emit.sticky().

emit.sticky("initialized", { worker: worker });

Then whenever someone adds a listener for this event it is called immediately.

plugin.on("initialized", function(e){
    console.log("This is called first");
});
console.log("This is called second");

Listening to events

Similar to Node.js use the on() and off() methods to set and remove events.

plugin.on("beforeExample", function(e){
    console.log("Event fired", e.data);
}, otherPlugin);

The third argument is a reference to the plugin that is setting the event listener. When the otherPlugin is unloaded this event handler is automatically cleared.

plugin.off("beforeExample", someFunction);

Adding a One-Time Listener

The once() method lets you set a listener that is only called once and is then removed.

fs.once("beforeFileWrite", function(e){
    console.log(e.path);
});

Listening to Event Listeners being Added & Removed

The newListener and removeListener events are fired each time a new listener is added or an existing listener is removed. This allows you to add special handling around event listeners to your plugin.

For instance you could use this feature to set an expensive listener only if another plugin is listening to it.

plugin.on("newListener", function(type, handler){
    if (type == "something") {
        doSomething();
    }
});

Similarly you can listen to removeListener.

plugin.on("removeListener", function(type, handler){
    if (type == "something") {
        dontDoSomething();
    }
});

Max Listeners

By default each event can only have ten listeners set at one time. If there are more than 10 listeners the on() method will throw an exception. This is a great way to find bugs where listeners are set but never removed or code is unexpectedly called more often. However in some cases you'll expect more than 10 listeners on a certain event. You can set the max number of listeners for your plugin as follows.

var emit = plugin.getEmitter();
emit.setMaxListeners(100);

A Separate Event Emitter

Sometimes you need an additional event emitter for your plugin. You can grab the EventEmitter constructor as follows.

var EventEmitter = require("events").EventEmitter

Then instantiate a new emitter and use that in your code.

var emitter = new EventEmitter();

emitter.on("eventName", function(){
    console.log("here");
});
emitter.emit("eventName");