Customizing: The navigate() method, oninit() and onslide event handlers

New Revised CSS Library Forums Web Tools

Home Image Effects Image Galleries and Viewers Simple Controls Gallery Supplementary Page

Creating custom controls by calling `navigate()`

Simple Controls Gallery supports a public method instance.navigate() method that lets you do everything from go to a specific slide, move forward or back, or even play/pause a gallery on demand. It opens the door to creating custom controls on the page to control a gallery.

Given the following configuration code:

Here's the documentation for instance.navigate() that lets you control it on demand:

Public Method Description

instance.navigate(keyword)

Goes to a specific slide, move forward or back, or play/pause a gallery on demand. The method supports a single keyword parameter that can contain the following values:

"prev": Moves gallery backwards by 1 slide.
"next": Moves gallery forward by 1 slide.
integer: An integer specifying the slide to go to, where 0=1st slide, 1=2nd etc.
"pause/play": String that causes gallery to pause if it's playing, and visa versa.

For example:

<div id="simplegallery"></div>

<ul>
<li><a href="javascript:mygallery.navigate('next')">Next Slide</a></li>
<li><a href="javascript:mygallery.navigate('prev')">Previous Slide</a></li>
<li><a href="javascript:mygallery.navigate(0)">Go to 1st Slide</a></li>
<li><a href="javascript:mygallery.navigate('playpause')">Play/ Pause Gallery</a></li>
</ul>

"`oninit()`" and "`onslide`" event handlers: Running your own code after each slide change

Want to run your own code each time a slide changes in your gallery? The "onslide" event handler, which is defined as the last parameter when calling new simpleGallery(), lets you do that.

"
"
fadeduration: 1000, //transition duration (milliseconds)
onslide:function(curslide, i){ //event that fires after each slide is shown
//your custom code here...
}
})

"onslide" fires at the end of the fade animation, after a slide has completely faded into view. When that happens, two parameters are passed into the event handler:

curslide: A DOM reference pointing to the DIV containing the current slide. For example, running alert(curslide.innerHTML) would alert the entire HTML contents of the current slide.
i: An integer that reflects the current image being shown, where 0=1st image, 1=2nd etc.

Furthermore, the "this" keyword when used inside oninit() or onslide() points to the current gallery instance.

So how is this useful? Lets say you want to show some description for each slide somewhere outside the gallery itself on the page. Here's a simple example of that:

Getting everything to work is very simple. I define a custom JavaScript array containing the descriptions I want to show, then inside the onslide event hander populate a DIV with a particular description based on the index of the current image being shown:

var vacationtext=[
"The river looks beautiful at sunset.",
"A nice day to enjoy the city.",
"That's a lot of cheese I must say.",
"Most buildings in the city are just 4 or 5 stories tall."
]

var mygallery2=new simpleGallery({
wrapperid: "simplegallery2", //ID of main gallery container,
dimensions: [400, 265], //width/height of gallery in pixels. Should reflect dimensions of the images exactly
imagearray: [
["amster1.jpg", "http://en.wikipedia.org/wiki/Summer", "_new"],
["amster2.jpg", "http://en.wikipedia.org/wiki/Winter", ""],
["amster3.jpg", "", ""],
["amster4.jpg", "", ""]
],
autoplay: [false, 2500, 2], //[auto_play_boolean, delay_btw_slide_millisec, cycles_before_stopping_int]
persist: true,
fadeduration: 1000, //transition duration (milliseconds)
oninit:function(){ //event that fires when gallery has initialized/ ready to run
},
onslide:function(curslide, i){ //event that fires after each slide is shown
document.getElementById("myvacation").innerHTML=vacationtext[i]
}
})

The above assumes there is an empty DIV on the page with ID="myvacation" that will be used to contain the description shown.

On a related note, the "oninit" event handler 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. For example, to make our custom code inside the "onslide" event a little more efficient, we can cache the reference to the "myvacation" DIV when the page first loads, so subsequent requests to it is made on the cached variable. Here's the above example again, but streamlined:

pause: 3000, //pause between slides (milliseconds)
fadeduration: 1000, //transition duration (milliseconds)
oninit:function(){ //event that fires when gallery has initialized/ ready to run
vacationdiv=document.getElementById("myvacation")
},
onslide:function(curslide, i){ //event that fires after each slide is shown
vacationdiv.innerHTML=vacationtext[i]
}