INTRODUCTION TO JQUERY – JQUERY LIGHTBOX

Displaying a gallery of photos is such a common task that you will find dozens of different ways to show off your images. One very popular technique dims the web page and displays the larger version of the thumbnail as if it were floating on top of the browser window.

document.doc Version 1Page 1 of 12

The most well known version of this method is a JavaScript program called Lightbox (www.huddletogether.com/projects/lightbox2). There have been many imitations of the original, as well as one script created to work with jQuery. jQuery lightBox (http://leandrovieira.com/projects/jquery/lightbox) is a jQuery plug-in that with just a single line of code creates a spectacular way to present images as part of a portfolio, gallery or slideshow.

The jQuery lightBox plugin, created by Leandro Vieira Pinho, is a very easy way to create an attractive, single-page photo gallery. You can navigate through a series of photos by clicking a Next or Previous button that appears when you mouse over the image. In addition, the left and right arrow keys, as well as the P and N keys, let you navigate through the gallery of large images.

The Basics

jQuery lightBox is very easy to use - you just need to set up your web page with links to the images you wish to display, attach .css and .js files to the page and add one line of code to call the light box into action.

Set up your gallery page.

There is not really much you need to do - just add links to the larger images you wish to display on the page. These could be links added to thumbnail images – so when the thumbnail is clicked the larger image appears. The important thing to remember is that the link points to a graphic file - a .png, .jpeg, or .gif file – not to a web page.

In addition, you need a way to identify just the gallery links (as opposed to other links on the page). One way is to wrap the links in a <div> tag with a specific ID - gallery, for example. Then you can target just those links with a selector like '#gallery a'. Another approach is to add specific class names to each gallery link: for example, <a href="images/terrier.jpg" class="gallery">. Then you can target those links with a selector like 'a.gallery'. This last method is handy if the links are scattered around the page and are not contained in a single <div>.

Note: To add a caption to a photo, just supply a title attribute to the <a> tag that links to the large image.For example:<a href="images/potato.jpg" title="A handsome terrier">

Download the jQuery lightBox files and put them into your site.

document.doc Version 1Page 2 of 12

You can find the files at http://leandrovieira.com/projects/jquery/lightbox.

There are a handful of files you will need - a JavaScript file, a CSS file and several graphics files.

The JavaScript file is named something like jquery.lightbox-0.5.js where 0.5 represents a version number. Your best choice is the minified version - jquery.lightbox-0.5.min.js - which is a compressed version of the file. You can place this file anywhere in your site though a common approach is to put external JavaScript files in a folder (named something like js or libs) in the root folder of your site.

The CSS file, jquery.lightbox-0.5.css, can also go anywhere in your site. You might want to put this in a folder where you keep all of your external CSS files, or if you are just adding the light box effect to a single page on your site you can put the file in the same folder as the light box enhanced web page.

jQuery lightBox depends on five graphic files: lightbox-blank.gif, lightboxbtn-close.gif, lightbox-btn-next.gif, lightbox-btn-prev.gif and lightbox-icoloading.gif. Some of these images are buttons for moving between images and closing the large image overlay. All five files should be located in a folder named images, which is located in the same folder as your lightBox-enhanced web page. In other words, the jQuery lightBox plug-in expects the images to be in a specific location

Attach the external style sheet to your page.

Query lightBox uses some fancy CSS to achieve the dark, transparent overlay effect and display the pop-up image. Attach this file as you would any CSS file.

For example:

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

Most JavaScript programmers place any style sheet information before their JavaScript programming - some JavaScript programs depend on having the style sheet information available first, in order for the program to work correctly.

That is especially true of many jQuery plug-ins - so get in the habit of placing all style sheets before JavaScript files and programs.

Attach the JavaScript files.

document.doc Version 1Page 3 of 12

jQuery lightBox gets most of its power from the jQuery library, so you must first attach the jQuery file to the page. Also, the lightBox JavaScript file (like any JavaScript that uses jQuery) must be attached after the jQuery file.

For example:

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

Add a <script> tag, the jQuery ready( ) function and call lightBox.Getting lightBox to work requires just a single line of JavaScript. You need to put that code inside a jQuery ready( ) function, which is run when the browser has processed the HTML and is ready to manipulate the DOM.

For example:

<script type = "text/javascript">$(document).ready(function( ){

$('#gallery a').lightBox( );});

</script>

The lightBox( ) function must be applied to just the links that point to the image files you wish to display. You use a jQuery selector - $('#gallery a') - for example, to tell lightBox which links to use. In this example, any <a> tag inside another tag with an ID of gallery becomes part of the lightBox effect.

lightBox works really well with a gallery of thumbnails to create a slideshow effect where a visitor can click a Next button to step through each photo in the gallery. However, you can also use it to display a single image on a page. Alternatively, you can apply lightBox to different images on a page so they are not part of the same gallery. In other words, each image will open independently, so the images are not connected with Next or Previous buttons. You just need to supply a jQuery selector to select a single image - for example, apply an ID to a link and then call lightBox on just that one link:

$('#soloImage').lightBox( );

Now, when you click each of the gallery links, a transparent background appears over the page and a large version of the image appears in the middle of the window.

Customizing lightBox

document.doc Version 1Page 4 of 12

While the general look of the lightBox effect is really impressive you may want to adjust its appearance a little. You can customize a variety of different parts of the light-Box look including the buttons that let you close the lightBox window or navigate to the previous and next images. You can also change the colour and opacity of the transparent background that overlays the page or change the background colour of the caption box and picture frame.

lightBox options

The lightBox plug-in lets you supply custom options that affect the appearance of the light box effect. Basically, you pass a JavaScript object literal to the lightBox function containing the names of the options you wish to set and the values you wish to set them to. For example, to change the background colour and opacity of the background placed over the page.

You can create a variable containing your new settings and pass that to lightBox like this:

var lbOptions = {overlayBgColor: '#FF0033',overlayOpacity: .5

}$('#gallery a').lightBox(lbOptions);

In this example, the colour of the overlay is set to a bright red #FF0033 and its opacity is set to 50% (.5).

jQuery lightBox accepts a lot of different options (visit http://leandrovieira.com/projects/jquery/lightbox for the complete list), but here are the most useful:

overlayBgColor - The background colour that covers the page while lightBox displays an image. This option accepts a hex colour value like #FF0033 which must be inside quotes:

overlayBgColor: '#FF0033'.

overlayOpacity - The opacity of the overlay. This option sets how much of the page below the overlay should show through. You specify a number from 0 to 1. .5, for example, is 50% opacity. If you do not want to be able to see through the overlay - for example, you want to completely black out the rest of the web page while the image appears - set this option to 1.

containerResizeSpeed - When you move from image to image in a lightBox-powered page the box containing the image is animated as it changes size from the dimensions of the current image to match the dimensions of the next image. You can control the speed of this transition by setting this option. The default is 400, meaning 400 milliseconds, or slightly less than half of a second.

document.doc Version 1Page 5 of 12

txtImag - When displaying multiple images, a message appears below the current image announcing which image you are viewing and the total number of images. For example, “Image 1 of 20”. You can change the default word Image to something else (like Photo) by setting this option.

txtOf - Same as txtImage, but replaces the default of with the word of your choice. Changing this setting comes in handy if the page uses a language other than English or you want the message to read something universal - like “Photo 1/6”.

imageBtnClose - The path to the image used for the Close button on the pop-up image window. Normally, this option points to images/lightbox-btn-close.gif but you can change that setting to point to a different location or to a different file name or type (for example, a PNG file).

imageBtnPrev - The path to the image used for the Previous button on the popup image window: normally images/lightbox-btn-prev.gif.

imageBtnNext - The path to the image used for the Close button on the pop-up image window - normally images/lightbox-btn-next.gif.

imageLoading - The path to the image used for the Close button on the pop-up image window. Normally this points to images/lightbox-ico-loading.gif but you can change the setting to point to a different location or to a different file name or type (for example, a PNG file).

imageBlank - Internet Explorer 6 needs a special image that allows it to respond correctly to the mouse hovering over the image to display Next and Previous buttons. Normally, this option points to images/lightbox-blank.gif. There is really no reason to change this setting unless you want to move the image to a different folder - thus changing the path.

Here is an example of how you might set these options Say you want to change the caption text to read “Photo 1/6” and the speed at which the images change size while navigating through the gallery and you want to use PNG files for the Close, Previous and Next buttons.

Just set up an object literal with those values and pass it to the lightBox function like this:

var lbOptions = {txtImage: 'Photo',txtOf: '/',containerResizeSpeed: 1000,imageBtnClose: 'images/close.png',

document.doc Version 1Page 6 of 12

imageBtnPrev: 'images/previous.png',imageBtnNext: 'images/next.png'

}$('#gallery a').lightBox(lbOptions);

In this example, the lightBox options are stored in a variable - lbOptions - in this case and then passed to the lightBox( ) function. You can also simply pass the object literal to the function (and skip the creating a variable step). For example, the above code could also be written like this:

$('#gallery a').lightBox({txtImage: 'Photo',txtOf: '/',containerResizeSpeed: 1000,imageBtnClose: 'images/close.png',imageBtnPrev: 'images/previous.png',imageBtnNext: 'images/next.png'

});

Both examples work exactly the same way, so use the method that is easiest for you.

lightBox images

As previously mentioned, you can use any images you would like to replace the ones supplied with the lightBox plug-in. You only need to set the proper options (like imageBtnClose or imageBtnPrev) to point to your new image files.

Another method to use your own images is to simply name your images identically to the ones supplied with the plug-in and put your new images into the images folder. That way you do not need to change any of the plug-in’s default settings.

However, the images you use should be close in size to the ones supplied with the plug-in. The Close, Previous and Next buttons are all 63 pixels wide by 32 pixels tall while the loading image is 32 pixels square.

Note: You can create your own “This image is now loading” icon at the Web 2.0 Ajax icon generator: www.ajaxload.info. At this site, you can choose from over 20 different animated designs and even choose background and foreground colours for the icon.

Note: You do not need to use lightBox’s option settings to customize the look of your lightBox. Simply replacing the supplied graphics and altering the CSS file lets you tweak the design to better match your site.

document.doc Version 1Page 7 of 12

lightBox CSS

A few of lightBox’s visual elements can only be controlled via CSS. For example, to change the font used for captions, you have to edit the #lightbox-image-detailscaption style in the CSS file supplied with lightBox.

In addition, to change the: Background colour of the frame surrounding the pop-up image, edit the background-

color property of the #lightbox-container-image-box style. Background colour of the caption box, edit the #lightbox-container-image-databox

style. Text formatting for the caption, edit the #lightbox-image-details-caption style. Text formatting for the photo numbers, edit the #lightbox-image-

detailscurrentNumber style.

Tutorial: lightBox Photo Gallery

document.doc Version 1Page 8 of 12

Although jQuery lightBox is really easy to use, it is always helpful to have a step-by-step tutorial showing you how it is done. You will now take a page with a basic set of thumbnail images and turn it into a lightBox slide show.

1. Locate, download and unzip the folder named jQuery LightBox Site Files found on BREO to your My Sites folder and rename the folder as jQuery LightBox.

2. Create a new Dreamweaver site pointing to this folder.

The folder jQuery LightBox contains all the files that you need – the jQuery library file, the lightBox JavaScipt and CSS files and all the images required.

3. Open the file lightbox\lightbox.html.

This file contains a simple group of thumbnail images. Each image is linked to a larger version of the photo and all of the thumbnails are contained within a <div> tag with an ID of gallery.

document.doc Version 1Page 9 of 12

The first step is to attach the CSS file used by lightBox.

4. In the <head> of the document, locate the empty line below the <link> tag which attaches the gallery.css style sheet file. On that line, type:

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

The lightbox.css file contains all of the styles used to format the background that lies over the web page, the pop-up image and the photo caption text.

Next, you need to attach the plug-in’s JavaScript file.

5. On the blank line immediately after the <script> tag that attaches the jquery.js file to this page, type:

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

Remember that you need to load any jQuery plug-in files after the jquery.js file itself.

This page already has another <script> tag complete with the jQuery ready( ) function and the preloading/rollover code. You just need to add the lightBox function and you set to go.

6. Click in blank line directly below $(document).ready(function( ) and type:

$('#gallery a').lightBox( );

All of the links that point to larger images are contained inside a <div> tag with the ID gallery. Thus, $('#gallery a') selects those and the .lightBox( ) function applies the lightBox effect to the page.

7. Save the page and preview it in a web browser. Click one of the thumbnail images. Now you can see why plug-ins are so useful - you do not really have to do any programming to get some fantastic effects!

We are missing captions for each photo. To add a caption, you do not need any JavaScript - just an HTML title attribute added to an <a> tag.

document.doc Version 1Page 10 of 12

8. In the <body> of the page, locate <a href="images/large/blue.jpg"> and add title="Blue still life" to the tag, so it looks like this:

<a href = "images/large/blue.jpg" title = "Blue still life">

9. Save the file and preview it in a web browser. Click the first thumbnail on the left and the caption appears. Add title attributes to the other <a> tags in this <div>.

Now, you will adjust some of lightBox’s default settings to customize its look.

Now adding an object literal between the lightBox( ) function’s parentheses.

The new code is shown below:

$('#gallery a').lightBox({txtImage: 'Photo',overlayOpacity: .5,overlayBgColor: '#003376'

});

This code passes an object literal to the lightBox( ) function. An object literal is made up of a property name followed by a colon and then a value. Thus, txtImage is the name of an option for lightBox and you are setting its value to Photo. This particular option changes the default text that appears in a pop-up box “Image 1 of 6” to read “Photo 1 of 6”.

The next two options change the opacity to 50% and assign a different background colour for the overlay on the page.

10. Save the page and preview it in a web browser.

document.doc Version 1Page 11 of 12

document.doc Version 1Page 12 of 12