XPages, jQuery, and Dojo - a new paradigm in Client Side JavaScript

Dr. Mark Roden - PSC Group

In this session we will take a deep look at how Dojo and jQuery can be used to easily manipulate the Document Model of your XPage. This truly opens up a new paradigm for solving every day development problems. Take back your web browser and significantly reduce your compatibility issues. We will look at several useful Tools to use in building your CSJS code, identify resources and illustrate effective methodologies for Client Side JavaScript development in XPages.

About Marky -

15 years Lotus Development Experience - All Web Development

5 years CSJS Libraries experience

3 Years jQuery experience
Taking Notes Podcast 157 - jQuery in XPages
Notes In 9 - ep 50 and 69
Twitter: @MarkyRoden

Full time XPages Developer Working for PSC Group Inc
jQuery mobile, XPages OneUI v2, jqPlot graphing dashboard, EXTJS filter grid


Why should you use a CSJS Library?

Using tools to debug CSJS

Dojo DOM Manipulation

How is jQuery any different than Dojo?

jQuery DOM Manipulation

Enhancing the user experience....


Why should you use a CSJS Library ?
	Don't Reinvent The Wheel
	Do More With Less Code
	Save Time -- You Don't Code Your Own OS, Do You?
	Chances Are, You Aren't The Expert
	Speed Thrills
	Avoid Cryptic JavaScript Base Code

What CSJS comes with XPages?

What Comes out of the box?

XPages 8.5.4	Dojo 1.7.2
XPages 8.5.3	Dojo 1.6
XPages 8.5.2	Dojo 1.4.3
XPages 8.5.1	Dojo 1.3.2

You should really go and see

Dojo in XPages - Where is it?

The simple answer is everywhere. Every button, action and effect all dojo

OneUI Styling
Date Picker TypeAhead Client Validation Partial Refresh Extension Library (Dojo disguised as a custom control)

We even create Client Side JavaScript (CSJS) using Server Side JavaScript (SSJS)

XPages gives us the ability to use SSJS in creating our CSJS. This gives us access to data at runtime
For example - some simple database information

<xp:button value="@DbName()" id="button3">
	<xp:eventHandler event="onclick" submit="false">
		  <![CDATA[alertD('#{javascript: @DbName()}')]]>

XPages Dojo Out of The Box

XPages gives us the ability to use some pretty sweet Dojo pre-formatted
for us to provide quick and easy to use functionality out of the box

The XPages extension library provides access to Dojo controls with little to zero
understanding required by the developer

8.5.3 also provides some neat tricks of its own

Using the pre-build Dojo capabilities

Here we have the XPages source code for creating an accordion and then "playing with it"

	<xe:alertAction loaded="true"
		text="Bye Bye !">

	<xe:dojofxSlideTo node="djAccordionContainer1"
		duration="1000" left="500" top="100">

	<xe:dojoFadeOut duration="1000"


Using the pre-build Dojo capabilities


IdE mail
Adriana Kerr
Alba Mendoza
Albert Dejesus

Using Tools to debug CSJS

Firebug -
The most popular and powerful web development tool

    Inspect HTML and modify style and layout in real-time
    Use the most advanced JavaScript debugger available for any browser
    Accurately analyze network usage and performance
    Extend Firebug and add features to make Firebug even more powerful
    Get the information you need to get it done with Firebug.

Firebug -

Select the Element
View the Document Model (DOM)
Change the DOM
Change the CSS
Write some JavaScript yourself!

Firebug - Debugging CSJS

Using "debugger" is your code
	Triggers the Script to stop the code execution so that you can 
	examine the variables and follow your code step by step

	Better than SSJS :)

Firebug - Debugging CSJS - using the console


Using the console give you a quick and easy way to prototype code
Without having to waste time with Build Test/Build Test cycles.

With all the other capabilities of Firebug this is a huge development time saver

Firebug - Debugging CSJS - REALLY using the console


Not only can we prototype code in the console we can also fix our code.

We can over-ride an existing function in the browser and change it to do 
our evil bidding.......yeah this is the scary part!

This allows us to either correct code - or create new code before copying 
it back into our XPage Source.

Firebug - Extending Firebug

There are multiple FireBug extensions like YSlow and FireQuery 
which will enhance the FireBug console and give you even more 
power in your CSJS development.

HTTPFox - Complimentary to FireBug

HTTPFox is a nice complimentary addition to your toolbox. In conjunction 
with FireBug no only can you see any changes which are made to the HTML in 
the console you can also see the HTTP calls made to the server. 

