New Revised CSS Library Forums Web Tools
FAQs Awards Usage Terms Contact
Other Sections
Sweet Ads
Bookmark online:

FF1+ IE7+ Opr9+

Simple Controls Gallery v1.4

Author: Dynamic Drive

Note: Adds ability to show image gallery only after all images within gallery has been loaded. Requires jQuery 1.5+

Description: Want to display images as an automatic slideshow that can also be explicitly played or paused by the user? Simple Controls Gallery rotates and displays an image by fading it into view over the previous one, with navigation controls that pop up when the mouse rolls over the Gallery. Lets take a look at the script's set of features:

  • Displays images either as an automatic or manual slideshow, with the image faded into view over the previous. A Navigational Panel slides up when the mouse rolls over the gallery to play, pause, or step through to a specific image within the gallery.
  • In automatic mode, set the number of cycles before the script stops rotating.
  • Each slide consists of an image that can be hyperlinked.
  • Each slide can have a description associated with it. When defined, a Description Panel slides down from the top of the gallery showing the description. New in v1.3
  • The gallery supports persistence of the last viewed image via session cookies, so going away then coming back to the gallery calls up the last viewed image within a browser session.

The images within the Gallery should all be the same size for best results.


Directions Developer's View

Step 1: Add the following script to the <head> section of your page:

Select All

The code above references two external .js files plus 5 images, which you need to download below (right click/ select "Save As"):

  1. simplegallery.js (customize variable "simpleGallery_navpanel" at the top)

Step 2: Then, where you wish a Gallery to appear on your page, add an empty DIV with a unique ID attribute:

<div id="simplegallery1"></div>

The DIV's ID value should match up with the value set in simpleGallery.wrapperid in the code of Step 1 above. When the page loads, the script will load the gallery into this DIV.

More information

To define a new Simple Controls Gallery, you should call new simpleGallery() in the HEAD section of your page with the supported parameters:

