IBMSBT in XPages: Getting set up with a Social Business Toolkit (Part #1)

In this article I will begin to introduce IBM Social Business Toolkit (SBT), provide links on how to get it set up, talk briefly about how it works and then provide my first demo on how to get “My Files”.

The whole of this series will be based on “Smart cloud (now Connections Cloud)” as opposed to Connections on premises. This should not however really affect too much other than how you make the initial connection. After that the API is pretty much the same (for my purposes anyway).

Thank you Kathy Brown

Setting up SBT is not the easiest thing to do – nothing IBM ever is. But I owe a huge thank you to Kathy who did the bulk of the hard work on this. Setting this up locally for me was pretty simple once she knew how. Part of the reason for me writing it down as I said before is self documentation ‘cos I know I will forget 🙂

IBM SBT

Here are some links on how to set it up and configure it – you will have to install it on your server as well as in your Domino Designer.

Setting up on Domino Designer 

Download the latest code from OpenNTF (I used this one). Unzip the file locally and within there you will find the following folder

  • sbtsdk/redist/domino/

Within there you will find the com.ibm.sbt.domino.updatesite-1.0.3.20140723-1200.zip!. That is the file you need to reference when you install the feature into Domino Designer. (If you want to run the playground locally you will also need to install from the playground updatesite)

Setting up the server

Within the zip file references above you will find the features and plugins folders.

j1

Copy them and paste them onto your server in the following directory. The features and folders for the server are listed there.

DominoIstallPath\data\domino\workspace\applications\eclipse

I am sure there is a better “updatesite” way of doing it, but this worked for me *shrugs*

The XPagesSBT.nsf

The database within the zip file gives you some examples of how to work with the API and provides links and examples for the JavaScript API, Java API, XPages snippets and other examples. I am not going to use those examples. There is some cool out of the box feature but

  • The JavaScript API is far from complete (which is why I am learning Java)
  • The Java examples are not complete (which is why I am doing this from scratch)
  • The XPages examples and snippets are very “XPagey” and I would rather do it myself

The faces-config.xml

Now this is the one useful thing you should get from the XPagesSBT.nsf because it contains all the managed beans used by the SBT to connect to Connections Cloud (and Facebook and Twitter and others). In there you will find examples for connecting to smartcloud and connections. You will need these in your quest to create an SBT application.

You will find this file through the Package Explorer, in the WEB-INF folder

j2

Setting up Connections OAuth app

Setting up a Smart (Connections) Cloud “App” for OAuth

Within Connections Cloud, not much less ew, but at least all browser based. This is how to register your app and get the OAuth tokens.

j1

 

 

j2

j3

 

j4

j6

j7

 

In the next article we will actually create our first example to Authorize and pull personal data from Connections Cloud.

 

 

 

 

Advertisements

OpenNTF Webinar – Getting Started with XPages – Tomorrow – 06-04-2013 10:00 EST

Tomorrow I have the honour of speaking with my mate Dave Leedy and presenting the second in the OpenNTF webinar series – Getting Started with XPages

Dave and I are going to go through a lot of information in a short period of time. The intention is to make the transition to XPages seem less scary, provide you information you need to know when making the transition and help you through the process.

This conversation is open to all developers of all skill levels and I encourage community members to attend and support OpenNTF and all those developers tuning in to find out more on the subject.

We are going to talk about:

  • Key concepts in XPages
  • Some of the  things you always wanted to do in Old Domino (good for selling XPages to your manager)
  • A live demonstration of how easy it is to create an initial app in the same manner as you would before.
  • Discuss some Rookie mistakes we all make
  • Look at some tools which make your life infinitely easier as an XPages developer
  • Detail and list some essential online resources for finding more information on XPages

Attendance is free and no registration is required. 

You can attend the webinars by simply joining the following IBM SmartCloud meeting. The e-meeting supports audio broadcasting. In order to speak you need to dial in the conference separately.

https://apps.na.collabserv.com/meetings/join?id=065-675
Meeting password: ICSAppDev

https://www.teleconference.att.com/servlet/glbAccess?process=1&accessCode=71387162&accessNumber=06924432290#C2 
Passcode: 71387162

How to always show OneUI action buttons with a simple CSS trick

In this article I will show how your ExtLib Application Layout Control action buttons (OneUI) can remain on the page at all times with a simple CSS Trick.

The following was created using the Extension Library Application Layout control – with OneUI v2.1 using the silver theme.

Introduction

OneUI is a great, simple layout for a nice clean application layout without too much worry about CSS and other complicated design things. There are some nice examples on the OpenNTF site about using the OneUI layout. The http://xpages.info/XPagesHome.nsf/Home.xsp website uses the same layout and you can see for yourself how the top bars scroll out of the screen as you move down the page.

The buttons in the PlaceBar stay put as the page scrolls down – as the page gets larger this becomes more of a pain for the user to have to scroll back to the top to get to the Save button.

The desired effect

My requirement in modernizing my current R5 web based application was to keep the look and feel as close to the original frameset as possible. The buttons were in the top frame and therefore visible on the page at all times. Without wanting to revert back 15 years and use frames in the XPage I had to come up with a way to keep the buttons on the page at all times.

The initial look

The initial buttons look like this in the placebar – nothing spectacular to see here

Save and Cancel button
Save and Cancel button

 

Using what else – FireBug 

So I had to figure out first of all what the CSS was for the buttons and then if I could change them. Looking at the HTML in FireBug you can see that the buttons are in a DIV with two classes: .lotusPlaceBar and .lotusBtnContainer

Looking at the OneUI buttons in FireBug
Looking at the OneUI buttons in FireBug

 

Fixing the position

Fixing the position of the buttons is as simple as using “position: fixed” and then they stay in that place on the screen. I added some other styling to pad it a little, and move at away from the side of the screen like this

Fixing the button position
Fixing the button position

This is achieved by adding the following style to the XPage

		.lotusPlaceBar .lotusBtnContainer {
		    background: url("/xsp/.ibmxspres/dojoroot-1.6.1/dijit/themes/claro/images/titlebar.png") repeat scroll 0 0 #EEEEEE;
		    border: 1px solid #CCCCCC;
		    float: right;
		    padding-bottom: 0.3em;
		    padding-right: 0.3em;
		    padding-top: 0.3em;
		    position: fixed;
		    right: 20px;
		    z-index: 99999;
		}

There we have it – fixed buttons on the page

As you can see from the picture below – the buttons stay in exactly the same place on the screen as the user scrolls down the page

Buttons fixed in place
Buttons fixed in place

All the way to the bottom of the screen

All the way to the bottom
All the way to the bottom

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?