Milkbox v3.0.3 - Expanded lightbox for Mootools 1.4.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.

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

What's Milkbox

Nothing special: just another lightbox clone, this time written for Mootools 1.4.x.

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

Main features

Take a look

To correctly see the 'L.' flash animation, you need to install flash player v10 or higher.

First photo by Retinafunk

How to use Milkbox (basic)

  1. Make sure that there is a HTML5 DOCTYPE declaration at the very top of the page, so the data- properties will validate. If validation is not a concern, use an xhtml doctype.

    <!DOCTYPE html>
    
  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.

    <link rel="stylesheet" href="css/milkbox/milkbox.css" media="screen" />
    
  3. Include the mootools js library. milkbox.js needs the following libraries to work properly:

    • - The Mootools core library.

    • - The Assets, Measure and QueryString Mootools More Components

    <script src="js/mootools-core.js"></script>
    <script src="js/mootools-more.js"></script>
    
  4. Include the milkbox.js or (maybe better) the milkbox-yc.js file.

    <script src="js/milkbox.js"></script>
    
  5. Add a data-milkbox attribute to any 'milkbox' link.
    If the linked file is not part of a gallery, set the data-milkbox prop to 'single'; otherwise, just choose an arbitrary name for the gallery.
    Optionally, you can add a caption by setting the title property of the link tag. 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 #mbox-caption.

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

    If a link points to an swf file or an html file, add a data-milkbox-size attribute with comma-separated width/height values:

    <a href="swf/banner.swf" data-milkbox="gall1" data-milkbox-size="width:600,height:200"
    title="Caption goes here...">image #1</a>
    

How to customize Milkbox

// CSS Properies

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

  • Overlay color (milkbox.display.overlay)

  • The outer box background color (milkbox.display.mainbox)

  • The outer box background image (milkbox.display.mainbox) > I mean 'add' a background image

  • The outer box border color and width (milkbox.display.mainbox)

  • The outer box padding (milkbox.display.mainbox)

  • The inner box properties (milkbox.display.filebox)

  • All the images (be careful: if you change the buttons dimensions, you must be quite confident in using css)

  • All text properties (milkbox.display.caption and milkbox.display.count)

  • The border-left of the navigation controls (milkbox.display.controls)

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.display.mainbox.setStyle('borderColor','#00ff00');
	milkbox.display.mainbox.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)

  • marginTop (50): good for big images: changes the offset from the top of the window.

  • initialWidth (250)

  • initialHeight (250)

  • fileboxBorderWidth ("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..

  • fileboxBorderColor ("#000000")

  • fileboxPadding ("0px")

  • resizeDuration (.5)

  • resizeTransition ('sine:in:out'): you can use a function (ex. Transitions.Sine.easeIn) or a string (ex. 'quint:out'). See the mootools docs.

  • 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

  • autoSizeMaxHeight (0): set the max autosize height. Works only if > 0 and autoSize == true.

  • centered (false): if Milkbox will be centered on the window

  • imageOfText ('of'): set the word between count numbers.

  • onXmlGalleries (function(){}): to set an optional function to be used when an xml gallery is loaded

  • onClosed (function(){}): to set an optional function to be used immediately after Milkbox is closed

  • onFileReady (function(){}): to set an optional function to be used when the current file is loaded and ready to be showed

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

You can set them in 2 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, centered:true });
});

3. In a js script, after the DOM is ready, by using the refreshDisplay(options:Object,keepBackup:Boolean = false) method:

window.addEvent('domready', function(){
	milkbox.refreshDisplay({
		fileboxBorderWidth:'5px',
		fileboxBorderColor:'#ffcc00',
		resizeTransition:'bounce:out',
		resizeDuration:1
	});
});

The refreshDisplay() takes the new options as the 1st argument, and a boolean value as the 2nd argument (pass true if you want to use the new options only once).

How to use Milkbox (advanced)

// Custom Events

Milkbox has 3 custom events: onXmlGalleries, onClosed and onFileReady.

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

- Use onFileReady when you want to do something when the current file is loaded and ready to be showed. The current file is milkbox.currentFile.

// 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 setAutoPlay() (described below):

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(object or array of objects)

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 open() method for galleries, or openWithFile() method for single files without the need of build a gallery first.

Use of open(gallery (string or instance of MilkboxGallery),index)

You use open() if you want to launch Milkbox directly from JavaScript. You can launch any gallery, starting from any file.
You can pass open() the name of the gallery (so, a string), or, if you're an advanced programmer and are for some reason using an instance of MilkboxGallery, you can pass it directly.

window.addEvent('domready', function(){
	$('testbutton').addEvent('click', function(e){
		e.preventDefault();
		milkbox.open('mygallery',3);
	});
});

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.open",['mygallery',3]);
}

//or AS3: /////////////////////////////////
function openMilkboxFromAS(e:MouseEvent){
	ExternalInterface.call("milkbox.open",['mygallery',3]);
}

sampleButton.addEventListener(MouseEvent.CLICK,openMilkboxFromAS);

