API: container YAHOO.widget.Dialog (YUI Library)

# Yahoo! UI Library

### Container 2.9.0

Yahoo! UI Library > container > YAHOO.widget.Dialog
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.Dialog - extends YAHOO.widget.Panel

Known Subclasses:
  YAHOO.widget.SimpleDialog

Dialog is an implementation of Panel that can be used to submit form data.

Built-in functionality for buttons with event handlers is included. If the optional YUI Button dependancy is included on the page, the buttons created will be instances of YAHOO.widget.Button, otherwise regular HTML buttons will be created.

Forms can be processed in 3 ways -- via an asynchronous Connection utility call, a simple form POST or GET, or manually. The YUI Connection utility should be included if you're using the default "async" postmethod, but is not required if you're using any of the other postmethod values.

### Constructor

YAHOO.widget.Dialog `( el , userConfig )`

Parameters:
  `el <String>` The element ID representing the Dialog OR
  `el <HTMLElement>` The element representing the Dialog
  `userConfig <Object>` The configuration object literal containing the configuration that should be set for this Dialog. See configuration documentation for more details.

### Properties

#### callback - `Object`

The internally maintained callback object for use with the Connection utility. The format of the callback object is similar to Connection Manager's callback object and is simply passed through to Connection Manager when the async request is made.

#### callback.argument - `Object`

The arbitrary argument or arguments to pass to the Connection callback functions

#### callback.failure - `Function`

The function to execute upon failure of the Connection submission

#### callback.success - `Function`

The function to execute upon success of the Connection submission (when the form does not contain a file input element).

#### callback.upload - `Function`

The function to execute upon success of the Connection submission, when the form contains a file input element.

NOTE: Connection manager will not invoke the success or failure handlers for the file upload use case. This will be the only callback handler invoked.

For more information, see the Connection Manager documenation on file uploads.

#### DEFAULT_CONFIG - `private final Object`

Constant representing the Dialog's configuration properties

#### EVENT_TYPES - `private final Object`

Constant representing the name of the Dialog's events

#### form - `HTMLFormElement`

Object reference to the Dialog's `<form>` element.
Default Value: null

#### YAHOO.widget.Dialog.CSS_DIALOG - `static final String`

Constant representing the default CSS class used for a Dialog

#### Properties inherited from YAHOO.widget.Panel:

`dd, DEFAULT_CONFIG, EVENT_TYPES`

#### Properties inherited from YAHOO.widget.Module:

`body, browser, cacheEffects, cfg, contructor, DEFAULT_CONFIG, element, EVENT_TYPES, footer, header, id, imageRoot, isSecure, platform`

#### Properties inherited from YAHOO.widget.Overlay:

`CONTEXT_TRIGGERS, DEFAULT_CONFIG, EVENT_TYPES, YAHOO.widget.Overlay._initialized`

### Methods

#### _doClose

`protected void _doClose ( e )`
Event handler for the close icon

Parameters:
  `e <DOMEvent>`

#### _getButton

`private YAHOO.widget.Button|HTMLElement _getButton ( button )`
Helper method to normalize button references. It either returns the YUI Button instance for the given element if found, or the passes back the HTMLElement reference if a corresponding YUI Button reference is not found or YAHOO.widget.Button does not exist on the page.

Parameters:
  `button <HTMLElement>`

#### _getFormAttributes

`protected Object _getFormAttributes ( oForm )`
Retrieves important attributes (currently method and action) from the form element, accounting for any elements which may have the same name as the attributes. Defaults to "POST" and "" for method and action respectively if the attribute cannot be retrieved.

Parameters:
  `oForm <HTMLFormElement>` The HTML Form element from which to retrieve the attributes

Returns: `Object`
  Object literal, with method and action String properties.

#### _setTabLoop

`protected void _setTabLoop ( firstElement , lastElement )`
Protected internal method for setTabLoop, which can be used by subclasses to jump in and modify the arguments passed in if required.

Parameters:
  `firstElement <HTMLElement>`
  `lastElement <HTMLElement>`

#### _submitHandler

`protected void _submitHandler ( e )`
Internal handler for the form submit event

Parameters:
  `e <DOMEvent>` The DOM Event object

#### blurButtons

`void blurButtons ( )`
Blurs all the buttons defined via the "buttons" configuration property.

#### cancel

`void cancel ( )`
Executes the cancel of the Dialog followed by a hide.

#### configButtons

`void configButtons ( type , args , obj )`
The default event handler for the "buttons" configuration property

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

#### configClose

`void configClose ( type , args , obj )`
The default event handler fired when the "close" property is changed. The method controls the appending or hiding of the close icon at the top right of the Dialog.

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

#### configPostMethod

`void configPostMethod ( type , args , obj )`
The default event handler for the "postmethod" configuration property

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

#### destroy

`void destroy ( shallowPurge )`
Removes the Panel element from the DOM and sets all child elements to null.

