Demo #1: Auto rotation enabled (every 3 seconds, 1 panel each time), left/right nav buttons enabled, persistence enabled.


Showing panels to

Demo #2: Wrap around disabled, left/right nav buttons enabled.


Current Panel: Total Panels:

Back 1 Panel Forward 1 Panel
To 1st Panel Forward 2 Panels

Demo #3: Variable content widths, left/right nav buttons disabled, moves 2 panels at a time.

1
2
3
4
5
6
7
Currently showing panels: to

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, which you need to download below (right click/ select "Save As"):

  1. stepcarousel.js (2 variables near the top you can customize)
  2. jquery-1.2.6.pack.js

Step 2: Add the following HTML to the <BODY> of your page, which corresponds to the HTML for the first demo you see above:

Select All

That's it for installation, but this script is only as good as your understanding of it, so time for some documentation.

Basic Set Up Information

The HTML for a Step Carousel viewer follows a set structure consisting of 3 levels of nested DIVs- the main "carousel" DIV, an inner "belt" DIV, finally followed by "panel" DIVs that each hold some actual content:

Sample Step Carousel HTML:

<div id="mygallery" class="stepcarousel">
<div class="belt">

<div class="panel">
Panel 1 content here...
</div>

<div class="panel">
Panel 2 content here...
</div>

<div class="panel">
Panel 3 content here...
</div>

</div>
</div>

   Visual interpretation:

Carousel DIV

Belt DIV

Panel DIV 1
Panel DIV 2
Panel DIV 3
Panel DIV 4 etc...

All the IDs and class names (in red above) can be arbitrary in their values, but must be defined for the script to know what's what. Each piece of content you wish to show would then be wrapped around its own "panel" DIV (in yellow), whether it's just an image, or rich HTML etc.

Moving on, we come to the sample HTML for the buttons/ links used to navigate a Step Carousel Viewer.

Sample HTML for Carousel Viewer navigation:

<p class="samplebuttons">
<a href="javascript:stepcarousel.stepBy('mygallery', -1)">Back 1 Panel</a> <a href="javascript:stepcarousel.stepBy('mygallery', 1)" style="margin-left: 80px">Forward 1 Panel</a> <br />

<a href="javascript:stepcarousel.stepTo('mygallery', 1)">To 1st Panel</a> <a href="javascript:stepcarousel.stepBy('mygallery', 2)" style="margin-left: 80px">Forward 2 Panels</a>
</p>

Simply call the two methods stepBy() or stepTo() using the ID of your Carousel Viewer plus how much to move by anywhere on your page.

Last but certainly not least, the initialization script and CSS in the HEAD of your page is what will transform the HTML into a Step Carousel Viewer:

Sample Step Carousel invocation code

<script type="text/javascript">

stepcarousel.setup({
galleryid: 'mygallery', //id of carousel DIV
beltclass: 'belt', //class of inner "belt" DIV containing all the panel DIVs
panelclass: 'panel', //class of panel DIVs each holding content
panelbehavior: {speed:300, wraparound:false, persist:true},
defaultbuttons: {enable: true, moveby: 1, leftnav: ['arrowl.gif', -10, 100], rightnav: ['arrowr.gif', -10, 100]},
statusvars: ['statusA', 'statusB', 'statusC'], // Register 3 "status" variables
contenttype: ['inline'] // content type <--No comma following the very last parameter, always!
})

</script>

   Sample Step Carousel CSS:

<style type="text/css">

.stepcarousel{
position: relative; /*leave this value alone*/
border: 20px solid navy;
overflow: scroll; /*leave this value alone*/
width: 280px;
height: 200px; /*Height should enough to fit largest content's height*/
}

.stepcarousel .belt{
position: absolute; /*leave this value alone*/
left: 0;
top: 0;
}

.stepcarousel .panel{
float: left; /*leave this value alone*/
overflow: hidden; /*clip content that go outside dimensions of holding panel DIV*/
margin: 15px; /*margin around each panel*/
width: 250px; /*Width of each panel holding each content. If removed, widths should be individually defined on each content DIV then. */
}

</style>

For the invocation code on your left, notice the first 3 parameters and their values in red, which should match up with the CSS class names you assigned to the DIVs in the HTML. The code supports other parameters, which we'll cover in detail later. On to the CSS code on your right, the 3 levels of DIVs- "carousel", "belt", and "panel" DIVs can be styled however you wish, but take note of the sideline comments on which ones should be left alone or treated with care. In particular, the "width" property in red deserves special attention:

width: 250px; /*Width of each panel holding each content. If removed, widths should be individually defined on each content DIV then. */
}

This property sets the width of each "panel" DIV (the ones in yellow visually above), and is required in the sense that the script needs to know in advanced the width of each panel. In the simplistic scenerio where all your panels can be the same width, you'd simply set the above property to the desired value and that's that. However, in the more common scenerio where your panels should be of differing widths, there's another way to set their widths that's flexible. See "Two ways to set panel widths" for more information.

Available stepcarousel.setup() parameters

The initialization code supports several parameters, although only the first three are required. Here they are in full force:

Parameter Description
galleryid: "galleryid"

Required

 Set this parameter to the ID attribute value of the outermost Carousel DIV.
beltclass: "belt_div_class"

Required

 Set this parameter to the CSS class of the main inner DIV that contains all the "panel" DIVs.
panelclass: "panel_divs_class"

Required

 Set this parameter to the shared CSS class of each "panel" DIV within the Carousel, which contains the actual contents.

Each panel DIV must have a width defined, either via global CSS or inline CSS, in order for the script to work properly! See "Two ways to set panel widths" for more information.
autostep: {enable:true, moveby:1, pause:3000}

v1.6 parameter

 Set this parameter to auto rotate the panels, specifying the number of panels to move each time, and pause between rotating. Note that during auto rotation, moving the mouse over the Carousel or the default buttons (if enabled) pauses it, while moving your mouse out resumes it again. Clicking on the Carousel stops auto rotation altogether. This parameter has 3 properties:
  1. enable: Boolean (true/ false) setting on whether to enable auto rotation.
  2. moveby: Number of panels to move by each time. Negative number moves panels backwards instead.
  3. pause: Pause between rotation in milliseconds.

Note that if autostep is enabled, this automatically sets "panelbehavior.wraparound:true" as well.
panelbehavior: {speed:300, wraparound:false, persist:true}

Required

 This parameter has 3 properties:
  1. speed: Sets the duration of the slide animation, in milliseconds. Lower=faster.
  2. wraparound: Boolean (true/ false) setting that sets whether the panels should wrap after reaching the two ends, or stop at the first/last panel.
  3. persist: Boolean (true/ false) setting on whether the last panel viewed within a browser session should be remembered and recalled upon the visitor's return.
defaultbuttons: {enable: true, moveby: 1, leftnav: ['arrowl.gif', -10, 100], rightnav: ['arrowr.gif', -10, 100]}

Required

 This parameter lets you enable/ disable two navigational images that are auto positioned to the left and right of the Carousel Viewer. You can further tweak each image's offsets from its default position. This parameter has 4 properties:
  1. enable: Boolean (true/ false) setting on whether to enable the two navigational images.
  2. moveby: Sets how many panels the Carousel should move by in either directions when the navigational buttons are clicked on (1=foward 1 panel, -1=back 1 panel etc).
  3. leftnav: An array containing the path to the left navigational image, plus any additional x and y offsets from its default location on the page (upper left corner of Carousel Viewer). For example: ['arrowl.gif', -10, 100]
  4. rightnav: An array containing the path to the right navigational image, plus any additional x and y offsets from its default location on the page (upper right corner of Carousel Viewer). For example: ['arrowr.gif', -10, 100]
statusvars: ["var1", "var2", "var3"] Optional parameter that lets you define 3 arbitrary but unique variable names to be used to store the currently shown panel (starting), currently shown panel (final), and finally, the total number of panels in this Carousel.

With the 3 variable names defined, you can also add 3 HTML elements on your page with the same 3 ID values that the script will use to show this information to your visitors.

See "Status Variables- "status1", "status2", and "status3" for full details.
contenttype: [contenttype, [filepath]] Optional parameter that lets you specify where your "panel" DIVs and the actual contents are located.. Defaults to "inline" which means they exist physically on the page (nested inside the main "Carousel" and "belt" DIVs.

You can move all the panel DIVs to an external file, and use Ajax to dynamically fetch them instead. In this case, set the 1st parameter to "ajax", and the 2nd to the full path to where the external file is located:

contenttype: ["ajax", "somefile.htm"]

When specifying an external content source, you can now empty all the panel DIVs on your page itself, and move that to the external file:

<div id="mygallery" class="stepcarousel">
<div class="belt">

//All panel DIVs removed!

</div>
</div>

somefile.htm should now contain:

<div class="panel">
Panel 1 content here...
</div>

<div class="panel">
Panel 2 content here...
</div>

<div class="panel">
Panel 3 content here...
</div>
oninit:function(){
 //custom code here
}		 Optional event handler that fires once as soon as a Carousel has finished initializing and is ready for user interaction. You can use this to run tasks that depend on the Carousel having finished loading:

oninit:function(){
 alert("Carousel Viewer has finished loading!")
 isloaded=true
}
onslide:function(){
 //custom code here
}		 Optional event handler that fires whenever the Carousel slides and completes going to a panel (such as after calling stepTo() and stepBy()). It's also fired 1 time when the Carousel has finished loading(similar to oninit()). Typically used in combination with the status variables (assuming you've defined them) to access the index number of the currently shown panels in your own scripts. For example, the below example uses the onslide() event handler plus the status variables to show in the browser's status bar which panels are currently being shown:

statusvars: ["startA", "startB", "total"],
onslide:function(){
 window.status="Currently showing panels "+startA+" through "+startB
}
onpanelclick:function(target){
 //custom code here.
}		 Optional event handler that fires whenever user clicks on one of the panels. A target parameter that contains the currently clicked on element (not necessarily the panel itself!) is automatically passed to your code. Using it, for example, you can easily have images within the Carousel pop up again in a new window when clicked on:

onpanelclick:function(target){
 if (target.tagName=="IMG") //if clicked on element is an image
  window.open(target.src, "", "width=900px, height=800px")
}

 

See "oninit(), onslide() and onpanelclick() event handlers" for full details.

Remember, all but the first 3 parameters above are optional depending on what features you need to use.

Public Navigation Methods

We haven't talked yet about how to add links on your page to navigate the panels within a Carousel Viewer. This is done by calling two public methods of the script:

Public Method Description
stepcarousel.stepBy('galleryid', steps)
 		 Increments a Carousel Viewer by x number of panels when invoked. The first parameter should be the ID of the Carousel Viewer itself, while the second an integer (1 or greater) indicating the number of panels you wish to step by. For example:

<a href="javascript:stepcarousel.stepBy('mygallery', 1)">Forward 1 panel</a>

<a href="javascript:stepcarousel.stepBy('mygallery', -1)">Back 1 panel</a>

<a href="javascript:stepcarousel.stepBy('mygallery', 2)">Forward 2 panels</a>

 
stepcarousel.stepTo('galleryid', index) Moves to a specific panel within a Carousel Viewer (count starts at 1). The first parameter should be the ID of the Carousel Viewer itself, while the second an integer (1 or greater) specifying the panel number to move to:

<a href="javascript:stepcarousel.stepTo('mygallery', 1)">Move to very first panel</a>

<a href="javascript:stepcarousel.stepTo('mygallery', 3)">Move to 3rd panel</a>

 

Table Of Contents

This script consists of an index page plus 4 supplementary pages: