Who?
jqRevolve

Smooth-action Carousel Scrolling with jQuery


What?

jqRevolve is a plugin for jQuery to help you add scrolling content areas to your webpage(s).

Features;

Why?

I wanted a small, easy to understand and modify "carousel" scrolling compontent. There are plenty of other carousel-like plugins out there, however none had the basic auto-sizing and pressure-based scrolling features I needed.

If you like my plugins, please consider a dontation to support their development:

When?

Current Version: 2008.11.13 +r2
© 2008 Brice Burgess - released under both the MIT and GPL licenses.

Where?

Download the Development Plugin (jquery.revolve.js - 5.42k)
Download the Production Plugin (jquery.revolve.packed.js - 2.29k)

  ** requires [jQuery >= 1.2.0+]

If you need support or have comments, please post to the jQuery mailing list.

How?

Usage

To add a revolver to your website you must ...
1. Add Revolver Markup
Revolvers/Carousels traditionally consist of:
  1. A fixed width (or height) container known as a clip region. This is your "Revolver".
  2. Forward and Backward buttons that scroll content when clicked
  3. A content container within the clip region. This is typically wider (or taller) than the clip region.

See the 'HTML' tab of the below examples for reference.

NOTE: The clip region should have relative, fixed, or absolute positioning and MUST have its overflow style set to hidden. The content container MUST have absolute posistioning. jqRevolve will automatically enforce these CSS rules.
2. Initialize Revolver(s)
Call the $.jqRevolver() method on all revolver(s) added to your page. This will enable the component or alert you of errors encountered. This method will automatically enforce CSS rules [above note].

See the 'Javascript' tab of the below examples for reference.

3. Re-Initialize the Revolver whenever content changes
If a Revolver's content changes, you should refresh using the $.jqrRefresh() method. This will re-calculate the scrolling bounds, as well as best size the clip region (if autoSize is enabled).

Methods

jqRevolve
Initialize element(s) as Revolver components. Accepts a parameters object.

$('#revolver').jqRevolve();
$('.revolvers').jqRevolve({autoSize:false, content:'div.carouselContent'});

jqrRefresh
Called when a revolver's content changes. Recalculates scrolling bounds, and best sizes the clip region (if autoSize is enabled).

$('#revolver').jqrRefresh();
$('.revolvers').jqrRefresh();

Parameters

Parameters allow tailoring the behavior of any jqRevolve to your needs. They are passed on-the-fly as an object to the $.jqRevolve function.
autoSize
Resize the clip region to best fit its content. Height is adjusted for horizontal revolvers, width for vertical.

(boolean) - default: true

autoCenter
Automatically center content in the clip region *IF* it fits within the region.

(boolean) - default: true

startPos
Start position of content in percent (0-100). 100 = all the way forward, 0 = all the way backward.

(integer) - default: 0

maxSpeed
Maximum Scroll Speed (pixels scrolled per animation sequence)

(integer) - default: 230

next
Assigns passed element(s) as next button(s). Clicking scrolls the content forward. Accepts;
  • (string) A jQuery Selector
  • (object) A jQuery Collection
  • (object) A DOM element

(mixed) - default: '.revolve-next'

prev
Assigns passed element(s) as previous button(s). Clicking scrolls the content backward. Accepts;
  • (string) A jQuery Selector
  • (object) A jQuery Collection
  • (object) A DOM element

(mixed) - default: '.revolve-prev'

content
Assigns passed element(s) as content container(s). Accepts;
  • (string) A jQuery Selector
  • (object) A jQuery Collection
  • (object) A DOM element

(mixed) - default: '.revolve-content'

Examples

1. Defaults - Basic CSS Styling
jqRevolve - CLICK THE RED BLOCKS TO SCROLL THROUGH THIS CONTENT! AAAA BBBB CCCC DDDD EEEE FFFF GGGG HHHH IIII JJJJ KKKK LLLL MMMM NNNN OOOO PPPP QQQQ RRRR SSSS TTTT UUUU VVVV WWWW XXXX YYYY ZZZZ Viola! Fin.
Javascript 
$().ready(function(){
  $('#example1').jqRevolve();
});
CSS 
#example1 {
    /* MUST be relative or absolute! */
    /* Plugin will automatically set if not. */
    /* See example 2 CSS */
  position: relative; 
  
    /* MUST be hidden! */
    /* Plugin will automatically set if not. */  
    /* See example 2 CSS */
  overflow: hidden;
  
  width: 360px;
  margin: 10px 24px;
  border: 1px solid black;
}


#example1 .revolve-content {
    /* MUST be relative or absolute! */
    /* Plugin will automatically set if not. */
    /* See example 2 CSS */
  position: absolute;
  z-index: 5;
}

#example1 .revolve-next, #example1 .revolve-prev {
  position: absolute;
  background-color: red;
  width: 25px;
  height: 100%;
  z-index: 10;
}

#example1 .revolve-next { right: 0; }
HTML 
<div id="example1">
  <div class="revolve-next"></div>
  <div class="revolve-prev"></div>
  <div class="revolve-content">
    jqRevolve -
    CLICK
    THE
    RED
    BLOCKS
    TO
    SCROLL 
    THROUGH
    THIS
    CONTENT!
    
    AAAA  BBBB
    CCCC  DDDD
    EEEE  FFFF
    GGGG  HHHH
    IIII  JJJJ
    KKKK  LLLL
    MMMM  NNNN
    OOOO  PPPP
    QQQQ  RRRR
    SSSS  TTTT
    UUUU  VVVV
    WWWW  XXXX
    YYYY  ZZZZ
    
    Viola! Fin.
  </div>
</div>
2. startPos - Specifying a start position
jqRevolve - CLICK THE RED BLOCKS TO SCROLL THROUGH THIS CONTENT! AAAA BBBB CCCC DDDD EEEE FFFF GGGG HHHH IIII JJJJ KKKK LLLL MMMM NNNN OOOO PPPP QQQQ RRRR SSSS TTTT UUUU VVVV WWWW XXXX YYYY ZZZZ Viola! Fin.
Javascript 
$().ready(function(){
  // Start mid-way (50%) through content
  $('#example2').jqRevolve({startPos: 50});
});
CSS 
#example2 {
  width: 360px;
  margin: 10px 24px;
  border: 1px solid black;
}

#example2 .revolve-next, #example2 .revolve-prev {
  position: absolute;
  background-color: red;
  width: 25px;
  height: 100%;
  z-index: 10;
}

#example2 .revolve-next { right: 0; }
HTML 
<div id="example2">
  <div class="revolve-next"></div>
  <div class="revolve-prev"></div>
  <div class="revolve-content">
    jqRevolve -
    CLICK
    THE
    RED
    BLOCKS
    TO
    SCROLL 
    THROUGH
    THIS
    CONTENT!
    
    AAAA  BBBB
    CCCC  DDDD
    EEEE  FFFF
    GGGG  HHHH
    IIII  JJJJ
    KKKK  LLLL
    MMMM  NNNN
    OOOO  PPPP
    QQQQ  RRRR
    SSSS  TTTT
    UUUU  VVVV
    WWWW  XXXX
    YYYY  ZZZZ
    
    Viola! Fin.
  </div>
</div>
3. autoCenter - Center content if it fits within the clip region
Javascript 
$().ready(function(){
  $('#example3 div.doNotCenter').jqRevolve({autoCenter: false});
  $('#example3 div.doCenter').jqRevolve({autoCenter: true}); // default
});
CSS 
#example3 div.carousel {
    /* MUST be relative or absolute! */
    /* Plugin will automatically set if not. */
    /* See example 2 CSS */
  position: relative; 
  
    /* MUST be hidden! */
    /* Plugin will automatically set if not. */
    /* See example 2 CSS */
  overflow: hidden;
  
  width: 520px;
  margin: 10px 24px;
  border: 1px solid black;
}

#example3 .revolve-content {
    /* MUST be relative or absolute! */
    /* Plugin will automatically set if not. */
    /* See example 2 CSS */
  position: absolute;
  z-index: 5;
}

#example3 .revolve-next, #example3 .revolve-prev {
  position: absolute;
  background-color: blue;
  width: 25px;
  height: 100%;
  z-index: 10;
}

#example3 .revolve-next { right: 0; }
HTML 
<div id="example3">
  <div class="carousel doNotCenter">
    <div class="revolve-next"></div>
    <div class="revolve-prev"></div>
    <div class="revolve-content">
      <img src="drink.jpg" />
    </div>
  </div>
  
  <div class="carousel doCenter">
    <div class="revolve-next"></div>
    <div class="revolve-prev"></div>
    <div class="revolve-content">
      <img src="drink.jpg" />
    </div>
  </div>
  
</div>
4. autoSize - Set appropriate height of clip region based on content
Javascript 
$().ready(function(){
  $('#example4 div.doNotAutoSize').jqRevolve({autoSize: false});
  $('#example4 div.doAutoSize').jqRevolve({autoSize: true}); // default
});
CSS 
#example4 div.carousel {
  width: 520px;
  
  margin: 10px 24px;
  border: 1px solid black;
  
  height: 20px; /* FIXED HEIGHT - LOOK! */
}

#example4 .revolve-next, #example4 .revolve-prev {
  position: absolute;
  background-color: blue;
  width: 25px;
  height: 100%;
  z-index: 10;
}

#example4 .revolve-next { right: 0; }
HTML 
<div id="example4">
  <div class="carousel doNotAutoSize">
    <div class="revolve-next"></div>
    <div class="revolve-prev"></div>
    <div class="revolve-content">
      <img src="drink.jpg" />
    </div>
  </div>
  
  <div class="carousel doAutoSize">
    <div class="revolve-next"></div>
    <div class="revolve-prev"></div>
    <div class="revolve-content">
      <img src="drink.jpg" />
    </div>
  </div>
  
