You will recieve your password to this address. Address is not made public.

Your preferred username that is used when logging in.

jquery scrollable 0.13 Make your HTML elements scroll horizontally or vertically

Simple example

Use mouse, mousewheel or keyboard arrows to scroll through these elements.



1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

(Version 0.13)

Features

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

As we are on Flowplayer site a natural usage for this tool is 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 this tool was made. Enjoy.

Demos

Setup

This is how the example in the beginning of this page was done 

<!-- root element for scrollable -->
<div id="scrollable">

	<!-- those small round navigational buttons are auto- generated. styled with CSS -->
	<div class="navi"></div>

	<!-- "prev page" link is generated here. styling with CSS -->
	<a class="prev"></a>

	<!-- container for the scrollable items -->
	<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>

	<!-- "prev page" link -->
	<a class="next"></a>

</div>

<script>
	// all the magic is done with this single line of code
	$("#scrollable").scrollable();
</script>

CSS coding

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 just a basic understanding of it.

Usage

There are many other ways of using this tool than in previous example. It is important to realize that scrollable items can contain any HTML such as text, images, forms, video and any combination of those. Flowplayer home page is a good example of creative use of scrollable. The scrolling effect and tabbed navigation is setup with this tool without additional programming.

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 scrollable list with 5 items. Again you will use CSS to make this look the way you like. Scrollable will automatically detect whether your items should be scrolled vertically or horizontally. This detection is based on the width and height of the container. In this simple configuration 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,

	// set this to true when you want your items to be scrolled vertically
	vertical: 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',


	// a flag whether scrolling starts over when last item is exceeded
	loop: false,


	// 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. Inside this
		function this- variable points to the current scrollable instance
		and you can use it's API (described later)
	*/
	onSeek: null

});

Using navigator

When you have lots 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 although 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 and 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 by using these JavaScript API calls. 

/*
	retrieve scrollable's programming interface (API) by selecting
	the scrollable element and calling scrollable without arguments
*/
var api = $("div.scrollable:first").scrollable();

/*
	seek one step forward. This and other seeking functions support
	and an optional scrolling time as milliseconds.
*/
api.next();

// seek one step backward
api.prev();

// seek one page forward
api.nextPage();

// seek one page backward
api.prevPage();

// go to second page page. first page index is 0
api.setPage(1);

// move two steps forward (negative number moves backward)
api.move(2);

// seek to specific index. first item is 0
api.seekTo(2);

// go to first element. shortcut to seekTo(0);
api.begin();

// go to last element;
api.end();

/*
	return's status objecth wit following properties
		- index: current seek position
		- total: total amount of scrollable items
		- size: amount of items visible at once
		- pages: amount of pages
		- page: index number of the current page
*/
var status = api.getStatus();


// return's the version of this tool
api.getVersion();

This tool also supports a different kind of API similar to jQuery UI "unified API" where you can call scrollable methods in following manner 

$("#scrollable").scrollable("next", 200);

where first argument is the name of the function to be called and following arguments are supplied to the this function. This syntax is more messy and harder to understand but it has small benefit: the call will return the the same jQuery object that is returned by the selector so you can more easily nest your jQuery calls. Note that getStatus() function does not work with this "unified" syntax.

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

$("#scrollable").scrollable().setPage(1);

Custom event listener

You can perform a custom action when scrollable list is seeked backward or forward. This can be done with an onSeek property as follows. 

$("#scrollable").scrollable({
	onSeek: function()  {
		// this- variable is a pointer to the scrollable API
		alert("current page is " + this.getStatus().page);
	}
});

Browser support

Download version

jquery.scrollable-0.13.js source code
jquery.scrollable-0.13.min.js minified with Douglas Crockford's minifier

Please right-click and choose "Save link as..." (or similar)

See the version history for this tool.

The scripts shown here depend on the jQuery JavaScript library which can be downloaded from Google Code. It must be included on the page before any other JavaScript code.

You can alternately include jQuery directly from Google API's by including this script block before all other scripts: 

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>

This file is located on a content delivery network (CDN) so it's served fast and it is also GZIP:ed on your behalf dramatically reducing it's file size.

Found a bug?

If you encounter problems in this script, please send a bug report to the bug reporting forum. If you have a problematic page, including a direct URL to that page is by far the most effective way of helping us to find a bug.

•