- Overview
- Documents
jqModal is a plugin for jQuery to help you display modals, popups, and notices. It is flexible and tiny, akin to a "Swiss Army Knife", and provides a great base for your windowing needs.
Features:
- Designer Frieldly - Use *your* HTML+CSS for Layout and Styling
- Translator/i18n friendly - No hardcoded English strings
- Developer friendly - Extensible through callbacks to make anything possible (gallery slideshows, video-conferencing, &c)
- Simple support for remotely loaded content (aka "ajax")
- Multiple Modals per page (including nested Modal-in-Modal)
There is no shortage of dialog scripts that dazzle their audience. Some will try to walk your dog. They can be rooted in unnecessary effects, rigid, and cumbersome. This is not where jqModal is headed! I wanted to write a simple modal framework. Something lightweight yet powerful and flexible. The original strived to resemble an assembly demoscene binary. Since r16 jqModal is readable and community maintainable.
Usage
1. Add modal element(s) to your page
Modal elements are usually <div> containers with their visibility set to hidden. CSS is used for styling and position. Modals are displayed("shown") when a trigger event occurs. Their contents can be inline (hardcoded in the HTML) or added via ajax when the modal is shown.
2. Initialize your modal(s)
- Modal elements are usually <div> containers with their visibility set to hidden. CSS is used for styling and position. Modals are displayed("shown") when a trigger event occurs. Their contents can be inline (hardcoded in the HTML) or added via ajax when the modal is shown.
-
Modal elements must be initialized via $.jqm() before they can be shown. You can customize your modals by passing an options object (e.g. $('#modal').jqm({modal: true, trigger: 'a.showModal'});).
NOTE: $.jqm() is usually called ONCE per modal. Subsequent calls to $.jqm() will update the modal(s) options using jQuery.extend().
3. Trigger your modal
- Modals are shown when a "trigger" element is clicked, or manually triggered via $('#modal').jqmShow().
Functions
jqm
Initialize element(s) as modals. Accepts an options object. If a modal is already initialized, the call will update its options via jQuery.extend().
$('#dialog').jqm();
$('.dialogs').jqm({ajax:'@href',modal:true});
jqmShow
Show modal element(s). Will not execute on opened modals.
$('#dialog').jqmShow();
$('.dialogs').jqmShow();
jqmHide
Hide modal element(s). Will not execute on closed modals.
$('#dialog').jqmHide();
$('.dialogs').jqmHide();
jqmAddTrigger
Called on a modal(s). Passed element(s) will show the modal(s) when clicked. Accepts;
- (string) A jQuery Selector
- (object) A jQuery Collection
- (object) A DOM element
$('#dialog').jqmAddTrigger('.openDialog');
$('.dialogs').jqmAddTrigger($('#openDialogs a'));
jqmAddClose
Called on a modal(s). Passed element(s) will close the modal(s) when clicked. Accepts;
- (string) A jQuery Selector
- (object) A jQuery Collection
- (object) A DOM element
$('#dialog').jqmAddClose('.hideDialog');
$('.dialogs').jqmAddClose($('#hideDialogs a'));
Defaults
$.jqm
- You may override default option values and the focus function by altering $.jqm.params and $.jqm.focusFuncaccordingly.
Options
Options allow tailoring the behavior of modals.
overlay
The overlay transparency as a percentage. If 0 the overlay is disabled and the page behind the modal will remain interactive. If 100 the overlay will be 100% opaque.
(integer) - default: 50
overlayClass
Name of CSS class applied to the overlay.
(string) - default: 'jqmOverlay'
closeClass
Child elements of the modal with a CSS class of closeClass will close the modal when clicked.
(string|false) - default: 'jqmClose'
trigger
Elements matching trigger will show the modal when clicked. Triggers can be;
- (string) A jQuery Selector
- (object) A DOM element (e.g. $.jqm({trigger: document.getElementByID("showDialog")})
- (false) The call to $.jqm() will not attach trigger events to elements.
(string|object|false) - default: '.jqModal'
ajax
Modal contents will be loaded remotely via ajax if passed. You can pass the URL (e.g. $.jqm({ajax:'remote/dialog.html'}) or extract it from an attribute of the triggering element. For instance, $(.jqm({ajax:'@href'}) would grab contents from `foo/bar.html` if the triggering element was <a href="foo/bar.html">Open Modal</a>. If a more complicated routine is desired, use the onShow() callback.
(string|false) - default: false
target
NOTE: target is applicable only if the ajax parameter is passed.
Child element(s) of the modal to load ajax response into. If false, modal contents will be overwritten by ajax response. Useful for retaining modal design. Target can be;
- (string) A jQuery Selector
- (object) A DOM element (e.g. $.jqm({target: $('#dialog div.contents')[0]})
- (false) ajax return overwrites dialog's innerHTML
(string|false) - default: false
ajaxText
NOTE: ajaxText is applicable only if the ajax parameter is passed.
Text shown while waiting for ajax return. Replaces HTML content of `target` element. May include HTML (such as an loading image). E.g. $.jqm({ajaxText: '<marquee style="width: 1.5em;">.. ... .</marquee>'});
(string) - default: ''
modal
Restricts input (mouse clicks, keypresses) to the modal. If false, and if overlay is enabled, clicking the overlay will close the modal.
(boolean) - default: false
toTop
When true; places the dialog element as a direct child of <body> when shown. This was added to help overcome z-Index stacking order issues.
See the toTop demo to learn what to do if your overlay covers the entire page *including* the modal dialog!
(boolean) - default: false
[Callbacks]
Callbacks allow advanced customization of jqModal dialogs. Each callback is passed the "hash" object consisting of the following properties;
- w: (jQuery object) The modal element
- c: (object) The modal's options object
- o: (jQuery object) The overlay element
- t: (DOM object) The triggering element
onShow (callback)
Called when a modal is to be shown. Responsible for showing a modal and overlay.
$('#dialog').jqm({
onShow: function(hash) {
hash.o.prependTo('body');
hash.w.css('opacity',0.88).fadeIn();
}});
(function|false) - default: false
From jqModal.js > // onShow callback. Responsible for showing a modal and overlay. // return false to stop opening modal. // hash object; // w: (jQuery object) The modal element // c: (object) The modal's options object // o: (jQuery object) The overlay element // t: (DOM object) The triggering element // display the overlay (prepend to body) if not disabled if(hash.c.overlay > 0) hash.o.prependTo('body'); // make modal visible hash.w.show(); // call focusFunc (attempts to focus on first input in modal) $.jqm.focusFunc(hash.w); return true; }
onHide (callback)
Called when a dialog is to be hidden. Responsible for hiding a modal and overlay.
$('#dialog').jqm({
onHide: function(hash) {
hash.w.fadeOut('2000',function(){ hash.o.remove(); });
}});
(function|false) - default: false
From jqModal.js > onHide = function(hash){ // onHide callback. Responsible for hiding a modal and overlay. // return false to stop closing modal. // hash object; // w: (jQuery object) The modal element // c: (object) The modal's options object // o: (jQuery object) The overlay element // t: (DOM object) The triggering element // hide modal and if overlay, remove overlay. hash.w.hide() && hash.o && hash.o.remove(); return true; }
onLoad (callback)
Called right after ajax content is loaded.
// onLoad : assign Mike Alsup's most excellent ajaxForm plugin to the returned form element(s).
var myLoad = function(hash){ $('form',hash.w).ajaxForm(); };
$('#dialog').jqm({onLoad:myLoad});
(function|false) - default: false