</div>
5. maxSpeed - Set Maximum Speed (pixels scrolled per animation sequence)
><(({°> ><(({°> Start... ><(({°> Fin. ><(({°> ><(({°>
Javascript 
$().ready(function(){
  $('#example5').jqRevolve({maxSpeed: 25}); // slow
});
CSS 
#example5 {
  width: 520px;
  
  margin: 10px 24px;
  border: 1px solid black;
}

#example5 .revolve-content img { vertical-align: middle; }

#example5 .revolve-next, #example5 .revolve-prev {
  position: absolute;
  background-color: green;
  width: 25px;
  height: 100%;
  z-index: 10;
}

#example5 .revolve-next { right: 0; }
HTML 
<div id="example5">
  <div class="revolve-next"></div>
  <div class="revolve-prev"></div>
  <div class="revolve-content">
    &gt;&lt;(({°&gt;
    
    &gt;&lt;(({°&gt;
    
    Start...
    
    <img src="drink.jpg" />
    
    &gt;&lt;(({°&gt;
    
    <img src="drink.jpg" />
    
    
    Fin.
    
    &gt;&lt;(({°&gt;
    
    &gt;&lt;(({°&gt;
  </div>
</div>
6. jqrRefresh method - Update the content area of a jqRevolver (will resize the clip region as necessary. NOTE: Uses the Flickr.com API)
Populate Me! Click "Update Content"...
Javascript 
$().ready(function(){
  $('#example6').jqRevolve({autoSize: true});
  
  $('#updateExample6').click(function(){
    
    // Grab random images from Flickr.com
    $.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?tags="+getTag()+"&format=json&jsoncallback=?",
        function(data){
          
      // create new content placeholder
      var newContent = '';
      
      $.each(data.items, function(i,item){
      newContent += '<img src="'+item.media.m+'" /> &nbsp;'
            if ( i == 5 ) return false;
          });
      
      // update example 6 carousel with newContent
      $('#example6').jqrRefresh(newContent);
      
        });

  });
  
  // random tags for Flickr Service
  var tags = ['kitten','goldfish','puppy'],i=0;
  function getTag(){
    if(i == 3)
      i = 0;
    return tags[i++];
  }
});
CSS 
#example6 {
  width: 600px;
  
  margin: 10px 24px;
  border: 1px solid black;
}


#example6 .revolve-next, #example6 .revolve-prev {
  position: absolute;
  background-color: yellow;
  width: 25px;
  height: 100%;
  z-index: 10;
}

#example6 .revolve-next { right: 0; }

#updateExample6 {
  margin: 10px 60px;
}
HTML 
<div id="example6">
  <div class="revolve-next"></div>
  <div class="revolve-prev"></div>
  <div class="revolve-content">
    Populate Me! Click "Update Content"...
  </div>
  
</div>

<button id="updateExample6">Update Content</button>
7. Specifing components - Use jQuery selectors to specify next, previous, and content element(s).
backward
forward
Populated by Flickr.com
Javascript 
$().ready(function(){
  
  // initialize revolver
  $('#example7 div.revolve').jqRevolve({
    next: $('#example7 div.next-button')[0],
    prev: $('#example7 div.prev-button')[0]
  });
  
  // fill revolver content with random Flickr.com imagery
  $.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?tags=lemur&format=json&jsoncallback=?",
        function(data){
      $.each(data.items, function(i,item){
       $("<img/>").attr("src", item.media.m).appendTo("#example7 div.revolve-content");
            if ( i == 7 ) return false;
          });
      
      // refresh example 7's content [sizes to native height]
      $('#example7 div.revolve').jqrRefresh();
        }
  );
});
CSS 


/**** CLIP REGION  *****/
#example7 div.revolve { 
  position: relative;  /* must be relative or absolute */
  overflow: hidden;  /* necessary for revolver behavior */
  width: 300px;     /* width of clip region */

}


/* example7 specific styling [optional] */
#example7 div.revolve {
  clear: both;    
  margin: 10px 30px;
  border: 1px solid #000;
}

#example7 div.revolve img {
  vertical-align: middle;
}


/**** SCROLL COMPONENTS  *****/
#example7 div.button {
  float: left;
  
  text-align: center;
  color: #FFF;
  background: #000;
  cursor: pointer;
  
  margin: 10px 10px;
  padding: 0 30px;
}
HTML 
<div id="example7">
  
  
  <div class="prev-button button">backward</div>
  <div class="next-button button">forward</div>
  
  <div class="revolve">
    <div class="revolve-content">
      Populated by <a href="http://flickr.com">Flickr.com</a>
    </div>
  </div>
  
  
  
</div>

Etc.

Previous Releases

All revisions of jqRevolve are available are available here.
Known Issues, Pending Fixes
  • Support Vertical Scrolling
  • Incorporate Wrap-Around (true Carousel) Feature
  • Add Callbacks [before scroll, after scroll]
  • Add a Scroll Bar / Progress Bar
  • Add mouseOver parameter to automatically start scrolling when next/previous elements are moused over
R2 Changes
  • Enhanced scrolling routine - use a sigmoid curve for pressure calculation
  • Fixed autoSizing under Linux Firefox, Safari.
  • Code cleanups, enhanced readability
R1 Changes
  • Initial Revision
Earlier Release Changes


Contributing;

If you come up with any cool designs or themes for jqRevolve, please feel free to share! Email your submissions, changes, or bug reports to <bhb@iceburg.net>.