SimpleModal

v1.2.3

Deprecated: please see the current version.

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

Tests / Examples

Download

Support

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

220 thoughts on “SimpleModal”

  1. Pingback: Блог web-мастера » Архив сайта » Модальные окна: плагин SimpleModal для jQuery. Часть 2

  2. Pingback: Блог web-мастера » Архив сайта » Модальные окна: плагин SimpleModal для jQuery. Часть$npsp;1

  3. Pingback: Modal Delete Confirmation Version Two Using jQuery SimpleModal Plugin Demo | Pedram Development

  4. Pingback: jQuery SimpleModal Plugin Version 1.2 with NicEdit WYSIWYG Editor

  5. Pingback: Excelente listado de 240 plugins para jquery | Adictos a la red

  6. Pingback: Modal Delete Confirmation V3 Using SimpleModal jQuery Plugin Demo

  8. Eric Martin

    @Doug – there is a version on source control (under branches) that I’ve been working on that has multiple dialog support and true modal support (prevents interaction with the page behind the dialog). I’m going to see what, if any, issues come from the 1.2 release and will work on refining the code for a 2.0 release.

  9. t vainisi

    Hi, I have not upgraded my simplemodal or contact js/css yet. I’ve had it installed since about february 08. I was sure it was working in Internet Explorer, but I’m a mac user so I don’t check often. As of yesterday, my simplemodal windows are no longer appearing on top of everything in ie7, even though they are still working fine in firefox (pc and mac) and safari. In ie7, they appear at the very bottom of the page, surrounded by grey (which is my bgcolor). Does 1.2.1 fix this? I make extensive use of modals with many many different forms (not just a contact form) and validations in the js class on my site, so I’d prefer to avoid an upgrade if I can get to work again using the old class and css. Any ideas?

  10. Eric Martin

    @t vainisi – sounds like your page does is in quirks mode. If that is the case, there are a couple of options. 1) fix your page/doctype to be valid, 2) apply the fix to your existing version of SimpleModal or 3) upgrade to 1.2.1.

  11. t vainisi

    Eric, wow thanks for the speedy response! I implemented the fix and the problem improved right away. But (isnt there always a but) its not quite right. Now the semi-opaque overlay only covers an area equal to the window size, starting from the top. But since my window scrolls, i can scroll away the modal window and the overlay, or, if I scrolled down to find the button to pop up the modal window, I have to scroll the page up to find the overlay and modal window. I’m almost positive this is a css issue – what values do i need to look at? Here is a link to my css page: https://www.curriculum-framer.com/css/contact.css

  12. t vainisi

    Eric, I thought it was curious that you felt I was running in quirks mode, since I use the exact same doctype that you do (xhtml trans). But it turned out I was indeed in quirks mode because some of my include files have html comments in them that preceded my doctype declaration! Once I removed them and made sure the doctype declaration was the absolute first thing on my page, simplemodal resumed its flawless operation in ie7. Thanks for the help and the great jquery module!

  15. Edmund

    I have a long modal div that is taller than the hosting page. Due to the modal nature (blocking the hosting page), I cannot scroll down to the bottom of the modal dialog. I tried adding vertical scrolls on the modal’s div, but that does not do the job, either.

    Any suggestions?

    Thanks,
    Edmund

  16. Simon Brown

    To make it work in IE6 I had to modify line 63 and 64 to:

    var ie6 = $.browser.msie && parseInt($.browser.version) == 6,
    ieQuirks = $.browser.msie,

    Otherwise it didn’t pick it up as IE6.

  17. Igor

    Hi. I think that I found an error in 1.2.1.

    When I’m using “position:[10,10]” in options – I get correct horisontal position, but incorrect vertical one (object centered vertically) in MSIE 6. FF 3 displays object correctly.

    If I’m commenting out line 319 (s.setExpression(‘top’,…) – error disappears (so I think that error in this line) but this line required for correct displaying of object on pages with vertical scrollbar – like my case 🙁

    I hope that You quicly fix this error 🙂

    P.S. Do you speak russian? 😉

  18. Eric Martin

    @Edmund – do you have a page I can view? The scrolling idea should work – what exactly is the problem?

    @Simon – hmm…I’m pretty sure I tested in IE6, but I’ll take another look. Thanks.

    @Igor – Thanks, I will test this one again as well…and no, I don’t speak Russian 😉

  19. Igor

    @Edmund – scrolling is working. You need to use

    overflow: auto;

    in modal container style and define height of your modal window explicitily or use max-height (max-height don’t work in MSIE).

  20. Tammie

    Eric,
    Is it possible to make the Simple Contact Modal contain my own html form?
    I like how it looks and functions.

    If it is possible how to do it? what code do I change and what files to change.

    I have been reading and reading and I am a bit lost.

  21. Eric Martin

    @Tammie – If you want to change the elements in the contact form, you’ll need to edit the data/contact.php file. You’ll have to add the form elements, add the code to capture them from the request and the code to send them in the email. You’ll also have to modify the js/contact.js and css/contact.css files as needed.

  22. Tammie

    Eric,
    It is not working correctly when I insert the code into contact.php, the window does not open at all.
    This is the type of html, I am using a form generated for my email list.
    Here it is:

    Name:

    Email:

  23. Eric Martin

    @Igor – I was able to get IE6 positioning correctly…will release shortly

    @Simon – AFAIK, IE6 does not support XMLHttpRequest, so I’m not sure why you had to remove that. A side effect of removing that check is the possibility of false-positive IE6 detection for IE7 browsers.

  24. Dimas

    Hi! Good work. But I find the bug. in Opera 9.62 when main window have flash (simple swf animation input by SWFObject). The modal is under the flash – flash is overrides part of modal window. Please fix it. I use simplemodal-1.2.1

  25. Eric Martin

    @Dimas – that is what the iframe:true option is for Removed in v1.2.2

    $(element).modal({iframe:true});

    UPDATE: It turns out that the iframe option does not work for all browsers. It looks like the correct way to deal with Flash is to use the wmode property (opaque or transparent). Example:

    <object>
	<param value="opaque" name="wmode"/>
	<param name="movie" value=""></param>
	<embed src="" wmode="opaque"></embed>
</object>

    So, I’m thinking of just removing the iframe option…

  26. Zacko

    I noticed a possible error in IE 7. By not setting the persist:true I got a ‘nodeType is null or not an Object’ message every other time I clicked a link that calls the modal. First click works fine. Second time error. I haven’t had enough time to test it further, but I thought I would bring this up. Also worth noting is that the page uses two modals, but the other modal doesn’t have this issue and it is set to persist:true. Not sure if this is related to the Clone issue in jQuery with IE 7.

    I will post more info if I come across anymore information! Other than that, awesome job Eric, and thanks!

  33. Pingback: Обзор SimpleModal 1.2.2 | В лабиринте извилин

  34. Paulo de Tarso

    Hi!

    Can I use the modal with class instead of id? I have many little “false windows” on page (made with divs and images to simulate a mini-window on window’s center), so because this I can’t use same id. To control what mini-window will be viewed, I use this:

    $('a.linkModify').click(function (e)
    {
    id = $(this).attr('rel');
    // I use the 'rel', that contains a number that indicates what div will be showed
    e.preventDefault();
    $('#inputProd' + id).modal();
    // and here I indicate the correctly div to show
    });
    Can you see the situation? I have 20, 25 divs on page that needs be viewed on modal…

    Can you help-me?

    I have the CSS code, I can’t use the basic.css, but, I don’t use id (#simplemodal-container), I need to use the class “.miniBox”…

    Sorry the grammar errors, I don’t speak english very well, but I tried…

    Thanks!

  35. Eric Martin

    @Paulo de Tarso – the id’s that are used by SimpleModal should not affect your situation – since only 1 modal dialog can be created at a time.

    You have the option to override the id’s being used, or you could just add the miniBox class to the element you are displaying.

  36. Caspar

    Hey,

    Awesome plugin, I’ve used it a few times now and it’s very easy to use. There’s only 1 minor issue I’ve come across while testing in IE6.

    If the content of the website isn’t as high or higher than the full browser window height, the overlay doesn’t stretch the full window, but stops right at the bottom of the content.

    Thanks

  39. Eric Martin

    @Birkalem – you could just open smcf.php and comment out the following line:

    wp_enqueue_script("jquery");

    However – the “best” option is to fix whatever else is loading jQuery to use the same function as above. If possible, all scripts and stylesheets should be loading through WordPress functions – it will help prevent these kinds of issues. 😉

  40. Suzan

    Hello,

    We are having problems posting form parameters from the same form. The application works perfectly good when we send input variables but it gives us issues when a file parameter is sent.

    Looking forward to hear from you.

  41. Eric Martin

    @Susan – Are you doing a traditional upload (form submit) or trying to do it via Ajax?

    If you are having issues just trying to do it the traditional way, let me know – otherwise, it is not possible to do a direct file upload with Ajax. There are a number of workarounds – one common way is to have the form post to an iframe, and then check the iframe for a response.

  44. Jain

    Hi,

    I was trying to put checkboxes in the modal box, but when the user closes it, the values are erased. How do I make the values (ie. checked checkbox) stay?

  47. Pingback: SimpleModal - jQuery Mesaj Kutusu | Enver Tekay

  49. Caspar

    I don’t have a link (yet..) as I’m still working on the website. I managed to fix the issue by changing a little bit of code:

    I changed this:

    
fixIE: function () {
	var p = this.opts.position;

	// simulate fixed position - adapted from BlockUI
	$.each([this.dialog.iframe || null, this.dialog.overlay, this.dialog.container], function (i, el) {
		if (el) {
			var bch = 'document.body.clientHeight', bcw = 'document.body.clientWidth',
				bsh = 'document.body.scrollHeight', bsl = 'document.body.scrollLeft',
				bst = 'document.body.scrollTop', bsw = 'document.body.scrollWidth',
				ch = 'document.documentElement.clientHeight', cw = 'document.documentElement.clientWidth',
				sl = 'document.documentElement.scrollLeft', st = 'document.documentElement.scrollTop',
				s = el[0].style;

			s.position = 'absolute';
			if (i  ' + bch + ' ? ' + bsh + ' : ' + bch + ' + "px"');
				s.setExpression('width','' + bsw + ' > ' + bcw + ' ? ' + bsw + ' : ' + bcw + ' + "px"');
			}

    into this:

    
fixIE: function () {
	var p = this.opts.position;

	// simulate fixed position - adapted from BlockUI
	$.each([this.dialog.iframe || null, this.dialog.overlay, this.dialog.container], function (i, el) {
		if (el) {
			var bch = 'document.body.clientHeight', bcw = 'document.body.clientWidth',
				bsh = 'document.body.scrollHeight', bsl = 'document.body.scrollLeft',
				dch = 'document.documentElement.clientHeight',
				bst = 'document.body.scrollTop', bsw = 'document.body.scrollWidth',
				ch = 'document.documentElement.clientHeight', cw = 'document.documentElement.clientWidth',
				sl = 'document.documentElement.scrollLeft', st = 'document.documentElement.scrollTop',
				s = el[0].style;

			s.position = 'absolute';
			if (i  ' + bch + ' ? ' + bsh + ' : (' + bsh + ' > ' + dch + ' ? ' + bsh + ' : ' + dch + ') + "px"');
				s.setExpression('width','' + bsw + ' > ' + bcw + ' ? ' + bsw + ' : ' + bcw + ' + "px"');
			}

    The things I’ve added were:

    
dch = 'document.documentElement.clientHeight',

    and:

    
s.setExpression('height','' + bsh + ' > ' + bch + ' ? ' + bsh + ' : (' + bsh + ' > ' + dch + ' ? ' + bsh + ' : ' + dch + ') + "px"');
  50. Anil

    Hello Eric,

    I guess this might be a simple question. Is it possible to open a new page in the modal popup? something like using window.open(…). If yes, could you please tell me how to do it?

    Thank you,
    Anil.

Comments are closed.

Scroll to Top