A hidden gem - the Modal script shipped with Joomla

Sometimes you are looking hard elsewhere to find an useful, much needed extensions, just to find out, that the tool is already in your toolbox. This is the case with the modal script shipped with Joomla, which is a great tool (even with the known limitations) to add a basic lightbox function to your site without needing anything else, but a few lines of code.
Here are few examples of what you can do with!

Basic usage is actually very simple. First of all you need to include the following in the php code for your extension or template:

 JHTML::_('behavior.modal');

This lines does nothing else, but simply ensures that the modal.js script and the modal.css stylesheet are loaded, plus the mootools JavaScript framework which the script requires, and initializes the modal window. You can add it to your site template very easily by opening the Joomla template manager, finding the list of site templates, then clicking on your default site template name. In Joomla 1.5 you will see a button labeled 'edit HTML'. In Joomla 1.6+ there is a more extensive list of options, you need to click on 'edit main template' from the options. In either case you need to make sure that the code is added to the php code at the top of the index.php file, not the HTML code.

Then to create a popup you simply give the css class 'modal' to the link <a> tag which links to the content you want to display. This is easier to demonstrate than explain. For example, if you have an image which you want to display in a modal (lightbox) window you can just use the following:

<a href="http://www.example.com/images/myimage.jpg" 
class="modal">
Click here to see my image</a>

You can also load an existing html element from your page, using the element id, for example suppose your page contains some HTML such as the following:

<div id="loadDiv">
  A div element containing some text that you want to display.
</div>

Then you can create the link

<a href="#loadDiv" 
class="modal">Click here to load the text in a popup</a>

Options and Handlers

In some cases you want to supply options which give added control to how the content is presented. This is done using the 'rel' attribute of the anchor tag, the options are listed using javascript object notation, for example the following would resize the popup to 700 x 300 pixels, and make it impossible to close. I'm not sure why you would want to do that, but there might be occasions when it is useful.

<a href="http://www.example.com/images/myimage.jpg" 
class="modal"
rel="{size: {x: 700, y: 300}, closable: false}">
Click here to see my image</a>

A common use of options is to set the appropriate handler. The modal script includes a variety of handlers: image, iframe, string, ajax, clone (also known as adopt, which is used to load an existing html element). Where the link is to an image, or an element on the page, as in the examples above, the script is smart enough to automatically detect this and load the appropriate handlers. In other cases you will need to do this explicitly. For example a common use of the modal window is to load the contents of an URL into an iframe, for this you need to set the iframe handler:

<a href="http://www.example.com/somepage.html" 
class="modal" rel="{size: {x: 700, y: 500}, handler:'iframe'}"
id="modalLink1">
Click here to see this interesting page</a>

Scripting With the Modal Window

There may be times when it is more useful to use Java Script to control the modal window, for example when the content of the popup needs to be set dynamically, or load the window immediately when the page loads.

Depending on the application you may want to load the modal script and stylesheet, and initialize the popup yourself rather than using the modal behavior. If so, the following included in the PHP code will load the relevant files in Joomla 1.5:

JHTML::_('behavior.mootools');
JHTML::_('script','modal.js', 'media/system/js', true);
JHTML::_('stylesheet','modal.css');

In Joomla 1.6+ you can use:

JHTML::_('behavior.framework',true);
$uncompressed = JFactory::getConfig()->get('debug') ? '-uncompressed' : '';
JHTML::_('script','system/modal'.$uncompressed.'.js', true, true);
JHTML::_('stylesheet','media/system/css/modal.css');

For example, if you want to use a different stylesheet for the popup you can substitute your own stylesheet for the default '/media/system/css/modal/css'.

In the javascript the window is referred to as 'Squeezebox'. You will need to initialize the Squeezebox with the options you want to use, then add call to the setContent method with the handler and the content as arguments. For example the following will display a popup window containing any text is passed to it which closes itself after a time interval of 3 seconds.

var timeoutID = null;
function example_alertBox( boxText )
{        
    if(timeoutID)
    {
       SqueezeBox.close();    
    }
        
    var options = {size: {x: 300, y: 250}};
    SqueezeBox.initialize(options);
    SqueezeBox.setContent('string',boxText);
            
    timeoutID = setTimeout( 'SqueezeBox.close()', 3000 );
}

I should add that in a case like this you should be careful about where the text is coming from, if it is being supplied from user input you will want to do some filtering to prevent scripting attacks.

To open an iframe using a script you can use

   SqueezeBox.setContent('iframe',url);

where url is the URL of the page you want to load into the iframe.

You can also use the fromElement() method to load the popup. The following example will load the iframe from example with the setting of handler above immediately when the page loads:

<script type="text/javascript">
 window.addEvent('domready', function() {
     SqueezeBox.fromElement('modalLink1');
  });
 </script>