Yahoo! UI Library

Container  2.7.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 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 (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>
Returns: void

_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>
Returns: YAHOO.widget.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.

_submitHandler

protected void _submitHandler ( e )
Internal handler for the form submit event
Parameters:
e <DOMEvent> The DOM Event object
Returns: void

blurButtons

void blurButtons ( )
Blurs all the buttons defined via the "buttons" configuration property.
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 ( )
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.
Returns: void

focusDefaultButton

void 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: void

focusFirst

void 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: void

focusFirstButton

void focusFirstButton ( )
Sets the focus to the first button created via the "buttons" configuration property.
Returns: void

focusLast

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

focusLastButton

void focusLastButton ( )
Sets the focus to the last button created via the "buttons" configuration property.
Returns: void

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 dependancy on the page), an array of YAHOO.widget.Button instances is returned.
Returns: Array

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

setFirstLastFocusable

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

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>
Returns: void

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

_addFocusHandlers, _autoFillOnHeightChange, _createHiddenFocusElement, _doClose, _onElementFocus, _removeFocusHandlers, 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, _initResizeMonitor, _supportsCWResize, appendToBody, appendToFooter, appendToHeader, 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, _getPreciseHeight, _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.
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,

Configuration Attributes

Copyright © 2009 Yahoo! Inc. All rights reserved.