{"_id":"54d5635632d98b0d00384b04","category":{"_id":"54d5635632d98b0d00384afd","project":"54d53c7b23010a0d001aca0c","version":"54d5635532d98b0d00384afb","__v":7,"pages":["54d5635632d98b0d00384b03","54d5635632d98b0d00384b04","54d5635632d98b0d00384b05","54d5635632d98b0d00384b06","54d5635632d98b0d00384b07","54d5635632d98b0d00384b08","54d5635632d98b0d00384b09","54d5635632d98b0d00384b0a","54d5635632d98b0d00384b0b","54d5635632d98b0d00384b0c","54d5635632d98b0d00384b0d","54d5635632d98b0d00384b0e","54d5635632d98b0d00384b0f","54e2254d22de1c230094b156","54e2255622de1c230094b158","54e23b349d045721004cbc26","54e65455d8873117005c773f","54e6b5c0ba1a980d00e3ecb0","551c12c781b8563500fd998e"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-06T23:43:39.709Z","from_sync":false,"order":7,"slug":"plugin-base-classes","title":"Plugin Base Classes"},"parentDoc":null,"project":"54d53c7b23010a0d001aca0c","user":"54cfa8e1a8a4fd0d00b7fd1d","__v":83,"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"},"updates":["55590ed2eb56ae2f00f7154b","55912a8d81614f0d0039e4b2","55e3fe7ee1dd8b0d0086eb96"],"next":{"pages":[],"description":""},"createdAt":"2015-02-06T23:57:34.086Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"The `Panel()` base class creates a new plugin that can be used to create a panel that sits on the left or right side of the Cloud9 user interface. For more information on base classes in general check out the [base class guide](doc:base-classes).\n\nPanels are containers that can be hidden and shown by pressing the button that has a caption describing the functionality of the panel. Panels can be enabled and disabled via the Window menu which hides and shows the button.\n\nThe screenshot below shows three panels on the left and three on the right. On the left side the \"Workspace\" panel is active and on the right side the \"Debugger\" panel is active. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/BwXooDE2QBi6UQAeGoYZ_c9panels2.png\",\n        \"c9panels2.png\",\n        \"2744\",\n        \"1650\",\n        \"\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n# Creating a Panel\n\nA basic panel on the left side.\n\n```\nvar plugin = new Panel(\"Your Name\", main.consumes, {\n    index: 300,\n    caption: \"The Button Caption\"\n});\n```\n\nLooks like this.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/NwTYxyGwTBuNjBvLDlS7_2015-03-09_1925.png\",\n        \"2015-03-09_1925.png\",\n        \"351\",\n        \"379\",\n        \"#373737\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nIn the same way as with [menus](doc:menus) the `index` property determines the vertical position of the button relative to any other panel plugin.\n\n# Panel Properties\n[block:html]\n{\n  \"html\": \"<table>\\n  <tr><th>index</th><td>Determine the vertical position of the button.</td></tr>\\n  <tr><th>caption</th><td>Sets the text displayed on the button.</td></tr>\\n<tr><th>width</th><td>Sets the width of your panel in number of pixels. Note that this is only set if your panel is the first to open, otherwise the existing with of the panel that is open is used.</td></tr>\\n<tr><th>minWidth</th><td>Sets the minimal width that your panel can take in pixels.</td></tr>\\n<tr><th>where</th><td>Takes \\\"left\\\" or \\\"right\\\" as values to determine the position of the panel.</td></tr>\\n<tr><th>buttonCSSClass</th><td>Takes a string that is set as the css class of the panel container.</td></tr>\\n<tr><th>panelCSSClass</th><td>Takes a string that is set as the css class of the panel button</td></tr>\\n<tr><th>autohide</th><td>Takes a boolean to specify which animation to use when hiding the panel.</td></tr>\\n</table>\"\n}\n[/block]\n# Adding your own contents\n\nThe easiest way to populate a panel is by adding custom html and css. The following example loads css from panel.css and adds a div element to the body of the panel.\n\n```\nvar plugin = new Panel(\"Your Name\", main.consumes, {\n    index: 300,\n    caption: \"The Button Caption\"\n});\n\nplugin.on(\"draw\", function(e){\n    // Insert css\n    ui.insertCss(require(\"text!./panel.css\"), options.staticPrefix, plugin);\n\n    // Set some custom HTML\n    e.html.innerHTML = \"<div class='myCSS'>Hello World</div>\";\n});\n\n// This is only here to make the example run \n// for when you are executing this in the console.\nplugin.load(); \n```\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/kap4ZgLITU6cpIf3sRau_2015-03-09_1925-b.png\",\n        \"2015-03-09_1925-b.png\",\n        \"351\",\n        \"379\",\n        \"#f8f807\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n# Showing and Hiding Panels\n\nUsers can hide and show panels by clicking on the panel button in one of the side bars. You can control this behavior and customize it to your needs.\n\nThe following common use cases are used by Cloud9:\n- *Normal* - Show the panel when clicking on the button. It won't hide until you click the button again.\n- *Auto Hide* - Show the panel when clicking on the button. It will hide automatically when any other element gets focus. The moving away animation is different.\n- *Auto Hide + Sticky* - Show the panel like in *Normal* mode when using the button. Have *Auto Hide* behavior when using the key binding to show the panel.\n\n## Auto Hide\n\nTo implement a panel that hides automatically when the user focusses something outside of the panel you should set the `autohide` property to `false` and call `plugin.hide()` when an element inside your panel is blurred. \n\n```\nfunction onblur(e) {\n    if (!plugin.aml.visible)\n        return;\n    \n    var to = e.toElement;\n    if (!to || apf.isChildOf(plugin.aml, to, true)) {\n        return;\n    }\n    \n    setTimeout(function() { plugin.hide() }, 10);\n}\napf.addEventListener(\"movefocus\", onblur);\n```\n\n## Auto Hide + Sticky\n\nTo implement the combination of auto hide and a sticky button, toggle the autohide property based on whether the button was used to show the panel.\n\n```\nplugin.on(\"show\", function(\n    plugin.autohide = !e.button;\n});\n```\n\nMake sure to check the `autohide` property in the `onblur()` function.\n\n```\nfunction onblur(e) {\n    if (!plugin.aml.visible || !plugin.autohide)\n        return;\n```\n\n# Setting the Command\n\nTo set the command that toggles your panel call the `setCommand()` method on your panel plugin. The object that you pass is the same as any [other command](doc:commands).\n\n```\nplugin.setCommand({\n    name: \"commandName\",\n    hint: \"Description of the command\",\n    bindKey: { mac: \"Command-U\", win: \"Ctrl-I\" }\n});\n```\n\n# Panels API\n\nThe `panels` plugin offers events and methods to listen to state changes and to manipulate the state of the panels. Each panel has a name and this name is used to reference panels when needed.\n\n## Resize Contents\n\nAfter the panel has animated and is fully visible you'll often want to adjust the size of some of the elements in your panel. This is especially true if you are using [ace widgets](doc:ace-tree).\n\n```\npanels.on(\"afterAnimate\", function(e) {\n    if (panels.isActive(\"yourPanelName\") && treeWidget)\n        treeWidget.resize();\n});\n```\n\n## Showing and Hiding panels\n\nYou can retrieve the currently active panel(s) using the `panels.activePanels` property which returns an array that contains the names of the active panels.\n\nTo activate a panel call the `activate()` method and use `deactivate()` to hide a panel.\n\n```\npanels.activate(\"tree\");\npanels.deactivate(\"tree\");\n```\n\nExternal plugins can best monitor the following two events to keep track of a specific panel being shown or hidden. The `<Name>` is the name of the panel with a capital first letter.\n\n```\npanels.on(\"showPanel<Name>\", function(e) {});\npanels.on(\"hidePanel<Name>\", function(e) {});\n```\n\n## Enabling and Disabling Panels\n\nWhen a panel is enabled its button is shown in the left or right area of the screen.\n\n```\npanels.enablePanel(\"tree\");\n```\n\nThe button of a disabled panel is hidden and a user can enable a panel via the Windows menu.\n\n```\npanels.disablePanel(\"tree\");\n```\n\n# A Full Example\n\n```\ndefine(function(require, module, exports) {\n    main.consumes = [\"Panel\", \"ui\"];\n    main.provides = [\"my-panel\"];\n    return main;\n\n    function main(options, imports, register) {\n        var Panel = imports.Panel;\n        var ui = imports.ui;\n\n        /***** Initialization *****/\n\n        var plugin = new Panel(\"Your Name\", main.consumes, {\n            index: 300,\n            caption: \"The Button Caption\"\n        });\n        \n        plugin.on(\"draw\", function(e){\n            // Insert css\n            ui.insertCss(require(\"text!./panel.css\"), options.staticPrefix, plugin);\n        \n            // Set some custom HTML\n            e.html.innerHTML = \"<div class='myCSS'>Hello World</div>\";\n        });\n\n        /***** Register *****/\n\n        plugin.freezePublicAPI({\n            \n        });\n\n        register(\"\", {\n            \"my-panel\": plugin\n        });\n    }\n});\n```","excerpt":"","slug":"panel","type":"basic","title":"Panel Plugin"}
The `Panel()` base class creates a new plugin that can be used to create a panel that sits on the left or right side of the Cloud9 user interface. For more information on base classes in general check out the [base class guide](doc:base-classes). Panels are containers that can be hidden and shown by pressing the button that has a caption describing the functionality of the panel. Panels can be enabled and disabled via the Window menu which hides and shows the button. The screenshot below shows three panels on the left and three on the right. On the left side the "Workspace" panel is active and on the right side the "Debugger" panel is active. [block:image] { "images": [ { "image": [ "https://files.readme.io/BwXooDE2QBi6UQAeGoYZ_c9panels2.png", "c9panels2.png", "2744", "1650", "", "" ] } ] } [/block] # Creating a Panel A basic panel on the left side. ``` var plugin = new Panel("Your Name", main.consumes, { index: 300, caption: "The Button Caption" }); ``` Looks like this. [block:image] { "images": [ { "image": [ "https://files.readme.io/NwTYxyGwTBuNjBvLDlS7_2015-03-09_1925.png", "2015-03-09_1925.png", "351", "379", "#373737", "" ] } ] } [/block] In the same way as with [menus](doc:menus) the `index` property determines the vertical position of the button relative to any other panel plugin. # Panel Properties [block:html] { "html": "<table>\n <tr><th>index</th><td>Determine the vertical position of the button.</td></tr>\n <tr><th>caption</th><td>Sets the text displayed on the button.</td></tr>\n<tr><th>width</th><td>Sets the width of your panel in number of pixels. Note that this is only set if your panel is the first to open, otherwise the existing with of the panel that is open is used.</td></tr>\n<tr><th>minWidth</th><td>Sets the minimal width that your panel can take in pixels.</td></tr>\n<tr><th>where</th><td>Takes \"left\" or \"right\" as values to determine the position of the panel.</td></tr>\n<tr><th>buttonCSSClass</th><td>Takes a string that is set as the css class of the panel container.</td></tr>\n<tr><th>panelCSSClass</th><td>Takes a string that is set as the css class of the panel button</td></tr>\n<tr><th>autohide</th><td>Takes a boolean to specify which animation to use when hiding the panel.</td></tr>\n</table>" } [/block] # Adding your own contents The easiest way to populate a panel is by adding custom html and css. The following example loads css from panel.css and adds a div element to the body of the panel. ``` var plugin = new Panel("Your Name", main.consumes, { index: 300, caption: "The Button Caption" }); plugin.on("draw", function(e){ // Insert css ui.insertCss(require("text!./panel.css"), options.staticPrefix, plugin); // Set some custom HTML e.html.innerHTML = "<div class='myCSS'>Hello World</div>"; }); // This is only here to make the example run // for when you are executing this in the console. plugin.load(); ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/kap4ZgLITU6cpIf3sRau_2015-03-09_1925-b.png", "2015-03-09_1925-b.png", "351", "379", "#f8f807", "" ] } ] } [/block] # Showing and Hiding Panels Users can hide and show panels by clicking on the panel button in one of the side bars. You can control this behavior and customize it to your needs. The following common use cases are used by Cloud9: - *Normal* - Show the panel when clicking on the button. It won't hide until you click the button again. - *Auto Hide* - Show the panel when clicking on the button. It will hide automatically when any other element gets focus. The moving away animation is different. - *Auto Hide + Sticky* - Show the panel like in *Normal* mode when using the button. Have *Auto Hide* behavior when using the key binding to show the panel. ## Auto Hide To implement a panel that hides automatically when the user focusses something outside of the panel you should set the `autohide` property to `false` and call `plugin.hide()` when an element inside your panel is blurred. ``` function onblur(e) { if (!plugin.aml.visible) return; var to = e.toElement; if (!to || apf.isChildOf(plugin.aml, to, true)) { return; } setTimeout(function() { plugin.hide() }, 10); } apf.addEventListener("movefocus", onblur); ``` ## Auto Hide + Sticky To implement the combination of auto hide and a sticky button, toggle the autohide property based on whether the button was used to show the panel. ``` plugin.on("show", function( plugin.autohide = !e.button; }); ``` Make sure to check the `autohide` property in the `onblur()` function. ``` function onblur(e) { if (!plugin.aml.visible || !plugin.autohide) return; ``` # Setting the Command To set the command that toggles your panel call the `setCommand()` method on your panel plugin. The object that you pass is the same as any [other command](doc:commands). ``` plugin.setCommand({ name: "commandName", hint: "Description of the command", bindKey: { mac: "Command-U", win: "Ctrl-I" } }); ``` # Panels API The `panels` plugin offers events and methods to listen to state changes and to manipulate the state of the panels. Each panel has a name and this name is used to reference panels when needed. ## Resize Contents After the panel has animated and is fully visible you'll often want to adjust the size of some of the elements in your panel. This is especially true if you are using [ace widgets](doc:ace-tree). ``` panels.on("afterAnimate", function(e) { if (panels.isActive("yourPanelName") && treeWidget) treeWidget.resize(); }); ``` ## Showing and Hiding panels You can retrieve the currently active panel(s) using the `panels.activePanels` property which returns an array that contains the names of the active panels. To activate a panel call the `activate()` method and use `deactivate()` to hide a panel. ``` panels.activate("tree"); panels.deactivate("tree"); ``` External plugins can best monitor the following two events to keep track of a specific panel being shown or hidden. The `<Name>` is the name of the panel with a capital first letter. ``` panels.on("showPanel<Name>", function(e) {}); panels.on("hidePanel<Name>", function(e) {}); ``` ## Enabling and Disabling Panels When a panel is enabled its button is shown in the left or right area of the screen. ``` panels.enablePanel("tree"); ``` The button of a disabled panel is hidden and a user can enable a panel via the Windows menu. ``` panels.disablePanel("tree"); ``` # A Full Example ``` define(function(require, module, exports) { main.consumes = ["Panel", "ui"]; main.provides = ["my-panel"]; return main; function main(options, imports, register) { var Panel = imports.Panel; var ui = imports.ui; /***** Initialization *****/ var plugin = new Panel("Your Name", main.consumes, { index: 300, caption: "The Button Caption" }); plugin.on("draw", function(e){ // Insert css ui.insertCss(require("text!./panel.css"), options.staticPrefix, plugin); // Set some custom HTML e.html.innerHTML = "<div class='myCSS'>Hello World</div>"; }); /***** Register *****/ plugin.freezePublicAPI({ }); register("", { "my-panel": plugin }); } }); ```