Yahoo! UI Library

Container  2.9.0

Yahoo! UI Library > container > YAHOO.widget.Dialog
Search:
 
Filters

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

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

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

Copyright © 2011 Yahoo! Inc. All rights reserved.