Version 1.1.0

Installation

Installing DialogBox.js is pretty straight forward: simply include DialogBox.min.js and DialogBox.min.css to your document. DialogBox.js relies on jQuery & jQuery UI, so you will also need to include those before including DialogBox.min.js . If you don’t want to include the full jQuery UI library, at the bare minimum you must include jQuery UI Core & jQuery UI Draggable. Here is a simple HTML structure to get you started:

<!DOCTYPE html>
<html>
    <head>
        <link href="dialogbox.min.css" rel="stylesheet" />
        <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
        <script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
        <script src="dialogbox.min.js"></script>
    </head>
    <body></body>
</html>

Note that you have to include DialogBox.min.js before using it in your script.

Templates

There are 7 available built-in templates, that can be used to create dialog boxes quickly with a few lines of code. Each template function accepts a settings object as an argument with a set of key/value pairs that configure the dialog box.

For custom dialog boxes, see the next section.

Error

The error dialog box takes two options:

  • title – The dialog box’s top bar title
  • html – The dialog box’s HTML content

Example code:

DialogBox.error({
    title: 'Error Dialog Box', 
    html: 'Some HTML content'
});

Success

The success dialog box takes two options:

  • title – The dialog box’s top bar title
  • html – The dialog box’s HTML content

Example code:

DialogBox.success({
    title: 'Success Dialog Box', 
    html:  'Some HTML content'
});

Notice

The notice dialog box takes two options:

  • title – The dialog box’s top bar title
  • html – The dialog box’s HTML content

Example code:

DialogBox.notice({
    title: 'Notice Dialog Box', 
    html:  'Some HTML content'
});

Info

The info dialog box takes two options:

  • title – The dialog box’s top bar title
  • html – The dialog box’s HTML content

Example code:

DialogBox.info({
    title: 'Info Dialog Box', 
    html:  'Some HTML content'
});

Confirm

The confirm dialog box asks a user to take action. The user must make a choice, cannot close or ignore it. The template takes four options:

  • title – The dialog box’s top bar title
  • html – The dialog box’s HTML content
  • yes – a function that will be called if the user clicks on “yes”
  • no – a function that will be called if the user clicks on “no”

Example code:

DialogBox.confirm({
    title: 'Confirm', 
    html:  'Some HTML content',
    yes:   function() {
        // Do something when the user clicks "yes"
    },
    no:    function() {
        // Do something when the user clicks "no"
    }
});

Prompt

The prompt dialog box asks a user for input. The input value can than be used in the callback function. The template takes 7 options:

  • title – The dialog box’s top bar title
  • htmlBefore – An HTML string to be inserted before the input element
  • htmlAfter – An HTML string to be inserted after the input element
  • inputs – An array of objects containing the following parameters:
    • type – One of HTML5 input types. See MDN for available types
    • placeholder – Some text to be used as a placeholder for the input
    • name – The name of the input. Must be unique
    • required – A boolean value specifying whether or not this input is required. When set to true, the dialog box will not be closed until input is provided
  • error – A function that accepts the current input values as an argument, and returns a string containing a message that will be shown to the user in the event that one or more of the required inputs is empty
  • success -A function that accepts the current input values as an argument, and returns a string containing a message that will be shown to the user if all required inputs have been filled, or if there are no required inputs

Example code:

DialogBox.prompt({
    title:       'Prompt', 
    htmlBefore:  'Some HTML content',
    htmlAfter:   '(Do not leave the input blank)',
    inputs:      [
        {
            type:'text', // One of HTML5's input types
            placeholder: 'Input\'s placeholder',
            name: 'name', // Must be unique
            required: true
        }
    ],
    inputType:   'text', // One of HTML5's input types
    requireInput:true,
    error: function( values ) { // Called if required inputs are empty
        return 'You must provide some input!';
    },
    success: function( values ) { // Called if required inputs are not empty or if there are no required inputs
        return 'Your name is <strong>'+values.name+'</strong>';
    }
});

Progress Bar

The progress bar dialog box can be used to show the progress of a certain task as it is being performed. It can be used to show the user the status of a task being performed in real time. The progress bar position can be changed after the dialog box has become visible by using the method  DialogBox.setProgress( num )   and giving it a integer between 0 – 100.

Example Code:

DialogBox.progress({
    onOpen: function(){
        DialogBox.setProcess( 34 ); // Set the process to a percentage between 0 and 100
    }
});

Custom Dialog Boxes

You can create fully customized dialog boxes by calling the DialogBox.open( settings ) function and providing some or all of the available options. For the full list of available options see the next section.

Example code:

DialogBox.open({
    width:         300,
    height:        300,
    draggable:     false,
    buttons:       [{
        text: 'Got it!',
        click: function() {
            alert('Dialog Box closed!');
        }
    }],
    html:          'Some HTML content',
    animationTime: 500,
    showTopBar:    false
});

Options

There are 20 available options that control the behavior of the dialog boxes. These options can be used with the DialogBox.open( settings ) function, or with any of the preset templates. If used with a preset template, the provided settings will override the preset settings.

Option Name Data Type Purpose
minWidth number The minimum width of the dialog box.
minHeight number The minimum height of the dialog box.
maxWidth number The maximum width of the dialog box.
maxHeight number The maximum height of the dialog box.
width number The width of the dialog box. If you use this option, minWidth and maxWidth are ignored.
height number The height of the dialog box. If you use this option, minHeight and maxHeight are ignored.
draggable boolean Set the draggability of the dialog box.
buttons array An array of objects that contain 2 parameters:

  • text – (string) The button’s label text
  • click – (function) a function that is called when the button’s onclick event is triggered. The this  variable will refer to the calling dialog box settings
  • type – (string) The button’s type. One of primary, secondary, positive, negative.
title string The dialog box’s title (appears inside the top bar).
html string The HTML content of the dialog box.
icon string The icon’s name. One of the built-in icons: check, exclamation, info, times, question, pencil and key. You can also specify your own name, for example myicon which will generate an element with the class name dialogbox-icon-myicon, which you can then use to add your own custom icon.
animationTime number The duration of the open/close animation (in milliseconds). Note that if you change it, you must change the css animation time as well.
showTopBar boolean True/false to show the dialog box’s top bar.
showCloseButton boolean True/false to show the close button in the dialog box’s top bar.
closeOnBgClick boolean True/false to close the dialog box when clicking outside of it.
bgColor string A string containing the color of the background cover. Colors can be given in the hex, hsl, rgb & rgba formats.
position object The position of the dialog box. Use an object with 2 parameters:

  • x – The x coordinate of the dialog box. Can be a number or a string. Accepted strings are center, left and right.
  • y – The y coordinate of the dialog box. Can be a number or a string. Accepted strings are center, top and bottom.
onOpen function A function that will be called once the dialog box is visible (after the animation has finished)
onClose function A function that will be called once the dialog box is being closed (before the animation begins)
delayedClose number An integer specifying the amount of time (in milliseconds) to wait before automatically closing the dialog box

Methods

DialogBox.open( settings ) – Open a new dialog box with the given settings.

DialogBox.close() – Close the currently opened dialog box.

DialogBox.isOpen() – Returns true if a dialog box is currently opened.

DialogBox.addButton( settings ) – Add a new button to the dialog box’s available controls. The settings argument is an object that contains 2 parameters:

  • text – (string) The button’s label text
  • click – (function) a function that is called when the button’s onclick event is triggered.

DialogBox.removeButton( buttonText ) – Remove a button by it’s label text.

DialogBox.setProgress( num ) – Sets the current progress bar position. Applicable when calling DialogBox.progress(). num is an integer between 0 – 100.

Events

The dialog box triggers different events that are despatched on the window object. To catch an event, add an event listener to the window object.

There are 5 available events that can be hooked onto:

  • dialogbox-open – Triggered when the dialog box is opened.
  • dialogbox-before-close – Triggered before the dialog box is closed.
  • dialogbox-close – Triggered after the close animation is finished and the dialog box is closed.
  • dialogbox-drag-start – Triggered when the dialog box is being dragged.
  • dialogbox-drag-stop – Triggered after the dialog box is stopped being dragged.

Code example:

window.addEventListener('dialogbox-open', function (e) { 
    console.log('The dialog box is open'); 
}, false);

Spread the word about DialogBox.js!