modal window with lightbox - native joomla javascript

Joomla's native modal.js ("squeezebox") is really easy to use to pop up a modal window with a lightbox overlay. You can popup images, hidden divs, internal and external urls.

It just takes one line of code in your component's template file, or in index.php if you want it site-wide.

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

This nifty one liner does all the heavy lifting - inserting links for media/system/js/modal.js and media/system/css/modal.css into the head of the document and adding a basic domready event as well. All you have to do is to put in the link(s) that triggers the modal behaviour.

inserting the links

Use an ordinary link specifying the default class (a.modal), and use the rel attribute to specify a handler, and any of the available optional presets in the format:

<a href="whatever" class="modal" rel="{handler:'specify', preset1:'value1', preset2:'value2'}">Link</a>

Handlers

• image
• adopt - great for hidden divs on the page
• url - use for internal urls
• iframe - use for external urls

Presets (optional)

• size
  - width(x) and height(y) of the final window. Default is 600x450
• sizeLoading
  - width(x) and height(y) of the initial window. Default is 200x150
• fxOverlayDuration
  - the time it takes for the background to darken/lighten when the link is clicked, or the lightbox is shut. Default is 250ms
• fxResizeDuration
  - the time it takes for the lightbox to go from sizeLoading to size. Default is 750ms
• fxContentDuration
  - the time it takes for the content to fade in. Default is 250ms
• classOverlay
  - adds a class to style the overlay. Put it in your template's css file as #sbox-overlay.your-class. Default is empty.
• classWindow
  - adds a class to style the modal window. Put it in your template's css file as #sbox-window.your-class. Default is empty.
• For the full list of presets see media/system/js/modal.js

examples of links

handler: image

Click here for <a class="modal" href="path/to/bigimage.jpg" rel="{handler: 'image', sizeLoading: {x:200, y:150}, size: {x:400, y:300}}"><img src="path/to/thumbnail.jpg /></a>

Note that sizeLoading and fxResizeDuration are not noticeable if the image loads quickly, or is cached.

handler: adopt

Perfect for a hidden div that can be triggered to popup by clicking a link. Use the adopt handler, and specify the div you are going to adopt.

<div style="display:none;">
<div id="spampolicy">
<h4 class="purple">Spam Policy</h4>
<p style="color:#ff3300;"><strong>We hate spam too - that's why we use a double opt-in strategy and a reputable newsletter service that upholds the CAN SPAM Act. We will never disclose your personal details to anyone unless the law requires us to do so.</strong></p>
</div>
</div>
<p><a class="modal" rel="{handler: 'adopt', adopt:'spampolicy', size: {x:300, y:200}, classWindow: 'spamwindow'}" href="javascript:void(0);">Read our Spam Policy</a></p>

Note that this is a cloned element, so the resizing effects are not available.

handler: url

This means a relative url from your site.

See our <a class="modal" href="index.php?Itemid=34" rel="{handler: 'url', sizeLoading: {x:150, y:100}, size: {x:640, y:480}, fxResizeDuration:1200, fxContentDuration:500">Privacy Statement</a>

handler: iframe

Use this for external urls.

<p>Click here for <a class="modal" href="http://www.google.com" rel="{handler: 'iframe'}">Google</a></p>

Note that this is an iframe, so the resizing effects are not available.

adding universal settings to JHTMLBehaviour

There are 2 params you can optionally add as universal settings if you need them (you probably won't):

1. The element and class you want to trigger the modal window
   (this is set to a.modal by default so you wouldn't normally change it unless you had good reason)
2. $params = array()
   (Note that these can also be added to each individual link that trigger the popup – so only add universal settings here.

Eg if you wanted to universally set the anchor element that triggers the lightbox to a.lightbox (instead of the default a.modal), you wanted all windows to open to 640x480 then you can also set your universal options:

$options = array(

'size'=>array('x'=>640, 'y'=>480)

);

JHTML::_('behavior.modal', 'a.popup', $options);

Note that the basic options you can use with JHTML::_('behavior.modal'); can be seen in libraries/joomla/html/html/behaviour.php. These are far fewer than in modal.js. This means the only useful preset you can use as a universal option is size.

Roll Your Own Code

If you want to roll your own code – eg to get more effects, then you have to hardcode links to modal.js and modal.css. In addition you need to write your own domready code.

Sample code to include in the <head> of your template's index.php:

<script src="<?php echo JURI::base(); ?>media/system/js/modal.js" type="text/javascript"></script>
<link rel="stylesheet" href="<?php echo JURI::base(); ?>media/system/css/modal.css" type="text/css" />
<script type="text/javascript">
// <!--
window.addEvent('domready', function() {
SqueezeBox.initialize({
size: { x:640,y:480 },
sizeLoading: { x:250,y:250 },
fxResizeDuration:1000,
fxContentDuration:1000,
classWindow: 'lightwin'
});
$$('a.modal').each(function(el) {
el.addEvent('click', function(e) {
new Event(e).stop();
SqueezeBox.fromElement(el);
});
});
});
// -->
</script>

Notice that I've put the universal presets into the initialise function. From here, it works just the same, presets in links overriding anything set universally. Not all the presets work for all the handlers – as already mentioned.

It's a simple class, so you'd need to write your own version of modal.js to get it to do more.

References: Joomla 1.5 API JHTMLBehaviour class
http://api.joomla.org/Joomla-Framework/HTML/JHTMLBehavior.html