YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: SimpleDialog

YUI 2: 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:

  1. <!-- Sam Skin CSS -->
  2. <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/container/assets/skins/sam/container.css">
  3.  
  4. <!-- OPTIONAL: You only need the YUI Button CSS if you're including YUI Button, mentioned below. -->
  5. <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/button/assets/skins/sam/button.css">
  6.  
  7. <!-- Dependencies -->
  8. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
  9.  
  10. <!-- OPTIONAL: Animation (only required if using ContainerEffect) -->
  11. <script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
  12.  
  13. <!-- OPTIONAL: Connection (only required if using asynchronous form submission) -->
  14. <script src="http://yui.yahooapis.com/2.9.0/build/connection/connection-min.js"></script>
  15.  
  16. <!-- OPTIONAL: Drag & Drop (only required if enabling Drag & Drop) -->
  17. <script src="http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop-min.js"></script>
  18.  
  19. <!-- OPTIONAL: YUI Button (these 2 files only required if you want SimpleDialog to use YUI Buttons, instead of HTML Buttons) -->
  20. <script src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script>
  21. <script src="http://yui.yahooapis.com/2.9.0/build/button/button-min.js"></script>
  22.  
  23. <!-- Source file -->
  24. <script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
  25.  
<!-- Sam Skin CSS -->
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/container/assets/skins/sam/container.css">
 
<!-- OPTIONAL: You only need the YUI Button CSS if you're including YUI Button, mentioned below. -->
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/button/assets/skins/sam/button.css">
 
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
 
<!-- OPTIONAL: Animation (only required if using ContainerEffect) -->
<script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
 
<!-- OPTIONAL: Connection (only required if using asynchronous form submission) -->
<script src="http://yui.yahooapis.com/2.9.0/build/connection/connection-min.js"></script>
 
<!-- OPTIONAL: Drag & Drop (only required if enabling Drag & Drop) -->
<script src="http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop-min.js"></script>
 
<!-- OPTIONAL: YUI Button (these 2 files only required if you want SimpleDialog to use YUI Buttons, instead of HTML Buttons) -->
<script src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/button/button-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
 
Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the SimpleDialog Control lives. You can usually accomplish this simply by putting the class on the <body> tag:

  1. <body class="yui-skin-sam">
  2.  
<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.

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

  1. mySimpleDialog = new YAHOO.widget.SimpleDialog("dlg", { 
  2.     width: "20em", 
  3.     effect:{
  4.         effect: YAHOO.widget.ContainerEffect.FADE,
  5.         duration: 0.25
  6.     }, 
  7.     fixedcenter: true,
  8.     modal: true,
  9.     visible: false,
  10.     draggable: false
  11. });
  12.  
  13. mySimpleDialog.setHeader("Warning!");
  14. mySimpleDialog.setBody("Are you sure you want to delete this item?");
  15. mySimpleDialog.cfg.setProperty("icon", YAHOO.widget.SimpleDialog.ICON_WARN);
  16.  
mySimpleDialog = new YAHOO.widget.SimpleDialog("dlg", {
    width: "20em",
    effect:{
        effect: YAHOO.widget.ContainerEffect.FADE,
        duration: 0.25
    },
    fixedcenter: true,
    modal: true,
    visible: false,
    draggable: false
});
 
mySimpleDialog.setHeader("Warning!");
mySimpleDialog.setBody("Are you sure you want to delete this item?");
mySimpleDialog.cfg.setProperty("icon", YAHOO.widget.SimpleDialog.ICON_WARN);
 

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:

  1. var handleYes = function() {
  2.     //user confirms the deletion of this item;
  3.     //this method would perform that deletion;
  4.     //when ready, hide the SimpleDialog:
  5.     this.hide();
  6. };
  7. var handleNo = function() {
  8.     //user cancels item deletion; this method
  9.     //would handle the cancellation of the
  10.     //process.
  11.     //when ready, hide the SimpleDialog:
  12.     this.hide();
  13. };
  14. var myButtons = [
  15.     { text: "Yes", handler: handleYes },
  16.     { text:"Cancel", handler: handleNo, isDefault:true}
  17. ];
  18.  
  19. mySimpleDialog.cfg.queueProperty("buttons", myButtons);
  20.  
var handleYes = function() {
    //user confirms the deletion of this item;
    //this method would perform that deletion;
    //when ready, hide the SimpleDialog:
    this.hide();
};
var handleNo = function() {
    //user cancels item deletion; this method
    //would handle the cancellation of the
    //process.
    //when ready, hide the SimpleDialog:
    this.hide();
};
var myButtons = [
    { text: "Yes", handler: handleYes },
    { text:"Cancel", handler: handleNo, isDefault:true}
];
 
mySimpleDialog.cfg.queueProperty("buttons", myButtons);
 

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:

  1. mySimpleDialog.render(document.body);
  2.  
mySimpleDialog.render(document.body);
 

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:

  1. mySimpleDialog.show();
  2.  
mySimpleDialog.show();
 

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 page X co-ordinate.
y Number null Sets the element's page Y co-ordinate.
xy Array null Sets the element's page XY co-ordinates.
context Array null Allows the Overlay to be aligned relative to a context element. The property expects an array value with the format: [contextElementOrId, overlayCorner, contextElementCorner], where "contextElementOrId" is the context element or the id of the context element.

The corner parameters are one of the following string values: "tr" (top right), "tl" (top left), "br" (bottom right), or "bl" (bottom left) and define which corners of the overlay and context element should be aligned.

The array also supports optional 4th and 5th entries.

The 4th entry is an optional array of event names, or Custom Event objects, which should trigger re-alignment of the Overlay with the currently configured context element. For example:

[contextId, overlayCorner, contextCorner, ["beforeShow", "windowResize"]]

Will re-align the Overlay to the context element just before it's shown, and whenever the window is resized.

The 5th entry is an optional XY pixel offset, which is to be applied after the Overlay is aligned to the specified corner of the context element, and can be used to add a pixel buffer between the context element and the Overlay. For example:

[contextId, overlayCorner, contextCorner, triggerEvents, [10, 20]]

Will offset the Overlay by 10 pixels along the X axis, and 20 pixels along the Y axis, after aligning the specified corners.
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 Overlay will have an 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.
hideaftersubmit Boolean true If set to true, the Dialog is hidden after it's submitted. If false, it is left visible after form submission.
autofillheight String "body" Which container element (header, body or footer) should be sized to fill out any remaining vertical space when a height is set on the container using the height configuration property. Supported values are "header", "body" and "footer". Can be set to null (or false) to turn off the feature.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out 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 YUILibrary.com 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:

bookmark on del.icio.us

be the first to bookmark this page!

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings