vex

Basic

Dialog API

vex-dialog exposes 4 main apis:

• vex.dialog.alert(stringOrOptions)
• vex.dialog.confirm(options)
• vex.dialog.prompt(options)
• vex.dialog.open(options)

These all call the vex.open method with different combinations of options. All of the options that vex.open supports are also supported here.

vex-dialog provides safe by default behavior by treating the message you provide as a regular string, not raw HTML.

If you need to pass through HTML to your dialog, use the unsafeMessage option. The unsafeMessage option is safe to use as long as you provide either static HTML or HTML-escape (html-escape, _.escape, etc.) any untrusted content passed through, such as user-supplied content.

Alert

Use alerts when you want to display a message to the user, but you don't want to give them any choice to proceed.

Open an alert

Play with this demo:

vex.dialog.alert('Thanks for checking out vex!')

When passing a string, the text is interpreted as a string and HTML-escaped for safety.

If you want to pass HTML tags into the alert() method, you need to use the unsafeMessage option and handle any escaping of potentially unsafe content you provide to this option:

// This use of raw HTML is made safe because the HTML is static.
vex.dialog.alert({ unsafeMessage: '<b>Hello World!</b>' })

// This use of raw HTML is made safe because the Underscore escape method is used to escape potentially unsafe content.
vex.dialog.alert({ unsafeMessage: '<b>Hello ' + _.escape(user.firstName) + '!</b>' })

Confirm

Use confirms when you want to present a yes-or-no option to the user.

Open a confirm

Play with this demo:

vex.dialog.confirm({
    message: 'Are you absolutely sure you want to destroy the alien planet?',
    callback: function (value) {
        console.log(value)
    }
})

message is interpreted as a string and HTML-escaped for safety. Explicitly use the unsafeMessage option instead when you need to pass raw HTML, making sure to HTML-escape any untrusted content (see above for example).

Prompt

Open a prompt

Play with this demo:

vex.dialog.prompt({
    message: 'What planet did the aliens come from?',
    placeholder: 'Planet name',
    callback: function (value) {
        console.log(value)
    }
})

message is interpreted as a string and HTML-escaped for safety. Explicitly use the unsafeMessage option instead when you need to pass raw HTML, making sure to HTML-escape any untrusted content (see above for example).

Open

With open, you are in full control.

Inputs

You can specify your own form inputs, and the name attribute will be the property name of the data object passed in the callback.

Buttons

You can specify your own buttons if you want more options than just OK or Cancel. If you simply want to change the labels, you can override the default options for the following:

vex.dialog.buttons.YES.text = 'Okiedokie'
vex.dialog.buttons.NO.text = 'Aahw hell no'

Custom buttons should use the following structure:

button {
    type: string, // the DOM `type` attribute
    text: string, // the textContent of the button
    className: string // the CSS class(es)
}

Demo

Putting this all together, let's create a dialog with the following customizations:

• Display a date input and a color input,
• Add an extra button which resets the color input to the default value (#000)
• Change the text for the OK button

todayDateString = new Date().toJSON().slice(0, 10)
vex.dialog.open({
    message: 'Select a date and color.',
    input: [
        '<style>',
            '.vex-custom-field-wrapper {',
                'margin: 1em 0;',
            '}',
            '.vex-custom-field-wrapper > label {',
                'display: inline-block;',
                'margin-bottom: .2em;',
            '}',
        '</style>',
        '<div class="vex-custom-field-wrapper">',
            '<label for="date">Date</label>',
            '<div class="vex-custom-input-wrapper">',
                '<input name="date" type="date" value="' + todayDateString + '" />',
            '</div>',
        '</div>',
        '<div class="vex-custom-field-wrapper">',
            '<label for="color">Color</label>',
            '<div class="vex-custom-input-wrapper">',
                '<input name="color" type="color" value="#ff00cc" />',
            '</div>',
        '</div>'
    ].join(''),
    callback: function (data) {
        if (!data) {
            return console.log('Cancelled')
        }
        console.log('Date', data.date, 'Color', data.color)
        $('.demo-result-custom-vex-dialog').show().html([
            '<h4>Result</h4>',
            '<p>',
                'Date: <b>' + data.date + '</b><br/>',
                'Color: <input type="color" value="' + data.color + '" readonly />',
            '</p>'
        ].join(''))
    }
})