UPDATE 01/02/2012: Version 2.0.0 of the Bootbox library is out. Whilst this tutorial is still largely accurate and version 1.1.2 will work with the 1.x series of Twitter's Bootstrap framework, you should check out the updated version here.
Dialogs using Twitter Bootstrap
You may be wondering why a few wrapper methods around bootstrap's built-in dialog capabilities are either necessary or desirable. To begin to answer that, let's look at the code required to show a simple
alert style dialog programatically using bootstrap:
Note that this example is purely for demonstration purposes - you probably don't want to show an obtrusive dialog as soon as the page loads! Nevertheless, as you can see from the previous snippet, we have to:
- Create the dialog's HTML and have it present somewhere in the DOM
- Add the buttons to dismiss the dialog
- Ensure the handlers are unbound when the dialog is hidden
- Show and hide the dialog itself
Let's dive straight in and see the most simple example of a bootbox alert in action:
Which results in the following dialog:
alert as best as possible, hence the 'OK' button is automatically focused so the user can dismiss it by hitting the return key. This brief example demonstrates how bootbox simplifies creating, showing and dismissing bootstrap's dialogs, so let's now go on and look at what else it can do.
confirm, meaning that as a developer you can guarantee that the alert has been dismissed before subsequent code executes. In userland, you can’t block the script's thread of execution, so we have to resort to a familiar ally if we want to delay execution of some code until we're sure a user has processed our notification. This ally comes in the form of a callback function provided as an argument to our bootbox alert method. Let’s take a look at an example:
Custom button labels
Last but not least on the subject of alert boxes, you can provide a custom label if you’re not happy with the standard ’OK’ button:
Resulting in the following button being displayed:
As you can see, the argument list is flexible - the general rule of thumb is that a callback method, if provided, should always be the last argument.
The native confirm method is as useful — and in some cases certainly more useful — than the alert method, as it not only alerts the user but prompts them to make a meaningful decision which will impact subsequent program flow based on their choice. Let's take a look at its most basic usage:
A confirm without a callback isn't particularly useful, but since it’s entirely possible using the native method, it’s possible with bootbox.
Let’s look at getting the most out of of the choices we offer the user. The callback we provide will be populated with a boolean representing which choice the user made as per the native method:
The API provided follows the same format of bootbox.alert, which means we can override one or both of the button labels we show the user if we want to:
Under the hood,
bootbox.confirm just process the arguments provided to them and ship them off to
bootbox.dialog which is a public method which you can call too. It takes a range of flexible arguments which allow the creation of complex dialogs with a variety of buttons and callbacks. Of course, you can create very simple dialogs too, and although you’re probably better off using
bootbox.alert to do so let’s take a look at the most simple dialog we can create:
The above snippet isn't very useful since it provides no buttons, meaning the user can't actually respond to the dialog at all. Let's sort that out, and while we're at it, let's add a callback function (though the
callback key is entirely optional):
For convenience, the following form is equivalent if you want to provide a label and a callback without a custom button class:
What's this about button classes? So far we haven't provided any at all, which causes bootbox to do some head scratching to work out the most appropriate classes to apply to each button (e.g.
primary on a single button,
primary for two buttons). We can provide a
class key to customise the appearance of our button labels as per the classes provided by twitter's bootstrap framework:
So far, we've only looked at a custom dialog with one button displayed to the user. However, if you're using
bootbox.dialog in the first place, you probably want more than this. Let's have a look at a significantly more complex dialog:
Please note the subtle difference in the method's arguments - the second of which is now an array of objects, rather than just a single button declaration.
We can specify a third argument to the dialog method which closely resembles the options accepted by bootstrap's
In fact, the only difference is that you can provide an
onEscape option, which is a callback to be executed when the user dismisses the dialog with the escape key:
onEscape option is used when calling
bootbox.alert meaning that a user can dismiss an alert message by pressing escape. Since confirm dialogs require a decision, the escape key is disabled when calling
bootbox.confirm. Of course, with
bootbox.dialog you can use
onEscape however you wish - you can disable it, you can pass it the same callback as one you provide to one of its buttons, or you can give it an entirely customised callback. The choice is yours.
By and large, you'll want your user to determine when it's time to hide a dialog by choosing one of its options. However, there may be times when you need to programatically do this. So far we haven't been interested in the return values of any of the bootbox methods, which is always the DOM element created representing the modal dialog box. If you assign this return value to a variable then you can hide it using twitter's
An alternative use case is when you want to hide all active instances of bootbox dialogs. Although you shouldn't really have more than one dialog on screen at once, if you do (or if you don't want to keep track of your dialogs using variables), then bootbox has a convenience method to hide all of its dialogs at once:
One final note on hiding dialogs in this manner - please note that none of your callbacks, either assigned to a button selection or the escape key, will be triggered when dialogs are programatically hidden.
Bootbox wasn't really designed as a plugin per-se, but as it evolved it felt like it was worth polishing off and releasing stand alone. The source code is naturally available on GitHub. A very simple demo page is available in the repository based largely on the example gists embedded throughout this article, though it could certainly do with a bit of attention. Any bugs, features or pull requests are of course most welcome. If you enjoyed this article, why not watch the project or follow me for updates about it, or spread the word using the tweet button below. Thank you!