Milkbox v2.3.2 - Expanded lightbox for Mootools 1.2.x
By Luca Reghellin - milkbox@reghellin.com

Hi! First of all, my english is not so good: please be patient with my mistakes. For anything wrong, as well as for debug questions and suggestions, you can try to send me an e-mail: I usually don't have much time, but I'll try to answer you.
You'll also find some posts in mootools users google group: http://groups.google.com/group/mootools-users/

As long as I'll have the time to do it, I'll try to help anyone who ask for some help with Milkbox implementation or for little customizations, but I'll definitely favour people that make a donation (see the bottom of this page).

Quick links:

What's Milkbox

Nothing special: just another lightbox clone, this time written for Mootools 1.2.x. I needed it, so I decided to write my own and I'm happy to share it.

Inspiration comes from THE VERY FIRST MAN ON THE MOON: Lokesh Dhakar, and his fabulous Lightbox: http://www.lokeshdhakar.com/projects/lightbox2/.

Main features

Take a look

To correctly see the flash animation, you need to install flash player 10.

First photo by Retinafunk

Below you will find some other examples.

How to use Milkbox

// Basic use (just like Lightbox)

  1. Make sure that there is a XHTML DOCTYPE declaration at the very top of the page. XHTML transitional or strict are good.

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

  2. Include the milkbox.css file in your page. Make sure the referenced images are in the right location. I suggest to leave them in the milkbox css folder.

    <style type="text/css">
	@import url(css/milkbox/milkbox.css);
</style>

  3. Include the mootools 1.2 js library. milkbox.js needs the following libraries to work properly:

    • - The Mootools core library.
    • - The Assets more component
    <script type="text/javascript" src="js/mootools-1.2.3-core-yc.js"></script>
<script type="text/javascript" src="js/mootools-1.2.3.1-more.js"></script>

  4. Include the milkbox.js or (maybe better) the milkbox-yc.js file.

    <script type="text/javascript" src="js/milkbox.js"></script>

  5. Add a rel="milkbox" attribute to any link tag to activate the Milkbox. Optionally, add a title attribute. If you have a set of related images that you would like to group, include a group name between square brackets in the rel attribute, or separate it from the 'milkbox' word with some other character: for example, if you'd like to validate your page as xhtml 1.1, you could use a colon or an underscore.
    If you want to add tags inside the title property (for example a link), please use html entities and no quotes, then eventually style them with css: the relevant id is #mbDescription.

    <a href="img/01b.jpg" rel="milkbox[gall1]" title="Caption goes here...">image #1</a>
<a href="img/02b.jpg" rel="milkbox[gall1]" title="Caption goes here...">image #2</a>
<a href="img/03b.jpg" rel="milkbox[gall1]" title="Caption goes here...">image #3</a>

    Example for xhtml 1.1 validation - A colon instead of the square brackets:

    <a href="img/01b.jpg" rel="milkbox:gall1" title="Caption goes here...">image #1</a>
<a href="img/02b.jpg" rel="milkbox:gall1" title="Caption goes here...">image #2</a>
<a href="img/03b.jpg" rel="milkbox:gall1" title="Caption goes here...">image #3</a>

    If a link points to an swf file, add a rev attribute with comma-separated width/height values:

    <a href="swf/banner.swf" rel="milkbox[gall1]" rev="width:600,height:200" 
title="Caption goes here...">image #1</a>

// CSS Properies

You can customize the following css properties by modifying the milkbox.css file (see comments inside) or the DOM elements via setStyle/setStyles. The relevant DOM elements are written in brackets:

You can also add border/padding to the images (or swf files) via the global JavaScript options.
To set some css property via JavaScript you can do something like this: 

window.addEvent('domready', function(){
	milkbox.center.setStyle('borderColor','#00ff00');
	milkbox.overlay.setStyle('backgroundColor','#aabbcc');
});

// Global JavaScript options

Here's the list of the global options you can modify. Default values are written in brackets:

  • overlayOpacity (0.7)
  • topPosition (50): good for big images: changes the offset from the top of the window.
  • initialWidth (250)
  • initialHeight (250):
  • canvasBorderWidth ("0px"): when your images have the same background color of the one you use for Milkbox, you want to add a border, and you don't want to do it with photoshop..
  • canvasBorderColor ("#000000")
  • canvasPadding ("0px")
  • resizeDuration:(500)
  • resizeTransition ('sine:in:out'): you can use a function (ex. Transitions.Sine.easeIn) or a string (ex. 'quint:out')
  • autoPlay (false)
  • autoPlayDelay (7): set it in seconds, not milliseconds
  • removeTitle (false): If true, you won't see the titles contents popping up while hovering the Milkbox links (default behaviour of browsers like FireFox)
  • autoSize (true): reduces the images if they don't fit the browser window
  • maxHeight (0): set the max autosize height. Works only if > 0 and autoSize == true.
  • imageOfText ('of'): set the word between count numbers.
  • onXmlGalleries ($empty): to set an optional function to be used when an xml gallery is loaded
  • onClosed ($empty): to set an optional function to be used immediately after Milkbox is closed

By modifying the global options, you change the options for all galleries in your page.

You can set them in 3 ways:

1. In the .js file, at the top of the class.
2. In the .js file, at the bottom, where Milkbox is instantiated: 
window.addEvent('domready', function(){
	milkbox = new Milkbox({ resizeTransition:'back:out', topPosition:30 });
});
3. In a js script, after the DOM is ready, by using the changeOptions() method: 
window.addEvent('domready', function(){
	milkbox.changeOptions({ 
		canvasBorderWidth:'5px',
		canvasBorderColor:'#ffcc00',
		canvasPadding:'10px'
	});
});

The changeOptions() method is essentially a wrapper for the setOptions() method. It makes sure that all the options are really changed (especially transition and duration).

If you want for some reason to temporarily change the global options and then restore them with the originals, you can do it with the restoreOptions() method:

window.addEvent('domready', function(){
	milkbox.restoreOptions();
});

Take a look to some other example.

Especially example 1 is quite processor-intensive, so keep in mind that if you use that kind of transitions, it could not run really fluid in some old computers.

// Custom Events

Milkbox now has 2 custom events: onXmlGalleries and onClosed.

- Use onXmlGalleries when you want to know if an XML file is completely loaded. See the XML Galleries paragraph for details.

- Use onClosed when you want to do something immediately after Milkbox is closed. I personally use this to restore the originally setted options or css if for some reason I temporarily changed them: 

		
window.addEvent('domready',function(){
	$('testbutton').addEvent('click',function(){
		milkbox.changeOptions({ resizeTransition:'bounce:out', canvasBorderWidth:'5px' });
		milkbox.addEvent('closed',function(){ 
			milkbox.restoreOptions(); 
		});
		milkbox.showGallery({ gallery:'gall1' })
	})
});

// AutoPlay

You can set it globally via the autoPlay and autoPlayDelay options like described in the 'Global JavaScript options' paragraph.
If you use an XML gallery, you can set different autoplay options for every gallery.
Finally, you can override the options on a per-gallery basis by using these methods (described below):

setAutoPlay()
showGallery()

But what's autoPlay? Well, yes, it's that! ;)
Milkbox will sequentially show all the files in a gallery, with a pre-defined delay between each.
You will be able to stop it either by clicking the play/pause button or the next/prev buttons. You will then use the play/pause button to re-start it.

Click here for an autoPlay example (delay: 7 seconds)

Use of setAutoPlay()

You use setAutoPlay() if you want to permanently override the global autoplay options for one or more galleries.
You can pass it an object or an array of objects. Every object should have 3 properties: gallery (string), autoplay (boolean), delay (number). 

window.addEvent('domready', function(){
	milkbox.setAutoPlay([
		{ gallery:'gall1', autoplay:true, delay:10 },
		{ gallery:'gall2', autoplay:false },
		{ gallery:'gall3', autoplay:true, delay:7 }
	]);
});

// Launch Milkbox from JavaScript

Instead of clicking a link, you can launch Milkbox directly from JavaScript (and therefore even from Flash, via ExternalInterface), usign the showGallery() method.

Use of showGallery()

You use showGallery() if you want to launch Milkbox directly from JavaScript. You can launch any gallery, starting from any file and with custom autoplay options. Autoplay options here are not modified permanetly: the originals will be restored after you close Milkbox. To permanently change autoPlay options, use setAutoPlay().
You can pass showGallery() an object. That object must have a gallery property (string: the name of the gallery you setted in the rel property), and optionally 3 more properties: index:(number), autoplay (boolean), delay (number). 

