SimpleModal

v1.2.3

Archives: SimpleModal v1.1.1 | SimpleModal v1.0.1

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

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

Tests / Examples

• https://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

#simplemodal-overlay {
  background-color:#000;
  cursor:wait;
}

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

#simplemodal-container 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'>
  #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]-->

Options

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

• iframe: [DEPRECATED in 1.2.2]
  Update your object and embed elements with the wmode property.
• 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: (‘simplemodal-overlay’)
  The DOM element id for the overlay div
• overlayCss: ({})
  The CSS styling for the overlay div
• containerId: (‘simplemodal-container’)
  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: (‘simplemodal-close’)
  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>"
});

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

Browser Compatibility

SimpleModal has been tested in the following browsers:

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

Changes in 1.2

* From ChangeLog.txt

• Added new internal variables (ie6, ieQuirks and w)
• Added better IE6 detection (preventing false positives with IE7)
• Fixed $.modal.close() function to correctly utilize an onClose callback without causing a infinite recursion crash
• Added new options (dataCss, zIndex, closeHTML and position)
• Renamed overlay option to opacity
• Removed closeTitle option
• Renamed default class and id names from modalXxx to simplemodal-xxx
• Added better z-index handling – initial value can be defined through the options
• Fixed element creation to be XHTML compliant
• Added window dimension detection
• Fixed Safari issue (directly setting display:’none’ as opposed to using .hide())
• Changed width/height setting for overlay and iframe
• Fixed IE7 positioning issue in quirks mode
• Added IE6 expression for elements – eliminating the need for an external stylesheet
• Added dynamic centering of container as well as a position option for manual positioning
• Added namespacing on events
• Added window resize listener to resize dialog elements
• Updated demo and test/example pages

Upgrading

Things to be aware of when upgrading to 1.2 from a previous version:

• If you used the overlay option, you’ll need to rename it to opacity
• If you used the closeTitle option, you’ll need to now use the closeHTML option instead
• Remove the container positioning CSS from your stylesheet (remove the top, left, and margin-left properties)
• Remove any IE specific container positioning CSS
• Overlay, container and data class and id names changed! Update your code/CSS or use the overlayId and containerId options to have SimpleModal to use the old id names.
• closeClass option value changed! Update your code or use the closeClass option to have SimpleModal to use the old class name (modalClose).

The following option overrides should help with backwards compatibility, although you’ll still have to update your CSS. Place this somewhere after you include SimpleModal but before you create a modal dialog:

$.extend($.modal.defaults, {
  closeClass: "modalClose",
  overlayId: "modalOverlay",
  containerId: "modalContainer"
});