O'Reilly logo

jQuery UI by Eric Sarrion

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

The dialog () Method

The dialog () method can be used in two forms:

  • $(selector, context).dialog (options)

  • $(selector, context).dialog ("action", params)

The dialog (options) Method

The dialog (options) method declares that an HTML element (and its contents) should be administered in the form of a dialog box. The options parameter is an object that specifies the appearance and behavior of that window. The available options manage the appearance, position, and size of the window, as well as the behavior of visual effects.

Table 4-1 describes the option for managing the appearance of the dialog box.

Table 4-1. Options for managing dialog box appearance

Options

Function

options.title

Give a title to the window.

options.buttons

Add buttons in the dialog box. These are listed as objects, and each property is the text on the button. The value is a callback function called when the user clicks the button.

Table 4-2 describes the options for managing the position of the dialog box.

Table 4-2. Options for managing dialog box position in the page

Options

Function

options.position

The position of the window is specified as coordinates [left, top] or a string such as:

  • "left top", "top right", "bottom left", or "right bottom" (for each of the four corners of the page)

  • "top" or "bottom" (top or bottom, centered in width)

  • "left" or "right" (left or right, centered in height)

  • "center" (centered in width and height)

By default, the window is centered in the width and height ("center").

Table 4-3 describes the options for managing the size of the dialog box.

Table 4-3. Options for managing dialog box size

Options

Function

options.height

The initial height (in pixels) of the dialog box. The default value is "auto" (the size adjusts automatically to display all content).

options.width

The initial width (in pixels) of the dialog box. The default is 300.

options.maxHeight

Maximum height (in pixels) to which the dialog box can be resized.

options.maxWidth

Maximum width (in pixels) to which the dialog box can be resized.

options.minHeight

Minimum height (in pixels) to which the dialog box can be resized. The default value is 150.

options.minWidth

Minimum height (in pixels) to which the dialog box can be resized. The default value is 150.

Managing the visual effects on the dialog box

It is also possible, thanks to jQuery UI, to specify an effect for the appearance and disappearance of the dialog box with the options.show and options.hide options (described in Table 4-4).

Table 4-4. Options for managing visual effects

Options

Function

options.show

Visual effect to occur at the appearance of the dialog box (the effects are listed in Table 4-5). When set to false (the default), there is no visual effect associated with the appearance of the dialog box.

options.hide

Visual effect to occur at the disappearance of the dialog box (listed in the table below). When set to false (the default), there is no visual effect associated with the disappearance of the dialog box.

Table 4-5. Effects provided by jQuery UI

Effect name

Function

"blind"

The element appears or disappears from the top.

"bounce"

The element appears or disappears fitfully, in a vertical movement.

"clip"

The element appears or disappears vertically from the center.

"drop"

The element appears or disappears from the left, with a change of opacity.

"fold"

The element appears or disappears from the top left corner.

"highlight"

The element appears or disappears with variations of opacity and background color.

"puff"

The element is scaled from its center. It appears by “shrinking” and disappears by “growing.”

"pulsate"

The element appears or disappears by flashing.

"scale"

The element is scaled from its center. It disappears by shrinking and appears by growing.

"slide"

The element appears or disappears from its right side.

Managing the behavior of the dialog box

Table 4-6 describes the options for managing the behavior of the dialog box when it is opened, moved, stacked, and resized.

Table 4-6. Options for managing dialog box behavior

Options

Function

options.autoOpen

If true (the default), the dialog box opens with the call to the dialog (options) method.

If false, the dialog box is created, but will only be visible by calling the dialog ("open") method.

options.draggable

If true (the default), the dialog box can be moved on the page.

options.resizable

If true (the default), the dialog box can be resized on the page.

options.modal

If true, the dialog box is modal (other elements on the page outside the dialog box are inaccessible).

The default value is false (the dialog box is not modal).

options.stack

If true (the default), the dialog box can be stacked (clicking on a window or dialog box brings it to the foreground).

If false, dialog boxes are open, one on top of another, but users cannot change the order of the stack.

Managing events in the dialog box

Dialog box event methods (described in Table 4-7) allow you to perform treatments at different stages of the dialog box. They correspond to callback functions called at these different stages. The value in the callback function is the <div> element associated with the contents of the dialog box.

Table 4-7. Options for managing dialog box events

Options

Function

options.focus

The focus (event) method is called whenever the dialog box is activated (in its first appearance and each click on it).

options.open

The open (event) method is called whenever the window is displayed (in its first appearance or following calls to the dialog ("open") method).

options.beforeclose

The beforeclose (event) method is called whenever the dialog box will be closed (when clicking on the close button or making a call to the dialog ("close") method). If the function returns false, the dialog box will not be closed. A closed dialog box can be reopened by dialog ("open").

options.close

The close (event) method is called whenever the dialog box is closed (when clicking on the close button or call to the dialog ("close") method). A closed dialog box can be reopened by dialog ("open").

options.drag

The drag (event) method is called for every mouse movement when the dialog box is moved on the page.

options.dragStart

The dragStart (event) method is called at the beginning of the movement of the dialog box on the page.

options.dragStop

The dragStop (event) method is called at the end of movement of the dialog box on the page (when the mouse button is released).

options.resize

The resize (event) method called for every mouse movement when the dialog box is resized on the page.

options.resizeStart

The resizeStart (event) method is called at the beginning of resizing the dialog box on the page.

options.resizeStop

The resizeStop (event) method is called at the end of resizing the dialog box on the page (when the mouse button is released).

The dialog (“action”, params) Method

The dialog ("action", params) method can perform an action on the dialog box, such as opening or closing it. The action is specified as a string in the first "action" argument (e.g., "open" to open a window).

Table 4-8 describes the actions you can perform using this method.

Table 4-8. The dialog (“action”, params) method actions

Method

Function

dialog ("open")

Open the dialog box.

dialog ("close")

Close the dialog box. It is then hidden and may be reopened by dialog ("open").

dialog ("destroy")

Remove dialog box management. Dialog boxes are reverted to simple HTML without CSS class or event management, and are hidden in the page.

dialog ("disable")

Make the dialog box appear disabled, without actually disabling it. The dialog box elements (title bar, content, borders) remain available.

dialog ("enable")

Restore the normal appearance to the elements of the dialog box.

dialog ("isOpen")

Returns true if one of the dialog boxes in the list is open, otherwise returns false.

dialog ("moveToTop")

Position the corresponding dialog boxes to the foreground (on top of the others).

dialog ("option", param)

Get the value of the specified param option. This option corresponds to one of those used in the dialog (options) method.

dialog ("option", param, value)

Changes the value of the param option. This option corresponds to one of those used in the dialog (options) method.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required