This is especially useful when considering ajax calls. Are they working?

Chrome Developer Tools

Chrome Developer Tools


Very similar in nature to FireBug but with a very nice 
visual representation of how the page downloads

IE Developer Tools

IE Developer Tools


Again similar to FireBug and Chrome Developer tools but very IE focused

** IE Browser compatibility Toggle **

IE9 is the first browser with a Console!

Firefox Web Developer Toolbar

Firefox Web Developer Toolbar 

Similar options to IE Developer Toolbar
Neat Edit HTML option to update mass changes to the web page

Dojo DOM manipulation

Document Model (DOM) manipulation is what happens all the time 
in XPages but you might not realize it.

Take the XPage TypeAhead for example. As the user hits the key:

The XPage knows to call the server using AJAX - how?
Takes the response - how?
Manipulates the DOM to show the results and then displays the selection - wow!

Dojo - Type Ahead - DOM manipulation

AJAX call to the server - shown with HTTPFox

DOM manipulation takes the response and add a new 
  <LI> to the HTML of the page - shown with FireBug

It is then displayed to the user in the form of a fancy dropdown

Dojo Getting a handle on the DOM - dojo.byId

When using a selector in Dojo - what is selected is returned is the DOM node

    var node = dojo.byId("someId");
    node.value = "Hi, World";

Dojo Getting a handle on the DOM - dojo.query

When using a selector in Dojo - what is selected is returned is the DOM node(s) as an array.

dojo.query('INPUT').style("color", "red");

// by class 

// by attributes 

// by tag type 

// first-children 
dojo.query("ul > li");

// odd table rows: 
dojo.query("table tr:nth-child(odd)");

// scoped to some other node as parent
dojo.query("", "someNode");

Dojo Manipulating the DOM -

