Scroll your HTML with jquery.scrollable.js

05/22/2008 - Tero Piirainen, download version 0.11

Features

I want to take a bunch of HTML nodes and do following things with them

• make those items scrollable horizotally or vertically
• decide how many items are visible at once
• scroll elements with mouse, arrow keys and mousewheel (requires mousewheel.js)
• make navigational buttons without programming
• have programmatic actions: next, prev, nextPage, prevPage, seekTo, begin, end
• need to know when list is scrolled with custom event listener
• I want this all in single js file that weights only 3.9 Kb!

As we are on Flowplayer site I wanted to make a robust scrollable playlist. I crawled the web and I couldn't find a scrolling solution that does this obvious thing nice and easily - they were too complex to use. So I made it myself.

Simple example

Here's how it was done.

HTML code

<div id="scrollable">
	
	<div class="navi"></div>
	
	<a class="prev"></a>	
	
	<div class="items">
		<a>1</a>  <a>2</a>  <a>3</a>  <a>4</a>  <a>5</a>
		<a>6</a>  <a>7</a>  <a>8</a>  <a>9</a>  <a>10</a>
		<a>11</a> <a>12</a> <a>13</a> <a>14</a> <a>15</a>		
	</div>
	
	<a class="next"></a>
	
</div>

JavaScript

$("#scrollable").scrollable({items:'.items',horizontal:true});

CSS

Here is our external CSS file. All visuals and layout is done with CSS as it should be. This leaves you room for very different implementations. CSS coding is actually the biggest work and you should have more than basic understanding of it.

Usage

There are many other ways of using this tool than in previous example. Note that scrollable items can contain any HTML such as text, images, forms, video and any combination of those.

Simpliest example

Here is simpliest configuration that you can do with this tool.

<div id="scrollable">
	<a>1</a>  <a>2</a>  <a>3</a>  <a>4</a>  <a>5</a>
	<a>6</a>  <a>7</a>  <a>8</a>  <a>9</a>  <a>10</a>			
</div>

<script>
	$("#scrollable").scrollable();
</script>

This will use default values and there will be a vertically scrollable list with 5 items. Again you will use CSS to make this look the way you like. There are no next/prev buttons and navigators.

Full syntax

Here are all options and their default values that this tool supports

// selects one or more elements to be scrollable
$("JQUERY SELECTOR").scrollable({

	// default size is 5
	size: 5,
	
	// by default scrolling is done vertically as opposed to our example 
	horizontal:false,
	
	// default scrolling time in milliseconds 
	speed: 300,
	
	/* 
		default selector for nested element that will have 
		"move backwards" action automatically bind to it
	*/
	prev:'.prev',	
	
	// default selector for "move onwards" action
	next:'.next',
	
	/*
		default selector for nested element that will contain a navigator
		for swithing between pages. more about this in next chapter.
	*/
	navi:'.navi',
	
	// HTML element name for single navigational entry inside navigator
	naviItem:'span',	
	
	
	// CSS class name for clicked items and active naviItem elements
	activeClass:'active',
	
	/*
		Items are selected by this selector. If none is found items will
		be all elements that are directly nested under the root element 
	*/
	items: '.items',
	
	// a function that is triggered when items are scrolled
	onSeek: null
	
});

Using navigator

When you have lot's of elements in your list you may want to use navigator feature. It will navigate between the pages you have. This navigator knows what page you are currently viewing althought you might switch pages in other ways. Try using mousewheel in our example above.

You will place an element inside your container that will work as a navigator. By default you'll use class navi but this can be changed from the option. By default navigator it will be auto-populated with elements specified in naviItem option as follows

<div class="navi">
	<span page="0" class="active"></span>
	<span page="1" ></span>
	<span page="2" ></span>
	<span page="3" ></span>
</div>

The number of nested SPAN elements depends on the amount of items you have. Again it's up to you how you visualize those elements with CSS.

You can also use existing HTML as navigator items as well. Let's take an example

<!-- manual navigator configuration -->
<ul class="tabs">
	<li>First item</li>
	<li>Second item</li>
	<li>Third item</li>
</ul>

This can be made as navigator with following settings.

$("jquery selector").scrollable({

	// ul.tabs work now as our navigator
	navi:'ul.tabs'
});

Scripting API

You can build wildly different navigational systems with following JavaScript API calls.

// first select your scrollable with jQuery
var el = $("div.scrollable");

// seek one step forward
el.scrollable("next", [speed]);

// seek one step backward
el.scrollable("prev", [speed]);

// seek one page forward
el.scrollable("nextPage", [speed]);

// seek one page backward
el.scrollable("prevPage", [speed]);

// go to specific page (from zero to amount of pages)
el.scrollable("setPage", 1, [speed]);

// move two steps forward (negative number moves backward)
el.scrollable("move", 2, [speed]);

// seek to specific position (from zero to amount of elements)
el.scrollable("seekTo", 2, [speed]);

// go to first element
el.scrollable("begin", [speed]);

// go to last element
el.scrollable("end", [speed]);

Syntax follows to jQuery UI "unified API standard" where you first get handle to the element and then call method "against" it. Second argument is optional and it specifies the scrolling time.

note: If you are using Firebug you can play with the API using our example above. For example try following command in Firebug Console.

jQuery("#scrollable").scrollable("setPage", 1);

Demos

• scrollable playlist
• scrollable tabbed navigation

Browser support

• Firefox 1.5/2.0+
• Internet Explorer 5.5/6.0/7.0+
• Safari 2.0+
• Opera 9.0+

Download version 0.11

jquery.scrollable.min.js (minified version, 3.9 kb)

jquery.scrollable.js (source code, 6.3 kb)

Contact

Scrollable is a very new plugin and it has not been tested on every combination of browsers and operating systems. If you encounter problems please drop a bug report to support@flowplayer.org. An URL pointing to the problematic page is most useful.