Use of openWithFile({object with href, size and title props}, {milkbox options})

You use openWithFile() if you want to open a single file with Milkbox directly from JavaScript without the need to build a single-item xml or json gallery first.

window.addEvent('domready', function(){
	$('testbutton').addEvent('click', function(e){
		e.preventDefault();
		milkbox.openWithFile({ href:'img/01b.jpg', title:'Test text'});
	});
});

Or maybe with some more options?

window.addEvent('domready', function(){

	$('testbutton').addEvent('click', function(e){
		e.preventDefault();
		milkbox.openWithFile(
			{
				href:'swf/flash.swf',
				title:'openWithFile() with some layout and transitions tweaks',
				size:'width:600,height:350'
			},
			{
				overlayOpacity:1,
				resizeTransition:'bounce:out',
				centered:true
			}
		);  //end openWithFile
	});  //end click event

});  //end domready event

// External 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 External galleries (XML and JSON galleries). Both types are loaded into Milkbox using the addGalleries(string or object) method

XML GALLERIES

To use xml galleries, 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 open(), but before doing it, it's safer to be sure that the xml file is really loaded, so you should wrap it in the onXmlGalleries custom event:

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

milkbox.addGalleries('galleries.xml');

JSON Galleries

To use JSON galleries, you need to pass the JSON object to addGalleries(). The JSON object must have this form:

[
{
	name:'gall1', autoplay:true, autoplay_delay:7,
	files:[
		{href:'file1.jpg', size:'width:900,height:100', title:'text'},
		{href:'file2.html', size:'w:800,h:200', title:'text'},
		{...},
		{...}
	]
},
{
	name:'gall2',
	files:[
		{href:'file1b.swf', size:'width:500,height:200', title:'text'},
		{href:'file3.html', size:'w:800,h:200', title:'text'},
	]
}
]

You can for example save it in a variable and pass that variable to addGalleries(), or pass it directly:

var gallery = [
	{
		name:'obj-gall1', autoplay:true, autoplay_delay:4,
		files:[
			{ href:'img/01b.jpg', title:'Test title' },
			{ href:'swf/testswf1.swf?var1=yellow&var2=300' }
		]
	}
]

milkbox.addGalleries(gallery);

Than you can use the usual milkbox methods like open().

// 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 reloadPageGalleries() method. For example, a generic Ajax application could do something like this:

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

There's also an utility method to clean all the external galleries already loaded (xml and json), and optionally load some new one. The method is resetExternalGalleries(list: single string/object or array of objects); you pass new galleries as the list parameter.

Notes

Tests (on Win and Mac Os X):

  • IE 7/8/9
    Still using IE 7 or (!!!) 6? Well, I think it's time to upgrade, DON'T YOU??

  • Latest Firefox

  • Latest Safari

  • Latest Chrome

If your page includes flash movies:

if you use Milkbox in a page that contains flash objects, you must set their wmode property to 'opaque' or 'transparent'.

Javascript compression:

If your site is running on an Apache server with an active deflate module (usually it's active by default, or you can ask your provider to switch it on for free) you could telling it to serve your js/css files gzipped. To do that, I usually write one of these lines in a .htaccess file (published in the root dir of the site):

AddOutputFilterByType DEFLATE text/html text/css application/x-javascript
#or
AddOutputFilterByType DEFLATE text/html text/css application/javascript

After doing that, milkbox-yc.js will be only 5.5Kb in size.

Software, plugins and people

Milkbox is also used by other developers all around the world for various softwares and plugins.
Please tale a look to the followings:

Feindura - Flat file cms

http://feindura.org
Feindura is a Open Source flat file based Content Management System for Web Designers and ideal for small and medium websites. There is no need of a database and it’s easy to integrate in your Websites.
(It uses milkbox for its image gallery.)

Mootools-FileManager

https://github.com/cpojer/mootools-filemanager
A filemanager for the web based on MooTools that allows you to view, upload and modify files and folders via your browser.

Gerrit E.G. Hobbelt

https://github.com/GerHobbelt
Ger Hobbelt uses Milkbox in some of his projects and helped me a lot in fine tuning v3.0.0.
He is a 20+ years of experience working as a software engineer, enjoying both systems architecture and hardcore development with a focus on security, stability and survivability of the product. Currently (as per 2011) the action is happening at a financial analysis and prognosis package with a strong focus on web technology and plenty of exiting math to drive the coding.

ScrollBox Pro - Plugin for Joomla

http://joomalungma.com/demos/scrollbox-pro
Milkbox is used by Nikita Zonov in his slideshow plugin for Joomla.

Serbo-Croatian translation

http://science.webhostinggeeks.com/kako-koristiti-milkbox
This is a translation of this page, made by Miss Anja Skrba to share it with the people from Former Yugoslav Republics: Serbia, Montenegro, Croatia, Slovenia, Macedonia, Bosnia and Herzegovina.

Download Milkbox

> Here's the Milkbox files with all assets and demo, and yui-compressed version too

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