Control.Modal

Introduction

By default, Control.Modal creates modal windows and lightboxes from any links/anchors elements on your pages. Since it attaches these behaviors to HTML that already has semantic meaning, it will degrade gracefully for browsers that do not support JavaScript, and is search engine friendly. It attaches in one line of code for simple use cases, but is highly customizable and can be used in a variety of edge cases.

Examples of Common Use Cases

Sample Code

<a href="#test_one_contents" id="modal_link_one">Relative Modal</a>
<div id="test_one_contents">
    I am the innerHTML of a div with the id "test_one_contents". You can make a modal window open relative to any element on the page.
</div>
<script>
    new Control.Modal('modal_link_one',{
        opacity: 0.8,
        position: 'relative',
        width: 300,
        height: 50
    });
</script>

Note that all of the examples above use id attributes in the anchor tags. If you were to assign class="modal" to each link, you could instead do the following if all modals are going to have the same options:

<a href="#modal_window_one" class="modal">Modal One</a>
<a href="#modal_window_two" class="modal">Modal Two</a>
<script>
    document.getElementsByClassName('modal').each(function(link){
        new Control.Modal(link);
    });
</script>

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. You need to assign some default styles to these containers. This is more or less what is used on this page:

#modal_container {
    padding:5px;
    background-color:#fff;
    border:1px solid #666;
    overflow:auto;
    font-family:"Lucida Grande",Verdana;
    font-size:12px;
    color:#333;
    text-align:left;
}
#modal_overlay {
    background-color:#000;
}

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.

Using Control.Modal as a Tooltip

Pass in the option {position: 'mouse'} on any modal to make it act like a tooltip (the modal will follow the mouse). {hover: true} is automatically applied when this happens, so most of the functionality and caveats that apply to a hoverbox apply here. Note that Safari 1 & 2 both have CPU usage problems on complex pages with this option. Firefox and IE both behave as expected. This will be fixed in an upcoming release.

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/#test_one_contents

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();

How to Read the API Table

A "Class Method or Property" is often referred to in other languages as a static method or property. The "overlay" property would be referenced as "Control.Modal.overlay". An "Instance Method or Property" refers to something that is available to each instance of the class. For example, the "open" would be referenced like so: "var my_modal = new Control.Modal(); my_modal.open();". Anything in the method and property lists that ends with "()" is a method, and anything that doesn't is a property. All events are specifiable in the options hash, or via "observe()" if Object.Event has been included on the page before Control.Modal was. In a method signature, each argument is separated by a comma, if the words are lower case it refers to the data type and gives a hint to what it is used for, if there is an upper case word it refers to the class of object that must be used. Arguments with [square brackets] around them are optional.

Class Methods and Properties

Instance Methods and Properties

Options

Events

All events can be passed in as an option, or if Object.Event has been included, they can be observed by calling Control.Modal.observe() to observe all instances, or by calling observe() on any particular instance to just observe that one.

Code Examples

//contents can be a string
new Control.Modal(link,{
    contents: 'contents of modal'
});
//or a function that returns a string, called each time the modal is opened
//"this" will refer to the modal object
m = new Control.Modal(false,{
    contents: function(){
        return 'contents of modal';
    }
});
m.open();
//or you can use Control.Modal.open() to do the same thing
Control.Modal.open('contents of modal');
link.observe('click',function(){
    Control.Modal.open('contents of my modal',{
        afterOpen: function(){
            //attach behaviors to the contents here
        }
    });
});
//this is an alternate way of doing AJAX modals with more granular control
//your loading html will be replaced by the Ajax.Request response when the call completes
m = new Control.Modal(false,{
    contents: function(){
        new Ajax.Request(url,{
            onComplete: function(request){
                this.update(request.responseText);
            }.bind(this)
        });
        return 'loading';
    }
});
m.open();

RSS Changelog

Is available at http://livepipe.net/projects/control_modal/changelog.rss

Downloads & SVN

The new 2.0 version is available via the button in the upper right. It introduces a backwards compatibility break with 1.0 by removing the responders functionality. This functionality is superseded by using the Object.Event library.

The Control Suite subversion repository is available at: svn://livepipe.net/control_suite/

The last 1.0 series release is available at http://livepipe.net/downloads/control.modal.1.2.12.js

Online Forum

Do you have questions, bug reports or suggestions? Visit the Control.Modal online forum.

Other Resources

Have you written a post or article about Control.Modal? Please contact me!