window.addEvent('domready', function(){
	$('testbutton').addEvent('click', function(e){
		e.preventDefault();
		milkbox.showGallery({ gallery:'mygallery', index:3, autoplay:true, delay:10 })
	});
});

If you want to lauch Milkbox from flash, simply use ExternalInterface: 

import flash.external.ExternalInterface;

//if you need, load some xml:
ExternalInterface.call("milkbox.addGalleries",'galleries.xml');

//AS2: ////////////////////////////////////
sampleButton.onRelease = function(){
	ExternalInterface.call("milkbox.showGallery",{gallery:'mygallery', index:3, autoplay:true});
}

//or AS3: /////////////////////////////////
function openMilkboxFromAS(e:MouseEvent){
	ExternalInterface.call("milkbox.showGallery",{gallery:'mygallery', index:3, autoplay:true});
}

sampleButton.addEventListener(MouseEvent.CLICK,openMilkboxFromAS);

Here there's a really nice tutorial written by Rafael Dery explaining how to build a flash gallery with Milkbox.

// XML Galleries

If you don't need to write HTML links, but still want to use Milkbox to show some gallery, you need to define them in some other way. Enter the XML galleries. :)

How to set and use an XML Gallery

First of all, you need to write an xml file, for example:

<?xml version="1.0" encoding="utf-8"?>
<div id="galleries">
	<div class="gallery" name="xmlG1" autoplay="true" delay="7" >
		<a href="swf/testswf1.swf" rev="width:550, height:400" title="Lorem ipsum..." />
		<a href="swf/testswf2.swf" rev="width:650, height:250" title="Lorem ipsum..." />
		<a href="img/01b.jpg" title="Lorem ipsum..." />
		<a href="img/03b.jpg" title="Lorem <a href=#>ipsum...</a>" />
	</div>
	
	<div class="gallery" name="xmlG2" >
		<a href="img/01b.jpg" title="Lorem ipsum..." />
		<a href="img/03b.jpg" title="Lorem <a href=#>ipsum...</a>" />
		<a href="swf/testswf1.swf" rev="width:550, height:400" title="Lorem ipsum..." />
		<a href="swf/testswf2.swf" rev="width:650, height:250" title="Lorem ipsum..." />
	</div>
</div>

As you can see, for every gallery you must use div tags with class="gallery" and set the name property. Optionally, you can add custom autoplay options for every gallery.
Please note that, since it's an xml document, tags are NOT real html tags, and the link tags must be empty tags, so you close them with a space followed by a slash ((an empty space)/>), not with a close tag like this: </a>

Once you have your xml file, load it with the addGalleries() method:

milkbox.addGalleries('galleries.xml');

Now you can use all the Milkbox methods with the new galleries. I think you'll at least use showGallery(), but before doing it, it's safer to be sure that the xml file is really loaded, so you wrap it in the onXmlGalleries custom event:

milkbox.addEvent('xmlGalleries',function(){
	$('testButton').addEvent('click', function(e){
		e.preventDefault();
		milkbox.showGallery({ gallery:'xmlG2' });
	});
});

milkbox.addGalleries('galleries.xml');

// Reload galleries

Often, using Ajax, links and galleries change without fully refreshing the main page and therefore without updating the internal Milkbox galleries.
To solve these kind of issues, you can simply use the reloadGalleries() method. For example, a generic Ajax application could do something like this: 

app.ajaxRequest.onSuccess(response){
	addResponseToHtml(); 
	milkbox.reloadGalleries();
}

Tests (on Win and Mac Os X)

A little note: using Milkbox in a page that contains flash objects, you must set their wmode property to 'opaque' or 'transparent'.

Download Milkbox

> Here's the Milkbox link. [Milkbox (with all assets and demo, and yui-compressed version too): 593 Kb]
Milkbox+mootools+css+buttons themselves are about 100 Kb in size. The extra weight is due to the included photos of the demo page.

> And here's the buttons graphics [5 Mb (.psd and .ai)]

> And finally, here's some other examples using xml, html image maps, and flash (AS3/CS4).
Did I kindly ask you to donate some little money??? ;)

Plugins:

Mr. Xavier Larquet wrote a Milkbox module for Joomla : you can download it from his site.