SimpleModal

Fork me on GitHub

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]

  • appendTo [String:’body’]
    The jQuery selector to append the elements to. For ASP.NET, use ‘form’.
  • focus [Boolean:true] (Changed in 1.4)
    Focus in the first visible, enabled element?
  • opacity [Number:50]
    The opacity value for the overlay div, from 0 – 100
  • overlayId [String:’simplemodal-overlay’]
    The DOM element id for the overlay div
  • overlayCss [Object:{}]
    The CSS styling for the overlay div
  • containerId [String:’simplemodal-container’]
    The DOM element id for the container div
  • containerCss [Object:{}]
    The CSS styling for the container div
  • dataId [String:’simplemodal-data’]
    The DOM element id for the data div
  • dataCss [Object:{}]
    The CSS styling for the data div
  • minHeight [Number:null]
    The minimum height for the container
  • minWidth [Number:null]
    The minimum width for the container
  • maxHeight [Number:null]
    The maximum height for the container. If not specified, the window height is used.
  • maxWidth [Number:null]
    The maximum width for the container. If not specified, the window width is used.
  • autoResize [Boolean:false] (Changed in 1.4)
    Resize the container if it exceeds the browser window dimensions?
  • autoPosition [Boolean:true] (Changed in 1.4)
    Automatically position the container upon creation and on window resize?
  • zIndex [Number: 1000]
    Starting z-index value
  • close [Boolean:true]
    If true, closeHTML, escClose and overlayClose will be used if set. If false, none of them will be used.
  • closeHTML [String:’‘]
    The HTML for the default close link. SimpleModal will automatically add the closeClass to this element.
  • closeClass [String:’simplemodal-close’]
    The CSS class used to bind to the close event
  • escClose [Boolean:true]
    Allow Esc keypress to close the dialog?
  • overlayClose [Boolean:false]
    Allow click on overlay to close the dialog?
  • position [Array:null]
    Position of container [top, left]. Can be number of pixels or percentage
  • persist [Boolean:false]
    Persist the data across modal calls? Only used for existing DOM elements. If true, the data will be maintained across modal calls, if false, the data will be reverted to its original state.
  • modal [Boolean:true] (Added in 1.3.4. Name changed from transient in 1.3.5))
    User will be unable to interact with the page below the modal or tab away from the dialog. If false, the overlay, iframe, and certain events will be disabled allowing the user to interact with the page below the dialog.
  • onOpen [Function:null]
    The callback function used in place of SimpleModal’s open
  • onShow [Function:null]
    The callback function used after the modal dialog has opened
  • onClose [Function:null]
    The callback function used in place of SimpleModal’s close

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

  • By default, SimpleModal will clone the data element that you pass in. When the dialog is closed, the cloned, unchanged, data element will be re-inserted into DOM in its original place. If the persist option is true, SimpleModal will “re-insert” the original element, with changes intact. If you use an onClose callback, you’ll need to call $.modal.close(); (see the onClose in the Options & Callback section above).
  • SimpleModal always removes the overlay, container and iframe elements when closed. If you use an onClose callback, you’ll need to call $.modal.close(); (see the onClose in the Options & Callback section above)

Known Issues

  • If you experience problems with the overlay not filling the entire page, try these suggestions: If the overlay is not extending to the bottom of the page, set the body height to 100%. If there is a small, white border on the right or bottom of the page, set the margin of the body to 0px. Tips provided by Daniel Kellogg.
  • In IE6, the state of checkboxes and radio buttons are not maintained using the persist option.
  • In IE7, the state of radio buttons is not maintained using the persist option.
  • To prevent Flash objects from “bleeding through” the dialog, make sure to set the wmode property for your object and embed elements to either opaque or transparent (reference).
  • For YouTube videos (and perhaps other objects), add type="application/x-shockwave-flash" in the object tag to prevent issues in IE6. Tip provided by Jimish Shah.

Browser Compatibility

SimpleModal has been tested in the following browsers:

  • IE 6+
  • Firefox 2+
  • Opera 9+
  • Safari 3+
  • Chrome 1+

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:

  • Help other SimpleModal users on stackoverflow
  • Blog about or link to SimpleModal so others can find out about it
  • Report issues or submit code on GitHub
  • Make a donation
If you find any errors on this page, please let me know.
Scroll to Top