{"_id":"54ded495e8e35a0d007551a0","parentDoc":null,"version":{"_id":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":10,"forked_from":"54d53c7c23010a0d001aca0f","createdAt":"2015-02-07T00:59:01.934Z","releaseDate":"2015-02-07T00:59:01.934Z","categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"user":"54cfa8e1a8a4fd0d00b7fd1d","__v":22,"project":"54d53c7b23010a0d001aca0c","category":{"_id":"54d5635632d98b0d00384afe","__v":19,"version":"54d5635532d98b0d00384afb","pages":["54d5635732d98b0d00384b12","54d5635732d98b0d00384b13","54d5635732d98b0d00384b14","54d847c125e90a0d00db551f","54d995416a09052100a6b6d7","54d995534c49f40d00dff98a","54d9956b4c49f40d00dff98c","54dbce210e553a0d00dc1d09","54dcdf7bac05560d00335a15","54dd133c08f6b61700a691f7","54dd136108f6b61700a691fa","54dd27e0db3b362100131294","54dd2838ca1e5219007e9dcb","54dd28c8db3b362100131296","54deb1133a91410d001b1791","54deb134c4a3570d009d4a60","54dec5c0c2b4b70d009c3f05","54ded495e8e35a0d007551a0","54ded57d8e7b000d007c7f31","551447a90edb420d0050016e","551c4369ff892b3700d1c616"],"project":"54d53c7b23010a0d001aca0c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-06T23:44:18.708Z","from_sync":false,"order":4,"slug":"api-plugins","title":"API Plugins"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-02-14T04:52:37.978Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"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](#a-separate-event-emitter).\n\n# Emitting events\n\nEmit plugins using the `emit()` function. You get a reference to this function by calling `getEmitter()` on the plugin.\n\n```\nvar plugin = new Plugin(\"Your Name\", main.consumes);\nvar emit = plugin.getEmitter();\n```\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"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.\",\n  \"title\": \"Only emit events from within your plugin\"\n}\n[/block]\nThe `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.\n\nThe `emit()` function takes two arguments; the event name and an optional event object.\n\n```\nemit(\"beforeExample\", { data: [1, 2, 3] });\n```\n\n## Sticky Events\n\nSticky 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.\n\nMake an event *sticky* by calling `emit.sticky()`.\n```\nemit.sticky(\"initialized\", { worker: worker });\n```\n\nThen whenever someone adds a listener for this event it is called immediately.\n\n```\nplugin.on(\"initialized\", function(e){\n    console.log(\"This is called first\");\n});\nconsole.log(\"This is called second\");\n```\n\n# Listening to events\n\nSimilar to Node.js use the `on()` and `off()` methods to set and remove events.\n\n```\nplugin.on(\"beforeExample\", function(e){\n    console.log(\"Event fired\", e.data);\n}, otherPlugin);\n```\nThe 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.\n\n```\nplugin.off(\"beforeExample\", someFunction);\n```\n\n## Adding a One-Time Listener\n\nThe `once()` method lets you set a listener that is only called once and is then removed.\n\n```\nfs.once(\"beforeFileWrite\", function(e){\n    console.log(e.path);\n});\n```\n\n## Listening to Event Listeners being Added & Removed\n\nThe `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.\n\nFor instance you could use this feature to set an expensive listener only if another plugin is  listening to it.\n\n```\nplugin.on(\"newListener\", function(type, handler){\n    if (type == \"something\") {\n        doSomething();\n    }\n});\n```\n\nSimilarly you can listen to removeListener.\n\n```\nplugin.on(\"removeListener\", function(type, handler){\n    if (type == \"something\") {\n        dontDoSomething();\n    }\n});\n```\n\n## Max Listeners\n\nBy 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.\n\n```\nvar emit = plugin.getEmitter();\nemit.setMaxListeners(100);\n```\n\n# A Separate Event Emitter\n\nSometimes you need an additional event emitter for your plugin. You can grab the EventEmitter constructor as follows.\n\n```\nvar EventEmitter = require(\"events\").EventEmitter\n```\n\nThen instantiate a new emitter and use that in your code.\n\n```\nvar emitter = new EventEmitter();\n\nemitter.on(\"eventName\", function(){\n    console.log(\"here\");\n});\nemitter.emit(\"eventName\");\n```","excerpt":"","slug":"events","type":"basic","title":"Events"}
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](#a-separate-event-emitter). # 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(); ``` [block:callout] { "type": "danger", "body": "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.", "title": "Only emit events from within your plugin" } [/block] 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"); ```