var mygallery=new simpleGallery({
 wrapperid: "simplegallery1", //ID of main gallery container,
 dimensions: [250, 180], //width/height of gallery in pixels. Should reflect dimensions of the images exactly
 imagearray: [
  ["pool.jpg", "", "_new", ""],
  ["cave.jpg", "", "", ""],
  ["fruits.jpg", "", "", ""],
  ["autumn.jpg", "", "", ""]
 autoplay: [true, 2500, 2], //[auto_play_boolean, delay_btw_slide_millisec, cycles_before_stopping_int]
 persist: false,
 preloadfirst:true, //v1.4 option on whether slideshow should only start after all images have preloaded
 fadeduration: 500, //transition duration (milliseconds)
 oninit:function(){ //event that fires when gallery has initialized/ ready to run
  //Keyword "this": references current gallery instance (ie: try this.navigate("play/pause")
 onslide:function(curslide, i){ //event that fires after each slide is shown
   //Keyword "this": references current gallery instance
   //curslide: returns DOM reference to current slide's DIV (ie: try alert(curslide.innerHTML)
   //i: integer reflecting current image within collection being shown (0=1st image, 1=2nd etc)

First and foremost, note the "mygallery" variable in bold red- this should be an arbitrary but unique variable that identifies this instance of the Gallery on your page. For multiple instances, use a different variable name each time.

  • "Wrapperid": Must be set to the ID of the empty DIV you've manually added on your page.

  • "dimensions": Should be set to the width and height of your images, which are assumed to all be the same size. Those images that are larger will be partially clipped, while those that are smaller will appear with extra whitespace inside the gallery.

  • "imagearray": An array containing the images to be shown in the following format:

    ["path_to_image", "optional_link", "optional_linktarget", "optional_textdescription"].

    For the parameters that are optional, set it to a blank string ("") if you don't want a particular one enabled.

  • "autoplay": An array that lets you set whether the gallery should play automatically when the page loads, and if so, the pause between slides and cycles to run before stopping:

    /[auto_play_boolean, delay_btw_slide_millisec, cycles_before_stopping_int]

    Setting the first parameter to false makes the later two irrelevant.

  • "persist": Boolean on whether gallery should remember and recall last viewed slide within a browser session.

  • "preloadfirst": v1.4 option: Boolean on whether slideshow should only start after all images have preloaded. Default value is true even if this option is not defined.

  • "fadeduration": The duration of the fade effect, in milliseconds.

  • oninit:function(): Event handler that fires once when the page has loaded and the gallery initialized, just about to fade the first image into view. You can use this event handler to define any custom variables that will be used by the gallery.

  • onslide:function(curslide, i): Event handler that fires each time a slide fades into view. See "Customizing: The navigate() method, oninit() and onslide event handlers".

Apart from the above, you'll probably also want to use CSS to further style your gallery container as desired. The CSS for the 1st demo looks like this:

<style type="text/css">

/*Make sure your page contains a valid doctype at the top*/
#simplegallery1{ //CSS for sample Gallery
position: relative;
visibility: hidden;
border: 10px solid orange;


At the minimum you should have "position:relative" and "visibility:hidden" defined, which will ensure the DIV container is hidden before the gallery is loaded into it.

Toggling whether slideshow should only begin after all images within the slideshow have preloaded

Starting in Simple Gallery v1.4, each slideshow by default will only start after all images within the slideshow have preloaded. This ensures an always smooth transition between image change, especially if the slideshow is set to automatically rotate. You can turn this behaviour off if you like by setting the option setting.preloadfirst to false within the initialization code above for that slideshow:

 preloadfirst:false, //v1.4 option on whether slideshow should only start after all images have preloaded

One situation you may wish to do this is when slideshow is set to manually rotate and the chances are good the upcoming image will have preloaded already by the time the user requests it. In this case it might make sense to disable this option and have the slideshow become interactive as soon as possible instead of wait for all images to preload first.

Adding a description to a slide

As seen in the 2nd Demo above, you can add a description to a slide by populating the very last element of the array containing the slide information:

imagearray: [
 ["", "", "_new", "There's nothing like a nice swim in the Summer."],
 ["", "", "", ""],
 ["", "", "", "Eat your fruits, it's good for you!"],
 ["", "", "", ""]

Here the first and 3rd slides will carry a description, which are shown inside a gliding Panel at the top of the gallery. Note that the height of this panel will automatically be set to that of the longest description of all your slides. To disable descriptions all together, just make sure none of the slides carry a description.

The DIV that houses the description carries a CSS class of "gallerydesctext". Style this DIV on your page if desired, such as add a padding around it:

#simplegallery1 .gallerydesctext{ //CSS for description DIV of Example 1 (if defined)
text-align: left;
padding: 2px 5px;

Tweaking the Navigation Controls Panel

At the top of simplegallery.js is where you'll find the settings for the Navigation Panel that glides up when the user mouses over the Gallery:

var simpleGallery_navpanel={
loadinggif: 'ajaxload.gif', //full path or URL to loading gif image
panel: {height:'45px', opacity:0.5, paddingTop:'5px', fontStyle:'bold 11px Verdana'}, //customize nav panel container
images: [ 'left.gif', 'play.gif', 'right.gif', 'pause.gif'], //nav panel images (in that order)
imageSpacing: {offsetTop:[-4, 0, -4], spacing:10}, //top offset of left, play, and right images, PLUS spacing between the 3 images
slideduration: 500 //duration of slide up animation to reveal panel

It allows you to modify the path to the 4 images used by the Panel, among other things. For example, if you've customized the images to your own, you may find the need to modify the Panel's height (panel.height) accordingly. The setting imageSpacing lets you change individually the vertical offset of the 3 images from their default position, plus the spacing between them, in that order.

Here's a tip- you can effectively hide the Navigational Panel altogether by setting panel.height to 0. If you do so, With the Panel hidden, you can still let users control the Gallery via custom controls that call galleryinstance.navigate(). See "Customizing: The navigate() method, oninit() and onslide event handlers" for more info.

Table Of Contents

This script consists of an index page plus 1 supplementary page: