Developer Network Home - Help

Yahoo! UI Library: SimpleDialog

Yahoo! UI Library: SimpleDialog

The SimpleDialog component is an extension of Dialog that reproduces the behavior of a simple dialog box (but without using an actual browser popup window); its primary use is to elicit binary decisions from the user (yes/no, okay/cancel, etc.). SimpleDialog makes it easy to implement this kind of interaction.

Getting Started

To use SimpleDialog, include the following code in your page:

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is container. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers; see "Serving YUI Files from Yahoo!" for important information about this service. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Using "CSS skins": One of the files listed above contains a CSS "skin" for the SimpleDialog Control. For this skin CSS to work correctly, you will need to apply the CSS class "yui-skin-sam" to an element that is a parent of the element in which the component lives. You can usually accomplish this simply by putting the class on the <body> tag:

<body class="yui-skin-sam">

For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article here on the website.

Using SimpleDialog

This section describes common tasks for creating and using SimpleDialog. It contains these sections:

SimpleDialog inherits its constructor and configuration, as well as several other important methods, from Dialog. See Dialog for more information on how to utilize SimpleDialog's inherited features.

Initializing SimpleDialog

SimpleDialog is designed to be...well...simple. In a single pass, you can instantiate a SimpleDialog and configure it to ask your user a question and retrieve that result. Here is an example of what a SimpleDialog constructor looks like when asking a simple question and using common options:

In this example you create a SimpleDialog instance (called mySimpleDialog); if no element on the page has an id of "dlg", SimpleDialog creates it — and that's the most common way to implement SimpleDialog. This example also:

  • Configures the SimpleDialog's width.
  • Directs it to fade in when shown and out when hidden.
  • Specifies that it should always remain in the center of the viewport.
  • Sets it to be modal (meaning that the user cannot interact with other parts of the page once the dialog appears.
  • Sets the SimpleDialog to start off hidden. It is visible by default.
  • Indicates that this SimpleDialog window shouldn't be draggable when it appears on the screen.

The last three lines of this example place content in the SimpleDialog's modular container that specifies its title, question text, and graphical icon.

Creating Buttons and Callbacks

The next step is to create buttons that the user can click on to answer the SimpleDialog's question (our question in the above example was applied via the setBody method and reads: "Are you sure you want to delete this item?"). We'll create a separate handler function for each button; that handler will take care of any appropriate action in response to the user's decision. The following code sample illustrates how we might handle buttons for our SimpleDialog:

NOTE: As with the Dialog control, if you've included the optional YUI Button script on the page, the buttons created will be instances of YAHOO.widget.Button otherwise regular HTML Buttons will be created.

Rendering and Showing SimpleDialog

To actually display the SimpleDialog on the page there are two further steps. First, render it into the DOM using the render method. This method takes as its argument the DOM element into which we want to insert the markup for SimpleDialog. The most common usage is to add SimpleDialog to the body element:

For most common applications, SimpleDialogs are usually not displayed when the page first loads and only appear when needed (by setting the "visible" configuration property to false, as in the above example code). To reveal the SimpleDialog on screen, invoke its show method:

Configuration Properties

SimpleDialog has the following configuration properties:

Name Type Default Description
text String "" The text to display in the body of the SimpleDialog.
icon String "none" The icon to render to the left of the SimpleDialog's text. Six constant values are provided for using Yahoo!'s standard network icons: ICON_BLOCK, ICON_WARN, ICON_HELP, ICON_INFO, ICON_ALARM, and ICON_TIP.

SimpleDialog also has the following inherited configuration properties:

Name Type Default Description
postmethod String "none" The method in which the Dialog's form should be posted. Options are "async", "form", or "none".
buttons Object[] null Array of button objects to render at the bottom of the Dialog.
visible Boolean true Sets whether or not the SimpleDialog is visible on the page (SimpleDialog uses the CSS "visibility" property to control this).
effect Object / Object[] none Sets the ContainerEffect (one or many) that should be used when showing and hiding the SimpleDialog.
monitorresize Boolean true Configures whether or not to create a hidden off-screen element that can be used to monitor for text size changes in the DOM.
x Number null Sets the element's "left" style property.
y Number null Sets the element's "top" style property.
xy Array null Sets the element's "top" and "left" style properties.
context Array null Allows the Overlay to be anchored to a context element. The format is: [element, elementCorner, contextCorner], where "element" is an element or element id, and the corner parameters are either "tr" (top right), "tl" (top left), "br" (bottom right), or "bl" (bottom left).
fixedcenter Boolean false Specifies whether the Overlay should be automatically centered in the viewport on window scroll and resize.
width String null Sets the element's "width" style property.
height String null Sets the element's "height" style property.
zIndex Number null Sets the element's "z-index" style property.
constraintoviewport Boolean false If set to true the Overlay will try to remain inside the confines of the size of viewport.
iframe Boolean false (true by default for IE 6 and below) If set to true the Menu will have and iframe behind it to prevent other elements with a higher z-index from poking through.
close Boolean null Whether a "close" icon should be displayed in the header.
draggable Boolean "true" if the Drag and Drop utility is included, otherwise "false." Whether to allow the user to drag the Panel using its header
underlay String "shadow" Specifies the type of underlay to display under the Panel. Other options include "none", and "matte", which renders a small white matte under the Panel.
modal Boolean false Specifies whether the document should be shielded with a partially transparent mask to require the user to close the Panel before being able to activate any elements in the document.
keylisteners YAHOO.util.KeyListener / Array null A KeyListener or Array of KeyListeners containing key events to enable when the Panel is displayed.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Dialog/SimpleDialog Controls Cheat Sheet:

Cheat Sheet for the Dialog and SimpleDialog Controls

Download full set of cheat sheets.

Container Family Examples:

Other YUI Examples That Make Use of the Container Family:

More Reading about the YUI SimpleDialog Control:

YUI SimpleDialog on del.icio.us:

Copyright © 2008 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings