boxplus for jQuery: a lightweight pop-up window engine

Description

boxplus is a lightweight pop-up window implementation (commonly known as lightbox) licensed under the GPL and written using the jQuery library. boxplus ships with sigplus, which is an all-inclusive image gallery for Joomla.

Features

  • Supports all modern browsers, including Firefox (≥ 2), Internet Explorer (≥ 7), Chrome and Opera.
  • Supports image captions. Each image can be assigned a title and a caption, which can make use of HTML tags.
  • Pop-up window centers vertically and horizontally. Vertical centering takes into account any caption text.
  • Various navigation controls. You can navigate to the next or previous image with the mouse or the keyboard, or use the thumbnail bar at the bottom to jump to any specific image.
  • Fit to browser window. Large images are automatically reduced to fit available browser window space. The pop-up window can be expanded with the enlarge control in the upper right corner to view the image in its original size.
  • Configurable layout. Panel containing captions and navigation icons can be aligned to bottom, right, top or left of image.
  • No dead time delay. The script launches as soon as the document structure is available, even if some images are still being downloaded.
  • Easily customizable appearance using valid CSS. All styling is done using cascading style sheet rules, which allows for simple theming.
  • Small network footprint. Even while boxplus has many extra features, its compressed size is comparable to Slimbox 2, which claims to be the smallest lightbox script available for the jQuery library (with a footprint of 4 KB).
  • Easy personalization. The boxplus demo page includes an interactive tool to customize boxplus appearance and behavior. Once you are satisfied with the result, you can use the code generator to produce the CSS and javascript code you need to make boxplus display the way you want.
  • 100% CSS and JavaScript. The implementation uses the jQuery base library and needs no additional jQuery plug-ins to work.

 

Setup

To use boxplus, it is imperative that boxplus cascading style sheets (CSS) and scripts be linked to your HTML document.

Style sheets

First, include the boxplus main cascading style sheet. Insert the following line in the head section of the HTML document:

<link rel="stylesheet" type="text/css" href="/levente/css/boxplus.css" />

Unfortunately, the standard CSS suitable for most modern browsers, including Firefox, Chrome and Opera, does not work as expected with Internet Explorer. To remedy the issue, link the boxplus CSS dedicated to Internet Explorer using the conditional comment mechanism. Conditional comments are only recognized by Internet Explorer and ignored by other browsers:

<!--[if IE]><link rel="stylesheet" href="/levente/css/boxplus.ie.css" type="text/css" /><![endif]-->

boxplus comes in several themes. To use a theme different from the default transparent one, include the appropriate style sheet for the theme. We demonstrate this by linking the black theme:

<link rel="stylesheet" type="text/css" href="/levente/css/boxplus.black.css" />

Scripts

jQuery version 1.4.2 or later is required for boxplus to work. Use the following lines in the head section of the HTML document to include jQuery using Google JavaScript API:

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">google.load("jquery", "1.4");</script>

or, alternatively

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>

Once jQuery in included, link the boxplus script to your document:

<script type="text/javascript" src="/levente/js/boxplus.js"></script>

Finally, include the following script in your HTML document to instruct boxplus to hook to your image gallery:

<script type="text/javascript">
jQuery(function ($) {
	$('#gallery').boxplusGallery();
});
</script>

This will subscribe to the event that is fired when the HTML DOM tree is finished loading and will hook boxplus to the image collection with the unique identifier gallery. See the section Usage on how to organize images into a gallery.

Alternatively, you may have boxplus subscribe to the click event of only certain links (anchor elements). The following example illustrates how to trigger a pop-up window when an anchor that points to an image with extension jpg, jpeg, png or gif is clicked:

jQuery(document).ready(function($) {
    $("a[href$=jpg], a[href$=jpeg], a[href$=png], a[href$=gif]").boxplus();
});

When this syntax is used, the images are treated as if they were independent from one another; boxplus presents no navigation controls inside the pop-up window.

