Class: Dialog

dialogs~ Dialog


new Dialog()

A class for a Dialog box.

An instance of a Dialog can be accessed indirectly by use of
one of the showXxx methods.

Example

Show a basic simple OK Dialog box

dialogs.showOk("Here's a nice OK dialog box!");

Methods


buttonJq(name)

Return the button DOM for the given name.

Parameters:
Name Type Description
name String

The name of the button.

Returns:

the Button's jQuery DOM object or null if nothing found.

Type
jQuery

cancel( [handler])

Add a 'cancel' handler to the Dialog or if no handler is specified,
simulate clicking the Dialog's 'cancel' button.

Parameters:
Name Type Argument Description
handler function <optional>

if specified, the handler to be invoked
when the Dialog's 'cancel' button is clicked. The first argument of the
function callback is the Dialog instance.

See:
Returns:
Type
module:dialogs~Dialog

click(name)

Click one of the Dialog's buttons.

Parameters:
Name Type Description
name String

The name of the Dialog button to click.

Returns:
Type
module:dialogs~Dialog
Example

Show a Dialog with an OK button and click it 2 seconds later

var dlg = dialogs.showOk("This is an OK Dialog")
setTimeout(function () {
  dlg.click("ok")
}, 2000);   

close( [name] [, fail])

Close the Dialog. This will remove the Dialog box from the screen.

Parameters:
Name Type Argument Description
name String <optional>

The name of the button used to close the dialog box.
This parameter is designed to be called from the Dialog JS framework itself.

fail * <optional>

optional failure reason. If truthy, the dialog's promise
will be rejected with this failure reason; otherwise, the promise will be
resolved.

Returns:
Type
module:dialogs~Dialog
Example

Open a Dialog and close it after 2 seconds

var dlg = dialogs.showOk("A notification");

setTimeout(function () {
  dlg.close();
}, 2000);

content()

If this dialog has content, return the jQuery DOM wrapper
for the Content.

Returns:

The DOM wrapper for the content. This wrapper will
be empty if the dialog is shown with no content.

Type
jQuery

disableButton(name)

Disable a button.

Parameters:
Name Type Description
name String

The name of the button.

Returns:
Type
module:dialogs~Dialog

enableButton(name)

Enable a button.

Parameters:
Name Type Description
name String

The name of the button.

Returns:
Type
module:dialogs~Dialog

hide()

Hide the Dialog without closing it. The preferred method
to use is close.

Returns:
Type
module:dialogs~Dialog
Example

Hide a dialog box after 2 seconds

dialogs.showYesNo("Meeting alert! Do you want to be reminded in 10 seconds?")
       .yes(function (dialog) {
         dialog.hide();
           setTimeout(function () {
           dialog.show();
         }, 10000);
         return false;
       });

hideButton(name)

Hide a button.

Parameters:
Name Type Description
name String

The name of the button.

Returns:
Type
module:dialogs~Dialog

isClosed()

Return true if the Dialog is closed and removed from the DOM.

Returns:

Return true if the Dialog has been closed.

Type
Boolean

isHidden()

Return true if the Dialog is hidden.

Returns:

Return true if the Dialog has been hidden.

Type
Dialog

jq()

Return the internal jQuery wrapped DOM element for the entire Dialog.

Returns:

the Dialog's jQuery DOM object.

Type
jQuery

no( [handler])

Add a 'no' handler to the Dialog or if no handler is specified,
simulate clicking the Dialog's 'no' button. The first argument of the
function callback is the Dialog instance.

Parameters:
Name Type Argument Description
handler function <optional>

if specified, the handler to be invoked
when the Dialog's 'no' button is clicked.

See:
Returns:
Type
module:dialogs~Dialog

ok( [handler])

Add a 'ok' handler to the Dialog or if no handler is specified,
simulate clicking the Dialog's 'ok' button.

Parameters:
Name Type Argument Description
handler function <optional>

if specified, the handler to be invoked
when the Dialog's 'ok' button is clicked. The first argument of the
function callback is the Dialog instance.

See:
Returns:
Type
module:dialogs~Dialog

on(name, handler)

Add a callback handler for a button via its name. This callback
handler will be invoked when the button is clicked.

Any handler function can return a jQuery Deferred Promise. This
can control when and if the Dialog box closes after the handler
has been invoked. It should be noted that multiple handlers
can be registered on a button.

  • If the handlers return nothing, the Dialog will be closed after
    all the Handlers have been invoked.
  • If one or more handlers return a jQuery Deferred Promise, the Dialog
    will only close after all the jQuery Promises have been resolved.
  • If one of the Deferred Promises is rejected, the Dialog will not close.
Parameters:
Name Type Description
name String

The name of the button to register the handler on.

handler function

The handler of the function to be
invoked when the button is clicked. When invoked, the first argument of the
handler is the Dialog instance.

See:
Returns:
Type
module:dialogs~Dialog
Example

Register a function be to be called when the 'foo' button is clicked.

dialogs.show({
  content: "Show some stuff",
  buttons: [
    name: "foo",
    handler: function () {
      alert("First annoying alert!");
    }
  ]
}).on("foo", function () {
  alert("This will also be called when foo button is clicked.");
});

promise()

Return a promise for the dialog that will be resolved when the dialog closes.
This is useful when wanting to use dialogs in a promise chain when creating a user interface.

Returns:

The promise to be resolved.

Type
Promise

show()

Show the Dialog.

Returns:
Type
module:dialogs~Dialog
Example

Create a blank dialog box and then show it.

dialogs.make("A dialog box with no buttons!")
         .show();

showButton(name)

Show a button.

Parameters:
Name Type Description
name String

The name of the button.

Returns:
Type
module:dialogs~Dialog

toBack()

Move the Dialog to the back.

Returns:
Type
module:dialogs~Dialog

toFront()

Move the Dialog to the front.

Returns:
Type
module:dialogs~Dialog

yes( [handler])

Add a 'yes' handler to the Dialog or if no handler is specified,
simulate clicking the Dialog's 'yes' button.

Parameters:
Name Type Argument Description
handler function <optional>

if specified, the handler to be invoked
when the Dialog's 'yes' button is clicked. The first argument of the
function callback is the Dialog instance.

See:
Returns:
Type
module:dialogs~Dialog