Parameters:
  `shallowPurge <boolean>` If true, only the parent element's DOM event listeners are purged. If false, or not provided, all children are also purged of DOM event listeners. NOTE: The flag is a "shallowPurge" flag, as opposed to what may be a more intuitive "purgeChildren" flag to maintain backwards compatibility with behavior prior to 2.9.0.

#### doSubmit

`void doSubmit ( )`
Submits the Dialog's form depending on the value of the "postmethod" configuration property. Please note: As of version 2.3 this method will automatically handle asyncronous file uploads should the Dialog instance's form contain `<input type="file">` elements. If a Dialog instance will be handling asyncronous file uploads, its `callback` property will need to be setup with a `upload` handler rather than the standard `success` and, or `failure` handlers. For more information, see the Connection Manager documenation on file uploads.

#### focusDefaultButton

`Boolean focusDefaultButton ( )`
Sets the focus to the button that is designated as the default via the "buttons" configuration property. By default, this method is called when the Dialog is made visible.

Returns: `Boolean`
  true if focused, false if not

#### focusFirst

`Boolean focusFirst ( )`

Sets focus to the first focusable element in the Dialog's form if found, else, the default button if found, else the first button defined via the "buttons" configuration property.

This method is invoked when the Dialog is made visible.

Returns: `Boolean`
  true, if focused. false if not

#### focusFirstButton

`Boolean focusFirstButton ( )`
Sets the focus to the first button created via the "buttons" configuration property.

Returns: `Boolean`
  true, if focused. false if not

#### focusLast

`Boolean focusLast ( )`
Sets focus to the last element in the Dialog's form or the last button defined via the "buttons" configuration property.

Returns: `Boolean`
  true, if focused. false if not

#### focusLastButton

`Boolean focusLastButton ( )`
Sets the focus to the last button created via the "buttons" configuration property.

Returns: `Boolean`
  true, if focused. false if not

#### getButtons

`Array getButtons ( )`
Returns an array containing each of the Dialog's buttons, by default an array of HTML `<BUTTON>` elements. If the Dialog's buttons were created using the YAHOO.widget.Button class (via the inclusion of the optional Button dependency on the page), an array of YAHOO.widget.Button instances is returned.

#### getData

`Object getData ( )`
Returns a JSON-compatible data structure representing the data currently contained in the form.

Returns: `Object`
  A JSON object reprsenting the data of the current form.

#### init

`void init ( el , userConfig )`
The Dialog initialization method, which is executed for Dialog and all of its subclasses. This method is automatically called by the constructor, and sets up all DOM references for pre-existing markup, and creates required markup if it is not already present.

Parameters:
  `el <String>` The element ID representing the Dialog OR
  `el <HTMLElement>` The element representing the Dialog
  `userConfig <Object>` The configuration object literal containing the configuration that should be set for this Dialog. See configuration documentation for more details.

#### initDefaultConfig

`void initDefaultConfig ( )`
Initializes the class's configurable properties which can be changed using the Dialog's Config object (cfg).

#### initEvents

`void initEvents ( )`
Initializes the custom events for Dialog which are fired automatically at appropriate times by the Dialog class.

#### registerForm

`void registerForm ( )`
Prepares the Dialog's internal FORM object, creating one if one is not currently present.

#### setFirstLastFocusable

`void setFirstLastFocusable ( )`
Configures instance properties, pointing to the first and last focusable elements in the Dialog's form.

#### setTabLoop

`void setTabLoop ( firstElement , lastElement )`
Sets up a tab, shift-tab loop between the first and last elements provided. NOTE: Sets up the preventBackTab and preventTabOut KeyListener instance properties, which are reset everytime this method is invoked.

Parameters:
  `firstElement <HTMLElement>`
  `lastElement <HTMLElement>`

#### submit

`void submit ( )`
Executes a submit of the Dialog if validation is successful. By default the Dialog is hidden after submission, but you can set the "hideaftersubmit" configuration property to false, to prevent the Dialog from being hidden.

#### toString

`String toString ( )`
Returns a string representation of the object.

Returns: `String`
  The string representation of the Dialog

#### validate

`void validate ( )`
Built-in function hook for writing a validation function that will be checked for a "true" value prior to a submit. This function, as implemented by default, always returns true, so it should be overridden if validation is necessary.

#### Methods inherited from YAHOO.widget.Panel:

`_addFocusHandlers, _autoFillOnHeightChange, _createHiddenFocusElement, _doClose, _focusFirstModal, _focusOnShow, _onElementFocus, _removeFocusHandlers, _renderBody, _renderFooter, _renderHeader, _setTabLoop, _testIfFocusable, buildMask, buildWrapper, configClose, configDraggable, configHeight, configKeyListeners, configModal, configStrings, configUnderlay, configWidth, configzIndex, destroy, focusFirst, focusLast, forceUnderlayRedraw, getFocusableElements, hideMask, init, initDefaultConfig, initEvents, registerDragDrop, removeMask, render, setFirstLastFocusable, setTabLoop, showMask, sizeMask, sizeUnderlay, stackMask, toString`

