MooTools API
Slimbox.open()
You can launch Slimbox using Javascript to display a single image or a group of images.
Call the Slimbox.open()
method with the following parameters:
Slimbox.open(url, description, options);
- url is mandatory, it's the URL of the image to display.
- description is optional, it's the image description text.
-
options is optional, it's a javascript object where the keys are option names and the values depend on the key. The options are described in detail in the Slimbox manual. Example of options object:
{ captionAnimationDuration: 0, loop: true, overlayOpacity: 0.5
}
Examples:
Slimbox.open("tree.jpg");
Slimbox.open("http://externalwebsite.com/tree.jpg", "My beautiful tree");
Slimbox.open("tree.jpg", "", {overlayOpacity: 0.2});
Call the Slimbox.open()
method with the following parameters:
Slimbox.open(images, startImage, options);
-
images is mandatory, it's an array of arrays. The main array contains one array for each image. The second-level arrays contain the image URL as a mandatory first element, and the image description as an optional second element. Example, for 2 images:
[["image1.jpg"], ["image2.jpg", "description2"]]
- startImage is mandatory, it's the zero-based index of the image that you want to show first when Slimbox opens. 0 is the first image of the array, 1 is the second, etc. Of course, this value must be smaller than the size of the main array. Most of the time, you will use 0.
- options is optional, it's the same parameter as the one described above for displaying a single image.
Examples:
Slimbox.open([["cat.jpg", "Nice cat"], ["dog.jpg"]], 0);
Slimbox.open([["left.jpg"], ["middle.jpg"], ["right.jpg"]], 1, {loop: true});
The autoload code block is the readable code block located by default inside the slimbox.js file of the official Slimbox distribution. This code is using the Slimbox API to register Slimbox for a specific kind of links, so that Slimbox will open when the user clicks on any of these links. The registration is performed as soon as the DOM is ready.
The default implementation mimics the original Lightbox behavior: it registers Slimbox for all links (<a>
tags) having a rel
attribute value starting with the word "lightbox". If the rel
attribute contains only the word "lightbox", it opens Slimbox to display a single image. Otherwise, it displays an image gallery containing all the images having the same rel
attribute value as the one that was clicked, like "lightbox-animal" for example. For each link, its target (href
attribute) is used as the image URL and its title
attribute is used as an optional description shown in a caption below the image.
All the aspects of this default implementation may be freely changed to fit your needs thanks to the powerful Slimbox API. The following section explains how to do it.
Slimbox makes a new function available on DOM elements when they are extended by mootools. This function can be called on a single extended DOM element, or on a group of extended DOM elements. Those elements will usually be link elements (<a>
tags) but it's not mandatory: for example you can also use image maps (<area>
tags). For other kinds of DOM elements, you'll need to provide a linkMapper function (described further in this page).
When calling this function on DOM elements, Slimbox will register itself and will open as soon as one of these DOM elements is clicked. The syntax is as follows.
$(element).slimbox(options, linkMapper);
where element is either:
- a DOM element.
- a string containing the id of a DOM element.
parameters are all optional:
- options is a javascript object where the keys are option names and the values depend on the key. The options are described in detail in the Slimbox manual.
- linkMapper is a function. It is described further in this page.
Example:
<a id="myLink" href="tree.jpg">Click Me</a>
$("myLink").slimbox();
$$(elements).slimbox(options, linkMapper, linksFilter);
where elements is either:
- a collection of DOM elements.
- an array containing DOM elements.
- a comma-separated list of DOM elements (multiple arguments).
- a string, which may contain either:
- A tag name. This will select all DOM elements with the specified tag name.
- A CSS selector.
Warning: If you are using mootools 1.2 or below (the older versions), your mootools build must include selectors support. The minimal mootools build included in the Slimbox distribution does not provide selectors support for these older versions and therefore you need to download the full Mootools Core from the Mootools website if you want to use this feature. Starting with mootools 1.3, selectors support is part of the mootools core and is always available.
parameters are all optional:
- options is a javascript object where the keys are option names and the values depend on the key. The options are described in detail in the Slimbox manual.
-
linkMapper is a function. It is described further in this page. If you want to omit this parameter, you can set it to
null
. - linksFilter is a function. It is described further in this page.
This is the magic part: calling the slimbox()
function on a group of elements which actually contains more than one element will cause the associated images to be shown together as a group in Slimbox, with one image for each DOM element. The order of the images in the Slimbox gallery will follow the order of the DOM elements in the group.
Example (using a CSS selector):
<div id="gallery">
<a href="tree.jpg">A tree</a>
<a href="cat.jpg" title="Nice cat">A cat</a>
<a href="dog.jpg" title="Look at this dog">A dog</a>
</div>
$$("#gallery a").slimbox();
The linkMapper is a function that you can pass as an optional parameter to the slimbox()
function. It is responsible for doing the mapping between a DOM element and the image URL and description that will be shown in Slimbox when clicking on that element.
You can change it in order to change the location where the URL and description will be retrieved, or even customize the URL or description itself.
It takes one parameter: a DOM element.
It returns an array containing 2 elements:
- The image URL.
- The image description. It may be
null
, an empty string or even omitted because the description is optional.
When you don't provide a linkMapper function, a default one is used. Here is it:
function(el) {
return [el.href, el.title];
}
As you can see, the default linkMapper uses the href
attribute of the DOM element as image URL, and the title
attribute of the DOM element (if present, otherwise it will return null
) as the image description.
This default implementation works well with <a>
and <anchor>
tags. If you call the slimbox()
function on other kinds of DOM elements which do not have an href
attribute, of course it will not work and you will need to override the default linkMapper function.
Example 1:
Let's say that you want to fetch the image description from the alt
attribute located in a DOM image node which is a direct child of the link node, instead of the title
attribute of the link node itself. The HTML code looks like this:
<a href="flower.jpg" id="mypicture"><img src="flower-thumbnail.jpg" alt="Beautiful flower" /></a>
Here's the linkMapper function that you will need to use:
function(el) {
return [el.href, el.firstChild.alt];
}
Please note that this function will only work if the DOM element actually has a child node, otherwise an error will occur when trying to access the title
attribute.
Example 2:
This time, let's say that you want to use the image URL itself as description, so no need to fetch it from the title
attribute of the DOM element. But you only want to keep the main part of the image URL, without the path at the beginning and without the file extension (.jpg). You will use a regular expression to achieve this. Here's what your custom linkMapper function will look like:
function(el) {
return [el.href, /[^\/]*(?=\.\w+$)/.exec(el.href)];
}
Example 3 (Flickr integration):
In this last example, we'll accomplish a complete Flickr integration with very little code. Let's say that we have links pointing to pages dedicated to pictures on the Flickr website. Each one of these links is surrounding an <img>
tag, which is actually a thumbnail of the picture hosted on the Flickr website. It looks like this:
<a href="http://www.flickr.com/photos/14516334@N00/345009210/"
title="A bee"><img src="http://farm1.static.flickr.com/159/345009210_1f826cd5a1_t.jpg" alt="" /></a>
By default, clicking on this link (and thus on the thumbnail) will just make the browser navigate to the Flickr page of the picture.
Now, without changing anything to the HTML, we want to register Slimbox on these links so that when the visitor clicks on them, Slimbox will open and display the medium-sized image, also hosted on the Flickr website.
How to achieve this using a linkMapper function? It's quite simple actually. URLs of images hosted on the Flickr website are always the same for the same picture, only the end of the URL changes depending on the image size. Square-sized images name ends with _s.jpg
, thumbnails name ends with _t.jpg
, small images name ends with _m.jpg
and medium-sized images name just ends with .jpg
. So, we need to retrieve the URL of the thumbnail image which is a direct child of the clicked link, and then using a regular expression, replace the end of this URL with ".jpg" to get the URL of the medium-sized image. Done!
But that's not all, we also want to automatically add a link to the Flickr page of the picture in its description inside Slimbox. This is easy to achieve: we just need to append some HTML at the end of the existing description.
Last but not least, we'll filter out the link elements, only keeping those pointing to the Flickr webpages and surrounding a thumbnail image.
Here's the code (using a CSS selector):
$$("a[href^=http://www.flickr.com/photos/] > img:first-child[src]").getParent().slimbox({}, function(el) {
return [el.firstChild.src.replace(/_[mts]\.(\w+)$/, ".$1"),
(el.title || el.firstChild.alt) + '<br /><a href="' + el.href + '">Flickr page</a>'];
});
The linksFilter is an optional function that you can pass as an optional parameter to the slimbox()
function when called on a group of DOM elements. It allows you to exclude specific elements of the group when clicking on a particular element, so they will not be part of the selection of images that will be displayed by Slimbox when it opens after the click. The element that was clicked must never be excluded because it's the one that will be displayed first when Slimbox opens.
In other terms, this function allows you to divide a group into sub-groups based on a selected criteria, by hiding some images depending on the element that was clicked.
It takes one parameter: a DOM element.
Also, the DOM element that was clicked is accessible by using the this
keyword from inside the function.
It returns a boolean: true
if the element that was passed as a parameter must be part of the selection of images that will be displayed, false
if the element must be excluded. When the passed DOM element is equal to this
, the function must return true
.
When you don't provide a linksFilter function, a default one is used. Here is it:
function(el) {
return true;
}
which means that by default no DOM element will ever be filtered out. There will only be one big group.
Example 1:
Let's say that you want to display all the images having the word "exclusive" somewhere in the title
attribute value of their DOM element together in a separate "exclusive" group, and all other images together in a default group. Here is the linksFilter function that you will use:
function(el) {
return /exclusive/i.test(this.title) == /exclusive/i.test(el.title);
}
Example 2:
This is a very useful one. Let's say that you want to automatically group together all the images with a DOM element having the same parent node (for example, all image links inside the same <div>
block or the same paragraph). Images with a DOM element having no parent node or being a "unique slimbox child" will be displayed individually. Here is the linksFilter function that achieves this:
function(el) {
return (this == el) || (this.parentNode && (this.parentNode == el.parentNode));
}
As you can see, we need to test first if the parent node exists before comparing the parent nodes of the clicked element and the passed element, otherwise all orphans will be grouped together. If there is no parent node, we return false
so that all images are excluded, except for the one which was clicked for which we always return true
.
Example 3 (Lightbox behavior):
The default autoload code block provided with Slimbox makes use of the following linksFilter function to mimic the default behavior of Lightbox:
function(el) {
return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
}
It may look a bit complicated at the beginning but it's not. Here's the detailed explanation.
- Before calling this linksFilter function, we have already narrowed our selection of DOM elements to the ones having a
rel
attribute value starting with the word "lightbox". - First, if the clicked element (
this
) is the one being tested, we returntrue
as required. It will always be part of the selection. - If it's not, then we test if the
rel
attribute value has exactly 8 characters. If it has, it means that therel
attribute value is exactly "lightbox" (8 letters) and in this case we returnfalse
so that in the end all images will be filtered out, except for the one that was clicked of course. This allows to display the image individually if therel
attribute value is exactly "lightbox". - Finally, if the
rel
attribute value has more than 8 characters, we know that it's a group name (like "lightbox-animals" for example) and we returntrue
far all DOM elements having exactly the same group name as the one being clicked, orfalse
to discard the other ones. This allows to display all the images having the same group name together.
In order to reverse the process and unregister Slimbox once the slimbox()
function has been called on a DOM element or a group of DOM elements, use the following code.
For a single element:
$(element).removeEvents("click");
or for a group:
$$(elements).removeEvents("click");
The normal behavior will then be restored for these DOM elements and clicking on them will not launch Slimbox anymore.