OBSOLETE: jQuery.rotator can accomplish similar things without as many bugs or maintenance problems.

Tired of using plugins like Flash to create slideshows for your website? Don’t have the time or money to create a custom Flash movie? Now you can create simple slideshows with ease, without viewers needing to download a plugin, and without the use of proprietary software! First I’ll discuss what this new application can do, then go over how to get it up and running on your website. Finally, I’ve included some technical documentation in case you are interested in what makes it work.

Overview

vvx_slideshow is an open-source application available under the MIT license. At present, it is in version 0.1.1 (which functions identically to version 0.1 but contains numerous performance improvements).
The application can be used on any website to create a slideshow. The images fade from one to another without an intermediate white screen (but see “bugs” below). The website manager can choose the speed at which the slideshow should progress, how tall and wide it should be, and other details such as how long the images should take to fade.

Using on your site

Installation

vvx_slideshow uses JavaScript, and requires the jQuery JavaScript library. To install the script, the library, and the “cachimage” plugin, just do the following (it may be easier to just ask your webmaster to do this):

1. Go to jquery.com and click “download jQuery”. Copy the entire contents of the page that is opened into a text file, using a program such as notepad or gedit. Do not use a word processor like Microsoft Word of OpenOffice. Save the file with a name like “jquery.js” (make sure it doesn’t have a .txt extension). Note: If you already have jQuery on your website (ask your webmaster if you’re not sure), you do not need to download/install it again! You may also want to ask your webmaster about compressing the file.
2. Go to the cacheimage plugin’s main page and click download. Save the code of the file the same way, naming it “jquery.cacheimage.js”. Alternatively, you can add the contents of this new file to the end of jquery.js (after all of the code).
3. Download the vvx_slideshow code and save it the same way. The most recent version of the program at the time of this post is located at this page. Name this file “vvx_slideshow.js”.
4. Upload the files to your web server. This can be done a number of ways depending on how your server is set up; if you’re unsure, contact your webmaster.
   • Using an FTP program, such as FileZilla.
   • Using the cPanel file manager, if your host has one. Just access the cPanel, go to where you want the scripts to be located (anywhere in public_html will work), click “upload”, and upload the files from there.
   • Using another code editor. If your server has a way to directly edit the code of pages, create new files with the same names as the ones on your computer and copy the code into them.
5. Include the scripts on the page where you want the slideshow. You will probably need to use an “HTML edit” mode or a “Code edit” mode to do this. On the page, locate the text </head>. Immediately before this text, add the following:
   <script type="text/javascript" src="PATH/TO/SCRIPT1"></script> <script type="text/javascript" src="PATH/TO/SCRIPT2"></script> <script type="text/javascript" src="PATH/TO/SCRIPT3"></script>
   Replace PATH/TO/SCRIPT1 with the relative path to the jquery.js file. Replace PATH/TO/SCRIPT2 with the relative path to the jquery.cachimage.js file (or remove the second pair of <script></script> altogether if you put the cacheimage code in the same file as the main jquery code. Replace PATH/TO/SCRIPT3 with the relative path to the vvx_slideshow.js file. If you don’t know the relative path, ask your webmaster.

Tada! The script is installed. It doesn’t actually do anything yet, but all it needs now is some configuration.

Configuration

Now it’s time to get the script configured so that it actually does something. This should be much easier than installing the script. First, we need to edit the page that the slideshow will be on.

1. Upload the images you want to have in the slideshow to your server (typically in a folder like “images”). All of these images should be the same height and width; otherwise, images of different dimensions may be distorted. You can change the size of images with a program like Adobe Photoshop or the GIMP.
2. Edit the page that you want the slideshow to be on. (use a code/text edit view in which you can directly change the HTML of the page, rather than a WYSIWYG editor). Add the following code: <div id="vvx_slideshow" style=""><!-- Slideshow can be edited in the vvx_slidshow.js file--><img id="vvx_slideshow_image_1" src="PATH/TO/IMAGE" alt="DESCRIPTIVE TEXT" width="WIDTH" height="HEIGHT" /></div>
3. Replace PATH/TO/IMAGE with the relative URL to the first image in the slideshow. For example, if the page the slideshow is on is located at public_html/index.html, and the image is at public_html/images/happy_customers.jpg, then the relative URL is images/happy_customers.jpg.
4. Replace DESCRIPTIVE TEXT with words the describe the image, in case the image doesn’t load for some reason. Replace WIDTH with a numeral equal to the width of the image (in pixels), and HEIGHT with a numeral equal to the height of the image (also in pixels).
5. Save, and find the page the slideshow should be on to make sure the image is on it. It won’t change yet, but the first image should be visible.
6. If the image’s position is good already, skip to the next step. Otherwise, return to editing the page. Find the text style="". In between the two quotation marks, put float: right; if you want the image to be on the right side of the page, or float: left; if you want the image to be on the left side of the page. If you want to add a border to the slideshow, add border: 3px solid black for a basic border, or contact your webmaster for a more elaborate border. Your webmaster should also be able to more precisely specify the image’s position.

That page is done! Finally, we need to edit the vvx_slideshow.js file to do the final configuration.

1. Open vvx_slideshow.js in a text or code edit view.
2. Find “Begin editing here” text. Below it locate the lines which contain width and height. Set these to the same values as the previous width and height; for example, height: 225,. Make sure to include the colon before the number and the comma after it.
3. In the same way, set the interval and time values. These are both represented in milliseconds (1,000 milliseconds equals 1 second). interval specifies the time that and image is visible, including the amount of time that it is fading in. time specifies how long it takes for one image to fade into another. A good rule of thumb for a normal picture slideshow is 5000 (5 seconds) for interval and 1000 (1 second) for time (note that there is no comma before the thousands place). A slower time value may cause the slideshow to appear jerky; see “bugs” below. Note that there should be no comma after the value for time, as there should for the others.
4. Finally, we need to set what images will be used. Look for the rows that say {image: , description: },. Copy this row once for each image that will be in the slideshow, minus one.
5. Put the relative URL of the the first image (the same one that you put on the other page) in quotation marks after image: , and put (also in quotation marks) the descriptive text for the image after description: .
6. Repeat this for all of the remaining images, putting one on each line. The last row also includes the text //No comma after the last one. This is important! This last row (the second of the two that were there before you started copying the text) must not have a comma after the description.
7. Save, and go to the page that the slideshow should be on. Give it a little while to load; the more images there are, or the bigger they are (in terms of filesize, not dimensions), the longer the slideshow will take to start. It should start fading from one image to the next smoothly enough after 10-30 seconds.

All done! You can always edit what images are used by editing this second file. If there seem to be any problems, contact your webmaster; he may be able to help you get it working right, or he may be able to file a descriptive bug report if there is a problem with the program itself.

Technical documentation

This is an overview of the technology behind the application. You probably don’t need to worry about this unless you are modifying the code or are trying to fix a bug in it. As such, I have written this section under the assumption that the reader understands at least basic JavaScript and HTML coding.
A human-readable (in other words, not minified) copy of the code can be found at this page. The previous version (0.1) is at this page.
First, as soon as the DOM is ready, the jquery.cachimage.js plugin is used to cache all of the images to be used in the reader’s browser. This way, the slideshow will (ideally) move smoothly from one image to the next, rather than forcing the browser to download the images as they are being faded in (which would not work).
On page load (this is after all images are downloaded, including the ones being cached), the vvx.slideshow.swapimgs function is set to run at the interval specified in the configuration. This function uses global variables (starting with vvx.slideshow.nextimg) to keep track of what image it should be swapping to next. It updates these each time it finishes executing.
The function first creates an HTML string to represent the new image. It has CSS display: none;, and an id of vvx_slideshow_image_2. It appends this image code to #vvx_slideshow the div that holds the images.
It then begins fading out the previous image and fading in the new one, using jQuery’s built-in .fadeIn() and .fadeOut() methods. Once these have finished (at which point the new image if fully opaque and the previous is fully transparent), a callback function starts. The callback checks if the new image was the last one and, if so, sets the nextimg variables to the beginning. Otherwise, it simply increments them appropriately. Finally, it uses jQuery’s .remove() method to remove the original image, and it replace the id of the new image with vvx_slideshow_image_1, so that the added image is now the “old” image. The cycle will then restart when the interval hits the configuration number again.

Bugs

This is a list of known bugs. I hope to fix them eventually; if you have found a way to fix them, please leave a description in the comments. (if you do so, you agree that I can use the code under the MIT license).

• In Internet Explorer 6 and some other browsers (Konquerer?), the slideshow fades to white and then the new image appears without fading in. This could be a problem with jQuery’s built in animation functions.
• The slideshow might not appear in the correct place depending on how it and its containing blocks are positioned with CSS.
• Images with a large file size and/or a long fade time may appear to fade jerkily. This could be a bug with jQuery; it is recommended to use slower fade times and smaller images to avoid this bug.
• The application ensures that all images in the slideshow have been cached before it starts the slideshow. If there are large images or a lot of images, there may be a noticeable delay before the slideshow starts.