Class wpModules.dialog.Dialog

wpModules.dialog.Dialog

Class Summary
Constructor Attributes	Constructor Name and Description
	wpModules.dialog.Dialog(args) Dialog API to create dialogs.

Method Summary
Method Attributes	Method Name and Description
	close(returnParams) Closes the dialog.
	open() Opens the dialog.
	resize(size) Resizes the dialog to the given width and height.
	set(args) Sets parameters for the dialog.

Class Detail

wpModules.dialog.Dialog(args)

Dialog API to create dialogs. When you create a dialog, you may specify parameters to define it's behavior. After you create a dialog, you call its member functions, e.g. open() to display it. Note : Currently the open() function always returns false.

Example 1:
// create a dialog
var d = new wpModules.dialog.Dialog({
  url: "/myURL",
  title: "MyTitle", 
  metrics: {
    width: 200,
    height: 300
  },
  autoClose: true
});
// open the dialog
d.open();

Example 2:
// create a dialog using inline markup
var d = new wpModules.dialog.Dialog({
  title: "MyTitle",
  markup: "my inline markup",
  autoResize: true,
  autoClose: true
});

// open the dialog
d.open();

Parameters:
{Object} args: object holding parameters to define the dialog behavior
{Object} args.url Optional: url pointing to contents to display. If the URL is to a different domain the content cannot be automatically resized due to cross domain restrictions, setting args.autoResize=true will have no affect, the content will be sized as specified in args.metrics. Either args.url or args.markup is to be specified.
{Object} args.markup Optional: inline markup to display. Either args.url or args.markup is to be specified.
{Object} args.title Optional: dialog title; defaults to not showing the header section; note that if title is not specified then description or labelledby must be specified for accessibility reasons. If title is provided then attribute aria-labelledby points to the header section. Else if description is provided instead aria-label is added containing the description. If there are no title and description specified then labelledby is evaluated and aria-labelledby is added with its content. The labelledby attribute should contain valid node id. Finally if non of the three is specified then the then the dialog is added aria-label attribute with the string "dialog".
{Object} args.description Optional: dialog description; if no title is specified, the description is presented as title information to impaired users. However, no visual title is presented in this case.
{Object} args.templateStyle Optional: predefined template styles to display dialog content. If not specified the default template style will be used. Available types are... 'flat' : flat UI look, no border, title bar or drop shadow 'help' : style defaults are autoResize: true, autoClose: true, modal: false, window: window.top, displayCloseOverlay: true
{Object} arg.learnMore.url Optional: the url to open when the the Learn more action is clicked, only applies when using the help template style.
{Object} arg.learnMore.width Optional: optional width of window used to open the learn more url, only applies when using the help template style, default is 800px.
{Object} arg.learnMore.height Optional: option height of window used to open the learn more url, only applies when using the help template style, default is 800px.
{Object} args.metrics Optional: object with dimension values
{Object} args.metrics.top Optional: integer to set the top position
{Object} args.metrics.height Optional: integer to set the height
{Object} args.metrics.left Optional: integer to set the left position
{Object} args.metrics.width Optional: integer to set the width
{Object} args.padding Optional, Default: 15: dialog content padding size, can be a single number to be applied to all sides or an array of four numbers to apply to each side individually in order of top, right, bottom and left.
{Object} args.draggable Optional, Default: false: boolean indicating if the dialog can be dragged on the view port
{Object} args.autoResize Optional, Default: false: boolean indicating if the dialog resizes automatically
{Object} args.autoPosition Optional: DOM node to align dialog position to; if the dialog and the DOM node overlap vertically with sufficient space, a pointer (aka shark fin) is displayed to visualize the alignment; by default, the dialog is placed at the position specified with the metrics, or centered in the view port
{Object} args.autoClose Optional: boolean indicating if the dialog closes automatically if the user clicks outside the dialog; defaults to true for non-modal and to false for modal dialogs respectively
{Object} args.tabOut Optional, Default: false: boolean indicating if tabbing outside of the dialog is allowed, if true and a user tabs to an element outside of the dialog it will close
{Object} args.modal Optional, Default: false: boolean indicating if the dialog is modal
{Object} args.window Optional: window object scope to launch the dialog in
{Object} args.parent Optional: parent DOM node to attach the dialog DOM node to
{boolean} args.displayCloseOverlay Optional: boolean indicating whether or not an overlay should be displayed which can be used to close the dialog (by clicking the overlay)
{Object} args.callbackFn Optional: callback function, which is invoked when the dialog is closed
{Object} args.setFocusFn Optional: set focus function, used to set focus after the dialog loads, the relative window instance will be set in arguments
{Object} args.onLoadCallbackFn Optional: callback function to execute when onload event occurs for resources loaded in the iframe, it's document and window object will be set as arguments
{Object} args.onUnloadCallbackFn Optional: callback function to execute when onunload event occurs for resources loaded in the iframe, it's document and window object will be set as arguments
{Object} args.labelledby Optional: used for accessibility reasons to provide aria-labelledby attribute when there are no title, header or description provided. Should contain valid node ID of the node that is triggering the dialog.