Usage

As illustrated with examples in the previous section, boxplus can operate either on image galleries or collection of anchor elements.

Usage with image galleries

boxplus image galleries are assumed to be ordered or unordered lists (ol or ul) with as many list items (li) as images in a gallery. Clicking the first anchor element (a) in the list item brings up the pop-up window. If the link element wraps an image element (img), the image will be used as a thumbnail for easier navigation inside the pop-up window. The title attribute of the anchor element (if given) will be displayed as a description text below the image in the pop-up window, while the alt attribute of the wrapped image will be shown as an image title.

Example

<ul>
<li><a href="/levente/image1.gif">Image without thumbnail</a></li>
<li><a href="/levente/image2.jpg"><img alt="Image with thumbnail" src="/levente/thumbnail2.jpg" /></a></li>
<li><a href="/levente/image3.png" title="Image with title and thumbnail"><img alt="" src="/levente/thumbnail3.png"></a></li>
</ul>

You find additional examples on the boxplus demo page.

Usage with individual anchors

When called on individual anchors or a collection of anchors, boxplus assumes that each anchor points to an image (i.e. a resource that can be assigned to the src attribute of an img element), points to DOM element on the current page (which has a unique HTML id), or is a relative or absolute URL to an external resource. When you click the anchor whose click event boxplus has subscribed to, the pointed image, document fragment, or document will be shown in the pop-up window.

Solving common problems

Usually, boxplus is not used in isolation but as part of a site. Page template CSS style sheet files are a common cause of layout problems with boxplus. Some agressive templates may apply unusual properties to certain elements globally. As HTML elements boxplus uses are inserted below the body element in the HTML DOM tree, boxplus is affected by rules with global scope. For example, if a template sets z-index:1 with a global element selector img, it will make all absolutely positioned images cover other absolutely positioned elements, hiding boxplus overlay navigation controls, the enlarge/shrink control as well as thumbnail images inside the pop-up window. To remedy the issue, any such global declarations should be reset before boxplus styles would be applied. In order to do so, paste the contents of reset.css at the end of your template CSS file. reset.css will clear any unusual style applications but will only affect boxplus due to the local selector scoping #boxplus.

Comparison

The following table compares boxplus to other lightweight pop-up window engines.

Comparison of boxplus to other engines
  boxplus Slimbox Slimbox2 prettyPhoto prettyPhoto FancyBox
Version 1.0 1.58 2.04 2.5.6 3.0 1.3.1
JavaScript library jQuery mootools jQuery jQuery jQuery jQuery
Compressed script size [bytes] 7887 4681 4123 16851 21240 14731
Displays images yes yes yes yes yes yes
Fit-to-window for large images yes no no yes yes yes
Thumbs in pop-up window for fast navigation yes no no no yes no
Wide-screen arrangement [*] yes no no no no no
Panel for image background information yes no no no no no
HTML in image captions yes yes yes yes yes yes
Captions outside or overlaying image no no no no no yes
Displays custom HTML content yes no no yes yes yes
Styling in CSS only yes no no no no no
Multiple languages yes no no no no no
Multiple themes on a single page yes no no no yes yes
Browser compatibility Internet Explorer 7 and laterFirefoxChromeSafariOpera Internet Explorer 6 and laterFirefoxChromeSafariOpera Internet Explorer 6 and laterFirefoxChromeSafariOpera Internet Explorer 6 and laterFirefoxChromeSafari Internet Explorer 6 and laterFirefoxChromeSafari Internet Explorer 6 and laterFirefoxChromeSafariOpera

Download

boxplus is bundled with sigplus version 1.3.0 or later. Download the latest version of the sigplus plug-in or the sigplus package from JoomlaCode; files that belong to the boxplus family of products are in the folder sigplus/engines/boxplus or engines/boxplus within the archive. The files have no external dependencies; they can be used stand-alone as discussed on this page.