A simple, mobile-friendly jQuery plugin for modal display windows.
You're free to download and use the already minifed files under the build directory or you can see the Build Guide for instructions on how to build the files for yourself.
The plugin requires jQuery 1.8.3+ as well as a css file to function properly. For example code look at the index.html page. Basic steps are to:
- Include the required css file:
<link rel="stylesheet" href="css/modalHome.css" /> - Include jQuery and the ModalHome code:
<script src="js/jquery-1.8.3.min.js"></script><script src="js/jquery.modalHome.js"></script> - Call the ModalHome code through a page action:
// inside some action
$.fn.modalHome({content: 'You clicked on the body element!'});
The ModalHome plugin has three main ways to be setup. The basic syntax is generally the same for each: $().modalHome('method',{data});
Content - By calling the plugin with no method (the method defaults to 'init') and an object that contains a "content" variable with a string the modal will immediately open with the included string. Example: $().modalHome({content: 'Lorem Ipsum'};
Ajax - The ajax method expects a url to load (required) and two optional variables that should contain success and failure functions respectively. Example:
$().modalHome('ajax', {
url: 'some url',
success: function (data) { console.log('success', data); },
failure: function (data) { console.log('failure', data) }
});In each case the data returned to the success or failure functions is a jqXHR object. You can specify an exact failure message to be displayed in the modal window if you wish by specifying the "ajaxFailureContent" string in the object you pass into the plugin.
jQuery Element - Chaining in a jQuery element will cause the modalHome plugin to gather it's data from the inner html of the selected element: $('.someClass').modalHome();
For each method, it's possible to pass in a JSON object that specifies a variety of settings for the plugin. Anything from the css classes the plugin will use and generate to the messages it will display.
| Setting | Type | Default | Description |
|---|---|---|---|
| content | String/HTML | blank | This is required by the first ("init") method. This is the string or HTML code to be displayed in the modal. |
| modalTopPadding | Integer | 75 | This is the top "offset" from the top of the window. Scroll position + modalTopPadding = the "top" css setting for the modal container div. |
| modalHomeBg | String | jhm-modal-bg | This is the class for the background div that covers all page content. |
| modalHomeDiv | String | jhm-modal | This is the class for the main modal container div. All modal window content is placed inside this. |
| modalHomeClose | String | jhm-modal-close | This is the class for the close div inside the modal content container. |
| modalHomeCloseMsg | String | x | This is the text displayed in the close div inside the modal content container. |
| modalHomeLoader | String | jhm-modal-loading | This is the class for the "loading" div that is displayed as Ajax requests are being loaded. |
| modalHomeContent | String | jhm-modal-content | This is the class for the content div that is displayed below the closing and loading divs. |
| modalHomeOpenEvent | String | jhm.modal.open | This is the name of the event that's tied to opening the modal. Fire events with $().trigger('event name') |
| modalHomeOpenEvent | String | jhm.modal.close | This is the name of the event that's tied to closing the modal. Fire events with $().trigger('event name') |
| success | function | null | This function will be called when the modal-home window is successfully generated. |
Ajax Specific Settings
| Setting | Type | Default | Description |
|---|---|---|---|
| ajaxFailureContent | String | Blank | This is the content that is loaded when an Ajax request fails. This is separate from the failure function that can be passed in through the Ajax method. |
| success | function | null | This function will be called when there is a successful Ajax call (see [jQuery.ajax() done()](http://api.jquery.com/jQuery.ajax/). |
| failure | function | null | This function will be called when there is failed Ajax call (see [jQuery.ajax() fail()](http://api.jquery.com/jQuery.ajax/). |
This plugin uses QUnit to run unit tests as well as Grunt to minify and deploy files.
QUnit will run without installation. Simply visit the test page to run and view the test results.
Grunt is used as the project build tool. If you haven't used Grunt before, please checkout their Getting Started guide first. It will walk you through installing the CLI and basic procedures with Grunt. Please note that you will also need to have Node.js installed to run everything. The main Grunt plugins used are stored in a local folder that is checked out with the project. You can view the plugins in the "node_modules" directory.
grunt - This will run the default task which in turn runs the jshint, qunit, css minification and javascript minification tasks. Minifed files will be outputted to the build/ directory
grunt test - This runs the jshint and qunit tasks but does not build the minified css and javascript files.
grunt dist - Purely a convenience function for me to allow the minified files to be automatically copied to a different project folder. Destination folder is set by the "distPath" property in the package.json file.
2/10/2014 - 0.2.2 - Added "modalHomeCloseMsg" setting to control the contents of the close div (defaults to "x"). Updated the modal window to be removed from the DOM when the modal is closed. This avoids messy situations with custom styles and close buttton div content. 2/18/2014 - 0.2.3 - Added success function call to non-Ajax content load. Allows a function to fire once the modal window is populated.
jQuery ModalHome is licensed under the terms of the MIT License.