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.
Xomino 
Very nice Dr Mark. I’ll definitely be using that soon.
You’re welcome John – glad you like it mate 🙂
Thanks!
I’m redoing a “web 1.2” application I did many years ago, to “web 2.0” with XPages. I say “web 1.2”, since I added some jQuery stuff later on once it was built. The main forms are very long, and I think the TOC concept looks nice and will work much nicer than the traditional tabbed tables that the users are accustomed to seeing.
I’m somewhat new to XPages, but fluent enough in jQuery and building web applications in traditional Notes/Domino since 5.0 came out. Should be fun!
Thanks, again!
Steve in NYC
Let me know how it works out Steve – one thing to bear in mind – it does not work if you use CSS display:none – you must use the visibility:hidden which takes up space on the web page.
Thanks!
I have 8.5.3, UP1, and I’m using a Navigator in the ApplicationLayout as the main menu. I’ve added the jQuery & TOC files, CSS, and other things. I’ve added an ID to the Navigator, but that doesn’t seem to work. Included it in a div, but that seems to disable the navigation in the Navigator. Minor detail. =8P Mind you, I can’t seem to get the TOC to appear, even if I’m deciding not to hide it by default, so perhaps adding an ID to the Navigator might work after all.
Any suggestions on getting it to work within a Navigator? I’ll give it another go tomorrow.
Cheers!
Steve in NYC
“It hurts to be on the cutting edge.”
Thanks, Doc!
I was able to get it to work perfectly! 🙂 The form used to have a tabbedPanel, and I’ve slowly been moving some of the formTables into the sections of the form. A couple of the sections have subsections, so I’ll see if I can either redo how it’s done, or add other sections. Stay tuned…
In the meantime, I changed the “showMenu” code to a “toggleMenu” code. This will show or hide each menu…
function toggleMenu() {
$(‘.ui-accordion’).toggle()
$(‘#toc’).toggle()
}
Have a good weekend!
Steve in NYC
Hello!
I was finally able to show the clients what I’ve been doing to replace their big form, and they really like the TOC concept. Thanks!
I do have a question, though… Since I’m using an ApplicationLayout, there is a banner, links and some other stuff on top. I’d like to add a “Top” TOC item, which would go to the top of the webpage.
So, before the xe:layout, I added a inTOC span and a div, and tried to hide the div in many different ways (display:none, rendered=false, visibility:hidden, etc…). It’s still showing a couple of blank lines at the top of the webpage, above the ApplicationLayout.
I suppose I can add an old fashioned anchor tag, and change the TOC script to add a Top menu item. Any other ideas?
Thanks, in advance!
Steve in NYC
Steve – very happy to know you got some traction with it – thanks for sharing 🙂
I found that display:none did not work and the anchor had to be hidden using the visibility property. Yes unfortunately it does then leave a space – I wonder if that can be countered by sizing the anchor with small height. It might also be possible to absolutely position the anchor – not something I played with I am afraid.
Another option could be to just have a “Home” link above the TOC menu which is not specifically in the TOC which just uses a scrollTo method to move to the top of the page.
Hello!
I hope you had a nice time at Lotusphere! Err… I mean IBM Connect! It’ll take a while to get used to that. =8P
I found an issue that I haven’t been able to resolve yet, with the TOC type form. I’m using an ApplicationLayout, FormTables, and all sorts of ExtLib stuff for this project! Going well.
However, it seems that typeAhead’s don’t always work, and most date controls change formats. Date pickers are no longer shown, and the date fields become shorter and taller. Date formats change to “yyyy-mm-dd”, instead of the “dd/mm/yyyy” we use here.
Any ideas?
Thanks, in advance!
Steve in NYC
Awesome time thanks mate.
Are you sure that it is TOC which is causing the issue? If you load up FireBug you should be able to see for each element what CSS is affecting it.
If it is TOC then you have two choices: 1) modify the TOC stylesheet to be absolutely specific to the DIV you have dropped it into or 2) override the other styles which it is affecting. IT is open source after all and you have the rights to modify the code to do what you need it to. Hope that helps.
Hey, Doc!
Thanks for the advice, but it didn’t seem to have anything to do with the CSS. I would get a lot of dojo errors about the “dijit.TitlePane”. I’m also using the view picklist OpenNTF custom control, which suggests to set the XPage to use the dojo theme and to trigger dojo onLoad. Once I disabled those two dojo properties from the XPage, most everything worked fine! 🙂
The only thing that worked outside of the TOC, but didn’t work in it, is the typeAhead feature. I have a simple edit box, which uses typeAhead and is inside a formTable. I consistently get an error like “TypeError: _42f.url is undefined”. (Sometimes, it’s a different number).
Other than that, it’s working great! Any ideas for this one?
I know that it’s a big learning curve to learn XPages for a longtime Domino developer like me. It is nice that some things stay the same… I find that most issues with traditional Notes, and now, XPages can be fixed by clicking a checkbox somewhere. The trick is finding the proper checkbox. 😉
Thanks!
dijit.TitlePane started to give me some grief – so i switched to using an <xe:widgetContainer instead and that seemed to settle things down quite nicely.
_42f indicates a minified library – no chance of tracing that sucker unfortunately.
internet marketing
jQuery in XPages #14 – TOC (Create a menu to scroll to a form section) « Xomino
A major part of the appeal of the Samsung Galaxy S is its large 4 inch touchscreen, which utilises super AMOLED touchscreen technology, displaying up to 16M colours within a pixel
resolution of 480x 800 resulting in superb quality and clarity
of image display, making it perfect for viewing photos and video
files. Of course, the impact on the screen resolution is magnified on
such a large device as this. Subtitles’ size and sync are also adjustable to suit you.