Jump to: navigation, search

Difference between revisions of "Orion/Dialog Support"

(Defining the template and referring to DOM objects)
(Dialogs (modal and modeless))
Line 8: Line 8:
 
Dialogs are implemented as an object which uses the <tt>Dialog</tt> prototype.  By convention, most Orion dialogs define a constructor whose sole parameter is an options object describing how the dialog is to be used.  This will be shown in the example code, but keep in mind that the client-facing API of the dialog is completely up to the developer.  The main requirement for implementation is that the <tt>Dialog</tt> prototype be used and the life-cycle methods called appropriately.  An example is the best way to demonstrate the behavior.  
 
Dialogs are implemented as an object which uses the <tt>Dialog</tt> prototype.  By convention, most Orion dialogs define a constructor whose sole parameter is an options object describing how the dialog is to be used.  This will be shown in the example code, but keep in mind that the client-facing API of the dialog is completely up to the developer.  The main requirement for implementation is that the <tt>Dialog</tt> prototype be used and the life-cycle methods called appropriately.  An example is the best way to demonstrate the behavior.  
  
 +
<pre>
 +
define(['i18n!orion/widgets/nls/messages','orion/webui/dialog'],
 +
function(messages, dialog) {
  
 +
/* This is the client facing API of OpenResourceDialog.  Up to the developer to decide what this looks like. */
 +
 +
/**
 +
* Usage: <code>new OpenResourceDialog(options).show();</code>
 +
*
 +
* @name orion.webui.dialogs.OpenResourceDialog
 +
* @class A dialog that searches for files by name or wildcard.
 +
* @param {String} [options.title] Text to display in the dialog's titlebar.
 +
* @param {orion.searchClient.Searcher} options.searcher The searcher to use for displaying results.
 +
* @param {Function} options.onHide a function to call when the dialog is hidden.  Optional.
 +
*/
 +
 +
function OpenResourceDialog(options) {
 +
this._init(options);
 +
}
 +
 +
/* Use the Dialog prototype to inherit the common dialog behavior.  */
 +
OpenResourceDialog.prototype = new dialog.Dialog();
 +
</pre>
 +
 +
=== The Dialog life-cycle ===
  
 
=== Defining the template and referring to DOM objects ===
 
=== Defining the template and referring to DOM objects ===

Revision as of 14:44, 2 January 2013

In Orion 2.0, we no longer rely on the dijit toolkit for our dialog implementations. Instead, we use lightweight Orion constructs and CSS. This document describes how to implement an Orion dialog.

Dialogs (modal and modeless)

The module "orion/webui/dialog" provides support for dialog behavior. This class defines a lightweight life-cycle for dialogs, provides optional modal behavior, template support, and automatic button creation.

Programming a dialog

Dialogs are implemented as an object which uses the Dialog prototype. By convention, most Orion dialogs define a constructor whose sole parameter is an options object describing how the dialog is to be used. This will be shown in the example code, but keep in mind that the client-facing API of the dialog is completely up to the developer. The main requirement for implementation is that the Dialog prototype be used and the life-cycle methods called appropriately. An example is the best way to demonstrate the behavior.

define(['i18n!orion/widgets/nls/messages','orion/webui/dialog'], 
		function(messages, dialog) {

/* This is the client facing API of OpenResourceDialog.  Up to the developer to decide what this looks like. */

/**
 * Usage: <code>new OpenResourceDialog(options).show();</code>
 * 
 * @name orion.webui.dialogs.OpenResourceDialog
 * @class A dialog that searches for files by name or wildcard.
 * @param {String} [options.title] Text to display in the dialog's titlebar.
 * @param {orion.searchClient.Searcher} options.searcher The searcher to use for displaying results.
 * @param {Function} options.onHide a function to call when the dialog is hidden.  Optional.
 */

function OpenResourceDialog(options) {
	this._init(options);
}
	
/* Use the Dialog prototype to inherit the common dialog behavior.  */
OpenResourceDialog.prototype = new dialog.Dialog();

The Dialog life-cycle

Defining the template and referring to DOM objects

By the time the dialog calls _initialize the HTML describing the dialog content must be specified in a dialog variable called TEMPLATE. By convention, most Orion dialogs define this variable in-line in the .js file that defines the dialog. Developers who prefer to use separate HTML files may do so using any preferred template/fragment mechanism. The key point is that the HTML is bound to the variable before calling _initialize.

The OpenResourceDialog defines the TEMPLATE in line.

OpenResourceDialog.prototype.TEMPLATE = 
'<div role="search">' + //$NON-NLS-0$
  '<div><label for="fileName">'+messages['Type the name of a file to open (? = any character, * = any string):']+'</label></div>' + //$NON-NLS-1$ //$NON-NLS-0$
  '<div><input id="fileName" type="text" placeholder="'+messages['Search']+'"</input></div>' + //$NON-NLS-1$ //$NON-NLS-0$
  '<div id="crawlingProgress"></div>' + //$NON-NLS-0$
  '<div id="favresults" style="max-height:400px; height:auto; overflow-y:auto;"></div>' + //$NON-NLS-0$
  '<div id="results" style="max-height:400px; height:auto; overflow-y:auto;" aria-live="off"></div>' + //$NON-NLS-0$
  '<div id="statusbar"></div>' + //$NON-NLS-0$
'</div>'; //$NON-NLS-0$

The field id's are bound to instance variables during the _initialize method. The dialog may refer to the field using '$' syntax once the dialog is initialized. For example:

this.$fileName.addEventListener("input", function() { // do something }, false);

The variable $fileName refers to the DOM node whose id is "fileName". All nodes assigned an id in the template will be bound to a $ variable.

Launching a dialog

Examples

Popup dialogs

Popup dialogs provide lightweight, tooltip-style dialogs, including automatic dismissal by clicking outside of the dialog.

Programming a popup

Launching a popup

Examples