Control.Modal : Unobtrusive CSS Modal Windows and Lightboxes for Prototype

Control.Modal is a light weight, unobtrusive JavaScript library for creating modal windows and lightboxes using HTML that is already on the page, images, AJAX calls or iframes. It can be added to your existing code in one line, completely styled with CSS, and supports a wide range of configuration options and callbacks.

Requirements

This script uses the Prototype javascript framework. You must include version 1.5 in your pages before including this script.

Examples

Relative Modal - Opens a local modal window relative to the position of the link. With custom width and height.
Centered Modal - Opens a local modal window in the center of the screen. Adds CSS classes to the container and overlay.
AJAX Modal - Opens a modal window that is the response of an AJAX call.
iframe Modal - Opens a modal window that contains an iframe.
Lightbox One - Opens a modal window with an image inside.
Lightbox Two - Opens another modal window with an image inside.
Hoverbox Example - Opens a local modal window relative to the link with "hover" set to true.

Code Used in the Example

(View source for the CSS used)


<div id="modal_window_one">Example One</div>
<div id="modal_window_two">Example Two</div>
<div id="hoverbox_container">I can also act like a hoverbox.</div>
<ul>
    <li><a href="#modal_window_one" id="modal_link_one">Relative Modal</a> - Opens a local modal window relative to the position of the link. With custom width and height.</li>
    <li><a href="#modal_window_two" id="modal_link_two">Centered Modal</a> - Opens a local modal window in the center of the screen. Adds CSS classes to the container and overlay.</li>
    <li><a href="http://livepipe.net/projects/control_modal/modal_ajax" id="modal_link_three">AJAX Modal</a> - Opens a modal window that is the response of an AJAX call.</li>
    <li><a href="http://livepipe.net/projects/control_modal/modal_iframe" id="modal_link_four">iframe Modal</a> - Opens a modal window that contains an iframe.</li>
    <li><a href="http://livepipe.net/ryan/photos/photos/Plants/Banners_Closeup.jpg" id="lightbox_link_one">Lightbox One</a> - Opens a modal window with an image inside.</li>
    <li><a href="http://livepipe.net/ryan/photos/photos/Water/Skippers_Creek.jpg" id="lightbox_link_two">Lightbox Two</a> - Opens another modal window with an image inside.</li>
</ul>
    <li><a href="#hoverbox_container" id="hoverbox_link">Hoverbox Example </a> - Opens a local modal window relative to the link with "hover" set to true. </li>
<script>
    Event.observe(window,'load',function(){
        new Control.Modal($('modal_link_one'),{
            opacity: 0.8,
            position: 'relative',
            width: 200,
            height: 200
        });
        new Control.Modal($('modal_link_two'),{
            containerClassName: 'test',
            overlayClassName: 'test'
        });
        new Control.Modal($('modal_link_three'));
        new Control.Modal($('modal_link_four'),{
            iframe: true
        });
        new Control.Modal($('lightbox_link_one'));
        new Control.Modal($('lightbox_link_two'),{
            opacity: 0.75
        });
        new Control.Modal($('hoverbox_link'),{
            hover: true,
            position: 'relative',
            offsetLeft: 120
        });
    });
</script>

Advanced Usage


