Super Simple Image Viewer V3

I have had several inquiries lately about the Super Simple Image Viewer widget that I built several years back. As it is still being used, I thought I would take a minute to revamp the code and get it into a public version control. If you are unfamiliar with the software, it is a simple JavaScript widget that allows developers to create an image slide show on their site. Here is a list of feature that the revamped version will have:

  • add any number of photos to the viewer
  • optional support for caption
  • a previous/next interaction for navigation
  • organize photos into groups
  • an autoplay feature
  • DOM agnostic
  • library agnostic

Super Simple Image View (Version 3) Demo

How do it…

The code is available at https://gist.github.com/4281520.

To use, simply instantiate the SimpleImageViewer object and add photos to the instantiated instance.

var oSIV = new SimpleImageViewer('idOfImageOrElement',
    {caption: 'idOfCaptionOrElement', next: 'idOfNextOrElement', previous: 'idOfPreviousOrElement'});
oSIV.addPhoto('pathToPhoto1', {caption: 'Caption 1'});
oSIV.addPhoto('pathToPhoto2', {caption: 'Caption 2'});
oSIV.addPhoto('pathToPhoto3', {caption: 'Caption 3'});

This will create a slide show using the idOfImageOrElement. If you want pictures organized into multiple groups, then provide a group option when calling addPhoto and use the changeGroup to switch between image group:

var oSIV = new SimpleImageViewer('idOfImageOrElement',
    {caption: 'idOfCaptionOrElement', next: 'idOfNextOrElement', previous: 'idOfPreviousOrElement'});
oSIV.addPhoto('pathToPhoto1', {caption: 'Caption 1'});
oSIV.addPhoto('pathToPhoto2', {caption: 'Caption 2', group: 'group1'});
oSIV.addPhoto('pathToPhoto3', {caption: 'Caption 3'});
oSIV.addPhoto('pathToPhoto4', {caption: 'Caption 4', group: 'group1'});
oSIV.changeGroup('group1');

You can manually move to the next and previous image using:

oSIV.previous();
oSIV.next();

You can start and stop autoplay using:

oSIV.play();
oSIV.stop();

How it works…

When you instantiate the SimpleImageViewer, you must at least pass in a reference to the image element as the first argument. The second argument is an object that can contain optional arguments, such as a pointer to the caption, next, and previous element, or the timeout speed for autoplay and the defaultGroup name. You should probably provide at least the next and previous elements, or the SimpleImageViewer will just show the first element (unless you programatically call the next and previous functions). Anytime an element is required, you may pass in an element instance or the element’s id.

Internally, the codebase maintains an array of photos that is appended to with the addPhoto function. You have to provide the path to the photo as the first argument, and the second argument is an object containing optional arguments, such as the image caption, alt text, and group. If you decide to use the group feature then images will be added to whatever group you specify or the defaultGroup (if not is specified), which is group0 by default. To change to a different group, call the function changeGroup, passing in the group name you want to change to.

I have added an autoplay feature, which uses a simple timeout to move through the images. To start the autoplay call the play function and to stop it, call the stop function.

There’s more…

If you use jQuery, I have also modified the script to leverage the jQuery system, instead of using document.getElementById. This means that you can pass in any selector query or jQuery element, where you previously would have passed in an id or element instance. The code is available at https://gist.github.com/4282050.

Or if you use YUI 2.x, I have also modified the script to leverage the YUI system. It will behave exactly the same as the standalone version, but have better event support. The code is available at https://gist.github.com/4288138.