{"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"}