Getting Started

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

<!-- Sam Skin CSS --> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.2/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.5.2/build/button/assets/skins/sam/button.css"> <!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js"></script> <!-- OPTIONAL: Animation (only required if enabling animation) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/animation/animation-min.js"></script> <!-- OPTIONAL: Connection (only required if using asynchronous form submission) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/connection/connection-min.js"></script> <!-- OPTIONAL: Drag & Drop (only required if enabling Drag & Drop) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/dragdrop/dragdrop-min.js"></script> <!-- OPTIONAL: YUI Button (these 2 files only required if you want Dialog to use YUI Buttons, instead of HTML Buttons) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/element/element-beta-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/button/button-min.js"></script> <!-- Source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/container/container-min.js"></script>

Using Dialog

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

• Defining Dialog Markup
• Setting up Dialog Buttons and Callbacks
• Initializing the Dialog
• Submitting Form Data
• Reading Current Form Data
• Configuration Properties

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

Defining Dialog Markup

HTML markup for Dialog uses the same modular format underlying Module. Because the core interaction supported by Dialog involves gathering information from the user via an HTML form, typically you place a form element in the "body" section of your Dialog module. Placing the form element in the page, rather than creating the form via script once the Dialog instance is created, enables you to use Progressive Enhancement — showing the full content and functionality to users who may have older browsers or who have JavaScript disabled while still providing a richer interaction to modern, standards-compatible browsers.

The following example illustrates the markup for a Dialog module:

<div id="myDialog"> <div class="hd">Please enter your information</div> <div class="bd"> <form name="dlgForm" method="POST" action="php/post.php"> <p>Please enter your personal contact information:</p> <label for="firstname">First Name:</label><input type="text" name="firstname" /> <label for="lastname">Last Name:</label><input type="text" name="lastname" /> </form> </div> </div>

The "action" attribute specified in the form is the one that is used to submit the data, regardless of whether you have configured your Dialog (via the postmethod attribute) to use XMLHttpRequest or standard form submission.

If no form is specified in your markup, one is automatically created for you by Dialog (its name attribute will be "frm_dialogid", where dialogid is the HTML element id you passed to the Dialog constructor). If you allow Dialog to create the form for you dynamically, be sure to set the form's action attribute by script if you wish the form to post via XMLHttpRequest or standard form submisison.

Setting up Dialog Buttons

Dialog provides a configuration property called "buttons" that allows you to automatically wire up buttons with callbacks to display in the footer of the Dialog. Buttons are configured by creating an array of objects as illustrated in the following code sample. Note that you can configure a separate handler script to respond to each of the buttons.

var handleCancel = function() { this.cancel(); } var handleSubmit = function() { this.submit(); } var myButtons = [ { text:"Submit", handler:handleSubmit, isDefault:true }, { text:"Cancel", handler:handleCancel } ]; myDialog.cfg.queueProperty("buttons", myButtons);

Each button object in the buttons array can have three properties:

• text: The text that will display on the face of the button;
• handler: the function that should fire when the button is clicked (the scope of this function is always its Dialog instance);
• isDefault: an optional boolean value that specifies that a button should be highlighted and focused by default.

In the example above, the "buttons" property is queued up to be executed upon render of the Dialog.

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

Initializing the Dialog

To instantiate a Dialog, use this code:

var myDialog = new YAHOO.widget.Dialog("myDialog");

This constructor uses an element with an HTML ID of "myDialog" on the page; the markup example above provides a template for this markup. Once instantiated, you may wish to configure the form's buttons (see above) and then render your Dialog instance on the page:

myDialog.render();

Generally, Dialogs are hidden when the page loads and only appear when needed. To reveal your Dialog on screen, invoke its show method:

myDialog.show();

Submitting Form Data

Submitting the Dialog via script is as simple as calling the submit function on the Dialog object:

myDialog.submit();

The default postmethod for the Dialog is async. Upon submission of a Dialog whose postmethod configuration is set to async (meaning that it will use Connection Manager to post the form's data via XMLHttpRequest to the URI specified in the form element's action attribute), all of the appropriate Connection Manager callbacks documented in the API will be executed, allowing for easy handling of the response. By default the Dialog is automatically hidden after submission, however the hideaftersubmit configuration property can be used to control this behavior.

For example, to set up the handlers for both successful and failing Dialog submissions when using an asynchronous form post, the code might look like this:

var onSuccess = function(o) { alert("Your data was successfully submitted. The response was: " + o.responseText); } var onFailure = function(o) { alert("Your submission failed. Status: " + o.status); } myDialog.callback.success = onSuccess; myDialog.callback.failure = onFailure;

If the Dialog's form contains a file upload input control (<input type="file">) the Dialog will use Connection Manager's file upload support when sending out the async request. For file uploads Connection Manager expects the callback to be defined with a single upload handler, replacing the success and failure handlers. The upload handler will be invoked on completion of the transaction:

var onUpload = function(o) { // NOTE: In this case, since Connection Manager uses an iframe for submission, // o.responseText will contain the contents of the iframe's document.body tag as a string. // See the Connection Manager documentation for more details alert("Your data was successfully submitted. The response was: " + o.responseText); } myDialog.callback.upload = onUpload;

It's also valuable to note that the callback object referenced in the above example is passed directly to the Connection Manager, and therefore can accept the argument and scope properties in addition to success and failure. More information on the usage of these properties is available in the Connection Manager documentation.

Reading Current Form Data

Dialog provides a function called getData that returns a simple object structure with the form's current data. For instance, in the example above, if you wanted to find out what someone typed in the field called "firstname" you could retrieve that value from getData like such:

var firstname = myDialog.getData().firstname;

Configuration Properties

Dialog has the following configuration properties:

Dialog has the following inherited configuration properties:

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.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.