FF1+ IE7+ Opr9+

Simple Controls Gallery v1.5

Author: Dynamic Drive

v1.5 (Oct 6th) : Gallery made responsive and mobile friendly, by supporting a percentage "width" value and swipe/ touch support. Also adds a new "scaleimage" option to scale the images inside the gallery in 2 different ways.

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.
  • Supports scaling of the images inside the gallery in 2 different ways to ensure they are visible regardless of image dimensions, by way of the "scaleimage" option. v1.5 feature
  • 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.
  • 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.
  • Responsive and mobile friendly. Width of gallery can be set to percentage value. On mobile devices, touch to activate description and play/pause controls, and swipe to navigate. v1.5 feature

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 three 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)
  2. jquery.touchSwipe.min.js v1.6.6 (project page)
  3. simplegallery.css

Step 2: Then, where you wish a Gallery to appear on your page, add an empty DIV with a unique ID attribute and a CSS class of "simplegallery" (required):

<div id="simplegallery1" class="simplegallery"></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, pixels] or ['percentage%', pixels]
	imagearray: [
		["pool.jpg", "http://en.wikipedia.org/wiki/Swimming_pool", "_new", ""],
		["cave.jpg", "http://en.wikipedia.org/wiki/Cave", "", ""],
		["fruits.jpg", "", "", ""],
		["autumn.jpg", "", "", ""]
	autoplay: [true, 2500, 2], //[auto_play_boolean, delay_btw_slide_millisec, cycles_before_stopping_int]
	persist: false,
	scaleimage: 'both', //valid values are 'both', 'width', or 'none'
	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 (ie: try this.navigate("play/pause")
		//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: The dimensions of the gallery, in pixels-pixels such as [500, 300], or percentage-pixels, such as ['50%', 300]. In the later case, the gallery becomes responsive, with its width changing depending on the width of its parent container. Make use of CSS  media queries at the same time to adjust the height of the gallery at certain breaking points.

  • 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.
  • scaleimage: v1.5 option:  Sets how the images inside the gallery should scale to fit in the container. Valid values are: "both", "width", or "none".  In "both", the image's width and height will both be examined to ensure they fit inside the gallery. In "width", only the image's width will be examined and scaled down if necessary (with the height adjusted proportionally).  In "none", the image's dimensions are left untouched.
  • 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".

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: [
	["http://i26.tinypic.com/11l7ls0.jpg", "http://en.wikipedia.org/wiki/Swimming_pool", "_new", "There's nothing like a nice swim in the Summer."],
	["http://i29.tinypic.com/xp3hns.jpg", "http://en.wikipedia.org/wiki/Cave", "", ""],
	["http://i30.tinypic.com/531q3n.jpg", "", "", "Eat your fruits, it's good for you!"],
	["http://i31.tinypic.com/119w28m.jpg", "", "", ""]

Here the first and 3rd slides will carry a description, which are shown inside a gliding Panel at the top of the gallery.

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

.simplegallery .gallerydesc .gallerydesctext{
	width: auto;
	color: white;
	text-align: left;
	padding: 5px; /* padding inside description panel */

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.

Making your gallery responsive

Simple Controls Gallery can easily be made responsive to cater to changes in layout size and mobile devices. See the supplementary page "Creating a responsive gallery" for more info.

Table Of Contents

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

Wordpress Users: Step by Step instructions to add ANY Dynamic Drive script to an entire Wordpress theme or individual Post