IBM Connect13 Demos

Based on my presentation at IBM Connect 13 Jan 27-31st 2013 I have published my examples to my normal demo database. From there you can also download the sample database which contains working examples of all the code used.

http://demo.xomino.com/

Here is the final presentation on SlideShare

I will be updating this post with more information regarding the World’s largest XPage project shortly.

Thanks to all those who attended the sessions – it was a pleasure to interact and learn from all of you 🙂

jQuery in XPages #17 – nanoScroller (game changing – mini scrollbar)

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 !

nanoScroller applied to an XPages viewPanel
nanoScroller applied to an XPages viewPanel

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 !

jQuery in Xpages #16 – Avgrund (dialog depth perception)

In this article I will describe how to implement and use the Avgrund modal dialog which uses CSS transitions to give the effect of depth between the dialog and the page.

It is hard to believe that it has been two months since the last jQuery in XPages article – and for that I apologize. My current project requires most of my time to be away from the XPages DDE and as such the opportunity to find new and exciting plugins is decreased. But I came across this one today and figured I would take the time to write it up.

Demonstration

The XPages integration of avgrund.js is demonstrated here

Download

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

Avgrund.js

Introduction

Avgrund is a very simple 2k jQuery plugin which uses a CSS transition to shrink the visible page while displaying a modal dialog to the user. This gives the perception of depth between the page and dialog and a neat visual transition between the two. The plugin also uses IE alpha filters to fail back for IE<10 browsers which do not have CSS transition support (nice touch).

Avgrund dialog
Avgrund dialog

How does it work

We add the jQuery library and the avgrund.js library file 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 – the avgrund.js also comes with two sample CSS files for the demonstration.

	<script type="text/javascript" src="/xomino/jQinX.nsf/jquery-1.7.1.min.js"></script>
	<link rel="stylesheet" href="avgrund/style/style.css"></link>
	<link rel="stylesheet" href="avgrund/style/avgrund.css"></link>
	<script src="avgrund/js/jquery.avgrund.js"></script>

The plugin itself is very simple to instantiate and use, and the properties are self explanatory and well explained in the demo file:

	$('element').avgrund({
		width: 380, // max is 640px
		height: 280, // max is 350px
		showClose: false, // switch to 'true' for enabling close button
		showCloseText: '', // type your text for close button
		holderClass: '', // lets you name custom class for popin holder..
		overlayClass: '', // ..and overlay block
		enableStackAnimation: false, // another animation type
		onBlurContainer: '', // enables blur filter for specified block
		template: 'Your content goes here..'
	});

The CSS transition is contained within the avgrund.css file and amongst other things scales the page to 0.9 of it’s size when active. A blur effect is also applied for greater visual effect.

body.avgrund-active {
	-webkit-transform: scale(0.9);
	-moz-transform: scale(0.9);
	-ms-transform: scale(0.9);
	-o-transform: scale(0.9);
	transform: scale(0.9);
 /* overflow: hidden;  TIP: disables scrolling for long documents */
}
.avgrund-active .avgrund-blur {
	-webkit-filter: blur(1px);
	-moz-filter: blur(1px);
	-ms-filter: blur(1px);
	-o-filter: blur(1px);
	filter: blur(1px);
}

In this case the element in question is the Show button.

Demonstration

The XPages integration of avgrund.js is demonstrated here

 

jQuery in XPages #15 – Trunk8 (Adding “read more” to your paragraphs)

In this article I will describe how to implement and use the jQuery plugin Trunk8. “trunk8 is an intelligent text truncation extension to jQuery. When applied to a large block of text, trunk8 will cut off just enough text to prevent it from spilling over.”

Demonstration

The XPages integration of Trunk8.js is demonstrated here

Download

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

Trunk8.js

Introduction

Trunk8 is a really neat and simple jQuery plugin which can neaten up your XPages and provide a truncated paragraph of text and can turn large sections of text into something a little more manageable and easier on the eye:

Trunk8 your paragraphs
Trunk8 your paragraphs

How does it work

We add the jQuery library and the trunk8.js library file 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

