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

# Yahoo! UI Library

### Container 2.2.2

Yahoo! UI Library > container > YAHOO.widget.Dialog

## 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, and button sets can be build dynamically, or the preincluded ones for Submit/Cancel and OK/Cancel can be utilized. Forms can be processed in 3 ways -- via an asynchronous Connection utility call, a simple form POST or GET, or manually.

### 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

#### callback.argument `- Object`

The arbitraty 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

#### YAHOO.widget.Dialog._DEFAULT_CONFIG `- private final Object`

Constant representing the Dialog's configuration properties

#### YAHOO.widget.Dialog._EVENT_TYPES `- private final Object`

Constant representing the name of the Dialog's events

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

Constant representing the default CSS class used for a Dialog

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

`YAHOO.widget.Panel._DEFAULT_CONFIG, YAHOO.widget.Panel._EVENT_TYPES`

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

`body, browser, cfg, contructor, element, footer, header, id, imageRoot, isSecure, platform, YAHOO.widget.Module._DEFAULT_CONFIG, YAHOO.widget.Module._EVENT_TYPES`

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

`YAHOO.widget.Overlay._DEFAULT_CONFIG, YAHOO.widget.Overlay._EVENT_TYPES, YAHOO.widget.Overlay._initialized`

### Methods

#### _onFormKeyDown

`protected void _onFormKeyDown ( p_oEvent )`
"keydown" event handler for the dialog's form.

Parameters:
  `p_oEvent <Event>` Object representing the DOM event object passed back by the event utility (YAHOO.util.Event).

Returns: `void`

#### blurButtons

`void blurButtons ( )`
Blurs all the html buttons

Returns: `void`

#### cancel

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

Returns: `void`

#### 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.

Returns: `void`

#### 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.

Returns: `void`

#### 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.

Returns: `void`

#### destroy

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

Returns: `void`

#### doSubmit

`void doSubmit ( )`
Performs the submission of the Dialog form depending on the value of "postmethod" property.

Returns: `void`

#### focusDefaultButton

`void focusDefaultButton ( )`
Sets the focus to the button that is designated as the default. By default, his handler is executed when the show event is fired.

Returns: `void`

#### focusFirst

`void focusFirst ( )`
The default event handler used to focus the first field of the form when the Dialog is shown.

Returns: `void`

#### focusFirstButton

`void focusFirstButton ( )`
Sets the focus to the first button in the button list

Returns: `void`

#### focusLast

`void focusLast ( )`
Sets the focus to the last button in the button or form element in the Dialog

Returns: `void`

#### focusLastButton

`void focusLastButton ( )`
Sets the focus to the first button in the button list

Returns: `void`

#### 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.

Returns: `void`

#### initDefaultConfig

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

Returns: `void`

#### initEvents

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

Returns: `void`

#### registerForm

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

Returns: `void`

#### submit

`void submit ( )`
Executes a submit of the Dialog followed by a hide, if validation is successful.

Returns: `void`

#### 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.

Returns: `void`

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

`buildMask, buildWrapper, configClose, configDraggable, configHeight, configKeyListeners, configModal, configUnderlay, configWidth, configzIndex, destroy, hideMask, init, initDefaultConfig, initEvents, onDomResize, registerDragDrop, removeMask, render, showMask, sizeMask, sizeUnderlay, toString`

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

`appendToBody, appendToFooter, appendToHeader, configMonitorResize, configVisible, destroy, hide, init, initDefaultConfig, initEvents, initResizeMonitor, onDomResize, render, setBody, setFooter, setHeader, show, toString`

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

`align, center, configConstrainToViewport, configContext, configFixedCenter, configHeight, configIframe, configVisible, configWidth, configX, configXY, configY, configzIndex, destroy, doCenterOnDOMEvent, enforceConstraints, hideIframe, hideMacGeckoScrollbars, init, initDefaultConfig, initEvents, moveTo, onDomResize, showIframe, showMacGeckoScrollbars, syncPosition, toString`

### Events

#### asyncSubmitEvent

`asyncSubmitEvent ( )`
CustomEvent fired prior to asynchronous submission

#### beforeSumitEvent

`beforeSumitEvent ( )`
CustomEvent fired prior to submission

#### cancelEvent

`cancelEvent ( )`
CustomEvent fired after cancel

#### formSubmitEvent

`formSubmitEvent ( )`
CustomEvent fired prior to form-based submission

#### manualSubmitEvent

`manualSubmitEvent ( )`
CustomEvent fired prior to manual submission

#### submitEvent

`submitEvent ( )`
CustomEvent fired after submission

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

`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 `- Object[]`

Object literal(s) defining the buttons for the Dialog's footer.
Default Value: "none"

#### 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, keylisteners, modal, underlay`

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

`effect, monitorresize, visible`

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

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

Copyright © 2007 Yahoo! Inc. All rights reserved.