Dialog Plugin

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). Before 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. # Creating a Dialog A basic dialog with close button. ```javascript var plugin = new Dialog("Your Name", main.consumes, { name: "my-plugin-name", allowClose: true, title: "Some Title" }); plugin.show(); ``` Looks like this. [block:image] { "images": [ { "image": [ "https://files.readme.io/I6L42ZjTvuQV4yJLtPV3_2015-02-16_1211.png", "2015-02-16_1211.png", "1570", "292", "#f2f2f2", "" ] } ] } [/block] # Dialog Properties The following properties can be passed to the `Dialog()` constructor. [block:html] { "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>" } [/block] # Adding your own contents The 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. ```javascript var plugin = new Dialog("Your Name", main.consumes, { name: "my-plugin-name", allowClose: true, title: "Some Title" }); plugin.on("draw", function(e){ // Insert css ui.insertCss(require("text!./dialog.css"), options.staticPrefix, plugin); // Set some custom HTML e.html.innerHTML = "<div class='myCSS'>Hello World</div>"; }); plugin.show(); ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/xnXiF78CTuSZusjKTRvg_2015-02-16_1018.png", "2015-02-16_1018.png", "1570", "400", "#fbfb04", "" ] } ] } [/block] # Managing State during the Plugin's Life Time. It 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. The following example shows a checkbox being reset when the form is shown. ```javascript var checkbox; plugin.on("draw", function(e){ e.html.innerHTML = "<label><input type='checkbox' name='example' /> Check me</label>"; checkbox = e.html.querySelector("input"); }); plugin.on("show", function(e){ checkbox.checked = false; }); ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/NP5FBPTVWu0uR161hP2Q_2015-02-16_1043.png", "2015-02-16_1043.png", "1570", "336", "", "" ] } ] } [/block] # Combining a `Dialog()` with a `Form()` For 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. First we'll create the form in our drawing function. ```javascript authform = new Form({ rowheight: 30, colwidth: 100, edge: "0 0 0 0", form: [ { type: "image", src: options.staticPrefix + "/images/cloud9_logo.png", margin: "0 0 10px 0" }, { title: "Username", name: "username", type: "textbox", }, { title: "Password", name: "password", type: "password", }, { name: "loginfail", type: "label", caption: "Could not login. Please try again.", style: "color:rgb(255, 143, 0);margin:5px 0 0 0px;" } ] }); ``` Then attach the form to the dialog. ```javascript var authform; plugin.on("draw", function(e){ authform = new Form({ ... }); authform.attachTo(e.html); }); ``` Make sure to reset the form when the dialog shows: ```javascript plugin.on("show", function(){ authform.reset(); }); ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/DN3a6sNQbOYRdDaPmLhA_2015-02-16_1137.png", "2015-02-16_1137.png", "1570", "552", "#5dadd6", "" ] } ] } [/block] In 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. ```javascript function login(){ if (!authform.validate()) return handleInvalidForm(); var json = authform.toJson(); sendData(json); } ``` # Adding a button bar You 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. The following widgets are supported: - checkbox - dropdown - textbox - button - label - image - divider - filler - custom The following example creates a button bar with an OK button accompanied by a checkbox on the right, and a small dropdown on the left. ```javascript var plugin = new Dialog("Your Name", main.consumes, { title: "Example Buttons", allowClose : true, elements : [ { type: "dropdown", id: "items", width: 150, defaultValue: "example1", items: [ { value: "example1", caption: "Example 1" }, { value: "example2", caption: "Example 2" }, { value: "example3", caption: "Example 3" } ] }, { type: "filler" }, { type: "checkbox", id: "all", caption: "All my base" }, { type: "button", id: "ok", color: "green", caption: "OK", "default": true } ] }); plugin.show(); ``` Which looks like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/hmqOQFhCRzqFKA1tz5j3_2015-02-16_1157.png", "2015-02-16_1157.png", "1570", "408", "#f1f1f1", "" ] } ] } [/block] Make sure to reset the state of these form elements each time the form is displayed. ```javascript plugin.on("show", function(){ plugin.update([ { id: "items", items: [ ... ] }, // Update the items of the dropdown { id: "all", checked: false } // Set the checkbox to false ]); }); ``` In the same way toggle the `visible` attribute to hide and show elements. # Modal Dialogs A 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. Create a modal dialog by setting the `modal` property to true. ```javascript var plugin = new Dialog("Your Name", main.consumes, { name: "my-plugin-name", modal: true, title: "A Modal Dialog" }); plugin.show(); ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/j2q35EyQYqL3OWiTHFkZ_2015-02-16_1207.png", "2015-02-16_1207.png", "1570", "272", "#7b7b7b", "" ] } ] } [/block] # Queued Dialogs When 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. The following is an example of a custom show method for your plugin. ```javascript function show(title, defaultChecked){ plugin.queue(function(){ plugin.title = title; checkbox.checked = defaultChecked; }); } plugin.freezePublicAPI({ /** * My custom show Method * @param ... */ show: show } ``` [block:callout] { "type": "success", "title": "Use the queue callback", "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!*" } [/block] # A Full Example The following code is the full implementation of the alert dialog. It uses most of the APIs discussed in this article. ```javascript define(function(require, module, exports) { main.consumes = ["Dialog", "util", "dialog.alert"]; main.provides = ["dialog.alert"]; return main; function main(options, imports, register) { var Dialog = imports.Dialog; var util = imports.util; /***** Initialization *****/ var plugin = new Dialog("Ajax.org", main.consumes, { name: "dialog.alert", allowClose: true, modal: true, elements: [ { type: "checkbox", id: "dontshow", caption: "Don't show again", visible: false }, { type: "filler" }, { type: "button", id: "ok", caption: "OK", "default": true, onclick: plugin.hide } ] }); /***** Methods *****/ function show(title, header, msg, onhide, options) { return plugin.queue(function(){ if (header === undefined) { plugin.title = "Notice"; header = title; msg = msg || ""; } else { plugin.title = title; } plugin.heading = util.escapeXml(header); plugin.body = options && options.isHTML ? msg : (util.escapeXml(msg) || "") .replace(/\n/g, "<br />") .replace(/(https?:\/\/[^\s]*\b)/g, "<a href='$1' target='_blank'>$1</a>"); plugin.update([ { id: "dontshow", visible: options && options.showDontShow } ]); plugin.once("hide", function(){ onhide && onhide(); }); }); } /***** Register *****/ /** * */ plugin.freezePublicAPI({ /** * @readonly */ get dontShow(){ return plugin.getElement("dontshow").value; }, /** * Show an alert dialog. * * @param {String} [title] The title to display * @param {String} header The header to display * @param {String} [msg] The message to display * @param {Function} [onhide] The function to call after it's closed. */ show: show }); register("", { "dialog.alert": plugin }); } }); ```

Cloud9 SDK

Getting Started

Development Workflow

License

Cloud9 Bundle

API Plugins

Editor Plugins

Runners & Debuggers

Plugin Base Classes

User Interface

Ace (text editor)

Language Modes

Language Tooling

Installer

Other