CSS Codes
CSS Layouts
FF1+ IE7+ Opr9+

Step Carousel Viewer v2.0

 Author: Dynamic Drive

Note (Nov 25th, 14): v2.0 Adds support for fluid width carousel, navigate by swiping/ mouse dragging, and image-less navigation buttons. See changelog.

Description: Step Carousel Viewer displays images or even rich HTML by side scrolling them left or right. Users can step to any specific panel on demand, or browse the gallery sequentially by stepping through x number of panels each time. A smooth sliding animation is used to transition between steps. And fear not in taming this script to go exactly where you want it to- two public methods, two custom event handlers, and three "status" variables are here for that purpose. Some highlights of this script:

  • Contents for the Step Carousel Viewer can be defined either directly inline on the page or via Ajax and extracted from an external file instead.

  • Carousel supports a fixed or percentage outer width, enabling responsive carousels. v2.0 feature

  • Ability to specify whether panels should wrap after reaching the two ends, or stop at the first/last panel.

  • Carousel can be navigated by swiping (in mobile devices), or mouse dragging. v2.0 feature

  • Panel persistence supported, so the last viewed panel can be remembered and recalled within the same browser session.

  • Ability for Carousel to auto rotate as dictated by the new parameter: autostep: {enable:true, moveby:1, pause:3000} During this mode, Carousel pauses onMouseover, resumes onMouseout, and clicking Carousel halts auto rotation altogether.

  • Option to specify two navigational images that's automatically positioned to the left and right of the Carousel Viewer to move the panels back and forth.

  • Ability to auto generate pagination buttons based on the total number of panels within a Carousel and positioned anywhere on the page.  v2.0 improved feature

  • The contents of a Carousel can be updated on demand after the page has loaded with new contents from an external file.

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


Demo #2: Wrap around enabled ("slide"), left/right nav buttons enabled, pagination buttons enabled, status variables enabled.



Current Panel: Total Panels:

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

Demo #3: Wrap around enabled ("pushpull"), variable content widths, moves 2 panels at a time, illustration of new content loaded on demand.

1
2
3
4
5
6
7

Currently showing panels: to

Load New content into gallery

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. 3 images used as part of script's interface:

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 scenario 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 scenario 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, wrapbehavior:"pushpull|slide", persist:true}

Required

 This parameter has 4 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. wrapbehavior: Sets how the Carousel should wrap around to the first or last panel when the "wraparound" option above is set to true. The two supported values are: "pushpull" or "slide".  v1.9 option
  4. 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]

nmnm
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

Step Carousel supports 3 public methods you can call anywhere on the page to navigate to specific panels in a Carousel or modify its contents on demand. They are:

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>

 
stepcarousel.loadcontent('galleryid', 'path_to_file')

v1.8 method

 Dynamically repopulates a Carousel with new content from an external file on your server using Ajax. The external file should contain the HTML for the new panels themselves, such as:

somefile.htm

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

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

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

To update a Carousel with contents from this file, call stepcarousel.loadcontent() with the required two parameters:

<a href="javascript:stepcarousel.stepTo('mygallery', 'somefile.htm')">Modify Step Carousel contents</a>

The above link when clicked on will update the Carousel with ID "mygallery" with contents defined inside "somefile.htm" that's located in the same directory as the Carousel page itself.

See "Populating a Carousel using Ajax content (initially or on demand)" for full details.

Navigating via swipe and mouse dragging- setting the number of panels to move each time

Navigating by swiping on mobile devices and mouse dragging inside the carousel is built into the script. The number of panels that's moved each time this action is taken is tied up with the same setting inside the option defaultbuttons:{} above:

defaultbuttons: {enable: true, moveby: 1, leftnav: ['arrowl.gif', -10, 100], rightnav: ['arrowr.gif', -10, 100]}

The "moveby" option in red sets the number of panels the auto generated navigation buttons move each time they are clicked on; this option also sets the same for when the carousel is swiped.

Lets say you do NOT wish to enable the default navigation buttons but want to set the carousel swipe to move 2 panels at a time. The following defaultbuttons:{} option will do that:

defaultbuttons: {enable: false, moveby: 2, leftnav: ['arrowl.gif', -10, 100], rightnav: ['arrowr.gif', -10, 100]}

Table Of Contents

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

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