README
jquery.dirtyforms.dialogs.bootstrap
This is a dialog module for the jQuery Dirty Forms project.
Purpose
This module causes Dirty Forms to use Bootstrap Modal as its dialog when the user attempts to leave the page by clicking a hyperlink (but not when interacting with the navigation buttons of the browser).
Only 1 dialog module can be used by Dirty Forms at a time. The default behavior without this package is to use the browser's built in dialog that is fired by the
beforeunload
event.
Prerequisites
Prerequesites must be included in this order:
- jQuery (>= 1.9.1)
- bootstrap (>= 3.0.0) - both the CSS and JS
- jquery.dirtyforms (>= 1.0.0)
If you are using a Package Manager, these dependencies will be installed automatically, but depending on your environment you may still need to add references to them manually.
Download & Installation
There are several different ways to get the code. Some examples below:
CDN
The Bootstrap Modal dialog module is available over jsDelivr CDN and can directly be included on every page.
<script type="text/javascript" src="//cdn.jsdelivr.net/jquery.dirtyforms/2.0.0/jquery.dirtyforms.dialogs.bootstrap.min.js"></script>
jsDelivr also supports on-the-fly concatenation of files, so you can reference only 1 URL to get jQuery, bootstrap, jquery.dirtyforms, and jquery.dirtyforms.dialogs.bootstrap in one request.
<script type="text/javascript" src="//cdn.jsdelivr.net/g/jquery@1.11.3,bootstrap@3.0.0,jquery.dirtyforms@2.0.0(jquery.dirtyforms.min.js+jquery.dirtyforms.dialogs.bootstrap.min.js)"></script>
Self-Hosted
Download and save one of two available files to include the Bootstrap Modal dialog module to your page, either the latest distribution or the latest minified version.
<script type="text/javascript" src="jquery.dirtyforms.dialogs.bootstrap.min.js"></script>
You can also conveniently get all of the latest Dirty Forms files in one Zip Download.
Package Managers
The Bootstrap Modal dialog module is even available through NPM, Bower, and NuGet. Just use one of the following commands below to install the dialog module, including all dependencies.
// NPM
$ npm install jquery.dirtyforms.dialogs.bootstrap
// Bower
$ bower install jquery.dirtyforms.dialogs.bootstrap
// NuGet
PM> Install-Package jquery.dirtyforms.dialogs.bootstrap
SourceMaps
A SourceMap file is also available via CDN or your favorite package manager.
CDN
<script type="text/javascript" src="//cdn.jsdelivr.net/jquery.dirtyforms/2.0.0/jquery.dirtyforms.dialogs.bootstrap.min.js.map"></script>
Package Managers
NPM, Bower, and NuGet will install the SourceMap file into the destination directory.
jquery.dirtyforms.dialogs.bootstrap.min.js.map
Usage
This dialog module is automatic. Simply include the reference to the dialog module after the prerequisites and use Dirty Forms as per the documentation and Bootstrap Modal as per the documentation. However, it is also possible to customize the HTML.
// CSS
<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/bootstrap/3.0.0/css/bootstrap.min.css" />
// JavaScript
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js" type="text/javascript"></script>
<script src="//cdn.jsdelivr.net/bootstrap/3.0.0/js/bootstrap.min.js" type="text/javascript"></script>
<script src="//cdn.jsdelivr.net/jquery.dirtyforms/2.0.0/jquery.dirtyforms.min.js" type="text/javascript"></script>
<script src="//cdn.jsdelivr.net/jquery.dirtyforms/2.0.0/jquery.dirtyforms.dialogs.bootstrap.min.js" type="text/javascript"></script>
If not using a CDN, you need to apply the dependencies in the same order as in the example above.
Options
The following options are available to set via $.DirtyForms.dialog.OPTIONNAME = OPTIONVALUE or get via OPTIONVALUE = $.DirtyForms.dialog.OPTIONNAME
Name | Type | Default | Description |
---|---|---|---|
title | string | ' Are you sure you want to do that?' | Sets the title of the dialog. Supports HTML. |
proceedButtonClass | string | 'dirty-proceed' | Sets the CSS class of the continue button of the dialog (an HTML button tag element). The element with this class will automatically have the proceedButtonText inserted into it and a click event handler bound to it before showing the dialog. |
proceedButtonText | string | 'Leave This Page' | Sets the text of the continue button of the dialog. |
stayButtonClass | string | 'dirty-stay' | Sets the CSS class of the cancel button of the dialog (an HTML button tag element). The element with this class will automatically have the stayButtonText inserted into it before showing the dialog. |
stayButtonText | string | 'Stay Here' | Sets the text of the cancel button of the dialog. |
dialogID | string | 'dirty-dialog' | Sets the ID of the outermost element of the dialog. If there is an element with this ID on the page, it will be used for the dialog. If not, a default dialog will be automatically generated. |
titleID | string | 'dirty-title' | Sets the ID of the element that represents the dialog title. The element with this ID will automatically have the title text inserted into it before showing the dialog. |
messageClass | string | 'dirty-message' | Sets the CSS class of the element that represents the message body. The element with this class will automatically have the message inserted into it before showing the dialog. |
preMessageText | string | '' | Sets the text that precedes the message text. May contain HTML. |
postMessageText | string | '' | Sets the text that follows the message text. May contain HTML. |
replaceText | boolean | true | Set to false to prevent the title, message, continue button text, and cancel button text in the dialog from being overwritten by the configured values. This is useful if you want to configure your dialog text entirely in the HTML of the page. |
Setting the width of the bootstrap modal requires custom CSS to ensure it will work with different viewport sizes. See this page for examples.
Customization
Because Bootstrap requires ultimate control over the HTML in order to function, it is possible to provide your own HTML either directly into the page or via JavaScript. Simply add it to the page and ensure that the following match what is specified in the options.
- dialogID (required)
- titleID (optional)
- messageClass (optional)
- proceedButtonClass (required)
- stayButtonClass (optional)
Example
$('<div id="custom-dialog" class="modal fade" tabindex="-1" role="dialog" aria-labelledby="custom-title">' +
'<div class="modal-dialog" role="document">' +
'<div class="modal-content panel-danger">' +
'<div class="modal-header panel-heading">' +
'<button type="button" class="close" data-dismiss="modal" aria-label="Close">' +
'<span aria-hidden="true">×</span>' +
'</button>' +
'<h3 class="modal-title" id="custom-title"></h3>' +
'</div>' +
'<div class="modal-body panel-body custom-message"></div>' +
'<div class="modal-body panel-body">This is some custom text to include in the dialog.</div>' +
'<div class="modal-footer panel-footer">' +
'<button type="button" class="custom-proceed btn btn-primary" data-dismiss="modal"></button>' +
'<button type="button" class="custom-stay btn btn-default" data-dismiss="modal"></button>' +
'</div>' +
'</div>' +
'</div>' +
'</div>').appendTo('body');
$('form').dirtyForms({
// Message will be shown both in the Bootstrap Modal dialog
// and in most browsers when attempting to navigate away
// using browser actions.
message: 'This is a custom message',
dialog: {
title: 'This is a custom title',
dialogID: 'custom-dialog',
titleID: 'custom-title',
messageClass: 'custom-message',
proceedButtonClass: 'custom-proceed',
stayButtonClass: 'custom-stay'
}
});
// If .dirtyForms() has already been called, you can override
// the values after the fact like this.
$.DirtyForms.dialog.title = 'This is an alternative custom title';
Support
For help or to report a bug please open an issue at the Dirty Forms development site.