HOME / PROJECTS / SIMPLEMODAL
OVERVIEW | OPTIONS & CALLBACKS | EXAMPLES | OTHER NOTES | SUPPORT
OVERVIEW
SimpleModal is a lightweight jQuery Plugin which provides a powerful interface for modal dialog development. Think of it as a modal dialog framework. SimpleModal gives you the flexibility to build whatever you can envision, while shielding you from related cross-browser issues inherent with UI development.
USAGE
SimpleModal provides 2 simple ways to invoke a modal dialog.
As a chained jQuery function, you can call the modal() function on a jQuery element and a modal dialog will be displayed using the contents of that element. For example:
$("#element-id").modal();
As a stand-alone function, a modal dialog can be created by passing a jQuery object, a DOM element, or a plain string (which can contain HTML). For example:
$.modal("<div><h1>SimpleModal</h1></div>");
Both of the methods described above, also accept an optional options object (nice tongue-twister, huh?). Using the examples above:
$("#element-id").modal({options}); $.modal("<div><h1>SimpleModal</h1></div>", {options});
Because SimpleModal is more of a modal dialog framework, both of the examples above would create very basic, unstyled, modal dialogs. Styling can be done through external CSS or through properties in the options object. See the Options section below for a detailed list of the available options.
STYLING
Styles can be applied through external CSS, the options object, or both. The CSS options for the modal overlay, container, and data elements are: overlayCss, containerCss and dataCss, all which take a key/value object of properties. See the jQuery CSS Docs for details.
SimpleModal handles setting the necessary CSS for displaying the modal dialog. In addition, SimpleModal dynamically centers the modal dialog, unless the position option is used, which takes precedence.
SimpleModal internally defines the following CSS classes: simplemodal-overlay​, simplemodal-container​, simplemodal-wrap (SimpleModal will automatically set the overflow to auto if the content gets larger than the container), and simplemodal-data​.
* Note: SimpleModal's default closeHTML option declares the modalCloseImg class in order to display an image for closing the dialog. Download the image. Because it is defined in an option, it cannot be styled through the options - an external CSS definition is required:
#simplemodal-container a.modalCloseImg { background:url(/img/x.png) no-repeat; /* adjust url as required */ width:25px; height:29px; display:inline; z-index:3200; position:absolute; top:-15px; right:-18px; cursor:pointer; }
For IE6, you might want to apply the PNG fix:
<!--[if lt IE 7]> <style type='text/css'> #simplemodal-container a.modalCloseImg { background:none; right:-14px; width:22px; height:26px; filter: progid:DXImageTransform.Microsoft.AlphaImageLoader( src='img/x.png', sizingMethod='scale' ); } </style> <![endif]-->
DEMOS
In addition to the examples below, I have a collection of demos that feature the different capabilities of SimpleModal:
View Demos
DOWNLOAD
SimpleModal is hosted on Google Code:
Download SimpleModal
There are two versions available; a full source version that contains comments and is formatted for readability, and a minified version with all comments and formatting removed. The full version is recommended for learning and testing, the minified version is for production use.
ARCHIVES
Previous version of SimpleModal documentation: v1.2.x, v1.1.x, v1.0.x
OPTIONS & CALLBACKS
OPTIONS
The following is a list of current options. Default values are indicated with: [Type:Value]
For a list of options in previous version, please refer to the appropriate archived documentation page (listed above).
CALLBACKS
The callback functions are called using the JavaScript apply function. One parameter, the dialog object, is sent, which contains the overlay, container, data and iframe objects. In addition, inside the callback, this will refer to the SimpleModal object, which will allow you to access all of the available modal elements and functions.
onOpen: Useful for adding effects to the opening of the modal dialog elements. SimpleModal will handle "showing" the iframe, if necessary.
$("#element-id").modal({onOpen: function (dialog) { dialog.overlay.fadeIn('slow', function () { dialog.container.slideDown('slow', function () { dialog.data.fadeIn('slow'); }); }); }});
onShow: Useful for binding events or any other actions you might want to perform after the modal dialog elements have been displayed. If you are including another plugin (TinyMCE, DatePicker, etc.) in a modal dialog, this is where you want to initialize that plugin.
$("#element-id").modal({onShow: function (dialog) { // Access elements inside the dialog // Useful for binding events, initializing other plugins, etc. // For example: $("a", dialog.data).click(function () { // do something return false; }); }});
onClose: Useful for adding effects to the closing of the modal dialog elements. After you’ve applied effects, etc., you’ll need to call $.modal.close(); so SimpleModal can re-insert the data correctly and clean up the dialog elements.
$("#element-id").modal({onClose: function (dialog) { dialog.data.fadeOut('slow', function () { dialog.container.slideUp('slow', function () { dialog.overlay.fadeOut('slow', function () { $.modal.close(); // must call this! }); }); }); }});
EXAMPLES
The following examples are aimed at showing you the various options and callbacks available in SimpleModal.
In order to provide some basic styling, all of the examples below are using the default CSS:
#simplemodal-overlay {background-color:#000;} #simplemodal-container {background-color:#333; border:8px solid #444; padding:12px;}
Each example below can be demonstrated by clicking "RUN EXAMPLE".
// Chained call with no options $("#sample").modal();
// Stand-alone call with no options $.modal($("#sample"));
// Enable overlay click-to-close $("#sample").modal({overlayClose:true});
// Change overlay color and opacity $("#sample").modal({ opacity:80, overlayCss: {backgroundColor:"#fff"} });
// Disable focus (allows tabbing away from dialog) $("#sample").modal({focus:false});
// Change min height and width $("#sample").modal({ minHeight:400, minWidth: 600 });
// Manually set position $("#sample").modal({position: [10,10]});
// Manually set position using percentages $("#sample").modal({position: ["50%","50%"]});
// Display an external page using an iframe var src = "https://365.ericmmartin.com/"; $.modal('<iframe src="' + src + '" height="450" width="830" style="border:0">', { closeHTML:"", containerCss:{ backgroundColor:"#fff", borderColor:"#fff", height:450, padding:0, width:830 }, overlayClose:true });
// Opening animations $("#sample").modal({onOpen: function (dialog) { dialog.overlay.fadeIn('slow', function () { dialog.data.hide(); dialog.container.fadeIn('slow', function () { dialog.data.slideDown('slow'); }); }); }});
// Closing animations $("#sample").modal({onClose: function (dialog) { dialog.data.fadeOut('slow', function () { dialog.container.hide('slow', function () { dialog.overlay.slideUp('slow', function () { $.modal.close(); }); }); }); }});
OTHER NOTES
CLOSING THE DIALOG
SimpleModal will automatically bind the close function (using the onclick event) to any element inside the dialog with the simplemodal-close class.
In addition, you can programmatically close the currently opened dialog by calling $.modal.close();
DEFAULT VALUES
If you have a value that you want to be used for all modal dialogs, instead of passing the option in for each one, you can globally modify the defaults.
Example – Single Property:
$.modal.defaults.closeClass = "modalClose";
Example – Multiple Properties:
$.extend($.modal.defaults, { closeClass: "modalClose", closeHTML: "<a href='#'>Close</a>" });
DATA CSS DISPLAY PROPERTY
SimpleModal "hides" the data when it adds it to the modal dialog. If you use an onOpen callback, the dialog.data display value will have been set to none and you’ll need to explicitly "un-hide" the element.
CLONING AND ELEMENT REMOVAL
KNOWN ISSUES
BROWSER COMPATIBILITY
SimpleModal has been tested in the following browsers:
SUPPORT
FROM ME
For questions, issues or feature requests, please post them on stackoverflow​.
If you contact me directly asking for support, know that, despite my best intentions, it may take me a while to get back to you, if at all.
FROM YOU
If you would like to contribute, the following is a list of ways you can help:
If you find any errors on this page, please let me know.
TWEET

RECENT POSTS
WordPress Plugins Under New Ownership
SimpleModal 1.4.4 Released
SimpleModal 1.4.3 Released
SimpleModal 1.4.1 Released
WP-Paginate 1.2 Released
SimpleModal Login 1.0 Released
SimpleModal 1.3.5 Released
SimpleModal 1.3.4 Released
POPULAR POSTS
WordPress Pumpkin
SimpleModal 1.4.1 Released
Conditional page/post navigation links in WordPress (redux)
5 Tips For Using jQuery with WordPress
SimpleModal 1.4.4 Released
Dropbox Beta Invites
Running Ubuntu 7.10 in VMWare Player
SimpleModal 1.4.3 Released
TOPICS

ARCHIVES
2014(1)
2013(1)
2012(1)
2010(6)
2009(22)
2008(28)
2007(15)


You can find me on Twitter as @ericmmartin

All content & design © 2001-2022 Eric Martin - Some Rights Reserved
homeblogprojectsphotographyaboutcontact