Bootstrap 4 dialogs

Quick start

BCP requires jQuery v1.9.1+, Bootstrap 4 modal component, and Bootstrap's CSS.

Several quick start options are available:

• Install with npm: npm i bgaze-bootstrap4-dialogs
• Install with yarn: yarn add bgaze-bootstrap4-dialogs
• Install via CDN: https://cdn.jsdelivr.net/gh/bgaze/bootstrap4-dialogs@2/dist/bootstrap4-dialogs.min.js
• Install with Composer: composer require bgaze/bootstrap4-dialogs
• Download the latest release: https://github.com/bgaze/bootstrap4-dialogs/releases
• Clone the repo: git clone https://github.com/bgaze/bootstrap4-dialogs.git

Just make sure to include required dependencies into your app, then include the library:

• If installed as a module, import it: const bsd = require("bgaze-bootstrap4-dialogs");
• Otherwise include the script into your page: <script src="path/to/bootstrap4-dialogs.js"></script>

That's it!
Now you can use the globally declared bsd object.

// Alert
bsd.alert('Lorem ipsum dolor sit amet');

// Confirm
bsd.confirm('Lorem ipsum dolor sit amet', function (confirmed) {
    if (confirmed) {
        // ...
    }
});

// Prompt
bsd.prompt('Lorem ipsum dolor sit amet', function (value) {
    if (value !== null) {
        if (value.trim() === '') {
            return false; // Prevent dialog closing, as provided value is empty.
        }

        console.log(value);
    }
});

Usage

When a bsd method is called, a customized Boostrap 4 modal will be dynamically built and inserted into the DOM.
Unless explicitly specified through options, it is automatically shown when created, and destroyed when closed.

Arguments

Dialog functions accept two arguments:

title: the html to insert into the dialog popup title.
options: an optional set of options. If a function is provided, it will be used as dialog callback.

All available options can be customized globally as explained in the global configuration section.

// Simple dialog
bsd.alert('A message to display');

// Simple dialog with direct callback assignment
bsd.confirm('A message to display', function (confirmed) {
    if (confirmed) {
        console.log('Confirmed !');
    }
});

// Customized dialog
bsd.confirm('A message to display', {
    callback: function (confirmed) {
        if (confirmed) {
            console.log('Confirmed !');
        }
    },
    size: 'sm',
    cancelText: "No",
    confirmText: "Yes"
});

Handling dialogs

Each dialog function returns it's modal element as a jQuery object, so Bootstrap modal methods and event can be directly used, except show.bs.modal.

bsd.alert('A message to display')
    .on('shown.bs.modal', function (event) {
        // ...
    })
    .modal('handleUpdate');

The show.bs.modal event is fired before returning the modal, so to use it, you'll need to manage modal opening manually:

bsd.alert('A message to display', {show: false})
    .on('show.bs.modal', function (event) {
        // ...
    })
    .modal('show');

As a shorthand, you can directly pass a function into the show option :

bsd.alert('A message to display', {
    show: function (event) {
        // ...
    }
});

Global configuration

BSD defaults options are stored into the bsd.defaults object and organized this way:

• bsd.defaults.dialog: common options for all dialogs.
• bsd.defaults.[dialogName]: dialog specific options.

You can easily make application wide customizations:

// Make all dialogs centered vertically and horizontally.
bsd.defaults.dialog.vcenter = true;
bsd.defaults.dialog.hcenter = true;

// Define default buttons texts for confirm dialogs.
bsd.defaults.confirm.cancelText = 'No';
bsd.defaults.confirm.confirmText = 'Yes';

Please note that each dialog specific configuration inherits with precedence from common options.
So global configuration can be overrided at each dialog level:

// Use small size for all dialogs except prompt.
bsd.defaults.dialog.size = 'modal-sm';
bsd.defaults.prompt.size = null;

Theming

There is no stylesheet provided with BSD, as it only relies on Bootstrap styles.
To ease dialogs theming, two CSS classes are automatically added to each dialog :

• bsd-dialog
• bsd-[dialogName] (for instance bsd-alert for alert dialogs).

Common options

This is the list of options available for all dialogs.

Built-in dialogs

Alert

Usage

Simple call:

bsd.alert('Lorem ipsum dolor sit amet');

Simple dialog with direct callback assignment:

bsd.alert('Lorem ipsum dolor sit amet', function () {
    // ...
});

Customized dialog

bsd.alert('Lorem ipsum dolor sit amet', {
    closeText: "OK",
    closeClass: "btn-success",
    callback: function () {
        // ...
    }
});

Options

Alert dialogs accept following options in addition to common options.

<div class="modal fade" tabindex="-1" role="dialog" aria-hidden="true">
    <div class="modal-dialog" role="document">
        <div class="modal-content">
            <div class="modal-body">
                <p class="lead bsd-message"></p>
                <div class="bsd-controls d-flex align-items-center mt-3">
                    <button type="button" class="btn bsd-close" data-dismiss="modal"></button>
                </div>
            </div>
        </div>
    </div>
</div>

Confirm

Usage

The callback function will receive a boolean as argument.
Make it return false to keep the dialog opened, otherwise it will be closed.

Simple call:

bsd.confirm('Lorem ipsum dolor sit amet', function (confirmed) {
    if (confirmed) {
        // ...
    }
});

Call with options:

bsd.confirm('Lorem ipsum dolor sit amet', {
    confirmText: "Delete",
    confirmClass: "btn-danger",
    callback: function (confirmed) {
        if (confirmed) {
            // ...
        }
    }
});

Options

Confirm dialogs accept following options in addition to common options.

<div class="modal fade" tabindex="-1" role="dialog" aria-hidden="true">
    <div class="modal-dialog" role="document">
       <div class="modal-content">
           <div class="modal-body">
               <p class="lead bsd-message"></p>
               <div class="bsd-controls d-flex align-items-center mt-3">
                   <button class="btn bsd-cancel mr-1" data-dismiss="modal"></button>
                   <button class="btn bsd-confirm ml-1"></button>
               </div>
           </div>
       </div>
    </div>
</div>

Prompt

Usage

The callback function will receive null on cancel/dismiss, and the user input on submit.
Make it return false to keep the dialog opened, otherwise it will be closed.

Simple call:

bsd.prompt('Lorem ipsum dolor sit amet', function (value) {
    if (value !== null) {
        if (value.trim() === '') {
            return false;  // Prevent dialog closing, as provided value is empty.
        }

        console.log(value);
    }
});

Call with options:

bsd.prompt('Lorem ipsum dolor sit amet', {
    confirmText: "Save",
    confirmClass: "btn-success",
    callback: function (value, event) {
        if (value !== null) {
            if (value.trim() === '') {
                return false;  // Prevent dialog closing, as provided value is empty.
            }

            console.log(value);
        }
    }
});

Options

Confirm dialogs accept following options in addition to common options.

function (multiline) {
    if (multiline) {
        return '<textarea class="form-control bsd-field"></textarea>';
    }
    return '<input type="text" class="form-control bsd-field"/>';
}

function ($dialog) {
    return $('.bsd-field', $dialog).val();
}

<div class="modal fade" tabindex="-1" role="dialog" aria-hidden="true">
    <div class="modal-dialog" role="document">
       <div class="modal-content">
           <div class="modal-body">
               <p class="lead bsd-message"></p>
               <div class="bsd-field-wrapper"></div>
               <div class="bsd-controls d-flex align-items-center mt-3">
                   <button class="btn bsd-cancel mr-1" data-dismiss="modal"></button>
                   <button class="btn bsd-confirm ml-1"></button>
               </div>
           </div>
       </div>
    </div>
</div>

Custom dialogs

If you need to create custom dialogs, you can easily extend BSD:

1/ Define your dialog options and defaults

Simply append them to bsd.defaults, using your dialog name as key.

Remember that your dialog options inherit from bsd.defaults.dialog, so you can override them.
The only required option is the dialog template (template key).

bsd.defaults.mydialog = {
    // The template used to generate dialog.
    template: `<div class="modal fade" tabindex="-1" role="dialog" aria-hidden="true">
                    <div class="modal-dialog" role="document">
                        <div class="modal-content">
                            <div class="modal-header">
                                <h5 class="modal-title bsd-title"></h5>
                                <button type="button" class="close" data-dismiss="modal" aria-label="Close">
                                    <span aria-hidden="true">&times;</span>
                                </button>
                            </div>
                            <div class="modal-body">
                                <p class="bsd-subtitle"></p>
                            </div>
                            <div class="modal-footer">
                                <div class="bsd-controls d-flex flex-grow-1 align-items-center">
                                    <button type="button" class="btn bsd-no mr-1" data-dismiss="modal"></button>
                                    <button type="button" class="btn bsd-maybe mx-1"></button>
                                    <button type="button" class="btn bsd-yes ml-1"></button>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>`,

    // No button.
    noText: 'No',
    noClass: 'btn-danger',

    // Maybe button.
    maybeText: 'Maybe',
    maybeClass: 'btn-primary',

    // Yes button.
    yesText: 'Yes',
    yesClass: 'btn-success',

    // DEFAULTS OVERRIDE EXAMPLE
    // Center horizontally the dialog text: true | [false]
    hcenter: false,
};

2/ Create the dialog function

You can easily generate the dialog thanks to bsd.dialog function which requires three arguments :

1. The dialog name (must match key into bsd.defaults).
2. The options set provided by the user.
3. A customize function, that will receive as arguments:
   • the modal jQuery object
   • the final settings (user's options set merged with dialog defaults and common defaults).

From the customize function:

1. Initialize the modal content based on settings.
2. Configure each dialog button to fire an event. As the dismiss.bsd event is fired when dialog is closed with Escape key or outside click, it should also be fired by any cancel button into the custom dialog.
3. Use these events to invoke callback function.

bsd.mydialog = function (title, subtitle, options) {
    return this.dialog('mydialog', options, function ($dialog, settings) {
        // Manage dialog texts.
        $('.bsd-title', $dialog).html(title || '');
        $('.bsd-subtitle', $dialog).html(subtitle || '');

        // Customize buttons.
        $('.bsd-no', $dialog).addClass(settings.noClass).text(settings.noText).click(function () {
            $dialog.trigger('dismiss.bsd');
        });
        $('.bsd-maybe', $dialog).addClass(settings.maybeClass).text(settings.maybeText).click(function () {
            $dialog.trigger('maybe.bsd');
        });
        $('.bsd-yes', $dialog).addClass(settings.yesClass).text(settings.yesText).click(function () {
            $dialog.trigger('yes.bsd');
        });

        // Manage dialog callback.
        if (typeof settings.callback === 'function') {
            $dialog
                .on('dismiss.bsd', function () {
                    settings.callback('no');
                })
                .on('maybe.bsd', function () {
                    if (settings.callback('maybe') !== false) {
                        $dialog.modal('hide');
                    }
                })
                .on('yes.bsd', function () {
                    if (settings.callback('yes') !== false) {
                        $dialog.modal('hide');
                    }
                })
            ;
        }
    });
};

3/ Usage

Simply use your dialog like other ones: Try it

$('#mydialog-demo').click(function () {
    var subtitle = 'Phasellus ultricies dolor ac velit tempus lobortis.<br>Duis ipsum justo, viverra et molestie eget, congue in nunc.';

    bsd.mydialog('Do you like my custom dialog?', subtitle, function (value) {
        console.log(value);
    });
});

Packages

Feel free to visit my other packages: