rlightbox – a jQuery UI mediabox

Table of Content

  1. Announcement
  2. News
  3. About
  4. Features
  5. Compatibility
  6. Getting Started
  7. Configuration Options
  8. Examples
  9. Themes
  10. How To…
  11. Changelog

Announcement

rlightbox development is discontinued at the moment. Maybe If I have more time and feel like it I will resume the work on the project. Anyway I encourage you to share it, fork it and whaterver you feel like. But please – respect the licence.

News

About

rlightbox is a jQuery UI mediabox that can display many types of content such as images, YouTube and Vimeo videos. It has many unique features like Panorama and Live Re-size. Like other jQuery UI widgets, it is ThemeRoller ready.

Features

Sets

Set is a group of images, Youtube, Vimeo, or Flash swf videos, or a mix of them all. There may be many sets on a page and elements belonging to a set does not have to be put one after another in a container.

YouTube support

rlightbox supports playing YouTube videos. To add a YouTube video, use standard YouTube URL scheme like http://www.youtube.com/watch?v=PLtGMqvazzo. Short YouTube URLs are not supported. Additional parameters are not taken into account.

Vimeo support

rlightbox supports playing Vimeo videos. To add a video use either URL like this: http://vimeo.com/13763341 or this: http://vimeo.com/groups/polska/videos/3116167. Additional parameters are not taken into account.

Flash swf video support

rlightbox also supports playing standard swf videos.

Panorama

Panorama is a way to display part of a full-sized image on the screen. Since often an image is larger than the screen, it has to be scaled down. Panorama allows you to to see it in its native resolutions by panning, i.e. drag & drop.

Panorama mode is available when the icon with four arrows pops up at the top left corner of the widget. To turn it on, you can either click on the icon or use keyboard ([Z] key is default).

Live Re-size

rlightbox is able to adapt to browser size, and it is great for so-called responsive design. To see it in action, open the following image and re-size the browser window a few times.

ThemeRoller ready!

rlightbox is compatible with ThemeRoller!

Keyboard Navigation

Nearly no need to use your mouse! You can even customize keyboard keys to better suit you!

Nice error handling

When an error occurs, the user-friendly Error Screen appears to help you decide what to do! You can change/translate the message and the labels on the buttons.

Compatibility

rlightbox was tested and has been tested in many browsers. If you come across a bug, please report it in the bug tracker. Some browsers like Internet Explorer 6 are too old and will not be supported. Because of some browsers release cycle like that of Chrome and Firefox until recently, it is very hard to keep track of rlightbox behaviour in these browsers. Thus the widget was tested just in Chrome/Chromium and Firefox 4 and 5. Also please note, it is not so easy to estimate the number of browsers to test in especially when it comes to minor releases or a bug fix releases. The more the better is not the answer. If the browser you want to use rlightbox in, is for some reason important to you, and the widget doesn't work in it, you can fill in a bug report in the bug tracker.

rlightbox was tested in the following browsers:

Getting Started

To get started, add the following JavaScript scripts. rlightbox is built on jQuery 1.6. Since rlightbox is a jQuery UI widget, some additional dependencies are required.

In examples below, replace path with the path to the folder where rlightbox is kept:

<script type="text/javascript" src="path/widget/lib/jquery-1.6.4.min.js"></script>
<script type="text/javascript" src="path/widget/lib/jquery.ui.core.min.js"></script>
<script type="text/javascript" src="path/widget/lib/jquery.ui.widget.min.js"></script>
<script type="text/javascript" src="path/widget/lib/jquery.ui.rlightbox.min.js"></script>

Then add the following style sheets in the head section:

<link type="text/css" rel="stylesheet" href="path/widget/css/ui-lightness/jquery-ui-1.8.16.custom.css" />
<link type="text/css" rel="stylesheet" href="path/widget/css/lightbox.min.css" />

rlightbox is compatible with ThemeRoller, and it uses jQuery UI themes. In above example I used ui-lightness theme, but you can use whatever you like.

To make it work, add anchors (a elements) with URLs to resources. For example:

<a href="flowers/tulip.jpg" title="a tulip">a tulip</a>
<a href="flowers/rose.jpg" title="a rose">a rose</a>
<a href="flowers/daisy.jpg"title="a daisy">a daisy</a>

To group above elements (make a set), add some common class to them, preceded by a prefix (default is lb) and the underscore character:

<a href="flowers/tulip.jpg" title="a tulip" class="lb_flowers">a tulip</a>
<a href="flowers/rose.jpg" title="a rose" class="lb_flowers">a rose</a>
<a href="flowers/daisy.jpg"title="a daisy" class="lb_flowers">a daisy</a>

And finally, to make rlightbox open when one of above elements is clicked, type:

