In this article I will describe how to implement and use the nanoScroller jQuery plugin to create discrete, feature full scroll bars within your XPages applications.

Demonstration

The XPages integration of nanoScroller.js is demonstrated here

As the short video demonstrates below – with 5 lines of code you can turn an ugly scrollbar in the middle of the page to a modern looking scrolling capability which is certain to impress clients.

Music: In Flames – Where The Dead Ships Dwell (The Qemists Remix)

Download

The demonstration database can be downloaded from the link above or from here

nanoScroller.js

Introduction

“nanoScroller.js is a jQuery plugin that offers a simplistic way of implementing Mac OS X Lion-styled scrollbars for your website. It uses minimal HTML markup being .nano > .content. The other scrollbar div elements .pane > .slider are added during run time to prevent clutter in templating. The latest version utilizes native scrolling and works with the iPad, iPhone, and some Android Tablets.”

As you can see from the picture below – the nanoScroller allows for a discrete, easy to style/configure scrollbar to be added to a panel within your XPages.

For my personal development, finding this is a game changer – seriously that important – having a normal scrollbar in the middle of the screen is always undesirable and confusing to a user – this is AWESOME !

How Does it work?

We add the jQuery library and the nanoScroller.js library file(s) to the database by adding them to the Web-Contents folder accessible via the package explorer.  (Window–>Show Eclipse Views–>Package Explorer) and drag and drop the two libraries from your computer into the “js” folder.

We add the libraries to our XPages like this in the source panel

	<link rel="stylesheet" href="css/nanoscroller/nanoscroller.css"></link>
	<link rel="stylesheet" href="css/nanoscroller/main.css"></link>
	<link rel="stylesheet" href="css/nanoscroller/style.css"></link>

	<script src="js/nanoScroller/jquery.nanoscroller.min.js"></script>
	<script src="js/nanoScroller/jquery.js"></script>
	<script src="js/nanoScroller/overthrow.min.js"></script>

I have to admit that I had some issues implementing the examples myself – so I copied and pasted the example from the nanoScroller demonstration page and then started hacking out the pieces I didn’t need down to the basic shell.

<div id="main">
    <div class="nano">
      <div class="overthrow content description">
            YOUR CODE HERE
      </div>
    </div>
</div>

I then inserted my ViewPanel right int he middle there – nothing more complicated that that.

The basic nanoScroller capability is then created using the following code on the XPages source panel

	$(function(){
	  $('.nano').nanoScroller({
	    preventPageScrolling: true
	  });
	});

Note: for those of you wondering what $(function(){ is…it is just an anonymous JavaScript function same as this….

	  $('.nano').nanoScroller({
	    preventPageScrolling: true
	  });

Except that because it is wrapped in a function it makes it anonymous – frankly IMHO unless you are writing your whole application in JavaScript then who cares – but some very influential people in the JavaScript world do 🙂 Check this video out for a great explanation of why you should use these in Javascript development Paul Irish’s 10 things I learned from the jQuery source

Extra Cool functionality

As you can glean from the documentation nanoScroller has multiple events/properties which you have access to which make this even more of a slam dunk when it comes to replacing the way you have used scrollbars before. Here are two examples:

scrollend

  $(".nano").bind("scrollend", function(e){
    alert('You have reached the end');
    $("[id$='button1']").css('display', 'block')
  });

A simple Use Case for Binding the scrollend event would be when you have some Terms of Service and you wanted to make sure that the user had scrolled to the end of the agreement before they click the “I Accept” option. In the example I just use an alert and used it to make visible the accept button.

iOSNativeScrolling

Enabling this option allows for the iOS5+ native scrollbar on your iPad (for example) to be displayed.

And there are many more – check out the documentation and excellent examples!!

Conclusion

As I said before and hopefully my enthusiasm shows in this article – this really is a game changer for me – sure the example styles need to be played with to fit your OneUI style sheet but that is not hard. The overall effect is so much more pleasing on the eye, takes up less space on the page and significantly improves the overall user experience.

There aren’t any plugins which I use in *every* project – but this may well become the first !