Does what it says on the tin - it styles.....not sure what else to tell you..., {
	border: "1px solid red",

// Passing only an ID or node returns the computed style 
// object of the node:"thinger");

// Passing a node and a style property returns the current 
// normalized, computed value for that property:"thinger", "opacity"); // 1 by default

// Passing a node, a style property, and a value changes the 
// current display of the node and returns the new computed value"thinger", "opacity", 0.5); // == 0.5

// Passing a node, an object-style style property sets each of the 
// values in turn and returns the computed style object of the node:"thinger", {
        "opacity": 0.5,
        "border": "3px solid black",
        "height": "300px"

Dojo Manipulating the DOM - dojo.connect

Events in JavaScript or Dojo based applications are essential to making applications work. Connecting an event handler (function) to an element or an object is one of the most common things you will do when developing applications using Dojo. Dojo provides a simple API for connecting events via the dojo.connect function.

function helloPressed(){
 alert('You pressed the button');

function init(){
   button = dojo.byId('helloButton');
   button.innerHTML = "Ready - Click Me"
   dojo.connect(button, 'onclick', 'helloPressed');

Dojo Manipulating the DOM - dojo.attr

dojo.attr allows you to get and set an attribute of the DOM element - just remember not to break anything that XPages needs to function

button = dojo.query('[id$=helloButton77]')[0];
dojo.attr(button, {
	style: "border: 5px solid green",
	onclick: function(e){ helloPressed() }
dojo.query('[id$=helloButton77]')[0].innerHTML =  "Ready - Click me"

// set some node to have a new id
dojo.attr(someNode, "id", "newId");

// get the id of a node reference
var id = dojo.attr(someNode, "id");

// set multiple attributes at once:
dojo.attr(someNode, {
    onclick: function(e){ /* handler code */ }

Dojo Manipulating the DOM - dojo.nodeList-manipulate

Method extensions to dojo.NodeList/dojo.query that manipulate HTML.
These methods are intended to match the API naming and behavior as the similarly named methods in jQuery.


// Add a span that says Hello World after each div in the DOM
// by using the "after" method added by dojo.NodeList-manipulate
dojo.query("div").after("Hello World");





Dojo Manipulating the DOM -

The method is used to find nodes in the DOM and move them to a different point in the DOM tree


Here is my content - it is very content :)


Here is the about - it gets about :)

//get the dojo node for the div with the ID "content"
//and the paragraph with the ID "about"
var content = dojo.byId('content');
var about = dojo.byId('about');

//place the paragraph before the div, content, "before"); //there is an "after" as well
//place the paragraph as the first element inside the div, content, "first");
//replace the div with the paragraph, content, "replace");
//replace the *contents* of the div with the paragraph, content, "only");

Dojo Manipulating the DOM - dojo.destroy

dojo.destroy() - Does not do what it says on the tin - it destroys nodes not dojo ;)


Here is my content - it is very content :)


Here is the about - it gets about :)


How is jQuery any Different than Dojo?

jQuery is just another JavaScript library, same as Dojo right?

It is not as "mature" as Dojo

"jQuery is for building websites and Dojo is for building enterprise applications"
(Kitson Kelly - Dojo committer)

JQuery: A minimalist system focused primarily on operating on existing DOM 
structures, JQuery features a hybrid XPath/CSS query language (Dojo uses 
standard CSS 3 queries) and provides a rich set of options and operations 
on the results of these queries. JQuery packs Ajax, effects, and other 
utilities into a small core (beating all but MooTools). While there is no 
widget or package system in JQuery per sae, 3rd party component libraries 
are available which build on top of JQuery.

What is jQuery anyway?

A JavaScript library which simplifies the common every day web development tasks 
of Document Model manipulation, event handling, animation and ajax/JSON

Created: June 2006 by John Resig

Removes browser dependencies 

Used Everywhere

Open Source

Over 3000 plugins registered

Usage Stats

Used “everywhere”

57% of world’s top 10,000 websites use jQuery
Used by Microsoft .Net v4 as part of the ASP .NET Ajax framework
Some websites you probably know using jQuery

jQuery Resources
	Download the latest version
	Review the documentation
	Look through the Tutorials
	Fantastic working examples/code
	Example code
	Example builder
	~211,000 questions/answers tagged jQuery !
	(~4,500 questions tagged Dojo)
	(~600 questions tagged XPages)

jQuery Core

Selectors	-	("ELEMENT")	(".class")	("#idTag")	etc
Attributes	-	.attr()		.html()		.toggleClass()	etc
Traversing	-	.children()	.closest()	.find()		etc
Manipulation	-	.appendTo()	.css()		.val()		etc
CSS		-	.height()	.position()	.width()	etc
Events		-	.blur()		.bind()		.keypress()	etc	
Effects		-	.animate()	.fadeIn()	.slideToggle()	etc
Ajax		-	.get()		.getJSON()	.serialize()	etc
Utilities	-	.grep()		.each()		.inArray()	etc
Internals	-	.error()	.pushStack()	.context()	etc

jQuery UI

jQuery UI created to 2007 is the equivalent to dojo core widgets
	Effects (Animation)
	Date picker
	Modal Dialogs
	Drag and Drop (pre-HTML5)
	Something dojo does not have
	Simple way to style your widgets to your corporate colors

jQuery Mobile

A unified, HTML5-based user interface system for all popular mobile device platforms, built on the rock-solid jQuery and jQuery UI foundation. Its lightweight code is built with progressive enhancement, and has a flexible, easily themeable design.

Demo jQuery Mobile Page

jQuery DOM Manipulation

We all take Cascading Style Sheets (CSS) for granted - using a simple <style> we can manipulate all the matching elements on a page.
jQuery uses a different selection model to Dojo but is more than just CSS 3
The selection engine is available independently @

	INPUT	{border: 1px solid red} 
	TD	{background: #FFFFCC}

jQuery $

jQuery uses the $ notation to identify the "Selector" and then functions and callbacks to perform actions based on those selectors

	function showDemo(){
		$('INPUT').css('border', '1px solid red')
		$('TD').css('background', '#FFFFCC')

jQuery Selectors - node iteration

Because we are affecting all elements in the previous example you would normally just use a style sheet.

Using jQuery however we have control over node iteration and can cycle through the selected elements

	alert('The value of i: '+i)
		'border', '1px solid red'

jQuery Selectors - Narrowing the selection

Selectors can be cumulative - for example - give me all the INPUT fields within a certain DIV

The selector reads from left to right as the containers move from parent to children

In this case the "." signifies a class - just like a CSS style!

$('.demo INPUT').each(function(i){
	alert('The value of i: '+i)
		'border', '1px solid red'

jQuery Selectors - Returning the jQuery object

When using a selector in jQuery - what is selected is returned as a jQuery object

jQuery objects contain an array of the selected element nodes
Using the browser console we can see this

$('.jQueryDiv INPUT')

jQuery Selectors - Chaining

Chaining is a really powerful capability of the jQuery model

All methods can be chained together to perform multiple action on one selection

$('.chaining INPUT').css('border', '1px solid red').css('color', 'blue')

$('.thePhone INPUT')
	.css('border', '1px solid red')
	.closest('TR').css('background', '#FFFFCC')

jQuery Selectors - Common

Here are some alternate "selectors" - For more information google "jquery selector"

Attribute Selector: 
	prefix 		[name|="value"]
	any		[name*="value"]
	word selector	[name~="value"]
	ends with	[name$="value"]
	equals		[name="value"]
	not equals 	[name!="value"]
	starts with 	[name^="value"]
Id Selector

Class Selector

Element Selector

jQuery Selectors - Less Common

Here are some alternate "selectors" - For more information google "jquery selector"

Select the element at index n within the matched set.

Select all elements at an index greater than index within the matched set.

Selects all elements that are hidden.	

Selects all elements that are the last child of their parent.

Selects odd elements, zero-indexed. See also even() 

jQuery Selectors - Less Common

Here are some alternate "selectors" - For more information google "jquery selector"

Selects all elements that are the nth-child of their parent.

Selects all elements that do not match the given selector. 
:not() Selector

Selects all direct child elements specified by "child" of elements specified by "parent".
(“parent > child”)

Selects the combined results of all the specified selectors.
(“selector1, selector2, selectorN”)

Multiple Attribute Selector 

jQuery Selectors - Custom Selectors

jQuery's api allows you to define your own selectors for your own needs

<a rel="Marky" href="">Xomino</a>

$.expr[':'].withRel = function(obj){
  var $this = $(obj);
  return ($this.attr('rel') != undefined);

function getMailLink(){
	$("a:withRel").css("color", "red");

Hello World in jQuery

Saying Hello world is the basic starting point for almost all programming languages. jQuery itself is not a programming language.

In JavaScript you would normally just do an alert box which is not user friendly - in jQuery we can "improve" on the user experience....

<script> alert('Hello World') </script>


Adding animation

Your imagination is the only thing stopping you from using animation in your XPage....
and possibly taste/common sense......but hey this is a demonstration.

  • Select everything with a class = hwButton

  • Animate a change to color = red and fontSize = 50px

  • Set a Delay of 1000ms

  • Run the effect "explode" over 3000ms

	function explodeButton(){
			.animate({ color: 'red', fontSize: '50px'})
			.effect( 'explode', {}, 3000, {}) 


The .slideToggle() method animates the height of the matched elements. This causes lower parts of the page to slide up or down, appearing to reveal or conceal the items. If the element is initially displayed, it will be hidden; if hidden, it will be shown.

<xp:div styleClass="reveal" id="showDiv">
	Your stuff HERE 

Nice Rows !

A nice way to enhance the user experience with tables is to provide alternate row coloring. This is simple within jQuery because we can

  • Select all the odd rows in the table

  • set a background color for each selected row

First nameLast nameE mailDelete

	$("#myTable TR:odd").css('background', '#DDDDFF')	

Nicer Rows !

Kicking it up a notch we can:

  • Select all the odd rows in the table

  • set a background color for each selected row

  • Toggle the yellowRow class on and off

First nameLast nameE mailDelete

$("#myTable TR:odd").css('background', '#DDDDFF')	
$("#myTable TR").hover(function(){

Nicest Rows ! (Dojo and jQuery working in harmony)

Here's where your user's expectation level is at:

  • Easy access to data - The XPages Repeat control and Pager

  • Easy readability - Color all the odd rows a different color

  • Interactivity - Toggle the yellowRow class on and off

  • Function - Click on theto delete the document

First namezLast nameE mailDelete

function nicestRows(){
	$(".myTable TR:odd").css('background', '#DDDDFF')	
	$(".myTable TR").hover(function(){

	$(".myTable IMG").on("click", function(){
		$(this).parents('tr').effect( 'highlight', '', 500, ''
	).fadeOut('slow') });

Drag And Drop

HTML5 provides the ability to drag and drop elements but jQuery has been doing it for years in ALL browsers.

  • Make something draggable

First nameLast nameE mailDelete


And Droppable

HTML5 provides the ability to drag and drop elements but jQuery has been doing it for years in ALL browsers.

Full NameEmail
Adriana Kerr
Alba Mendoza
Albert Dejesus
Alexandra Mays
Alexandria Roach

Drop here

	$( "#droppable" ).droppable({ 
	hoverClass: "ui-state-active", 
	drop: function( event, ui ) { 
		$( this )
			.addClass( "ui-state-highlight" ) 
			.find( "p" ) 
			.html("Dropped!" ); 

Controlling the Drop

By adding the UNID of the document in the repeat we are able to access the document properties.....

Full NameEmail
Adriana Kerr
Alba Mendoza
Albert Dejesus
Alexandra Mays
Alexandria Roach

Drop here

<xp:text escape="false">
		<xp:attr name="id" value="#{javascript:myPeople.getUniversalID()}">

Getting the Data to do the REST

Using a Dynamic REST service we can get back end data based on the Name as a lookup key

Full NameEmail

Drop here

			$( "#dialog-modal" ).html(data).dialog({
				height: 240,
				width: 400,
				modal: true

jQuery Plugins

Ultimately what is the point of DOM Manipulation? To enhance the user experience !

The jQuery community is much larger than dojo

jQuery plugins massively out number Dojo plugins 

Don't re-invent the wheel

Embrace the plugin!


In-line field helper text to set user expectation


This example was built using code created by Stuart Langridge -

<xp:eventHandler event="onClientLoad" submit="true" refreshMode="norefresh">
		x$("#{id:panel1}", " input").labelify({ 
			text: "label", labelledClass: "labelHighlight"  

			labelledClass: "labelField"

Masked Input

In-line field helper text to set user expectation (part deux)

(cannot enter a letter)

(999) 999-9999
(cannot enter a letter)

(cannot enter a letter)

(only accepts alphanumeric in the format shown)

$("[id$=phone6_3]").mask("(999) 999-9999");

TokenInput Autocomplete

Makes your dojo type ahead look like last year's news...

Plain Vanilla all defaults With facebook styling with custom labels

Searching a local JSON list
search for "a"

Twitter Feed (type Twitter id - e.g. xpages)

$(document).ready(function() {
	$("#[id$=inputText6_43]").tokenInput("xMWLUG_1.xsp/contactjson", {
		propertyToSearch: "email",
		theme: "facebook"


jQuery Vector Map - Just an amazing plugin

labels are turned off for US and Germany

		    map: '#{javascript: getComponent("comboBox6_6").getValue()}',
		    backgroundColor: '#333333',
		    color: '#ffffff',
		    hoverOpacity: 0.7,
		    selectedColor: '#666666',
		    enableZoom: true,
		    showTooltip: false,
		    values: sample_data,
		    scaleColors: ['#FFFFCC', '#336600'],
		    normalizeFunction: 'polynomial',

Pines Notify

A classier and more flexible way to talk to your users

You can change the delay in removing the popups
Current Timer:

Regular Error Non-Blocking Notice Shadow Notice Notice to Error To Info

Top Error Bar

Rich Notice

Sticky Error (won't close)

Lower Timer

	pnotify_title: 'Oh No!',
	pnotify_text: 'Something terrible happened.',
	pnotify_type: 'error'

Joy Ride

A really simple way to take your users round your application

  1. Add a New Image

    Apparently this functionality is available in the live demo :)

  2. A simple Lightbox

    You can produce a lightBox Slide show of the images by clicking on one of these

  3. See YouTube

    Clickin on the NotesIn9 image will show you an example of the prettyPhoto running a YouTube video.
    You can also include images in the popup!

  4. View Inline Content

    Clickin on the globe image will show you an example inline content within the prettyPhoto popup


Add a new image - only jpg, gif, png will be displayed 
Click on one of the images to view the slideshow

The example database contains a working version
MarkyWooo fireA RiversideYou know you want to buy this a man a pint....Who's a cutie?
Nin9 YouTube Video example

David Leady Rocks You Tube
Inline Content

Ajax content - prettyPhoto[ajax]
(content is loaded on the fly)

Ajax content

External Websites openned in an iFrame - prettyPhoto[iFrame]



No good reason other than a little Wow factor !

Adam Jane
Apples 6.0 9
Bananas 1.0 2
Oranges 2.0 4
Plantains 23.0 1

	$("#flipPad a").bind("click",function(){
		var $this = $(this);
		var thePanel = '[id$="'+$this.attr("thePanel")+'"]'
			direction: $this.attr("rel"),
			color: '#FFFFFF',
			content: $(thePanel).html()
		return false;

So what was he on about again? (In conclusion)

DOM Manipulation is not rocket science

There are over 100,000 questions tagged "jQuery" on StackOverflow

There are over 245,000 questions tagged "JavaScript" on StackOverflow

Use your imagination and make your user's experience better !

JavaScript libraries are NOT a new paradigm in web-development

Their out of the box inclusion in XPages IS a new paradigm

Use it :)


This presentation was made with Ascensor.js


HTML5, CSS3, Firefox 14, Firebug, HTTPFox, Chrome Developer Tools, IE developer tools,
Firefox DeveloperToolbar, jQuery and Dojo

and XPages!!!