FAQ

Christophe Beyls edited this page Apr 18, 2015 · 4 revisions

Table of Contents

Is Slimbox able to display Flash content (like videos), iFrames or other content?

No, Slimbox has been designed from the ground up to display images only, to be simple and to have the smallest code. However, some people have created Slimbox derivatives that implement these features. Because it's open source, you are free to modify the code to fit your needs, as long as you respect the terms of the licence and keep the credits.

Can Slimbox automatically resize my images when they are too large to be contained in the browser window?

Slimbox should not be used to display very large images. The general rule is that the images that you want to show with Slimbox must never exceed the width of your website template. You need to create reduced-size versions of your large images before displaying them with Slimbox.

Why?

First, very large images are better handled by the browser itself when opened in a dedicated window: usually in this case the browser will show the image progressively while it's loading and will automatically resize it to fit the browser window which is exactly what you want.

Second, Slimbox preloads images and only shows them when they are completely loaded. For very large images, this takes some time and this is bad for the user experience. Then, when the image is eventually loaded and shown, next and previous images of the gallery will start to preload too, even if the user does not intend to see them, thus it will use a lot of bandwidth on your website.

Third, dynamically resized images look pixellated in most browsers.

And finally, dynamic image resizing would make the Slimbox code very complex and there is actually no way to make it work flawlessly. Here's a quick technical explanation (you may skip it to avoid headaches):

  • The borders around the images in Slimbox can be freely adjusted in the CSS, so Slimbox cannot determine its own width or height until the resize animation is complete. But then it's too late because we need to know the size in order to launch the animation. And I don't want to hardcode the borders dimensions in the javascript code like Lightbox does, because I prefeir to keep the design part in the CSS file.
  • The caption under the image would ideally need to be fully visible too. It has a variable height and this height cannot be computed until it is displayed (it depends on the used font, the margins, the number of text lines, and so on), but again it's too late.
  • Even if the height is adjusted at the end of the animation so that the caption becames fully visible, then the width must be adjusted too in order to preserve the aspect ratio of the image. But if the width is reduced, the caption's height may increase because the text has less available space and could take up more lines. In this case, in order to make the caption fully visible, the height must be reduced again, and the width also, and so on... in a loop until everything is finally able to fit the screen. This effect will look buggy and unpredictable. So we need to forget about making the caption visible without scrolling when the image is automatically resized.

Slimbox display is incorrect on my website (sometimes only in a particular browser). What's wrong?

Most of the time, this is an issue with the CSS of your web page. Check that your CSS rules are valid and do not override Slimbox' CSS rules. In particular, check that there is no margin applied to your <body> and <html> tags, and that you don't override the default appearance of all <div> tags.

If your CSS is correct, you may have invalid or malformed HTML code. Don't expect Slimbox to work well in web pages containing two <body> elements, for example.

In particular, Internet Explorer tends to be less tolerant regarding invalid CSS or HTML.

Can I change the Slimbox images, colors, fonts, margins, border sizes?

Yes of course, you just need to edit the values in the CSS file. Slimbox uses CSS instead of javascript whenever possible.

How can I use HTML for the image descriptions?

You can use HTML for the image descriptions without problems. But if you insert HTML markup inside a "title" attribute in your HTML page, you need to replace the following characters:

  • < must be replaced with &lt;
  • > must be replaced with &gt;
  • " must be replaced with &quot;

You don't need to do this if you set the HTML markup for the description programmatically using Javascript (see jQuery API or MooTools API).

You can also write a custom linkMapper function which will grab the whole HTML content of a paragraph in the page for example and use it as a description instead of fetching it from the "title" attribute. This way, you don't need to transform the HTML markup either.

The loading of one of my images in Slimbox takes forever. What's wrong?

This happens when the URL of the image is incorrect or unavailable. Check that the URL is correct and that the server hosting the image is online.

Slimbox does not display images containing parenthesis in their URL. What's wrong?

Parenthesis are invalid characters for URLs. You must use their URL-encoded equivalent instead.

Just replace ( with %28 and ) with %29. You must also replace spaces with %20 or +. Other invalid characters include commas, square brackets, exclamation marks, question marks, semicolons, quotes.

If you are using PHP, the urlencode() function will automatically replace all invalid characters with their URL-encoded equivalent.

Is there a way for the visitors of my website to save the images displayed by Slimbox?

When you right-click on an image displayed in Slimbox, there is no option to save it because it's actually a <div> tag, not an <img> tag.

However if Slimbox is opened by clicking on an image link, your visitors can right-click on that link and choose "save target as..." to save the image.

If it's not enough for you and you want the visitors to be able to save the image from inside Slimbox, you can modify the "autoload code block" so that a link to the image is added automatically after the image caption. This is achieved by defining a linkMapper function (see the jQuery API or MooTools API documentation for more information). The autoload code block is located by default in slimbox.js but may be moved inside the HTML page if you want. Here's the new code:

jQuery version

