My first jQuery plugin - An image gallery

Posted on Saturday, July 12th, 2008

This is my first jQuery plugin and to be honest I am quite proud of it. It’s nothing complicated - a simple image gallery/viewer. When calling the plugin you specify which images you want to use like this:

$('div.some-images img').gallery();

The script would take all images within "div.some-images" (or whatever you specified) and put them within the gallery.

You can see a DEMO of it here.

Other styles:

It’s fully unobtrusive, so you can still view the images when JS is disabled.

It can take three arguments: "speed" (generic speed for everything), "slideshow speed" (amount of time each image is shown during slideshow) and it can also take a third argument which I will explain later (Look below - “other tips”). I recommend having a speed of between 1000 and 2000:

$('div.some-images img').gallery(1000);

So, if you wanted to specify the amount of time paused on each image during a slideshow you would do it like this:

$('div.some-images img').gallery(1000,5000);
// So 5000 is the amount of time (milliseconds) each image is shown during a slideshow
// If you want to specify the slideshow speed but NOT the generic speed then do the following:
$('div.some-images img').gallery(null,5000); // 'null' induces the default speed

Most of the styling is handled in the CSS so the plugin has quite a lot of flexibility style-wise.

As you can see (in the DEMO) there is a description shown in the lower left hand corner of the image. This description can be specified by you in the longdesc attribute of the images. If an image does not have this attribute then the description box will not be shown for that particular image.

Originally, I put this script together for a project (and had not considered making it available as a plugin) so it’s not 100% customizable but I’ve tried my best.

A typical setup would be something like this (HTML):

<ul class="gallery">
	<li><img src="london.jpg" alt="Usual stuff happening in London" longdesc="A photo taken in London... blah blah blah" /></li>
	<li><img src="lens.jpg" alt="A Nikon Camera lens" longdesc="An emotive shot of a Nikon Lens... Yeh! ;)" /></li>
	<li><img src="goose.jpg" alt="A goose" longdesc="Just... a goose!" /></li>
	<li><img src="pagani.jpg" alt="Dream car - Pagani Zonda" longdesc="Not my photo, but still amazing! ... My dream car, the Pagani Zonda! ;)" /></li>
</ul>

With the above HTML you would call the script like this:

$('ul.gallery img').gallery(1000);

Downloads:

jQuery core
This plugin script
CSS StyleSheet (basic style - like in demo)

Other tips:

Earlier, I said that when calling the plugin you can specify styles within a third argument. I am using this in the DEMO to position the description box and the image menu:

$('ul.gallery img').gallery(null,null,
	function(){
		// * Some styles which need to be applied on every image-change:
		var imageOffset = $('#img-gallery img').offset();
		var bottomOfImage = $('#img-gallery img').height() - $('#img-description').height();
		$('#img-description').css({top: bottomOfImage});
		$('#img-gallery ul').css({right: -$('#img-gallery ul').width()});
	}
);

If you don’t want to specify the speeds in the first two arguments simply set them as “null” - this will set the speeds to the script’s default.

By default, the gallery will prepend itself within the body of the document. To change where the gallery puts itself within the DOM you’ll have to edit a line within the script. (line ~31)

For example, changing it to the following would make it append itself to the "mygallery" div:

$('div.mygallery').append(galleryStructure); // <- Line ~31

If you find any errors please let me know!

41 Responses to “My first jQuery plugin - An image gallery”

#1 :: Thomas Milburn Says:
July 13th, 2008 at 11:41 am

Well done for making a great plugin! With a few modifications, I might use this in my own projects.

Can I suggest that you write a tutorial explaining how to make a jQuery plugin.
#2 :: Daniel Says:
July 26th, 2008 at 4:42 pm

Wonderful, simply wonderful. Definitely a del.icio.us from me. You mast submit it to Noupe, so others could find and use your creation. I’ll look into this one, maybe I could add some more fancy stuff to it. But, yes, James, you are ought to be proud of it!
#3 :: henk Says:
August 1st, 2008 at 9:17 am

How can i make the slideshow start automaticly?
#4 :: Melissa Says:
August 21st, 2008 at 6:29 pm

I am getting this message:
The requested URL /imagegallery.html was not found on this server.

Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request.

