# jScrollPane

jScrollPane is a jquery plugin which allows you to replace the browsers default vertical scrollbars on any block level element with an overflow:auto style. You can easily control the apperance of the custom scrollbars using simple CSS.

jScrollPane is crossbrowser, working on all browsers that support jquery and it also degrades gracefully. If a user's browser doesn't support jQuery or has JavaScript turned off then they will see the browsers default scrollbars. If the mouse wheel plugin is included in the page then the scroll panes will respond to mouse wheel events as well.

jScrollPane is built on top of the awesome jQuery library and utilises the dimensions plugin and (optionally) the mouse wheel plugin.

## Usage

Just include the following files in the head of your page:

- jQuery (I'm using 1.1.1 here)
- the dimensions plugin
- the mouse wheel plugin (if you want mouse wheel support)
- jScrollPane.js (or the 4KB compressed version
- jScrollPane.css

Like so:

    <script type="text/javascript" src="jquery-1.0.4.js"></script>
    <script type="text/javascript" src="dimensions.js"></script>
    <script type="text/javascript" src="mousewheel.js"></script>
    <script type="text/javascript" src="jScrollPane-c.js"></script>
    <link rel="stylesheet" type="text/css" media="all" href="jScrollPane.css" />

Then you can use any query selector to select the elements you would like to apply jScrollPane and then initialise it. The following code runs when the document is ready and finds any element with a class of "scroll-pane" and then calls jScrollPane on them.

    $(function()
    {
    	$('.scroll-pane').jScrollPane();
    });

You can pass some optional parameters to the jScrollPane function. These take the form of an object with the following attributes:

- scrollbarWidth [int] - the width of the created scrollbar in pixels (defaults to 10)
- scrollbarMargin [int] - the margin to leave to the left of the scrollbar in pixels (defaults to 5)
- wheelSpeed [int] - controls how fast the mouse wheel makes the content scroll in pixels (defaults to 18)
- showArrows [boolean] - controls whether to display arrows for the user to scroll with (defaults to false)
- arrowSize [int] - the height of the arrow buttons if showArrows=true (calculated from CSS if not provided)
- animateTo [boolean] - whether to animate when calling scrollTo and scrollBy (defaults to false)
- dragMinHeight [int] - the minimum height to allow the drag bar to be (defaults to 0)
- dragMaxHeight [int] - the maximum height to allow the drag bar to be (defaults to 99999!)

## Downloads

You can download this plugin in a number of ways. Easiest is the zip file which contains all the files used in this example page. Alternatively you can download the indivdual files from the links above. jScrollPane.js is also available in the jQuery svn repository.

## Examples

There are now a number of examples of using jScrollPane - check the links directly below or the example below that...

- OS style scrollbars
- scrollTo functionality
- fullpage scroll

### #pane1

>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec condimentum pretium nisl. Integer quis tellus nec turpis placerat scelerisque. In semper lacus eu nisi. Praesent dignissim metus sit amet enim. Nam auctor, neque semper congue sagittis, risus mi commodo pede, nec euismod magna libero at sem. In enim magna, vestibulum et, blandit sit amet, tempor vel, ligula. Phasellus ante augue, congue vitae, faucibus quis, gravida sit amet, diam. Nullam congue accumsan magna. Etiam a nunc. Aliquam elit urna, ornare vitae, ultrices et, tempus non, nisl. Duis eros neque, luctus quis, interdum ultricies, auctor eu, urna. Donec nibh. Integer in purus tempus mi venenatis mollis. Cras nunc odio, porttitor at, accumsan ac, adipiscing vitae, ante.

Nam dui enim, fringilla vitae, rhoncus non, pharetra in, nunc. Sed a lectus vel orci bibendum placerat. Aliquam erat volutpat. Integer odio. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Duis dictum egestas lorem. Donec ultricies volutpat tellus. Phasellus justo arcu, pharetra eget, cursus non, consectetuer ac, nunc. Fusce orci tortor, semper vel, lacinia vitae, accumsan id, quam. Mauris semper molestie lectus. Duis venenatis erat ultrices nisl.

Morbi augue enim, ultricies nec, lobortis sed, iaculis eu, quam. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Curabitur sollicitudin, elit eu porttitor varius, tellus velit tristique sem, vitae blandit nisi eros id purus. Nunc non lorem. Nunc blandit purus nec nisi. Donec vulputate, urna vel interdum tristique, tellus mauris pretium lacus, quis sodales lectus nunc sit amet turpis. Suspendisse potenti. Fusce accumsan. Maecenas aliquam consectetuer augue. Fusce est neque, condimentum nec, condimentum vitae, consectetuer ac, tortor. Praesent ultricies urna in lectus. Nam erat nunc, venenatis nec, facilisis sed, feugiat ac, pede. Vivamus aliquam aliquet libero. Curabitur dolor nunc, scelerisque at, gravida dignissim, rutrum at, orci. Maecenas vitae libero id eros rutrum hendrerit. Duis lacinia mauris non erat. Nullam et dolor vel leo sollicitudin suscipit. Sed laoreet libero.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Praesent turpis. Suspendisse molestie, neque non congue ullamcorper, neque sem consequat nisl, eget pulvinar odio erat et tellus. Nunc luctus convallis dolor. Nullam non mauris. Etiam nisi magna, adipiscing eu, nonummy ac, laoreet nec, est. Pellentesque tristique, est vel condimentum feugiat, nisi justo rhoncus pede, in pulvinar mauris lectus vitae dui. Pellentesque scelerisque. Vestibulum tellus dolor, porta quis, facilisis nec, convallis vitae, quam. Quisque nisi. Nunc vitae nulla vel turpis mollis molestie. Etiam vitae massa.<

### #pane2

>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec condimentum pretium nisl. Integer quis tellus nec turpis placerat scelerisque. In semper lacus eu nisi. Praesent dignissim metus sit amet enim. Nam auctor, neque semper congue sagittis, risus mi commodo pede, nec euismod magna libero at sem. In enim magna, vestibulum et, blandit sit amet, tempor vel, ligula. Phasellus ante augue, congue vitae, faucibus quis, gravida sit amet, diam. Nullam congue accumsan magna. Etiam a nunc. Aliquam elit urna, ornare vitae, ultrices et, tempus non, nisl. Duis eros neque, luctus quis, interdum ultricies, auctor eu, urna. Donec nibh. Integer in purus tempus mi venenatis mollis. Cras nunc odio, porttitor at, accumsan ac, adipiscing vitae, ante.

Nam dui enim, fringilla vitae, rhoncus non, pharetra in, nunc. Sed a lectus vel orci bibendum placerat. Aliquam erat volutpat. Integer odio. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Duis dictum egestas lorem. Donec ultricies volutpat tellus. Phasellus justo arcu, pharetra eget, cursus non, consectetuer ac, nunc. Fusce orci tortor, semper vel, lacinia vitae, accumsan id, quam. Mauris semper molestie lectus. Duis venenatis erat ultrices nisl.

Morbi augue enim, ultricies nec, lobortis sed, iaculis eu, quam. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Curabitur sollicitudin, elit eu porttitor varius, tellus velit tristique sem, vitae blandit nisi eros id purus. Nunc non lorem. Nunc blandit purus nec nisi. Donec vulputate, urna vel interdum tristique, tellus mauris pretium lacus, quis sodales lectus nunc sit amet turpis. Suspendisse potenti. Fusce accumsan. Maecenas aliquam consectetuer augue. Fusce est neque, condimentum nec, condimentum vitae, consectetuer ac, tortor. Praesent ultricies urna in lectus. Nam erat nunc, venenatis nec, facilisis sed, feugiat ac, pede. Vivamus aliquam aliquet libero. Curabitur dolor nunc, scelerisque at, gravida dignissim, rutrum at, orci. Maecenas vitae libero id eros rutrum hendrerit. Duis lacinia mauris non erat. Nullam et dolor vel leo sollicitudin suscipit. Sed laoreet libero.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Praesent turpis. Suspendisse molestie, neque non congue ullamcorper, neque sem consequat nisl, eget pulvinar odio erat et tellus. Nunc luctus convallis dolor. Nullam non mauris. Etiam nisi magna, adipiscing eu, nonummy ac, laoreet nec, est. Pellentesque tristique, est vel condimentum feugiat, nisi justo rhoncus pede, in pulvinar mauris lectus vitae dui. Pellentesque scelerisque. Vestibulum tellus dolor, porta quis, facilisis nec, convallis vitae, quam. Quisque nisi. Nunc vitae nulla vel turpis mollis molestie. Etiam vitae massa.<

### #pane3

>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec condimentum pretium nisl. Integer quis tellus nec turpis placerat scelerisque. In semper lacus eu nisi. Praesent dignissim metus sit amet enim. Nam auctor, neque semper congue sagittis, risus mi commodo pede, nec euismod magna libero at sem. In enim magna, vestibulum et, blandit sit amet, tempor vel, ligula. Phasellus ante augue, congue vitae, faucibus quis, gravida sit amet, diam. Nullam congue accumsan magna. Etiam a nunc. Aliquam elit urna, ornare vitae, ultrices et, tempus non, nisl. Duis eros neque, luctus quis, interdum ultricies, auctor eu, urna. Donec nibh. Integer in purus tempus mi venenatis mollis. Cras nunc odio, porttitor at, accumsan ac, adipiscing vitae, ante.

Nam dui enim, fringilla vitae, rhoncus non, pharetra in, nunc. Sed a lectus vel orci bibendum placerat. Aliquam erat volutpat. Integer odio. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Duis dictum egestas lorem. Donec ultricies volutpat tellus. Phasellus justo arcu, pharetra eget, cursus non, consectetuer ac, nunc. Fusce orci tortor, semper vel, lacinia vitae, accumsan id, quam. Mauris semper molestie lectus. Duis venenatis erat ultrices nisl.

Morbi augue enim, ultricies nec, lobortis sed, iaculis eu, quam. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos. Curabitur sollicitudin, elit eu porttitor varius, tellus velit tristique sem, vitae blandit nisi eros id purus. Nunc non lorem. Nunc blandit purus nec nisi. Donec vulputate, urna vel interdum tristique, tellus mauris pretium lacus, quis sodales lectus nunc sit amet turpis. Suspendisse potenti. Fusce accumsan. Maecenas aliquam consectetuer augue. Fusce est neque, condimentum nec, condimentum vitae, consectetuer ac, tortor. Praesent ultricies urna in lectus. Nam erat nunc, venenatis nec, facilisis sed, feugiat ac, pede. Vivamus aliquam aliquet libero. Curabitur dolor nunc, scelerisque at, gravida dignissim, rutrum at, orci. Maecenas vitae libero id eros rutrum hendrerit. Duis lacinia mauris non erat. Nullam et dolor vel leo sollicitudin suscipit. Sed laoreet libero.

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Praesent turpis. Suspendisse molestie, neque non congue ullamcorper, neque sem consequat nisl, eget pulvinar odio erat et tellus. Nunc luctus convallis dolor. Nullam non mauris. Etiam nisi magna, adipiscing eu, nonummy ac, laoreet nec, est. Pellentesque tristique, est vel condimentum feugiat, nisi justo rhoncus pede, in pulvinar mauris lectus vitae dui. Pellentesque scelerisque. Vestibulum tellus dolor, porta quis, facilisis nec, convallis vitae, quam. Quisque nisi. Nunc vitae nulla vel turpis mollis molestie. Etiam vitae massa.<

### #pane4

>Lorem ipsum dolor sit amet.<

You can add more copy to pane4 by clicking here - this illustrates how to update the scrollbar when content is dynamically added to a page (e.g. as the result of an AJAX call). You can also reduce the amount of content in pane4 by clicking here.

Also, check out this example of jScrollPane providing scroll bars for the entire contents of a webpage. As you will see, this introduces some new challenges but can be made to work nicely...

AND, now there is scrollTo functionality so that you can control your jScrollPane from your page in general - the example shows how to hotlink paragraphs inside a scrollPane...

## Limitations

Because the element that you turn into a scrollpane is wrapped in another element you can't apply any positional styling to it. This is a shame but the problem is easily avoided by wrapping the element in another div with the positional styling on it (like the divs on this page with a class of holder).

## To do

This is a list of functionality I would like to add into the plugin:

- BUG: The "drag bars" are all the same height in IE6 currently.
- BUG: The width of pane4 in the above example shouldn't be effected by the call to jScrollPane.
- BUG: The mouse wheel amount shouldn't be effected by the amount of scrolling content.
- BUG: When you use the mouse wheel and the pane gets to it's end then the documents default scroll handler should be re-instated.
- You should be able to recalculate the size/ position etc of the scrollbars when the contents of the pane is updated.
- You should be able to click on an empty piece of the track and the pane should scroll towards that point.
- If you select text inside the scroll pane and drag then the pane should automatically scroll to keep your selection in view.
- You should be able to scroll the contents of a pane using the keyboard.