Nav & Search

Lumebox

The Lumebox is an Open-Source (GPL) Lightbox clone written as a JavaScript jQuery plugin (weighing in at around 11kB minified) with a few added features. One of the main features is that it adapts to devices with mobile optimizations, another is that it can parse RSS feeds just as easily as displaying images. The plugin searches the post or page for links leading to images (and RSS-feeds) and opens them in a popup instead of following them.

There are a couple of major new features in version 2.0, the first is that it uses the Google Ajax Feed API to pull RSS-feeds (no need for local proxies for feeds on other domains), the second is that the next image in queue to be displayed is now preloaded. Lots of small improvements are also made, particularly in scaling, positioning and transforming the images.

By default the mobile optimizations make the lightbox work more like the native gallery applications. The entire content is hidden instead of positioning the lightbox in an overlay to get around scrolling and scaling problems, gestures with feedback is also used instead of clicking the image.

The plugin was started as a project in the Research and Development initiative within Sogeti which lets its consultants work with a variety of projects when they are in between customer objects. The Lumebox project was started on my initiative to gain more experience in creating Open Source tools and utilities.

The Lumebox plugin is released under the GNU GPL and can be downloaded at the bottom of this page and forked on GitHub.

Usage

Prerequisites

The Lumebox was written using jQuery 1.4.3 so I recommend it is used in combination with this or a later version but it might very well work with previous versions as well, I just haven’t tested it. To show external RSS-feeds a Google API key is needed.

Installation

  1. Load the lumebox.css or copy the classes to another file that’ll be loaded
  2. Load the Lumebox Javascript file somewhere on the page after jQuery has been loaded
  3. Copy the image files in style/ somewhere and change the lumebox init-object if that directory is somewhere else than “style/”
  4. Optional, get a Google API key from http://code.google.com/apis/ajaxfeeds/signup.html

Usage

Place the following somewhere on your page after the jQuery import to load the plugin

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

The plugin will automatically load and traverse the page if the file is loaded. It uses a set of sensible defaults for its options, to change these just initialize a variable called lumeboxOptions containing a map of the options and their values.

<script type="text/javascript">
    var lumeboxOptions = {showAsList: false, graphicsDir: "/another_style_dir", feedApiKey: "ENTER_API_KEY_HERE"};
</script>

Add rel=”lightbox” to any links that you want to be parsed by the Lumebox and the title with the caption. It’ll find the target of the link and use it for source to the image in the popup and the content of the title attribute as caption. Images and feeds can be grouped by naming them rel=”lightbox[groupName]“. To avoid potential confusion between images and feeds all RSS-feeds have to be grouped in a name starting with “rss”, for example rel=”lightbox[rssGroup1]“.

The title of a link will be used as a caption unless the link has the noCaptionClass class-attribute (“tn” by default).

Options

Options are passed as an object when initializing the Lumebox (i.e $.lumebox({showAsList: true});). All have default values to the only ones that has to be specified are the ones which need to change, defaults are shown in the parentheses.

  • showAsList (false): If true all items in a group will be shown in a list in the Lumebox.
  • rss (empty array): An array of urls to RSS-feeds.
  • proxy (empty string): path/url to local proxy to use when fetching external feeds.
  • duration (“fast”): Keyword (slow, normal, fast) or duration in milliseconds used for animating transitions.
  • rssWidth (680): The width of the popup used for RSS-posts.
  • fullscreen (false): Boolean that optimizes the lumebox for full screen viewing.
  • opacity (0.7): The opacity of the overlay.
  • loop (true): Whether to start over at item number one after pressing next at the last item.
  • scrollToTop (false): Force scroll to the top of the popup everytime it’s opened.
  • autoNext (false): Loads the next item after autoNext milliseconds if the Lumebox is open.
  • parentElementId (false): The id of an element to use as a parent for the popup, it will be inserted just before this element is closed. If no element id is passed the Lumebox is inserted right before the closing body-tag.
  • useParentOffset (true): Whether to use the offset of the closest positioned parent when positioning the popup i the z-axis
  • useGestures (false): Whether to use gestures for post navigation in addition to keys. Click and drag left loads the previous post, click and right the next
  • graphicsDir (“style/”): Relative path to the directory where the icons are stored.
  • feedApiKey (false): If provided, this key is used to load the Google Ajax Feed  API (http://code.google.com/apis/ajaxfeeds/) which is used to fetch external  RSS-feeds.
  • platformMode (“auto”): Whether to use gestures (“mobile”), clicks (“normal”)  or choose automatically depending on the platform (“auto”). For the moment this option doesn’t really have an effect.
  • noCaptionClass (“tn”): If the link has this class the title-attribute won’t be used as a caption.

Demo

Click any of the following links or images to open them in a Lumebox.

Elektra Micro Casa a LevaMolly at SkansenLloyds Building in London

Changelog

2.1

  • Added new option to disable the caption added through the title-attribute.
  • The mobile lightbox now completely hides everything else in the DOM to provide  a more consistent gallery-like experience, also changed the look in desktop mode.

2.0

  • Added support for pulling RSS-feeds using Google Ajax Feed API and for using  gestures on mobile platforms (although not used for consistency). The next image in line is also preloaded and  images are now scaled to fit the screen if they are too big. There’s a lot of  small changes as well.
  • Removed some options (proxy and fullscreen) and added some other (feedApiKey  and platformMode) and changed the name for popupMaxWidth (now rssWidth).

1.06

  • Removed the leading “>” in RSS-posts that wordpress inserts in CDATA encoded RSS-feeds due  to placing it in a tag.

1.05

  • Single images are now fetched and then shown using a callback to fix the positioning bug (top left corner is centered due to width of the popup is calculated to zero when it’s shown before the image has been loaded)

1.04

  • General stability enhancements
  • Updated the styling of the lumebox, using some CSS3
  • Updated the sample
  • Added click areas for previous and next navigation
  • The close button was added (again…)
  • Removed info and help
  • Don’t have any good plan on how to display index information, so that’s been removed for now
  • Changed some default values for the options

1.03

  • Fixed the sample in the release

1.02

  • The close button was removed. Everyone clicks outside, right?
  • Better resizing, the size and position are now animated simultaneously
  • Fixed the bug that resized the popup with the content visible when using the next() or previous() functions
  • Added basic gesture control, click and drag left to go to previous, click and go right to load the next post

1.01

  • Clicks on links are now intercepted instead of changed to onCLicks
  • The popup uses the browser scroll bar instead of adding a new one
  • New option, useParentOffset, will use the offset of the parent element to offset the popup
  • Some browser compatibility issues concerning size and position of the popup were fixed

1.0

  • The first official release of Lumebox

Known Issues

  • None for the moment

Download

Head over to GitHub to download a zip containing the project. There are two versions in the zip, the source has some comments and is suitable if you want to extend it yourself, the min version is minified and ready for use.