Creative Juices Bo. Co.

Satisfy Your Thirst For Something Refreshing!

CJ Simple Slideshow 3.0

A Simple Cross-Fade Slideshow Plug-In for JQuery

JQuery Plug-In: Simple Slideshow v3.0

It's been a long and interesting journey since I first wrote the first CJ Simple Slideshow. As you may or may not know, this was literally my first attempt at writing a jQuery plug-in. And as luck would have it, I needed to use it for a project I'm currently working on. The problem is, it sucks. I've never claimed to be a jQuery expert. I'm basically just like you, a simple web developer learning and experimenting with the awesomness that is jQuery. Trying to implement version 2.1.1, I soon realized how sucky it was. I was doing a lot of things in javascript that I could have done a lot easier in jQuery. So I took it upon myself to fix this terrible wrong that I have bestowed upon the world and present you with CJ Simple Slideshow v3.0. New, improved and full of slideshow might! It's now about 30% smaller than the previous versions. So you have a nice lightweight footprint to boot.

First, let's go back to what this plug-in is. It's a "simple" slideshow tool. Nothing more, nothing less. I have received comments in the past from people asking for a variety of bells and whistles, but I strongly feel this goes against the concept of what this plug-in needs to do. And that is to take a series of images and do a simple cross-dissolve. Maybe show captions, maybe allow some basic interaction and maybe allow links. That's it. With that in mind, lets go through how to use it.

Requirements

I have been testing this with JQuery version 1.4.3 (The most current at the time of this writing). It should work with older versions, but I'm going to leave that up to you to discover. I have tested this with FireFox 3.6, Safari 5, Chrome 8 and Internet Explorer 8.

Implementing

As with previous versions, implementing the plug-in is pretty straight foward, you just need to have a container that contains a group of images, like so (Also, note we have a link on one of the images. The plug-in handles links as well):

<div id="MySlideShow">
   <img src="sample1.jpg" width="250" height="150" alt="This is caption 1." /><br />
   <a href="page.html"><img src="sample2.jpg" width="250" height="150" /></a>
</div>

The plugin will create a new dom structure with special class names, which can be used to style things using standard CSS. The new structure will look something like this:

<div id="MySlideShow">
   <div class="cj_slideshow_wrapper">	
      <div class="cj_slideshow_slide">
         <img src="sample1.jpg" width="250" height="150">
         <span class="cj_slideshow_caption">This is caption 1.</span>
      </div>
      <div class="cj_slideshow_slide">
         <img src="sample2.jpg" width="250" height="150" />
      </div>
   </div>
   <div class="cj_slideshow_pause">Paused</div>
</div>

The plug-in will create a wrapper arround all of the images with a class name of "cj_slideshow_wrapper". Each image will receive it's own wrapper called "cj_slideshow_slide". It will also create a caption block with a class name of "cj_slideshow_caption" (If you choose to show captions). The caption will be automatically populated with the images ALT text. Lastly, a pause block with a class name of "cj_slideshow_pause" with the supplied inner text (if you have this option turned on). These elements can be styled pretty much any way you please. You just have to be careful not to set the positioning, since the plug-in handles this automatically. For further information, you can check out the demo page for an example of how to style these elements.

You may notice, that you are no longer seeing the link we have in our example up above. Don't worry, the plug-in will bind a "click" event to the slide block if it detects a link tag.

Activating the slideshow is pretty much the same a previous versions, you need to call the plug-in by placing a load wrapper in your code, like so...

$("#MySlideShow").cjSimpleSlideShow();

...or, place on onload in your body tag, like so:

<body onload="$('#MySlideShow').cjSimpleSlideShow();">

But this method is so un-jquery like, don't you think? If you want to pass some options, you might do something like this:

$("#MySlideShow").cjSimpleSlideShow({
   autoRun: false,
   delay: 6000, // miliseconds
   dissolve: 300 // miliseconds
});

// delay the slideshow and then start it later...
$("#MySlideShow").cjSimpleSlideShow("start");

User Options

You have a few options that you can pass to the plug-in. These change basic functionality and are listed below:

ArgumentDescriptionDefault
autoRunDetermines if the slideshow starts automatically. If you set this to false, then you will need to start the slideshow by calling $("#MySlideShow").start();true
delayThe delay in miliseconds between slide transitions,5000
dissolveThe amount of time in miliseconds that it takes to do the transition between slides.500
showCaptionsDetermines wether or not to display the slide captions. If set to true, the plug-in will use the value of the images ALT tag for the slide caption.true
centerImageIf you have variable sized images, then you can use this option to center the image withing you slideshow box.false
allowPauseIf the user mouse's over the slideshow, this option will pause the dissolves until the user's mouse leaves the container.false
pauseTextIf allowPause is true, then you can supply text to display while the slideshow is paused. You may also pass, HTML, but this hasn't been thoroughly tested."Paused"

Methods

You have a few methods that you can use with the plug-in. These effect operational functionality and are listed below:

MethodDescriptionExample Usage
startStarts the slideshow if you passed the option autoStart: false.$("#MySlideShow").cjSimpleSlideShow("start");
pauseInitiates a pause in the slideshow.$("#MySlideShow").cjSimpleSlideShow("pause");
resumeResumes a paused slideshow.$("#MySlideShow").cjSimpleSlideShow("resume");

Classes

You have a few classes that you can use with the plug-in. These effect style of variouls elements and are listed below:

ClassDescription
cj_slideshow_wrapperThis block wraps the entire slideshow. You should be able to play around with borders, background and margins, but it has not been thoroughly tested.
cj_slideshow_slideThis block wraps each slide. It's primarily used to "dissolve" each slide as well as set the overall position. I wouldn't recomend playing around with it, but it's listed here for your coding enjoyment.
cj_slideshow_captionIf your image has a "ALT" attribute with text, then the plug-in will use this block to hold the text. You should be able to style everything about this block with no worries about conflicting with the functionality. Initially it is set to with a position to the upper, left hand corner (5px away).
cj_slideshow_pauseIf you have the allowPause set to true and have supplied some text in the pauseText, then this block will hold your text. You should be able to style everything about this block with no worries about conflicting with the functionality. Initially the text is set to Paused.

Notes

I haven't included any "image" load detection in this version, though this is something I'm pondering for future versions. So, it's possible that if you have a lot of large images, you may notice some weird behavior. If you do let me know. This might convince me to add it quicker.