<script type="text/javascript">
    jQuery(function($) {
	$( ".lb_flowers" ).rlightbox();
    });
</script>

Now rlightbox is active on these anchors, all these images are grouped and clicking on one of them allows you to go to the others (with a mouse or a keyboard).

Optionally you can modify the default options to better suit you. As an example we will change the delimiter that separates counters. Instead of / we will use of:

<script type="text/javascript">
    jQuery(function($) {
	$( ".lb_flowers" ).rlightbox({counterDelimiter: " of "});
    });
</script>

Now the 2nd image in the flower set is shown as 2 of 3.
To find out more about options, have a look at Configuration Options section below.

Configuration Options

Option Type Default value Description
againButtonLabel string "Try again" Label on the left button in the error screen.
animationSpeed string ["fast" | "slow" | "normal"] | integer "fast" How fast rlightbox is to appear, re-size, etc. Values are normal values used in jQuery. Integer should be given in milliseconds.
counterDelimiter string " / " Separates current content number in a set from the total number
errorMessage string "Oh dear! Something went wrong! If the problem still appears let the page’s admin know. Would you like to try again or reject the content?" The message which appears when there is an error while loading content or when a URL is broken. Sometimes an error may appear unexpectedly and it depends on a browser.
keys object {next: array, previous: array, close: array, panorama: array} {next: [78, 39], previous: [80, 37], close: [67, 27], panorama: [90, null]} Codes pointing to real keyboard keys. To determine which code is a key, use this page.
loop boolean false Make navigation in a set continuous.
overwriteTitle boolean false Overwrites original title taken from Vimeo or Youtube video when title attribute is provided.
rejectButtonLabel string "Reject this content" Label on the right button in the error screen.
setPrefix string "lb" What prefix followed by ‘_’ and a name use to group (make a set) content. To group 2 images, add a new class, e.g. ‘lb_flowers’ to both of them.
showMap boolean true Indicate whether to show or not mini map in Panorama mode.
videoHeight integer 385 Height of a video. It may denote maximum value.
videoWidth integer 640 Width of a video. It may denote maximum value.

Examples

Images Set

The photos below were taken by Arkadiusz Franczak who was in the heart of the Warsaw celebration. He took very valuable photos.

Warsaw, April 10, 2011: ‘combat lie with the truth’ authority vs. the people ‘Katyń: I remember’ take Tusk to court thousands of lights

YouTube set

Animated history of Poland The battle of Warsaw Sabaton: 40 to 1 Sabaton: (Warsaw) Uprising The City of Ruins

Vimeo set

The Polish History Grunwald 1410 The Ark The Cathedral The Fallen Art

Flash video

flash demo #2

Mixed set

Animated history of Poland The Kinematograph ‘1940-2010 genocide’ The Fallen Art flash demo

Other

The error screen Overwritten title

Themes

theme thumbLightness theme thumbBlitzer theme thumbSmoothness theme thumbStart theme thumbSunny

rlightbox is compatible with ThemeRoller, so you can choose many themes to fit your needs. As an example to see what rlightbox can look like, select one of above themes and open an example.

How to…

Control the Lightbox

open the lightbox

To open rlightbox, just click on an anchor rlightbox was initiated on.

close the lightbox

There are three ways to close the lightbox. You can either click the close icon (at the bottom bar), or click the overlay (it’s the background behind the widget), or use keyboard (default are [C] and [Esc] keys).

load next/prev element

In order to load next or previous element you can either use mouse (in case of images), keyboard, or small buttons in the bottom bar. The default keyboard keys to load next element are [→] and [N] key. To load previous one use [←] or [P] key.

zoom images

To zoom in/out an image (enable or disable Panorama mode) use either icon with four arrows (when it appears) or press [Z] key.

Set Size of Content

Images

There is no need to set size for an image. rlightbox uses its native size.

YouTube, Vimeo

Use videoHeight and videoWidth options to set size of this kind of content.

Flash swf video

If you do not want swf video to use videoHeight and videoWidth you can overwrite them adding parameters at the end of the URL:

<a href="http://www.adobe.com/products/flashplayer/include/marquee/design.swf?width=790&height=290" title="flash video">Flash video</a>

Only integers are accepted – no width=42px please!

Changelog

1.1 → 1.1.1

1.1.1 is a quick point release that fixes issue #5. Only Firefox has been affected.

1.0.1 → 1.1

Features

Enhanced layout

Now bottom bar sports buttons for easy navigation for flash videos. In images, instead of cursors as a navigation cue, new small arrows have been added.

Loop in sets

When set to true, navigation in a set doesn’t finish on first and last element.

Bug Fixes

  • Panorama works correctly in Firefox 3.0, 3.5 and 3.6
  • Fixes regression in Panorama in IE7 & 8.