In this article I will demonstrate how to implement the jQuery plugin TOC (Table of Contents) into your XPage and let your users select the section of the document they want to scroll to at the click of a link.

Introduction

When you are dealing with a long complex form and you need to open the document, edit one field and exit – it can be a pain to scroll down and find the section. Another frustration is having to scroll up and down the page comparing two different fields. The TOC jQuery plugin can help with this and it works especially well within the confines of the OneUI construct with the Left Column already provided as a perfect spot to put the menu.

The Demonstration

The demonstration can be found here

Download

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

What does it do?

Well the TOC plugin creates a “menu” of sorts on the page and allows the user to click on the menu and scroll to that place on the page.

The menu is created on the left and scrolls with the user – clicking on the link

Scrolls the user down the page to the section

Setting up the database

As with many of the jQuery plugins this one is very simple and easy to implement within your XPage. You first need to download jQuery and the TOC plugin and add them to your database.

jQuery TOC can be found here and the source code can be downloaded from here.

The latest version of jQuery can be downloaded from the jQuery.com website

The jQuery and TOC JavaScript libraries are added to the database through the WebContents folder. Change the Designer perspective to show the Package Explorer (Window–>Show Eclipse Views–>Package Explorer) and drag and drop the two libraries from your computer into the “js” folder. (You can see the demo database as an example)

The js libraries are added to our XPage Source as follows

	<script src="js/jquery-1.8.min.js" clientSide="true"></script>
	<script src="js/toc.js" clientSide="true"></script>

The CSS is added to our XPage like this

	<link rel="stylesheet" href="toc.css"/>

Adding TOC to our XPage

Instantiating TOC on the XPage uses code which looks like this. I just used the basics but I changed highlightOffsets to be 200 as I think that works better:

$('document').ready( function(){
	$('#toc').toc({
	    'selectors': '.inTOC', //elements to use as headings
	    'container': 'body', //element to find all selectors in
	    'smoothScrolling': true, //enable or disable smooth scrolling on click
	    'prefix': 'toc', //prefix for anchor tags and class names
	    'onHighlight': function(el) {}, //called when a new section is highlighted
	    'highlightOnScroll': true, //add class to heading that is currently in focus
	    'highlightOffset': 200, //offset to trigger the next headline
	    'anchorName': function(i, heading, prefix) { //custom function for anchor name
	        return prefix+i;
	    },
	    'headerText': function(i, heading, $heading) { //custom function building the header-item text
	        return $heading.text();
	    }
	});
});

Where #toc is a <div with id=”toc” as an attribute and .inTOC are the HTML elements (class=”inTOC”) which are used to determine the titles of the TOC and the sections on the webpage which they refer to. In my demo database you will find the toc <div> in the commonContainer custom control.

In my case I added a <Span to the page above the section I wanted – but to “hide” it from being seen I used a style. The reason I did this is because of the dijitTitlePane which did not lend itself well to being a selector for this purpose.

	<style>
		.inTOC {visibility: hidden;}
	</style>

	<xp:span styleClass="inTOC">Personal Information</xp:span>
	<xp:div id="titleChildren" dojoType="dijit.TitlePane" title="Personal Information" style="font-weight:bold">
		Panel contents
	</xp:div>

Scrolling up and down the page

A really nice feature of the TOC plugin is that when you scroll up and down the page the menu highlights to show that you are looking at that section. Can seem fairly obvious but that is a really nice touch for the user experience.

Overall

I really like this plugin – it is very simple, very, and fulfills a common requirement perfectly.

jQuery side note

As I have told many people my purpose of these jQuery in XPages examples is not to make you use them today – but when the requirement comes along you know it is there. Just this week my customer said to me that they wanted a menu on their LONG web form to be able to click on it and scroll to the section in question. I had seen the TOC plugin and bookmarked it a few months ago – I knew it existed and within 2 hours it was implemented within the design of their application.

2 hours !

And that is why jQuery rocks – not just the code itself but the fact that so many people have written so many cool plugins for the rest of us to take advantage of.