Do you know what I am doing wrong? I have found it’s easier to look at the source of the demo site to copy and I did that on someone else’s sample for the Form instructions and that one worked. But this one I think I must be doing something wrong. I have copied your CSS, JS and HTML do I need a PHP and if I need a PHP what do I put in it?
#5 :: Melissa Says:
August 21st, 2008 at 7:07 pm

I realized what the problem was I was having and I have fixed it but now I have the page up and 4 images but it’s just the images (4) in a column down and no buttons or anything. Suggestions?
#6 :: James Says:
August 21st, 2008 at 7:29 pm
@Melissa- I’m glad you sorted out the problem!

The reason that you can only see the images in a column and no buttons is either because you have JavaScript disabled or you’ve not downloaded the JavaScript dependencies correctly. The two needed files are jQuery and The plugin file. Make sure you have both of these in <script> tags at the top of your document in the <head>… And make sure you’re initiating the plugin at the bottom of your document:
```
$('ul.gallery img').gallery(null,null,
	function(){
		// * Some styles which need to be applied on every image-change:
		var imageOffset = $('#img-gallery img').offset();
		var bottomOfImage = $('#img-gallery img').height() - $('#img-description').height();
		$('#img-description').css({top: bottomOfImage});
		$('#img-gallery ul').css({right: -$('#img-gallery ul').width()});
	}
);
```
Please note it doesn’t have to be exactly as above.
#7 :: Melissa Says:
August 22nd, 2008 at 3:20 pm

Thank you so much! I got it to work.
#8 :: James Says:
August 23rd, 2008 at 12:50 am

@Melissa great!
#9 :: X-Factor Blog Says:
October 16th, 2008 at 9:44 pm
Hiya, love the plugin, thank you.
However, is it possible to make the images clickable?
I have tried adding
```
<a></a>
```
but no joy.
#10 :: Natalya Says:
October 28th, 2008 at 6:33 pm

Good for people to know.
#11 :: JJ Says:
October 30th, 2008 at 11:42 am
X-Factor, I have adapted the code to allow the use of hyperlinks for your separate images. First of all you need to create a hyperlink inside the gallery class and inside the separate li tags as shown:
```
<a href="URL" rel="nofollow"></a>
```
Then you need to add a function caller for this new tag in the javascript on the page, as shown:
```
$('ul.gallery a').getHyper();
```
just above
```
$('ul.gallery img').gallery( . . . )
```
This completes the work on the html page.
Next you need to add a handlling function for this a tag as shown:
```
var hypes = [];
jQuery.fn.getHyper = function() {	
    var hypers = this;
    $(hypers).each(function(i){
        hypes[i] = [this.href];
    })
}
```
this code will save the URL of each li tag into the hypes[] array. Make sure the hypes[] array is outside the function as it is used later.
Next you need to add the a tag into the output string:
```
var galleryStructure = '<a href="" rel="nofollow"></a>'+ssOption+'';
```
make sure to add a class to this hyperlink so you can reference it later in the Start function.
Next is to add URL to the hyperlink to the a tag with the class “img-hyp”:
```
$('#img-gallery img').attr('src', img[n][0]).attr('alt', img[n][1]);
$('#img-gallery a.img-hyp').attr('href', hypes[n]);
var width = $('#img-gallery img').width();
```
if you add in the middle line as shown here the code should work giving you the ability to add hyperlinks to each of your images.
#12 :: Omid Says:
October 30th, 2008 at 8:27 pm

Hi,

This is one of best jQuery plug-ins that I have ever seen .
But I have one problem ! I tried to load your demo page with dial-up and ADSL connection , with both of them , first image of your gallery appears below of green frame but when I refresh page , the demo page loads correctly and I could see only green frame with 4 images inside it and there is not any image below of frame .
Can I solve this problem !!?

TNX
#13 :: Marc Says:
November 7th, 2008 at 12:08 pm

Has anyone figured out how to autostart this gallery yet?

#14 :: Mike Says:
November 7th, 2008 at 6:53 pm

Firebug says :

$("ul.gallery img") is null
$('ul.gallery img').gallery(null,null,

#15 :: sutra Says:
November 9th, 2008 at 12:11 pm

Hi, nice gallery! I am testing it right now but it’s conflicting with Prototype Library. I’d already adding the noConflict, still it’s not working and worse, cripples my jquery accordion. In the plugin code, I see there are many “$”. Do I change them all to “jQuery”? Or is there a quicker way to fix this?

Was comparing your plugin code with galleira, I see it has this at the very top:
(function($){

var $$;

Thanks!

#16 :: JJ Says:
November 11th, 2008 at 1:41 pm

In answer to henk and Marc, the following changes to the code will allow the javascript to play automatically on load.

First of all you need to add a variable that will hold the currently active image. This is done previously using the “active” class in the hyperlink itsself. However if you try to use this then you will run into trouble. So I created the variable

var gallery = this;
var img = [];
var currentImage = 0;
. . .

In the startSlideShow function at the bottom of the javascript file you need to change the code to the following

function startSlideShow(){
     imgToLoad = currentImage;
     if (imgToLoad == gallery.length) {imgToLoad = 0;}
     window['galleryTimeout'] = setTimeout(function(){startSlideShow()}, slideShowSpeed)
     changeImage(imgToLoad, function(){eval(galleryTimeout);});
     currentImage++;
}

This will use the variable currentImage instead of using the active class to determine which is shown.

Next you need to add into the changeImage function the new currentImage. So just add
currentImage = n;

The last step starts the animations automatically and makes sure that it doesnt play if there is only one image

The code

$('#img-gallery ul a#playstop').toggle(
. . .
)

Needs to be replaced by

$('#img-gallery ul a#playstop').toggle(
   function(){
      if(gallery.length &gt; 1){
         $(this).toggleClass('stop');
         stopSlideShow();
         return false;
      }else{
         $(this).toggleClass('stop');
         startSlideShow();
         return false;
      }
   },
   function(){
      if(gallery.length &gt; 1){
         $(this).toggleClass('stop');
         startSlideShow();
         return false;
      }else{
         $(this).toggleClass('stop');
         stopSlideShow();
         return false;	
      }
   }
);
 
if(gallery.length &gt; 1){
   $('#img-gallery ul a#playstop').toggleClass('stop');
   startSlideShow();
}

Now your page should automatically start playing provided there is more than one image.

#17 :: jeanny Says:
December 11th, 2008 at 3:12 pm

Like Omid, I have a problem when the browser first loads. It shows the first photo and a blank outline box of all the other photos underneath. When the browser is refreshed it loads properly.
How can I sort this problem as it does look very strange on the initial view.
Thanks
#18 :: Mario Luevanos Says:
December 19th, 2008 at 7:28 pm

Great work bro… I like this a lot.
#19 :: jimladd Says:
January 9th, 2009 at 11:47 am

Like the others, I have a problem on initial load of the page, which is fixed upon refresh.
Also, every so often the frame will not resize properly and you are left with an image with a big black bar to the side of it.
Apparently it also doesn’t work on Safari 2 on Mac, but I’m yet to see this first-hand.
Cheers
#20 :: Invectus Says:
January 17th, 2009 at 2:57 pm

Hi there,

Can anyone write an easy-to-follow guide for hyperlinks? I’ve followed the steps above by JJ, but I still can’t add links to my images. It would be great if someone could post a live example so newbies like me can learn from seeing

Thanks a lot
#21 :: JC Says:
January 19th, 2009 at 11:02 am

Great stuff!

JJ - I tried your step by step guide to get it to automatically rotate on load however it doesn’t seem to work, I end up with image1 duplicated several times and displayed in a column. I’ve repeated the process several times.. Is there a step I might be missing?
#22 :: Edgar Says:
February 18th, 2009 at 7:10 pm

if I want to put more than 10 images, what should I do?
#23 :: Edgar Says:
February 18th, 2009 at 7:11 pm

sorry, already decided how to add more photos, thanks.
#24 :: Zone Says:
February 20th, 2009 at 11:56 am

Hi !

“Like Omid, I have a problem when the browser first loads. It shows the first photo and a blank outline box of all the other photos underneath.”

Try to change the following lines in the script:

gallery[gallery.length-1].onload = function(){
$(this).remove();
start();
started = true;
}

to this:

gallery[gallery.length-1].onload = function(){
$(this).remove();
if(!started)
{
start();
started = true;
}
}

Hope this helps !
#25 :: Zone Says:
February 20th, 2009 at 1:31 pm

Hi !

Sorry, my previous solution was inefficient. The multiply load at the first time is caused by the timer in the script:

setTimeout(function(){
if(!started) start();
},2000)

If you comment it out the first apperar will be fine, but it will take some time to load.
#26 :: Jade Says:
March 3rd, 2009 at 7:08 am

@JC (#21)

I tried imlemented JJ’s mod as well. I got the same errors but managed to get mine working.

I’m using firebug and there seems to be a problem with the “greater than” sign evaluating.

His last instructions about adding in this code:

$(’#img-gallery ul a#playstop’).toggle(
function(){
if(gallery.length > 1){
$(this).toggleClass(’stop’);
stopSlideShow();
return false;
}else{
$(this).toggleClass(’stop’);
startSlideShow();
return false;
}
},
function(){
if(gallery.length > 1){
$(this).toggleClass(’stop’);
startSlideShow();
return false;
}else{
$(this).toggleClass(’stop’);
stopSlideShow();
return false;
}
}
);

if(gallery.length > 1){
$(’#img-gallery ul a#playstop’).toggleClass(’stop’);
startSlideShow();
}

Replace:
gallery.length > 1

with this:
gallery.length>1
#27 :: Robin Says:
March 18th, 2009 at 7:20 pm

Very nice.

Want to place #img-gallery ul above #img-gallery and display horizontally, so changed #img-gallery ul li to ‘display: inline’, but no go.

Ideas welcome.

BTW, do not alter CSS with any function(s) in embedded script, so wonder what’s stopping above CSS from displaying ul li inline.

Thanx in advance.
#28 :: Robin Says:
March 18th, 2009 at 7:43 pm

OK, notice your styling for ’simple’ and ’swish’ place #img-gallery ul at top of #img-gallery, so may only need your CSS for either ’simple’ or ’swish’ demos.
#29 :: Robin Says:
March 18th, 2009 at 7:44 pm

Dang, I meant ’swish’ style only.
#30 :: Robin Says:
March 18th, 2009 at 10:11 pm

OK, checked your stylesheet ’simple.css’ for ’swish’ gallery, took hints, worked out horizontal ul above my #img-gallery.

Sorry for repeated comments.

Thanx for excellent plugin.
#31 :: Steve Says:
March 19th, 2009 at 7:06 pm

Hi,

Great plugin, which I was thrilled to find. I’m having real hassle following the steps to add a link via tag to each image.

Anyone got a working example by any chance?

Cheers,
Steve
#32 :: Erik Says:
March 30th, 2009 at 5:25 pm

Hi,

thank you very much for your gallery, i think it’s awesome!

I have only one problem: the longdesc at the bottom of the image, overlaps the footer (that follows the content of the site, it’s not a bottom 0px).

Are there any ways to solve this problem?

Thanks

Bye!
#33 :: HansB Says:
April 9th, 2009 at 2:39 pm

Hey,
is it possible to change the numbers into thumbnail pictures instead?
#34 :: Mayron Cachina Says:
May 6th, 2009 at 8:00 pm

Hello,

I had a problem with the plugin, using the example was proposed in the comments to start it automatically. I had a problem, the currentImage++ function in startSlideShow() always add more so I decided the following code:

(currentImage == gallery.length)? currentImage = 0: null;

in the last line of startSlideShow(), I know that there are better ways, plus there is my solution:)
#35 :: Zeal Says:
May 16th, 2009 at 7:09 am

how do I change the transition?
#36 :: K Says:
June 3rd, 2009 at 7:20 pm

Hi JJ,

Thanks for adding hyperlinks, I followed your instructions for adding hyperlinks but no luck, can you please describe with detail code modifications
#37 :: J Design Says:
June 3rd, 2009 at 7:57 pm

Hello
Can somebody please tell me how i start the slideshow on body load?
Thanks from a JQeury noob

Please mail it to me : j [dot] design [at] live [dot] be
#38 :: J Design Says:
June 3rd, 2009 at 8:10 pm

I already tried with the above solution but got stuck with the 3th step..
#39 :: SohoInteractive Says:
June 5th, 2009 at 1:38 pm

Great little script.
Thank you

K.
#40 :: accounting homework Says:
June 6th, 2009 at 8:19 am

Good one, image rotator can be useful at times especially for projects etc

Thanks for posting them
#41 :: Navjyoti Says:
June 8th, 2009 at 7:40 am

Hey
Thanks for this great plugin, good work.