I tend to write these guides when I look for information on a particular subject and can't find what I need, and end up having to figure it out for myself. This is very much the case with the current subject. So here is my rough guide to using the Joomla modal script in your extension or template.

In spite of some limitations (mentioned below), the Joomla modal script is a useful way to add a basic lightbox function to your site without requiring any specialist extensions.

Basic Usage

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

Example 1

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

This simply ensures that the modal.js script and the modal.css stylesheet are loaded, plus the mootools javascript framework which the script requires, and initialises 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 labelled '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:-

Example 2

<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:-

Example 3

<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.

Example 4

<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:-

Example 5

<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 javascript 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 initialise the popup yourself rather than using the modal behaviour. If so, the following included in the PHP code will load the relevant files in Joomla 1.5:-

Example 6

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 initialise 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.

Example 7

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 5 above immediately when the page loads:-

Example 8

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

The Ajax Handler

Unfortunately, unless I am missing something, the Ajax handler doesn't seem to work. (If anyone reading this has some examples that work I would be pleased to hear them). If you want the results of an Ajax request to be displayed in a popup window then you can submit the request yourself using the Mootools Request class, update the results to your page, then use the Squeezebox 'clone' handler to load the results into the modal window, using

 SqueezeBox.setContent('clone',updateID); 

where updateID is the ID of the element containing the results.

More Options

I have found that not all of the modal window options appear to work as they should, so if you find this too, you are probably not going mad. For example you would think that the boolean option 'closeBtn' could be used to set whether or not the close button is displayed, but in fact it does nothing. There are also options for a series of event handlers: onOpen, onClose, onUpdate, onResize, onMove, onShow, and onHide. Unfortunately these all seem to fire when the window is opened (in Firefox and IE9 at least), so are less useful than you might hope.

Author Profile