<script type='text/javascript' src='/xomino/jQinX.nsf/jquery-1.7.1.min.js'></script>
<script type='text/javascript' src='/xomino/jQinX.nsf/js/trunk8.js'></script>

The trunk8.js plugin comes with a number of parameters which can help control how the plugin interacts with your page and how it displays the resulting trunk8ed text.

settings = {
    fill: '<a href='#'> read more </a>',  //this is what is inserted into the text as placeholder
    lines: 1, //the number of lines of orginal text displayed
    side: 'right', //the placement of the 'read more' left center right
    tooltip: true, //show a tooltip of the original text
    width: 'auto' // style the final text to fit the container.
}

We then apply the plugin to the page via a selector. In this example is I am going use the same viewPanel as, and this can be seen as an alternate to my original blog post regarding Dynamically expanding viewPanel rows.

We are going to select the 4th column in the viewPanel1 table

selecting the 4th column in the table
selecting the 4th column in the table

the jQuery selector for this is shown below – we select the viewPanel1 table by id an within that table we select the TR table rows and then within those the 4th TD table cell (i.e. the 4th column)

	$('[id$='viewPanel1'] tr td:nth-child(4)')

and then to that we apply the trunk8 method and its parameters

		<script>
			XSP.addOnLoad(function(){
				$('[id$='viewPanel1'] tr td:nth-child(4)').trunk8({
					fill: '<a href='#'> read more </a>',  //this is what is inserted into the text as placeholder
					lines: 3, //the number of lines of orginal text displayed
					side: 'right', //the placement of the 'read more' left center right
					tooltip: true, //show a tooltip of the original text
					width: 'auto' // style the final text to fit the container.
				});
			})
		</script>

And we get the following – much neater and easier on the user

Trunk8'd viewPanel column
Trunk8’d viewPanel column

Flexible

The parameters are fairly self explanatory and allow you to control the way the output looks. What I like about this plugin over others of a similar vein is that the width is dynamically calculated correctly and always fills the container. With a little more imagination you could have the “read more” link to a better tooltip or even click to open a dialog – because you can insert your own HTML the choice is yours – love it!

Conclusion

Every time I see a new plugin like this it just re-enforces to my why I evangelize using jQuery in XPages so much. It took me less than 10 minutes to implement the demonstration and took longer to write up this article. This is a real business requirement which is met with no effort at all on the part of the XPage developer. It’s a no brainer!

Demonstration

The XPages integration of Trunk8.js is demonstrated here

jQuery in XPages #14 – TOC (Create a menu to scroll to a form section)

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

Clicking on the TOC link
Clicking on the TOC link

Scrolls the user down the page to the section

Scrolls to the new section
Scrolls to the new 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.

 

 

jQuery in XPages #13 – Peity – Small charts in a big world

In this article I will demonstrate how you can easily include small charts inside your XPages. As the saying goes, sometimes a picture can speak louder than a thousand words and in this case it really can. Using Peity you can easily insert small, yet effective, charts into your XPages

Do  you know what percentage of  the blog posts on this site are XPages related?

 

Over 80% of them.

Demonstration

The XPages integration of Peity is demonstrated here

Download

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

Peity

Introduction

from the website

Peity

Peity is less than 5k in size and yet really imposes itself as a big visual improvement to any site. It is HTML5 based which as normal precludes any none-canvas supporting browser. But it does work in Chrome, Firefox, IE9+, Opera, Safari.  With it you can make pie, bar, line or even custom charts by simply adding your data to a <span> element and calling the plugin.

Check out the original Peity demo site for the full information on the plugin.

Peity is one of those jQuery plugins which does not itself use jQuery – but to make it available to the masses it has been wrapped as a jQuery plugin.

Examples

The basic format for creating a Pity image could not be simpler

	<span>1/5</span>

 

	$("span.pie").peity("pie")

How does it work?

The jQuery and Peity 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.7.1.min.js" clientSide="true"></script>
	<script src="js/jquery.peity.js" clientSide="true"></script>

The examples given on the plugin homepage show that the following options are available:

  • Chart Type with options
    • pie
      •  colours,diameter and delimeter
    • line
      • colourstrokeColourstrokeWidthdelimetermaxmin,width and height.
    • bar
      • colourdelimetermaxminwidth and height
    • custom

