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
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')
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.
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
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.
What I want to do is something like this…… just not today
Xomino 