v2.x Documentation

dialogSettings global object

A global object which includes default values and behaviors for the dialog boxes. It has the following properties (all strings):

Property	Default value	Description
defType	"alert"	Default type of dialog box. Possible values are "alert", "prompt" and "confirm".
defTitle	"Message"	Default title for the dialog boxes.
defContent	"Missing text"	Default message for the dialog boxes.
okText	"OK"	Label for the ok button.
continueText	"Continue"	Label for the continue button.
cancelText	"Cancel"	Label for the cancel button.

Changing this properties may be useful to localize the dialog box. For example, this snippet will show a confirm dialog with content in Italian, if the function dialog() is called without arguments:

dialogSettings = {
    defType: "confirm",
    defTitle: "Conferma",
    defContent: "Contenuto non impostato",
    okText: "Accetta",
    continueText: "Continua",
    cancelText: "Annulla"
};

// Show the default dialog
dialog();

dialog() global function

Main function to display the dialog box.

It takes only one optional argument, an object containing the following properties:

Property	Type	Description
type	string	Type of dialog box. Possible values are "alert", "prompt" or "confirm".
title	string	Title of the dialog. HTML is not supported.
content	string	Message of the dialog. HTML is not supported, but whitespaces are preserved.
placeholder	string	On a prompt dialog, this will be a placeholder text for the input box.
id	string	An identifier that will be referenced in the returnObj object.
callback	Function	Reference to a function to be executed when the dialog is closed. Its first argument will be the returnObj.
vars	Object	Reference to a status object that will be referenced in the returnObj object.

This is an example of a standard usage:

dialog({
    type: "prompt",
    title: "Example",
    content: "What's your name?"
});

returnObj argument of the callback function

The most important object which allows to know, after the user closed the dialog box, if they chose ok, continue or cancel, what text they typed in the input box, etc...

The first argument of the callback function will be an object - called returnObj in this documentation for reference - containing the following parameters:

Property	Type	Description
action	boolean	true if the user has pressed ok or continue, false for cancel.
value	string	Value of the prompt input box. If the dialog box requested was not a prompt dialog it's set to undefined.
id	string	Same identifier passed when calling the dialog() function.
vars	Object	Same object reference passed when calling the dialog() function. Useful to memorize data between subsequent dialogs.

This is the previous example, but with some callback functions:

var options = {
    type: "prompt",
    title: "Example",
    content: "What's your name?",
    callback: check,
    id: "first",
    vars: {foo: "bar"}
};

function check(box) {
    if (box.id === "first" && box.action) {
        box.vars.name = box.value != "" ? box.value : "Unnamed";
        dialog({
            type: "confirm",
            content: "Do you want to have your name printed on a message?",
            vars: box.vars,
            callback: check,
            id: "second"
        });
    }
    else if (box.id === "second" && box.action) {
        dialog({
            // default type is alert, so we don't need to specify it
            title: "Print out",
            content: "Hello " + box.vars.name + "\nFoo: " + box.vars.foo
        });
    }
}

// Start the chain
dialog(options);

Live demo

The three examples reported on this documentation are available live here.

NB: the live demo refers to the latest version of this library, syntax and properties may differ.