Size and color attributes

as an alternate to setting the colour and size using the function call you can add attributes to the chart

	<span data-colour="red" data-diameter="40">1/7</span>

Adding it to your XPage

In the example on the demo site I reused the highCharts fruit custom control to give me some data on the page. I haev added a chart to the page in two ways:

  • Using a DbLookup()
  • Using some jQuery to add the charts after loading
Integrating Peity charts into your XPage

The line chart is created by adding a computed field to the form. using the readonly=”true” parameter a SPAN is created by the XPage which is exactly what we need for the Peity chart.

The source code to create the line chart looks like this:

	<xp:inputText styleClass="line" id="inputText1" readonly="true">
		<xp:this.defaultValue><![CDATA[#{javascript:@DbColumn(@DbName(), "vwFruit", 2)}]]></xp:this.defaultValue>
	</xp:inputText>
	<script>
		$("[id$=inputText1]").peity("line")
	</script>

The Pie Charts are inserted into the viewPanel by using the following process:

  • Select all the table cells  in the 2nd column of the table (except for the first row)
  • Cycle through the values and total the column
  • Cycle through the table cells again and replace the Table contents with
    • The existing text and a SPAN (class .pie) containing the value / the total
  • Create the Peity pie charts for all matching elements (.pie)

And that looks like this in the code:

	var total=0
	var sTemp=""
	//get the total
	$("TABLE[id$=viewPanel1] TR:gt(0) td:nth-child(2)").each(function(i){
		total += parseInt($(this).text())
	})
	//replace the cell with the new contents
	$("TABLE[id$=viewPanel1] TR:gt(0) td:nth-child(2)").each(function(i){
		sTemp = $(this).text()+':    <span data-colour="red" data-diameter="20" class="pie">'+ $(this).text()+"/"+total+"</span>"
		$(this).html(sTemp)
	})
	//create all the Peity pie charts based on the .pie selector
	$(".pie").peity("pie", {
		colours: function() {
		    	return ["#dddddd", this.getAttribute("data-colour")]
		  	},
		diameter: function() {
		    return this.getAttribute("data-diameter")
		}
	  })

jQuery in XPages #12 – Flip.js (animated context changing)

In this article I will demonstrate how you can easily add a custom “Flip” to show different data on your XPage. This is a stylistic decision you have to make when creating your XPage. If you have a lot of Static data to fit on the screen and your user is ok not seeing all the same data at the same time this is a nice looking transition from one context to another.

Demonstration

The XPages integration of Flip.js is demonstrated here

Download

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

Flip.js

Introduction

Flip.js is a simple plugin which facilitates an aesthetically pleasing transition between data contexts on your XPage. The jQuery Plugin is capable of “flipping” context in 4 directions and also reverting back to the previous context display.

For more information flip.js check out their website – http://lab.smashup.it/flip/

Example

In my example I took the existing code which created my highcharts demo  and instead of showing both the data and the chart at the same time – I am flipping between them. This is a very simple demo and yet created a dynamic effect on the page for very little overhead (12k, 5k minified). As you can see from the video above the transition is “cute” and adds something appealing to the site.

How does it work

The demonstration site uses jQuery, jQueryUI which are already added to my demo site through a theme and the following files.

  • js/jquery.flip.js
  • css/flip_099.css

These files are added to the database via the WebContents folder as described in previous articles within this series.

jQuery and jQueryUI are referenced through the database theme as follows:

<theme extends="oneuiv2.1_onyx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="platform:/plugin/com.ibm.designer.domino.stylekits/schema/stylekit.xsd" >
	<resource>
		<content-type>application/x-javascript</content-type>
		<href>jquery-1.7.1.min.js</href>
 	</resource>
	<resource>
		<content-type>application/x-javascript</content-type>
		<href>js/jquery-ui-1.8.18.custom.min.js</href>
 	</resource>
 	<resource>
		<content-type>text/css</content-type>
		<href>css/custom-theme/jquery-ui-1.8.18.custom.css</href>
	</resource>
</theme>

The Flip.js files are added to the XPage via the following script/link files

	<script src="js/jquery.flip.js" clientSide="true"></script>
	<link rel="stylesheet" href="css/flip/flip_099.css" />

The XPage contains two main display elements – the flipbox and the the flipPad which controls the flipbox. As you can see from the code below the flipbox contains my chart data by default. The anchor tags have the following attributes:

  • rel
    • The direction of the flip (rl = right left, lr, ud=up down, du)
  • thePanel
    • The idTag of the element whose innerHTML will be displayed in the flip
<div id="flipPad">
	<a href="#" class="left" rel="rl" thePanel="panelFlip1" title="Show Chart" style="padding-right: 20px">
		Show Chart
	</a>
	<span>     </span>
	<a href="#" class="right" rel="lr" thePanel="panelFlip4" title="Show Data">Show Data</a>
</div>
<div id="flipbox" style="background: white; color: black">
	<xc:formFlip_Fruit_Data_Table></xc:formFlip_Fruit_Data_Table>
</div>

The Flip.js capabilities are then controlled by binding the jQuery functions to the anchor tags:

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

Here’s the English version of what’s happening in the above function:

  • For all a in the #flipPad
    • Bind the click event of the anchor tag to do the following:
    • Get the “thePanel” attribute from the anchor tag
      • [id$=”‘+$this.attr(“thePanel”)+'”]’ equates to
        • [id$=”panelFlip1″]
    • When the click event happens
      • Flip the flipbox in the “rel” direction
      • color the background white (returns from the gray flip color)
      • display the html() of the selected panel

And finally the panels on the XPage containing the chart and the data are custom controls (slightly modified from the original demonstration for this purpose)

	<xp:panel id="panelFlip1" style="display:none">
		<xc:formFlip_Fruit_Data></xc:formFlip_Fruit_Data>
	</xp:panel>

	<xp:panel id="panelFlip4" style="display:none">
		<xc:formFlip_Fruit_Data_Table></xc:formFlip_Fruit_Data_Table>
	</xp:panel>

Conclusion and The Next Step

As you can see form the demo this is a quick and simple, effective, way to add some animation to your XPage and kick things up a bit for the user. This demonstration uses static data which in many cases works, but in others you might want to retain the XPage functionality in your flip…..

The limiting factor for this demonstration is that it uses a COPY of the HTML within the panel container – what that means if that if you have a viewPanel with a pager, it will not work in this context because you are copying the HTML the XPage gets very confused if you try and then do something functional with it.

What would be a major step up would be to modify the plugin code to replace the flipbox with the object itself and not a copy of the HTML container. In that way you would be able to move the viewPanel and all its functionality in and out of the flip and it would retain all the paging functionality.

  • You’d need to create a container holding div with the panel objects within it.
  • You’d them pop the panel objects off the container object and append them to the flipbox
    • be careful that the select the whole panel and not the contents (a viewPanel creates an outer table around itself)
    • Suggest that each “panel” is wrapped with a div you know the id of – that way you don’t have to worry about all the dynamic HTML the XPage creates for the control.
  • when the user “flips”, you programmatically pop the panel in the flipbox back to the container and pop in the new object from the container

I am fairly positive that can be done but there are only so many hours in the day 🙂

jQuery in XPages #11 – Joyride.js (How to add a website feature tour)

In this article I will demonstrate how you can easily create a website feature tour using the Joyride.js jQuery plugin and XPages. When releasing a new site or new features within a site it is always a good idea to let your users know what’s new and why. This can be done in a number of ways, but Joyride provides a fun and interactive way of showing the new information and can be linked to the wiki or other more formal documentation you create with a release.

Demonstration

The XPages integration of Joyride.js is demonstrated here

Download

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

Joyride.js

Introduction

Have you ever released a new XPage or website and wanted to visually guide a user around the new features or capabilities? Well now you can with Joyridejs in your XPage.

“Joyride gives you everything you need to call out new features in your app or website. Joyride is extremely flexible and lets you take control of how people interact with your tour. ” – http://www.zurb.com/playground/jquery-joyride-feature-tour-plugin

Example

Example – Using my previous article about prettyPhoto.js as an example I can highlight to sections in a visually appealing way and guide new users around the page.

prettyPhoto original XPage
prettyPhoto original XPage

Becomes and interactive site with descriptions and popups showing users around:

Joyride introduction to the site #1
Joyride introduction to the site #1
Joyride introduction to the site #2
Joyride introduction to the site #2

How does it work?

We first have to add our libraries and CSS to the database. I have started to move away from using xp:resources in my source code because the XPage is trying to load the files every time we build and save the XPage which slows down development. I am using the <script> and </link> tags directly within the XPage source itself.

The files are added to the database in the WebContents folder as described in previous articles within this series

	<script src="js/jquery-1.7.2.min.js" clientSide="true"></script>
	<script src="js/jquery.joyride-1.0.3.js" clientSide="true"></script>
  	<link rel="stylesheet" href="css/JoyRide/joyride-1.0.3.css"/>
  	<link rel="stylesheet" href="css/JoyRide/demo-style.css"/>

This plugin is controlled by creating an ordered-list of the elements you wish to highlight and within that list you state the contents of the popup for that element.

The attributes of the list elements controls the functionality of the Joyride:

  • data-id
    • The idTag of the element you wish to display this popup on “addNew”
  • data-text
    • What do you want displayed in the button “Next”
  • class
    • Styling information
  • <h2>
    • The Title of the popup
  • <p>
    • the Text (or HTML) within the popup
  • data-options
    • Gives you more control of the look/feel of the popup “tipLocation:top;tipAnimation:fade”
  	<ol id="joyRideTipContent">
  	  <li data-id="addNew" data-text="Next" class="custom">
  	    <h2>Add a New Image</h2>
  	    <p>Apparently this functionality is available in the live demo :)</p>
  	  </li>
  	  <li data-id="clickOnOne" data-text="Click ME" data-options="tipLocation:top;tipAnimation:fade">
  	    <h2>A simple Lightbox</h2>
  	    <p>You can produce a lightBox Slide show of the images by clicking on one of these</p>
  	  </li>
  	  <li data-id="seeYouTube" data-text="Next">
  	    <h2>See YouTube</h2>
        <p>Clickin on the NotesIn9 image will show you an example of the prettyPhoto running a YouTube video</p>
  	  </li>
  	  <li data-id="inLine" data-text="Close">
  	    <h2>View Inline Content</h2>
        <p>Clickin on the NotesIn9 image will show you an example of the prettyPhoto running a YouTube video</p>
  	  </li>
  	</ol>

At the end of the code we add the activation of the Joyride – this can also be added to a button on the form if you don’t want it loading when the page loads.

	$(window).load(function() {
		$(this).joyride();
	});

Options

Joyride.js comes with a lot of options for changing the presentation of the popups – you will also notice that some of these options are stored within the data-options of the controller ordered-list. It provides another layer of flexibility for being able to control all the popups in the same way or individually depending on what effect you are looking for.

/* Setting your options to override the defaults */
$(this).joyride({
  'tipLocation': 'bottom',         // 'top' or 'bottom' in relation to parent
  'scrollSpeed': 300,              // Page scrolling speed in ms
  'timer': 2000,                   // 0 = off, all other numbers = time(ms )
  'startTimerOnClick': true,       // true/false to start timer on first click
  'nextButton': true,              // true/false for next button visibility
  'tipAnimation': 'pop',           // 'pop' or 'fade' in each tip
  'tipAnimationFadeSpeed': 300,    // if 'fade'- speed in ms of transition
  'cookieMonster': true,           // true/false for whether cookies are used
  'cookieName': 'JoyRide',         // choose your own cookie name
  'cookieDomain': false,           // set to false or yoursite.com
  'tipContainer': body,            // Where the tip be attached if not inline
  'inline': false,                 // true/false for inline positioning
  'tipContent': '#joyRideContent', // The ID of the <ol> used for content
  'postRideCallback': $noop,       // a method to call once the tour closes
  'postStepCallback': $noop        // A method to call after each step
});

Something to think about
You don’t want to show the tour to every user every time for the first week of the new website. There are a number of ways you could control this – how you do it is really up to you….

  • Provide the users a “Click Here” button to take the tour
  • Provide user an opt out option and track their selection in a notesdocument or a cookie.
    • When the user enters the application check the option and do not render the window.joyride() script to start the tour.

Conclusion

In less than 1 hour I was able to knock up the demonstration page for this article – in the real world though you would add this tour option into the website planning from the start. The tags which the tour is displayed on are not going to affect the site if they are not used and can be added as part of the overall design from the start.

These popups are also a very good way of providing helptext to a user.

This is a very simple and very useful plugin which I know has lots of applicability to our applications and customers.

Improve your typeAhead with “xTypeAheadify.js” – a jQuery plugin specifically for XPages

In this article I will introduce the xTypeAheadify.js jQuery plugin which I have created and submitted to openNTF.org. xTypeAheadify works in conjunction with the XPages typeAhead control to created an enhanced user experience above and beyond the out of the box control. The plugin is an evolution of the original enhancement I published back in February 2012.

I went down the path of creating a jQuery plugin rather than using an XPages custom control because of the power of the selectors. This method provides greater flexibility in assigning the plugin to specific fields and also allows for other enhancements via the jQuery chaining capability.

Introduction

The current out of the box XPages typeAhead control is a very simple and easy way for a developer to provide real-time lookup capability within their XPages. This capability meets lots of different use cases, simplifies the user interface and most importantly increases data fidelity. Unfortunately the capability falls a little short in overall user experience due to a lack of feedback to the user that a lookup is being performed and there is no indication that no results were found.

xTypeAheadify.js

xTypeAheadify adds the following fully customizable enhancements to the out of the box typeAhead control:

  • waitingIcon – A visual indicator when the user is typing to indicate a lookup is in progress
  • failIcon – A visual indicator to indicate to the user that no results are found
  • toolTipMsg – A optional popup message when no results are found to assist the user
  • tooTipPosition – A positional optional for the popup message
  • continueAfterFail – A option to prevent further typing once a non-matching string has been entered
  • visualTimeout – A timeout option allowing the developer to determine how long the icons are displayed for
xTypeAheadify custom waiting icon
xTypeAheadify custom waiting icon
The xTypeAhead custom icon showing no results and the visual popup message
Two examples of the xTypeAhead custom icon showing no results and the visual popup message

Demonstration

Click here to see working demonstrations of xTypeAheadify.js

Get the code

GitHub

The code is currently posted on github and can be checked out and modified by anyone who feels the need to 🙂

OpenNTF

The project is released on OpenNTF

http://www.openntf.org/internal/home.nsf/project.xsp?action=openDocument&name=xTypeAheadify.js

What is xTypeAheadify.js

xTypeAheadify.js is a JavaScript library which is added to your notes database as a JavaScript Library. It added to the XPage (along with jQuery) as an xp:resource

	<xp:this.resources>
		<xp:script src="js/jquery-1.7.1.min.js" clientSide="true"></xp:script>
		<xp:script src="/xTypeAheadify.js" clientSide="true"></xp:script>
	</xp:this.resources>

Default functionality

The plugin has five optional, customizable, parameters but in its most basic format the plugin is instantiated using one line of code. The following code will add a default waiting icon, default fail icon and default dojo popup to the inputText1 typeAhead field on the form.

			$("INPUT[id$='inputText1']").xTypeAheadify()

Chainable
The plugin is “chainable” and can be integrated into any standard jQuery method call chain

			$("INPUT[id$='inputText1']").xTypeAheadify().css('color', 'blue')
xTypeaheadify is a chainable plugin
xTypeaheadify is a chainable plugin

Customizable

Using the parameters described above and demonstrated below, the developer has control of what is displayed and when.  This code would be added as  XML markup at the bottom of your XPage source tab

<script>
	//This runs BEFORE the onLoad and before the dojo changes all the HTML
	//because we are getting ALL typeAheads then we need to set a flag to easily tag off
	//in this case the .getTypeAhead
	$("[dojoType$='TypeAhead']").addClass('getTypeAhead')
</script>

<xp:eventHandler event="onClientLoad" submit="false">
	<xp:this.script><![CDATA[
		$(".getTypeAhead INPUT[role='textbox']").xTypeAheadify({
			continueAfterFail: false,
			failIcon: 'Stop.png',
			waitingIcon : "loading.gif",
			visualTimeout : 5000,
			toolTipMsg : "You must select from the displayed list",
			toolTipPosition : "['above', 'after']" //"above", "below", "after", "before"
		})

	]]>
	</xp:this.script>
</xp:eventHandler>

How does it work?

I have added the xTypeAheadify.js to my demonstration database as a JavaScript Library rather than an attached js file. This is to facilitate easier reading of the code and easier accessibility for developers to make modifications to the code.

To start, we create a typeAhead field in your XPage in this case I created a field with an @dbColumn as the suggestions.

Creating a basic XPage typeAhead

We add the the xTypeAheadify.js either as a Javascript Library or a js attachment in the database.

Then you add your xTypeAheadify to your XPage in the onClientLoad event as shown below…..

Using selectors to add the plugin to the typeAhead fields

Individual Fields

You can either add the effect to the typeAhead field individually (where inputText1 is the name of your field)

<xp:eventHandler event="onClientLoad" submit="false">
	<xp:this.script><![CDATA[
		$("INPUT[id$='inputText1']").xTypeAheadify()
	]]></xp:this.script>
</xp:eventHandler>

To get more than one field by id we change the selector to select the fields using the comma to separate selectors (here selecting inputText1 and inputText3)

			$("INPUT[id$='inputText1'], INPUT[id$='inputText3']").xTypeAheadify()

All typeAhead Fields
We can select all on the page using the following code. This is more complex because it takes two steps to ensure we attach to just the typeAhead fields and not any other fields on the page. If you view the source of your XPage (with a typeAhead on it) you will see that there are attributes dojoType=”ibm.xsp.widget.layout.TypeAhead” on the fields. Unfortunately this is lost when the widget is instantiated onClientLoad. Using the initial

	$("[dojoType$='TypeAhead']").addClass('getTypeAhead')

 

<input type="text" id="view:_id1:_id2:_id47:inputText1" name="view:_id1:_id2:_id47:inputText1" style="font-size:12pt" class="xspInputFieldEditBox" dojoType="ibm.xsp.widget.layout.TypeAhead" store="view__id1__id2__id47_typeAhead1">1<br id="view:_id1:_id2:_id47:br1">

we are able to tag each typeAhead field with the getTypeAhead class. This in turn is transformed into the following code by the widget.

Then we are able to select in the onClientLoad using the class and the INPUT text box inside it

	$(".getTypeAhead INPUT[role='textbox']") //select all INPUT with attribute "role" inside the elements with class .getTypeAhead
Firebug display of the typeAhead field capability
Firebug display of the typeAhead field capability

Images

If you are adding images to the database yourself they should be added either as image resources or through the WebContents folder.

Event Handling

The plugin works by adding custom events to the selected field based on the user interaction with the page. The plugin adds the following:

  • onblur
    • triggered when the user clicks out of the field.
    • Removes visual indicators from the webpage
  • keydown
    • triggered when the user starts to type
    • displays the visual indicators if appropriate
    • check to see if a fail has been encountered and if the parameter is set – prevents further typing
  • keyup
    • checks to see if the field is blank and clears all visual indicators if they are displayed
  • onchange
    • if the user selects a value from the displayed list the visual indicators are removed

The plugin also intercepts the dojo xhr request to the database and if zero results are returned then a visual indicator is displayed along with e a dojo tooltip (if the parameters are set appropriately)

Source Control Code repository

The full code for the plugin is available on github and can be checked out and modified if you want to.

https://github.com/markyroden/xTypeAheadify/blob/master/xTypeAheadify.js

Conclusion

I hope that you will find use for this plugin. I have already received positive feedback from the customers who I have implemented the capability for and I look forward to hearing what you think and how it can be improved further.

Next?

This works nicely for single select typeAhead fields but the out of the box multiple typeAhead is, quite frankly, ugly…..adding a custom separator and just increasing the text in the field.

typeAhead multi-value separator
typeAhead multi-value separator

What I want to do is something like this…… just not today

xTypeAheadify the next version?
xTypeAheadify the next version?

jQuery in Xpages – development tip – using Firebug Console

In this article I will demonstrate how using Firebug can significantly reduce your development time with jQuery (or dojo) when you are trying to use selectors. There is no doubt that that out of the box functionality provided by XPages is very powerful, but to accomplish the capabilities we all know (and love?) the accompanying HTML is complex and not necessarily easy to navigate manually.

For more information on FireBug check this out

Things are busy at home and at work so I won’t have a plugin demonstration this week – just a development tip

Introduction
As I have discussed in this blog, using dojo and JQuery selectors are a very powerful way to facilitate “enhancing” your user experience with some nice UI changes. Many times however this can be a frustratingly slow process if you are doing trial and error development something like this:

  • Write your jQuery selector code in the XPage source panel
    • Save
    • Test In Webpage
      • Nothing happens
  • Change your jQuery code is XPage source panel
    • Save
    • Test in Webpage
      • Nothing happens
    • Curse
  • Change your jQuery code in XPage source Panel
  • Remember what it was like in the good old pre-XPages days
  • *sigh blissfully*
  • Curse
  • continue…..

Using the FireBug console we can significantly speed up this process by enacting real time changes to the webpage and not creating the XPage code until we know we have good working JavaScript.

Example

Here is a sample page with a typeAhead and a ViewPanel

typeAhead and ViewPanel
typeAhead and ViewPanel

and here’s our firebug console with a simple piece of jQuery code to change the css of all input fields, giving them a red border

  • Enter the text
  • Hit run
  • And there we have it – nothing happened ?!?
  • Curse
  • #FAIL 😦
fail
fail

What happened?

Well if you look over on the left you can see the jQuery object which has been returned

jQuery object returned
jQuery object returned

Clicking on it shows us the element and look it DID get set……..

Viewing the field through firebug
Viewing the field through firebug

What’s happening is that the INPUT we see is actually masked by DIV styles which are pegged as “!important” in the stylesheet and over-ride the inline style 😦 Can you imagine how long it would have taken you to figure that out just by looking at the code? Using FireBug has given us a quick insight into what’s going on….so if we want a red field then we have to traverse up the Document Model (DOM) tree and color the DIV containing the INPUT field…..

As you can see below I tried a few examples but could not get the field to color – and then I took too many parents and made all the DIVs red. it is also a fascinating way to see in real time how the jQuery DOM navigation works…..still I don’t have what I was looking for – a red field on its own 😦

Too many Red DIVS
Too many Red DIVS

Starting again if you look at the HTML in the DOM you can see what needs to be selected and we can make it red….select the DIV with the id ending in inputText1

  • yay !
A Red field!
A Red field!

Now of course you wouldn’t do this in real life – you would set a class and/or style on the field in the XPage client but this is a demonstration 😉

Coloring the viewPanel

We can use a CSS3 selector to style the nth column of the viewPanel – but unfortunately this does not work in IE

	<style>
		TABLE[id$='viewPanel1'] td:nth-child(3) {background-color: yellow}
	</style>
CSS fail in IE
CSS fail in IE

But jQuery rocks browser incompatibility issues and we can use firebug to get the right  jQuery and then apply it through the code to work in IE. Yes we used firebug to make sure the jQuery works – but this is jQuery and it is BUILT to overcome browser incompatibility issues. Instead of using the CSS3 nth-child selector, jQuery detects IE and trverses the table manually looking for the nth child in a loop – this is inefficient but the final effect is the same.

This is a big reason why you should use a library like jQuery or dojo – they were designed to help get around browser incompatibility problems.

jQuery CSS selector
jQuery in the firebug console
	<script>
		$("TABLE[id$='viewPanel1'] td:nth-child(3)").css('background-color', 'green')
	</script>
jQuery rocks around IE CSS support failure

 

Conclusion

I hope you enjoyed this quick(ish) tip. This only scratches the surface on FireBug and there is SO much more to learn/discuss !