Summary

SimpleModal is a lightweight jQuery plugin that provides a simple interface to create a modal dialog.

The goal of SimpleModal is to provide developers with a cross-browser overlay and container that will be populated with data provided.

Demos

• http://www.ericmmartin.com/simplemodal/

Tests / Examples

• http://www.ericmmartin.com/simplemodal-test/

Download

• Releases
• SVN trunk

Support

• jQuery Discussion Group
• Contact me

Usage

As a jQuery chained function, where data is a jQuery object:

data.modal({options});

Examples:

$('<div>my data</div>').modal({options});
$('#myDiv').modal({options});
jQueryObject.modal({options});

As a stand-alone jQuery function, where data is a jQuery object, a DOM element, or a plain string (which can contain HTML):

$.modal(data, {options});

Examples:

$.modal('<div>my data</div>', {options});
$.modal('my data', {options});
$.modal($('#myDiv'), {options});
$.modal(jQueryObject, {options});
$.modal(document.getElementById('myDiv'), {options});

Styling

• New in 1.2, you have the option to use external CSS or to pass in CSS attributes for the modal overlay, container, and data elements as options. The options are: overlayCss, containerCss and dataCss and take a key/value object of properties. See the jQuery CSS Docs for details.
• SimpleModal internally handles the setting of the critical CSS properties, to prevent having to manually define them. Now in 1.2, SimpleModal dynamically centers the modal dialog and also adds a position option, for manual positioning.
• SimpleModal internally defines the following CSS classes:
  • simplemodal-overlay: (previously modalOverlay) used to style the overlay div - helpful for applying common styles to different modal dialogs
  • simplemodal-container: (previously modalContainer) used to style the container div - helpful for applying common styles to different modal dialogs
  • simplemodal-data: (previously modalData) used to style the data element - helpful for applying common styles to different modal dialogs
  • modalCloseImg: used to style the built-in close icon (part of the closeHTML option, so this class is not changable)

Example: Applying CSS directly via the options

* Note: because modalCloseImg is not an actual element, you’d still need to use external CSS to style it

data.modal({
  overlayCss: {
    backgroundColor: '#000',
    cursor: 'wait'
  },
  containerCss: {
    height: '400',
    width: '600',
    backgroundColor: '#fff',
    border: '3px solid #ccc'
  }
});

Example: Applying CSS via an external stylesheet

#modalOverlay {
  background-color:#000;
  cursor:wait;
}

#modalContainer {
  height:400px;
  width:600px;
  background-color:#fff;
  border:3px solid #ccc;
}

#modalContainer a.modalCloseImg {
  background:url(../img/x.png) no-repeat;
  width:25px;
  height:29px;
  display:inline;
  z-index:3200;
  position:absolute;
  top:-14px;
  right:-18px;
  cursor:pointer;
}

• For IE 6, the following will handle the PNG used for a.modalCloseImg:

<!--[if lt IE 7]>
<style type='text/css'>
  #modalContainer a.modalCloseImg{
    background:none;
	right:-14px;
	width:22px;
	height:26px;
    filter: progid:DXImageTransform.Microsoft.AlphaImageLoader(
        src='img/x.png', sizingMethod='scale'
      );
  }
</style>
<![endif]-->

Options

Both of the SimpleModal modal() functions accept an optional options object, which can contain any/all of the following (default value):

• iframe: (true) [new in 1.2]
  Use an iframe with every modal dialog, not just IE6. Useful for blocking page content using OBJECT and EMBED tags.
• overlay: [DEPRECATED in 1.2]
  See opactiy, below
• opacity: (50) [renamed from overlay in 1.2]
  The opacity value, from 0 - 100. 0 = transparent 100 = opaque
• overlayId: (‘modalOverlay’)
  The DOM element id for the overlay div
• overlayCss: ({})
  The CSS styling for the overlay div
• containerId: (‘modalContainer’)
  The DOM element id for the container div
• containerCss: ({})
  The CSS styling for the container div
• dataCss: ({})
  The CSS styling for the data div
• zIndex: (1000) [new in 1.2]
  Starting z-index value
• close: (true)
  Show the code in the closeHTML option (below)?
• closeTitle: [DEPRECATED in 1.2]
  See closeHTML, below
• closeHTML: (‘<a class=”modalCloseImg” title=”Close”></a>’)
  [new in 1.2] - The HTML for the default close link. SimpleModal will automatically add the closeClass to this element.
• closeClass: (‘modalClose’)
  The CSS class used to bind to the close event
• position: (null) [new in 1.2]
  Position of container [top, left]. Can be number of pixels or percentage. If not set, SimpleModal will center the container. To only set one value, leave the other blank. For example: [top,] or [,left].
• persist: (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
• onOpen: (null)
  The callback function called in place of SimpleModal’s open function
• onShow: (null)
  The callback function called after the modal dialog has opened
• onClose: (null)
  The callback function called in place of SimpleModal’s close function

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. Your callback function will be passed an object that contains the overlay, container, data, and iframe elements. SimpleModal will handle “showing” the iframe, if necessary.

Example

data.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. Your callback function will be passed an object that contains the overlay, container, data, and iframe elements. If you are including another plugin (TinyMCE, DatePicker, etc.) in a modal dialog, this is where you want to initialze that plugin.

• onClose: Useful for adding effects to the closing of the modal dialog elements. Your callback function will be passed an object that contains the overlay, container, data, and iframe 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.

Example

data.modal({onClose: function (dialog) {
  dialog.data.fadeOut('slow', function () {
    dialog.container.slideUp('slow', function () {
      dialog.overlay.fadeOut('slow', function () {
        $.modal.close(); // must call this!
      });
    });
  });
}});

Other Notes

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>"
});

iframe

• Starting in 1.2, an iframe is created with every modal dialog, unless the iframe option is set to false. This was added to prevent certain elements, like object tags, from bleeding through the modal dialog window. In IE6, the iframe will be created regardless of the iframe option.

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 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 Callback section above)

Known Issues

• 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.

Browser Compatibility

SimpleModal has been tested in the following browsers:

• IE 6, 7
• Firefox 2, 3
• Opera 9
• Safari 3