#### Methods inherited from YAHOO.widget.Module:

`_addToParent, _createEffects, _initResizeMonitor, _renderBody, _renderFooter, _renderHeader, _supportsCWResize, appendToBody, appendToFooter, appendToHeader, configEffect, configMonitorResize, configVisible, destroy, hide, init, initDefaultConfig, initEvents, initResizeMonitor, onDomResize, render, setBody, setFooter, setHeader, show, toString`

#### Methods inherited from YAHOO.widget.Overlay:

`_alignOnTrigger, _autoFillOnHeightChange, _findTriggerCE, _getComputedHeight, _getConstrainedPos, _getPreciseHeight, _preventOverlap, _primeXYFromDOM, _processTriggers, _setDomVisibility, _validateAutoFillHeight, align, bringToTop, center, configAutoFillHeight, configConstrainToViewport, configContext, configFixedCenter, configHeight, configIframe, configVisible, configWidth, configX, configXY, configY, configzIndex, destroy, doCenterOnDOMEvent, enforceConstraints, fillHeight, fitsInViewport, forceContainerRedraw, getConstrainedX, getConstrainedXY, getConstrainedY, hideIframe, hideMacGeckoScrollbars, init, initDefaultConfig, initEvents, moveTo, onDomResize, showIframe, showMacGeckoScrollbars, stackIframe, syncIframe, syncPosition, toString`

### Events

#### asyncSubmitEvent

`asyncSubmitEvent ( conn )`
CustomEvent fired after asynchronous submission, before the generic submit event is fired

Parameters:
  `conn <Object>` The connection object, returned by YAHOO.util.Connect.asyncRequest

#### beforeSubmitEvent

`beforeSubmitEvent ( )`
CustomEvent fired prior to submission

#### cancelEvent

`cancelEvent ( )`
CustomEvent fired after cancel

#### formSubmitEvent

`formSubmitEvent ( )`
CustomEvent fired after form-based submission, before the generic submit event is fired

#### manualSubmitEvent

`manualSubmitEvent ( )`
CustomEvent fired for manual submission, before the generic submit event is fired

#### submitEvent

`submitEvent ( )`
CustomEvent fired after submission

#### Events inherited from YAHOO.widget.Panel:

`beforeHideMaskEvent, beforeShowMaskEvent, dragEvent, hideMaskEvent, showMaskEvent,`

#### Events inherited from YAHOO.widget.Module:

`appendEvent, beforeHideEvent, beforeInitEvent, beforeRenderEvent, beforeShowEvent, changeBodyEvent, changeContentEvent, changeFooterEvent, changeHeaderEvent, destroyEvent, hideEvent, initEvent, renderEvent showEvent YAHOO.widget.Module.textResizeEvent`

#### Events inherited from YAHOO.widget.Overlay:

`beforeMoveEvent, moveEvent, YAHOO.widget.Overlay.windowResizeEvent, YAHOO.widget.Overlay.windowScrollEvent,`

### Configuration Attributes

#### buttons `- {Array|String}`

Array of object literals, each containing a set of properties defining a button to be appended into the Dialog's footer.

Each button object in the buttons array can have three properties:

text:
  The text that will display on the face of the button. The text can include HTML, as long as it is compliant with HTML Button specifications. The text is added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.
handler:
  Can be either:
  1. A reference to a function that should fire when the button is clicked. (In this case scope of this function is always its Dialog instance.)
  2. An object literal representing the code to be executed when the button is clicked.

     Format:

     `{
     fn: Function, // The handler to call when the event fires.
     obj: Object, // An object to pass back to the handler.
     scope: Object // The object to use for the scope of the handler.
     }`

isDefault:
  An optional boolean value that specifies that a button should be highlighted and focused by default.

NOTE:If the YUI Button Widget is included on the page, the buttons created will be instances of YAHOO.widget.Button. Otherwise, HTML Buttons (`<BUTTON>`) will be created.
Default Value: "none"

#### hideaftersubmit `- Boolean`

This property is used to configure whether or not the dialog should be automatically hidden after submit.
Default Value: true

#### postdata `- String`

Any additional post data which needs to be sent when using the async postmethod for dialog POST submissions. The format for the post data string is defined by Connection Manager's asyncRequest method.
Default Value: null

#### postmethod `- String`

The method to use for posting the Dialog's form. Possible values are "async", "form", and "manual".
Default Value: async

#### Configuration attributes inherited from YAHOO.widget.Panel:

`close, draggable, dragOnly, keylisteners modal strings underlay`

#### Configuration attributes inherited from YAHOO.widget.Module:

`appendtodocumentbody, effect monitorresize visible`

#### Configuration attributes inherited from YAHOO.widget.Overlay:

`autofillheight, constraintoviewport, context, fixedcenter, height, iframe preventcontextoverlap width x xy y zIndex`

Copyright © 2011 Yahoo! Inc. All rights reserved.