// AUTOLOAD CODE BLOCK (MAY BE CHANGED OR REMOVED)
jQuery(function($) {
        $("a[rel^='lightbox']").slimbox({/* Put custom options here */}, function(el) {
                return [el.href, el.title + '<br /><a href="' + el.href + '">Download this image</a>'];
        }, function(el) {
                return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
        });
});

mootools version

// AUTOLOAD CODE BLOCK (MAY BE CHANGED OR REMOVED)
Slimbox.scanPage = function() {
        $$($$("a").filter(function(el) {
                return el.rel && el.rel.test(/^lightbox/i);
        })).slimbox({/* Put custom options here */}, function(el) {
                return [el.href, el.title + '<br /><a href="' + el.href + '">Download this image</a>'];
        }, function(el) {
                return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
        });
};

window.addEvent("domready", Slimbox.scanPage); 

I'm using sIFR and the sIFR text appears over Slimbox instead of being hidden. How can I fix that?

When calling sIFR.replaceElement(), you must set the "sWmode" parameter to "transparent". Please read the sIFR documentation for more information about how to do this.

Is it possible to open Slimbox in the parent frame when clicking on a link inside an iframe?

(i)frames should be avoided as often as possible. It's generally a bad idea to use them: they are deprecated by the W3C, they make things more complex and slow down page loading.

Note that you can mimic the appearance of an iFrame with the scrollbars using a div block having the CSS property "overflow: auto;" and a fixed width and height. Also, you can change its content using ajax calls.

However, if you really, really want iFrames, there are two ways to do this by modifying the "autoload code block" of the parent frame. By default, this code is located in slimbox.js but you can move it inside the HTML page if you want to. Each way has its own drawbacks and will not work as well as if you were not using iframes.

In both cases, you need to setup the full slimbox in the parent frame (jQuery/mootools + slimbox + css) and you only need to include jQuery/mootools in the child frame (no slimbox or css). If you don't add jQuery/mootools in the child frame, an error will occur when clicking on a slimbox-enabled link.

Solution 1

jQuery version

// AUTOLOAD CODE BLOCK (MAY BE CHANGED OR REMOVED)
jQuery(function($) {
        function scanFrame() {
                $("a[rel^='lightbox']", this.document).slimbox({/* Put custom options here */}, null, function(el) {
                        return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
                });
        }
        scanFrame.apply(window);
        $.each(window.frames, function() {
                this.onload = scanFrame;
                scanFrame.apply(this);
        });
});

mootools version

// AUTOLOAD CODE BLOCK (MAY BE CHANGED OR REMOVED)
Slimbox.scanPage = function() {
        function scanFrame() {
                $$($$(this.document.links).filter(function(el) {
                        return el.rel && el.rel.test(/^lightbox/i);
                })).slimbox({/* Put custom options here */}, null, function(el) {
                        return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
                });
        }
        scanFrame.apply(window);
        Array.forEach(window.frames, function(frame) {
                frame.onload = scanFrame;
                scanFrame.apply(frame);
        });
};

window.addEvent("domready", Slimbox.scanPage);

Drawbacks:

  • Slimbox-enabled links will be activated instantly (before the images of the page are fully loaded) in the parent frame only. In the child frames, slimbox links will only be activated after the full content (mainly images) is loaded.
  • Images of each frame will be grouped independently. This means that you can not display all images of the page plus all images of its child frames in one big group, and you can not create groups which include some images from a frame with other images from another frame.
  • The keyboard navigation will not work when you click on a slimbox-enabled link inside an iframe, because the iframe will capture the keyboard events instead of the main frame.

Solution 2

jQuery version

// AUTOLOAD CODE BLOCK (MAY BE CHANGED OR REMOVED)
jQuery(window).load(function() {
        var $ = jQuery, links = [];
        $.each($.merge([window], window.frames), function() {
                $.merge(links, $("a[rel^='lightbox']", this.document));
        });
        $(links).slimbox({/* Put custom options here */}, null, function(el) {
                return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
        });
});

mootools version

// AUTOLOAD CODE BLOCK (MAY BE CHANGED OR REMOVED)
Slimbox.scanPage = function() {
        var links = [];
        [window].extend(window.frames).forEach(function(frame) {
                links.extend(frame.document.links);
        });
        $$($$(links).filter(function(el) {
                return el.rel && el.rel.test(/^lightbox/i);
        })).slimbox({/* Put custom options here */}, null, function(el) {
                return (this == el) || ((this.rel.length > 8) && (this.rel == el.rel));
        });
};

window.addEvent("load", Slimbox.scanPage);

Drawbacks:

  • You will need to wait for the full page content to load (including the content of all its child frames) before all slimbox-enabled links are activated, which is the same limitation the original Lightbox has. But this time you can create image groups spanning accross multiple frames.
  • The keyboard navigation will not work when you click on a slimbox-enabled link inside an iframe, because the iframe will capture the keyboard events instead of the main frame.

Which minification tool are you using for the main Slimbox code?

The best one: YUI Compressor by Julien Lecomte. The code was also written in a way that allows it to be efficiently minified with this tool.