Returns:: {Object} dialog object

Method Detail

close(returnParams)

Closes the dialog. May challenge the user with a confirmation.

The close function is called, when you use the resolver dialog framework to trigger a return-URI (based on the Portal-URI) from within the dialog contents. The parameters specified with the return-URI are passed to the close function. The close function in turn invokes the callbackFn, which may be set with the dialog, and passes in these parameters.

The close function is also called, when you invoke window.closeDialog() from within the dialog. window.onTerminateDialog() will be called if specified if the dialog is terminated by clicking the X control, clicked outside the dialog in a non-modal dialog or by pressing ESC key.

Example 1:
// invoke the close function on the dialog
dialog.close()

Example 2:
// use the resolver dialog framework and trigger the return-URI from
// within the dialog contents
"?uri=dialog:CloseModalDialog?mode=view&n1=v1&n2=v2" to have the close 
function invoked with returnParams = {n1:"v1", n2: "v2"}.

Example 3:
// call the close function on the window object of the dialog contents
window.closeDialog({n1: "v1"});

Example 4:
// set onbeforeunload callback function on the window object of
// the dialog contents which may return a string, a boolean value or nothing at all,
// if string a user is challenged with this string to confirm closing the dialog,
// if a boolean value returned and is false the dialog remains open, the developer is
// responsible for providing any necessary notifications and options, if the return
// boolean value is true the dialog will proceed to close
window.onbeforeunload = function() {
  if (pendingChanges) {
    return "You have pending changes. Close the dialog anyway?";
  }
};

Parameters:
{Object} returnParams Optional: return parameters

open()

Opens the dialog. Currently always returns false.

resize(size)

Resizes the dialog to the given width and height. The size refers to the size of the dialog, including its decorations. Note: If you specify a dimension (width and/or height), you disable auto resizing for it. For all dimensions that are not specified, auto resizing is enabled.

The resize function is also called, when you invoke window.resize() from within the dialog.

Example 1:
// invoke the resize function on the dialog to auto resize 
dialog.resize()

Example 2:
// call the resize function on the window object of the dialog contents to 
// size to the specified dimensions
window.resize({width: 400, height: 400});

Parameters:
{JSON} size Optional: object holding dimensions, defaults to autoResizing

set(args)

Sets parameters for the dialog. Depending on the parameters you set, the dialog may resize itself or reload the contents. The parameters are the same as used with the constructor of the dialog, but limited to the following:

Example:
// set parameters to existing dialog
myDialog.set({
  url: "/myNewURL",
  metrics: {
    width: 200,
    height: 300
  }
});

Parameters:
{Object} args: object holding parameters to define the dialog behavior
{Object} args.url Optional: url
{Object} args.markup Optional: markup
{Object} args.title Optional: title
{Object} args.description Optional: description
{Object} args.metrics Optional: metrics
{Object} args.metrics.top Optional: top
{Object} args.metrics.height Optional: height
{Object} args.metrics.left Optional: left
{Object} args.metrics.width Optional: width
{Object} args.autoPosition Optional: autoPosition

Classes

Class wpModules.dialog.Dialog