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 content provided to SimpleModal.

Demo

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

Download

• http://code.google.com/p/simplemodal/downloads/list
• SVN trunk: http://simplemodal.googlecode.com/svn/

Support

• jQuery Discussion Group: http://groups.google.com/group/jquery-en
• Contact me: simplemodal@ericmmartin.com

Usage

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

content.modal([settings]);

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

$.modal(content, [settings]);

Styling

• Other than dealing with some IE issues, SimpleModal does not apply styling to any of the elements. modalCloseImg is the only internally defined CSS class, used to style the built-in close icon.

Sample CSS, using default values

#modalOverlay {
  height:100%;
  width:100%;
  position:fixed;
  left:0;
  top:0;
  z-index:3000;
  background-color:#000;
  cursor:wait;
}

#modalContainer {
  height:400px;
  width:600px;
  position:fixed;
  left:50%;
  top:15%;
  margin-left:-300px;
  z-index:3100;
  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;
  left:588px;
  cursor:pointer;
}

• For IE 6, the following will handle the PNG used for a.modalCloseImg and fixed positioning for the container and IFRAME:

<!--[if lt IE 7]>
<style type='text/css'>
  body {
    width:100%;
    height:100%;
    padding:0;
    margin:0;
  }
  #modalContainer a.modalCloseImg{
    background:none;
    filter: progid:DXImageTransform.Microsoft.AlphaImageLoader(
        enabled=true, src='img/x.png',sizingMethod='scale'
      );
  }
  #modalContainer {
    position: absolute;
    top: expression((document.documentElement.scrollTop
        || document.body.scrollTop) + Math.round(15 *
        (document.documentElement.offsetHeight
        || document.body.clientHeight) / 100) + 'px');
  }
  #modalIframe {
    z-index:1000;
    position:absolute;
    width:100%;
    height:100%;
    top:0;
    left:0;
  }
</style>
<![endif]-->

Settings

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

• overlay: (50) The opacity value, from 0 - 100. 0 = transparent 100 = opaque
• overlayId: (‘modalOverlay’) The DOM element id for the overlay div
• containerId: (‘modalContainer’) The DOM element id for the container div
• iframeId: (‘modalIframe’) The DOM element id for the iframe (IE 6)
• close: (true) Show the default window close icon? Uses CSS class modalCloseImg
• closeTitle: (‘Close’) The title value of the default close link. Used if close == true
• closeClass: (‘modalClose’) The CSS class used to bind to the close event
• cloneContent: (true) If true, SimpleModal will clone the content element
• 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, content and iframe objects. In addition, inside the callback, this will refer to the SimpleModal object. This will allow you to call the close function, among other things.

• 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, content, and iframe (for IE6) elements. SimpleModal will handle “showing” the iframe, if necessary.

Example

content.modal({onOpen: function (dialog) {
  dialog.overlay.fadeIn('slow', function () {
    dialog.container.slideDown('slow', function () {
      dialog.content.fadeIn('slow'); // See Other Notes below regarding
                                     // content display property and
                                     // iframe details
    });
  });

• 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, content, and iframe (for IE6) elements.

• 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, content, and iframe (for IE6) elements. $.modal.remove(dialog); can be called to remove all of the elements, or you will need to remove them manually. Example: dialog.content.remove();, etc.

Example

content.modal({onClose: function (dialog) {
  dialog.content.fadeOut('slow', function () {
    dialog.container.slideUp('slow', function () {
      dialog.overlay.fadeOut('slow', function () {
        $.modal.remove(dialog); // must call this to remove
                                // the elements from the DOM
                                // or remove the elements manually
      });
    });
  });
}});

Other Notes

iframe

• For IE6, SimpleModal handles the creation and removal of an iframe, which is needed to prevent select options from bleeding through the modal dialog. If you use an onClose callback, see onClose in the Callback section above.

Content CSS display Property

• If you use an onOpen callback, the dialog.content display value will be the same as what was passed in to SimpleModal. So, if you want to use an effect on the dialog.content and the element is not set to display:none, you’ll have to call dialog.content.hide(); first, before you call your open effects.

Cloning and Element Removal

• By default, SimpleModal will clone the content element that you pass in. In the close function, when cloneContent is true, SimpleModal will “remove” the element, otherwise it will just “hide” it. If you use an onClose callback, you’ll have to deal with removing vs hiding the content element.
• SimpleModal always removes the overlay, container and iframe elements when closed. If you use an onClose callback, see onClose in the Callback section above.

Browser Compatibility

SimpleModal has been tested in the following browsers:

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