The JQuery Lightbox Plugin is probably one of the most commonly used lightboxes on the Internet.

And for good reason. Its simple to use, both for the developer and the user, and it works in pretty much any browser you can think of.

However, it has one minor deficiency in comparison to other lightboxes: it doesn’t have a slide show feature.

I recently set up a site with this plugin, and while the customer was happy, they did want a slideshow. I contemplated installing a different lightbox, but there was pain involved in this too, so I set about trying to add slideshow functionality to the existing JQuery Plugin.

This post got me started, but it was only half the battle, as it didn’t include any functionality to stop and start the slideshow, which is what people would normally expect. So I made my own modifications to the plugin ,and here they are.

So, we’re editing the actual plugin Javascript file that we load in our HTML header. The logic behind the code may or may not be apparent to you, but basically, we are initiating and terminating a Javascript setTimetout function that calls functions use by the Lightbox. Off we go…

First off, add some settings:

$.fn.lightBox = function(settings) {
		// Settings to configure the jQuery lightBox plugin how you like
		settings = jQuery.extend({
			//SLIDESHOW
		        slideshow: true,
		        nextSlideDelay: 4000,
                        [....]

Next, include the Slideshow in the initiate function:

	function _initialize() {
		//SLIDESHOW
		if(settings.slideshow){
		  var tmFunc = function(){ _doSlideShow(); };
		  t = setTimeout(tmFunc, settings.nextSlideDelay);
		}
                [....]

Next, add a new function to the Lightbox, which creates the slidehow:

		function _doSlideShow(){
		     settings.activeImage++;
		     if(settings.activeImage >= settings.imageArray.length){
			  settings.activeImage = 0;
		     }
		     _set_image_to_view();
		     var tmFunc = function(){ _doSlideShow(); };
		     if($('#jquery-lightbox').length > 0){
			  t = setTimeout(tmFunc, settings.nextSlideDelay);
		     }
		};

The above will give you the guts of the slideshow, but now you need the Pause/Unpause functionality.

First, find the _set_interface function and add some HTML to create a Pause link.

Pause

This will appear in the white navigation section that unfurls below each image. You may want to update Lightbox CSS file too to make this nice and neat.

Now, add another new click event function to the _set_interface function. This controls the Pause/Unpause.

	$('#lightbox-secNav-btnPause').click(function() {
		if (timer_is_on > 0) {
			clearTimeout(t);
			$(this).html('Unpause');
			timer_is_on = 0;
		} else {
			var tmFunc = function(){ _doSlideShow(); };
			t = setTimeout(tmFunc, settings.nextSlideDelay);
			$(this).html('Pause');
			timer_is_on = 1;
		}
		return false;
	});

You also need to create 2 variables at the lightbox object level (ie outside the _set_interface function) to control the state of the slideshow, to say if it is paused or unpaused.

var t;
var timer_is_on=1;

Now, the last part. The Prev and Next click functions are still part of the Lightbox in Slideshow mode. It would be my expectation that if I had paused the slideshow, and then clicked Next, that the slideshow would revert back to unpaused mode. Therefore, I also need to add some extra functionality to the Prev and Next click events. This occurs in the _set_navigation function, which is reproduced in its entirety below:

function _set_navigation() {
	$('#lightbox-nav').show();

	// Instead to define this configuration in CSS file, we define here. And itŽs need to IE. Just.
	$('#lightbox-nav-btnPrev,#lightbox-nav-btnNext').css({ 'background' : 'transparent url(' + settings.imageBlank + ') no-repeat' });

	// Show the prev button, if not the first image in set
	if ( settings.activeImage != 0 ) {
		if ( settings.fixedNavigation ) {
			$('#lightbox-nav-btnPrev').css({ 'background' : 'url(' + settings.imageBtnPrev + ') left 15% no-repeat' })
				.unbind()
				.bind('click',function() {
                                //SLIDESHOW
				clearTimeout(t);
				var tmFunc = function(){ _doSlideShow(); };
				t = setTimeout(tmFunc, settings.nextSlideDelay);
				$('#lightbox-secNav-btnPause').html('Pause');
				timer_is_on = 1;
                                //
				settings.activeImage = settings.activeImage - 1;
				_set_image_to_view();
				return false;
			});
	} else {
		// Show the images button for Next buttons
		$('#lightbox-nav-btnPrev').unbind().hover(function() {
			$(this).css({ 'background' : 'url(' + settings.imageBtnPrev + ') left 15% no-repeat' });
			},function() {
				$(this).css({ 'background' : 'transparent url(' + settings.imageBlank + ') no-repeat' });
			}).show().bind('click',function() {
                                //SLIDESHOW
				clearTimeout(t);
				var tmFunc = function(){ _doSlideShow(); };
				t = setTimeout(tmFunc, settings.nextSlideDelay);
				$('#lightbox-secNav-btnPause').html('Pause');
				timer_is_on = 1;
                                //
				settings.activeImage = settings.activeImage - 1;
				_set_image_to_view();
				return false;
			});
		}
	}

	// Show the next button, if not the last image in set
	if ( settings.activeImage != ( settings.imageArray.length -1 ) ) {
		if ( settings.fixedNavigation ) {
			$('#lightbox-nav-btnNext').css({ 'background' : 'url(' + settings.imageBtnNext + ') right 15% no-repeat' }
				.unbind()
				.bind('click',function() {
                                        //SLIDESHOW
					clearTimeout(t);
					var tmFunc = function(){ _doSlideShow(); };
					t = setTimeout(tmFunc, settings.nextSlideDelay);
					$('#lightbox-secNav-btnPause').html('Pause');
					timer_is_on = 1;
                                        //
					settings.activeImage = settings.activeImage + 1;
					_set_image_to_view();
					return false;
				});
		} else {
			// Show the images button for Next buttons
			$('#lightbox-nav-btnNext').unbind().hover(function() {
				$(this).css({ 'background' : 'url(' + settings.imageBtnNext + ') right 15% no-repeat' });
			},function() {
				$(this).css({ 'background' : 'transparent url(' + settings.imageBlank + ') no-repeat' });
			}).show().bind('click',function() {
                                //SLIDESHOW
				clearTimeout(t);
				var tmFunc = function(){ _doSlideShow(); };
				t = setTimeout(tmFunc, settings.nextSlideDelay);
				$('#lightbox-secNav-btnPause').html('Pause');
				timer_is_on = 1;
                                //
				settings.activeImage = settings.activeImage + 1;
				_set_image_to_view();
				return false;
			});
		}
	}
	// Enable keyboard navigation
	_enable_keyboard_navigation();
}

You can download a copy of the converted file from here. You can view a demo on any post on gigape.com

Believe it or not, this is actually one of the trickiest things you can do with PHP.

There are a couple of reasons for this.

1. Facebook is pretty anal about security, and really, really, really wants only logged in users to update user accounts. This is the complete opposite of Twitter, who really, really, really want all sorts of apps and 3rds parties to able to update Twitter statuses.

2. The Facebook Documentation Glop: Facebook has moved through various iterations of its API over the last 5 years, but they’ve left all the documentation for the old APIs in place, so its pretty easy to get confused. This in turn has led to lots of people offering solutions on blogs etc, but quite often these refer to the old APIs, so finding any sort of a solution via a Search Engine is all but impossible.

Anyway, here’s the meat.

The key to this is to use the Facebook Graph API. This is a really unfortunate name for the API, as it suggests something to do with dynamic graphing. In fact, its a really simple API that allows you do all sorts of stuff with FB by sending HTTP POST requests, which is the method us developers love the most.

Step 1:

Add the Developer Application to your FB account

Step 2:

Create a new application, called anything you want. There’s a bundle of info you can add for your app, but the basic stuff you need is:

Profile->Tab URL

eg http://apps.facebook.com/garrethsstatus/

Canvas->Canvas Page URL

eg http://apps.facebook.com/garrethsstatus/

Canvas->Canvas Callback URL

(This can be anything, provided it is a valid URL eg http://www.nightbluefruit.com/; you must include trailing slash)

Connect->Connect URL

(This can be anything, provided it is a valid URL eg http://www.nightbluefruit.com/; you must include trailing slash)

Save and you are done with the application bit.

Step 3

We now need to tell Facebook that we want to allow this application do stuff with our account, and obtain an access token that we can use in our PHP code to send HTTP POST requests off to FB to update our FB account. This is where the Graph API comes in.

First off, give the application permission to update your account as described in the

“Authenticating Users in a Web Application” and “Requesting Extended Permissions” sections of this page:

http://developers.facebook.com/docs/authentication/

The extra scope permissions are: publish_stream,offline_access

(These will give you an access token that doesn’t expire, for a while at least anyway)

At the end of this process, you should have an access token, which you lift from a URL to which FB will redirect you. Be careful when copying and pasting, as the access token is very long, and you want to make sure you are only copying the access token and not other parts of the URL string.

When you have your access token, you can then plug it into a cURL request to update your status, as described here:

http://developers.facebook.com/docs/api#publishing

You’re going to have to use cURL for this, as the required HTTP method is POST.

Important Note: using cURL is this way is not to be confused with using cURL to login to Facebook and make updates. There are lots of scripts out on the Internet that will do this for you, but use of these scripts is in contravention of the FB T&Cs, so if you use them, Facebook could close your account.