{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Dialog Plugin","type":"basic","slug":"dialog","excerpt":"","body":"The `Dialog()` base class creates a new plugin that can be used to create a dialog plugin. For more information on base classes in general check out the [base class guide](doc:base-classes).\n\nBefore creating your own dialog, be sure to check out the [built-in dialogs](doc:using-dialogs). There might already be an implementation of the dialog you are looking for.\n\n# Creating a Dialog\n\nA basic dialog with close button.\n```javascript\nvar plugin = new Dialog(\"Your Name\", main.consumes, {\n name: \"my-plugin-name\",\n allowClose: true,\n title: \"Some Title\"\n});\n\nplugin.show();\n```\n\nLooks like this.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/I6L42ZjTvuQV4yJLtPV3_2015-02-16_1211.png\",\n \"2015-02-16_1211.png\",\n \"1570\",\n \"292\",\n \"#f2f2f2\",\n \"\"\n ]\n }\n ]\n}\n[/block]\n# Dialog Properties\n\nThe following properties can be passed to the `Dialog()` constructor.\n[block:html]\n{\n \"html\": \"<table>\\n<tr><th>name</th><td>The name of the plugin.</td></tr>\\n<tr><th>left</th><td>The left position of the dialog in pixels.</td></tr>\\n<tr><th>top</th><td>The top position of the dialog in pixels.</td></tr>\\n<tr><th>width</th><td>The width of the dialog in pixels.</td></tr>\\n<tr><th>title</th><td>The title, displayed in the title bar of the dialog.</td></tr>\\n<tr><th>heading</th><td>An optional heading displayed in the body of the dialog.</td></tr>\\n<tr><th>body</th><td>An optional html string set as the body of the dialog.</td></tr>\\n<tr><th>modal</th><td>Whether the user is prevented to interact with the application while the dialog is shown.</td></tr>\\n<tr><th>zindex</th><td>The zIndex of the dialog.</td></tr>\\n<tr><th>allowClose</th><td>Whether to show an x button and close on ESC.</td></tr>\\n<tr><th>elements</th><td>An array of elements to show in the button bar</td></tr>\\n<tr><th>resizable</th><td>Whether the dialog is resizable</td></tr>\\n<tr><th>class</th><td>The css class for the wizard dialog.</td></tr>\\n</table>\"\n}\n[/block]\n\n\n# Adding your own contents\n\nThe easiest way to populate a dialog is by adding custom html and css. The following example loads css from `dialog.css` and adds a div element to the body of the dialog.\n\n```javascript\nvar plugin = new Dialog(\"Your Name\", main.consumes, {\n name: \"my-plugin-name\",\n allowClose: true,\n title: \"Some Title\"\n});\n\nplugin.on(\"draw\", function(e){\n // Insert css\n ui.insertCss(require(\"text!./dialog.css\"), options.staticPrefix, plugin);\n\n // Set some custom HTML\n e.html.innerHTML = \"<div class='myCSS'>Hello World</div>\";\n});\n\nplugin.show();\n```\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/xnXiF78CTuSZusjKTRvg_2015-02-16_1018.png\",\n \"2015-02-16_1018.png\",\n \"1570\",\n \"400\",\n \"#fbfb04\",\n \"\"\n ]\n }\n ]\n}\n[/block]\n# Managing State during the Plugin's Life Time.\n\nIt important to note that the `draw` event only fires once during the life time of a dialog. To update the state of the dialog, use the `show` or `hide` events to manipulate the UI. \n\nThe following example shows a checkbox being reset when the form is shown.\n```javascript\nvar checkbox;\n\nplugin.on(\"draw\", function(e){\n e.html.innerHTML = \"<label><input type='checkbox' name='example' /> Check me</label>\";\n checkbox = e.html.querySelector(\"input\");\n});\n\nplugin.on(\"show\", function(e){\n checkbox.checked = false;\n});\n```\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/NP5FBPTVWu0uR161hP2Q_2015-02-16_1043.png\",\n \"2015-02-16_1043.png\",\n \"1570\",\n \"336\",\n \"\",\n \"\"\n ]\n }\n ]\n}\n[/block]\n# Combining a `Dialog()` with a `Form()`\n\nFor a complete guide on the `Form()` class check out the [Form guide](doc:form). Here, we'll create a simple authentication form to place in our dialog.\n\nFirst we'll create the form in our drawing function.\n```javascript\nauthform = new Form({\n rowheight: 30,\n colwidth: 100,\n edge: \"0 0 0 0\",\n form: [\n {\n type: \"image\",\n src: options.staticPrefix + \"/images/cloud9_logo.png\",\n margin: \"0 0 10px 0\"\n },\n {\n title: \"Username\",\n name: \"username\",\n type: \"textbox\",\n },\n {\n title: \"Password\",\n name: \"password\",\n type: \"password\",\n },\n {\n name: \"loginfail\",\n type: \"label\",\n caption: \"Could not login. Please try again.\",\n style: \"color:rgb(255, 143, 0);margin:5px 0 0 0px;\"\n }\n ]\n});\n```\n\nThen attach the form to the dialog.\n\n```javascript\nvar authform;\nplugin.on(\"draw\", function(e){\n authform = new Form({ ... });\n authform.attachTo(e.html);\n});\n```\n\nMake sure to reset the form when the dialog shows:\n```javascript\nplugin.on(\"show\", function(){\n authform.reset();\n});\n```\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/DN3a6sNQbOYRdDaPmLhA_2015-02-16_1137.png\",\n \"2015-02-16_1137.png\",\n \"1570\",\n \"552\",\n \"#5dadd6\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nIn the following section we'll show how to add buttons to your form. The next code block shows a handler that could be called by a `Login` button.\n\n```javascript\nfunction login(){\n if (!authform.validate())\n return handleInvalidForm();\n \n var json = authform.toJson();\n sendData(json);\n}\n```\n\n# Adding a button bar\n\nYou can configure a bar in the bottom of your dialog and configure it to display a set of form elements. The definition of the elements are the same as the definition of the `Form()` plugin. Only a subset of widgets are supported and unlike the `Form()` element, these widgets are stacked horizontally without labels.\n\nThe following widgets are supported:\n- checkbox\n- dropdown\n- textbox\n- button\n- label\n- image\n- divider\n- filler\n- custom\n\nThe following example creates a button bar with an OK button accompanied by a checkbox on the right, and a small dropdown on the left.\n```javascript\nvar plugin = new Dialog(\"Your Name\", main.consumes, {\n title: \"Example Buttons\",\n allowClose : true,\n elements : [\n { \n type: \"dropdown\", \n id: \"items\",\n width: 150,\n defaultValue: \"example1\",\n items: [\n { value: \"example1\", caption: \"Example 1\" },\n { value: \"example2\", caption: \"Example 2\" },\n { value: \"example3\", caption: \"Example 3\" }\n ]\n },\n { type: \"filler\" },\n { type: \"checkbox\", id: \"all\", caption: \"All my base\" },\n { type: \"button\", id: \"ok\", color: \"green\", caption: \"OK\", \"default\": true }\n ]\n}); \n\nplugin.show();\n```\n\nWhich looks like this:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/hmqOQFhCRzqFKA1tz5j3_2015-02-16_1157.png\",\n \"2015-02-16_1157.png\",\n \"1570\",\n \"408\",\n \"#f1f1f1\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nMake sure to reset the state of these form elements each time the form is displayed.\n\n```javascript\nplugin.on(\"show\", function(){\n plugin.update([\n { id: \"items\", items: [ ... ] }, // Update the items of the dropdown\n { id: \"all\", checked: false } // Set the checkbox to false\n ]);\n});\n```\n\nIn the same way toggle the `visible` attribute to hide and show elements.\n\n# Modal Dialogs\n\nA modal dialog is a dialog that, while shown, prevents the user from interacting with the application in the background. In Cloud9 all modal dialogs show a semi-opaque layer on top of the rest of the UI to indicate that no interaction is possible.\n\nCreate a modal dialog by setting the `modal` property to true.\n```javascript\nvar plugin = new Dialog(\"Your Name\", main.consumes, {\n name: \"my-plugin-name\",\n modal: true,\n title: \"A Modal Dialog\"\n});\n\nplugin.show();\n```\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/j2q35EyQYqL3OWiTHFkZ_2015-02-16_1207.png\",\n \"2015-02-16_1207.png\",\n \"1570\",\n \"272\",\n \"#7b7b7b\",\n \"\"\n ]\n }\n ]\n}\n[/block]\n# Queued Dialogs\n\nWhen you want to create a dialog to notify users of an event, you want to make sure no other dialog is shown at the same time. This is the case for several of the built-in dialogs, such as [alert](http://cloud9-sdk.readme.io/v0.1/docs/using-dialogs#dialog-alert), [confirm](http://cloud9-sdk.readme.io/v0.1/docs/using-dialogs#dialog-confirm) and [question](http://cloud9-sdk.readme.io/v0.1/docs/using-dialogs#dialog-question). To make sure your dialog interacts nicely with any of the other dialogs, instead of calling `show()`, call `queue()` instead. This will only display your dialog if no other queued dialog is shown.\n\nThe following is an example of a custom show method for your plugin.\n```javascript\nfunction show(title, defaultChecked){\n plugin.queue(function(){\n plugin.title = title;\n checkbox.checked = defaultChecked;\n });\n}\n\nplugin.freezePublicAPI({\n /**\n * My custom show Method\n * :::at:::param ...\n */\n show: show\n}\n```\n[block:callout]\n{\n \"type\": \"success\",\n \"title\": \"Use the queue callback\",\n \"body\": \"Instead of setting the state of the dialog in the `show` event, set the state in the callback of the `queue` call. This is important because your dialog *might be queued more than once!*\"\n}\n[/block]\n# A Full Example\n\nThe following code is the full implementation of the alert dialog. It uses most of the APIs discussed in this article.\n\n```javascript\ndefine(function(require, module, exports) {\n main.consumes = [\"Dialog\", \"util\", \"dialog.alert\"];\n main.provides = [\"dialog.alert\"];\n return main;\n \n function main(options, imports, register) {\n var Dialog = imports.Dialog;\n var util = imports.util;\n \n /***** Initialization *****/\n \n var plugin = new Dialog(\"Ajax.org\", main.consumes, {\n name: \"dialog.alert\",\n allowClose: true,\n modal: true,\n elements: [\n { type: \"checkbox\", id: \"dontshow\", caption: \"Don't show again\", visible: false },\n { type: \"filler\" },\n { type: \"button\", id: \"ok\", caption: \"OK\", \"default\": true, onclick: plugin.hide }\n ]\n });\n \n /***** Methods *****/\n \n function show(title, header, msg, onhide, options) {\n return plugin.queue(function(){\n if (header === undefined) {\n plugin.title = \"Notice\";\n header = title;\n msg = msg || \"\";\n }\n else {\n plugin.title = title;\n }\n plugin.heading = util.escapeXml(header);\n plugin.body = options && options.isHTML ? msg : (util.escapeXml(msg) || \"\")\n .replace(/\\n/g, \"<br />\")\n .replace(/(https?:\\/\\/[^\\s]*\\b)/g, \"<a href='$1' target='_blank'>$1</a>\");\n \n plugin.update([\n { id: \"dontshow\", visible: options && options.showDontShow }\n ]);\n \n plugin.once(\"hide\", function(){\n onhide && onhide();\n });\n });\n }\n \n /***** Register *****/\n \n /**\n *\n */\n plugin.freezePublicAPI({\n /**\n * @readonly\n */\n get dontShow(){ \n return plugin.getElement(\"dontshow\").value;\n },\n \n /**\n * Show an alert dialog.\n * \n * @param {String} [title] The title to display\n * @param {String} header The header to display\n * @param {String} [msg] The message to display\n * @param {Function} [onhide] The function to call after it's closed.\n */\n show: show\n });\n \n register(\"\", {\n \"dialog.alert\": plugin\n });\n }\n});\n```","updates":["5832235beab9440f0050216b"],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"54d5635632d98b0d00384b0b","__v":62,"createdAt":"2015-02-07T00:02:28.618Z","user":"54cfa8e1a8a4fd0d00b7fd1d","version":{"version":"0.1","version_clean":"0.1.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"_id":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":10,"createdAt":"2015-02-07T00:59:01.934Z","forked_from":"54d53c7c23010a0d001aca0f","releaseDate":"2015-02-07T00:59:01.934Z"},"parentDoc":null,"category":{"sync":{"isSync":false,"url":""},"pages":["54d5635632d98b0d00384b03","54d5635632d98b0d00384b04","54d5635632d98b0d00384b05","54d5635632d98b0d00384b06","54d5635632d98b0d00384b07","54d5635632d98b0d00384b08","54d5635632d98b0d00384b09","54d5635632d98b0d00384b0a","54d5635632d98b0d00384b0b","54d5635632d98b0d00384b0c","54d5635632d98b0d00384b0d","54d5635632d98b0d00384b0e","54d5635632d98b0d00384b0f","54e2254d22de1c230094b156","54e2255622de1c230094b158","54e23b349d045721004cbc26","54e65455d8873117005c773f","54e6b5c0ba1a980d00e3ecb0","551c12c781b8563500fd998e"],"title":"Plugin Base Classes","slug":"plugin-base-classes","order":7,"from_sync":false,"reference":false,"_id":"54d5635632d98b0d00384afd","project":"54d53c7b23010a0d001aca0c","version":"54d5635532d98b0d00384afb","__v":7,"createdAt":"2015-02-06T23:43:39.709Z"},"githubsync":"","project":"54d53c7b23010a0d001aca0c"}