//this shows all available options, set to their defaults
m = new Control.Modal($('my_link'),{
    beforeOpen: function(){}, //called before the modal opens
    afterOpen: function(){}, //called after the modal opens
    beforeClose: function(){}, //called before the modal closes. you can cancel the close by returning false
    afterClose: function(){}, //called after the modal window is closed
    beforeLoad: function(){}, //for an AJAX window, called before the Ajax.Request is made
    onLoad: function(request){}, //for an AJAX window, called first thing in the onComplete method of Ajax.Request
    afterLoad: function(){}, //for an AJAX window, called as the very last thing in the onComplete method of Ajax.Request
    beforeImageLoad: function(){}, //for an image / lightbox, called after the window is open, and the image is hidden
    afterImageLoad: function(){}, //for an image / lightbox, called after the image is finished loading
    hover: false, //make the modal window act like a hover box
    image: false, //force a modal window into image / lightbox mode
    imageTemplate: new Template('<img src="#{src}" id="#{id}"/>'),
    imageAutoDisplay: true, //for an image / lightbox,  auto hide and show the image as it loads
    imageCloseOnClick: true, //for an image / lightbox, close the modal when the image is clicked
    iframe: false, //turns a remote modal from an AJAX request into an iframe 
    iframeTemplate: new Template('<iframe src="#{href}" width="100%" height="100%" frameborder="0" id="#{id}"></iframe>'),
    requestOptions: {}, //hash that will be passed to Ajax.Request for AJAX windows
    overlayClassName: '', //the class name that will be added to #modal_overlay each time the window is opened
    containerClassName: '', //the class name that will be added to #modal_container each time the window is opened 
    opacity: 0.3, //the opacity amount for #modal_overlay
    zIndex: 9998, //the css z-index for #modal_overlay. #modal_container is always set to this value + 1
    width: null, //manually specify a width in pixels for this modal window
    height: null, //manually specify a height in pixels for this modal window
    position: 'absolute', //'absolute' or 'relative', 'absolute' is centered, 'relative' to the clicked link
    offsetLeft: 0, //for 'relative', number of pixels the opened window will be offset
    offsetTop: 0, //for 'relative', number of pixels the opened window will be offset
    evalScripts: true //for AJAX modal windows, wether or not to eval scripts in the response
});

//programatically open or close the modal window
m.open();
m.close();
//or
Control.Modal.close(); //closes any open modal

//programatically set the contents of a modal
m.update('contents');

//get a reference to the currently open, or last opened modal
current_modal = Control.Modal.current;

Using Control.Modal as a Lightbox

If your link ends in a file name that has any of the following extensions jpg, jpeg, gif, png, tif, tiff, Control.Modal will automatically treat it as an image modal / lightbox. An image element with an id of #modal_image is automatically created and destoryed each time the modal opens and closes.

Using Control.Modal as a Hoverbox

You can easily repurpose any modal window to act as a hoverbox by specifying {hover: true} in the options hash. In the example used above notice that position was set to relative and an offsetLeft was specified. The modal can be in any mode (local, iframe, ajax, image), and the two differences in functionality are that the overlay never appears, and instead of a click opening and closing the window, the onmouseover and onmouseout events on the link trigger it. Note that if the modal completely overlaps the link that opened it, you won't be able to close the modal in some browsers since the onmouseout even will no longer fire. You can prevent this by offsetting the modal window from the link or attaching Control.Modal.close events to other elements on the page.

HTML / CSS Containers & Names

This script automatically creates two nodes that are direct children of the body node of your document. They are #modal_overlay and #modal_container. The overlay is what makes the screen dim. The container contains the contents of the currently open modal window.

Local, AJAX or iframe Modals

You can open a modal window to content that is already on the page, so long as it is conatained in any element that has an id. You create this kind of link just as you would link to any other element id <a href="#my_container_name">. If you want to link to an AJAX call just specify the full URL in your link's href. To create an iframe, do the same and pass in the parameter {iframe: true}. The iframe element will have an id of #modal_iframe by default.

Linking to a Modal Window from Another Page

You can have a modal window pre opened on the page if is local / on page (not an AJAX, iframe or image modal), by adding the id of the container to the page url. For example load the following URL in another window: http://livepipe.net/projects/control_modal/#modal_window_two

Closing the Modal Window with a Link

You can close any modal window by calling Control.Modal.close(); You don't need a reference to the currently open modal window to do that. From inside an opened iframe you'll need to call parent.Control.Modal.close();

Callbacks and Responders

Each of the following beforeOpen, afterOpen, beforeClose, afterClose, beforeLoad, onLoad, afterLoad callbacks can be defined as shown in the example above. But if you want to add callbacks to every modal window, you can do so by using Control.Modal.addResponder() :


var open_modals = 0;
Control.Modal.addResponder({
    afterOpen: function(){
        ++open_modals;
    },
    afterClose: function(){
        --open_modals;
    }
});

Odds and Ends

This is a work in progress. Please send me suggestions or bug reports.
You can hit the escape key to close a modal window.
Creating iframes in Safari with JavaScript is buggy at the moment.

Online Forum

I'd love to hear your feedback and suggestions for this library. Please head over to the Control.Modal discussion forum. This is a brand new forum so there aren't many discussions yet, but I do check it regularly.

LivePipe™

Control.Modal