Getting Started with the Dialog Control

The Dialog component is an extension of Panel that is meant to emulate the behavior of an dialog window using a floating, draggable HTML element. Dialog provides an interface for easily gathering information from the user without leaving the underlying page context. The information gathered is collected via a standard HTML form; Dialog supports the submission of form data through XMLHttpRequest, through a normal form submission, or through a manual script-based response (where the script reads and responds to the form values and the form is never actually submitted to the server).

Instantiating a Dialog is very similar to other controls in the Container collection. In this tutorial, we will create a Dialog from existing markup where the container element's id is "dialog1":

The properties for width, fixedcenter, visible, and constraintoviewport are inherited from Panel. Unique to the Dialog control is the buttons property, which takes an array of object literals representing the buttons that will be rendered in the Dialog's footer. Each one of these button literals has three possible properties: "text" which represents the button text, "handler" which is a reference to the function that will execute when the button is clicked, and "isDefault" which will apply a bold style to the button when set to true.

Next, we must define the handleCancel and handleSubmit handlers for our buttons. In this tutorial, the submit and cancel buttons will call the corresponding functions in the Dialog:

By default, the Dialog is submitted using the Connection Manager. In order to handle the response from the server, we must define callback functions that will execute when the submission has occurred. First, we will define the functions, and then we will set them into our Dialog's callback — the same callback object that will be passed to Connection Manager's asyncRequest method. For the purposes of this example, the success handler will simply diplay the server response on the page. The failure handler will alert the response status code, if something goes wrong:

You can also take advantage of Dialog's built-in validation function so that you can verify that the values entered by the user are valid prior to form submission. In this tutorial, we will verify that the user has entered, at the very least, a first and last name. Using the getData function, we can easily query the values of the form fields. In a valid scenario, the function should return true, otherwise the function should return false, which will prevent the submission:

Finally, we will build the markup for the Dialog. A Dialog contains a form whose fields will be submitted to the server. Note that the URL where the form will be submitted is specified in the "action" attribute of the form.