ShowTable of Contents
Overview
The IBM® Sametime® Proxy Software Development Kit (SDK) describes how to include Sametime functionality in a Web application that uses the Dojo Toolkit JavaScript
TM framework to manage the user interface. However, many applications have another JavaScript framework already loaded in their Web pages or perhaps don't want to load any particular framework. In these cases, it's not immediately apparent how to add Sametime functionality such as Livename.
This article explains how to achieve these, helping you to use the Sametime Proxy's functionality without requiring any particular framework. In other words, our goal is to explain how to leverage Sametime functionality in your Web application by creating an alternative form of the Sametime Livename that is not dependent on the Dojo Toolkit.
Brief introduction to the Sametime Proxy SDK
Rather than assume that you are already familiar with the Sametime Proxy SDK, this is a basic introduction to what you will need. This is necessarily not very detailed, so you should read the SDK reference documentation if you want more information.
You need to know this basic information about your system:
- The address of your application. Again, as a simplification, we'll assume that the Web application is hosted on http://www.company.com.
Integrating Sametime Proxy functions into your application is actually rather simple and straightforward. The following steps are a simple recipe for doing so, and should work in any application. Note that, if you intend to Sametime-enable a portlet to run on IBM WebSphere® Portal, these steps should be followed in the theme rather than the portlet itself.
- Copy the tunnel file to somewhere on your application server; this is the only piece you need to install in your application. All other files are loaded from the Sametime Proxy server.
- On each page that will use the Sametime Proxy functions, you need to do the following:
a) Create the stproxyconfig JavaScript object as described in Chapter 4 of the documentation. At a minimum, you'll need to specify the location of the Sametime Proxy server and the location of the tunnel file.
b) Include the baseComps.js JavaScript file to provide your application with basic Sametime functions.
c) Add the required Cascaded StyleSheets (CSS) styles to make your Livenames look similar to the standard IBM-provided Livenames, or match your preferred UI (see figure 1).
Figure 1. Standard Livename look
3. You must perform a login on every page: Provide an error function, if you want to gracefully handle any errors, and create a success callback function that is called when the login has completed successfully.
This means that the first thing you must do is copy a single file, the OpenAjax Hub tunnel, to the Web application server. This file allows the Sametime code to connect across domains, despite JavaScript's same origin policy.
NOTE: JavaScript's same origin policy is an important security concept, preventing scripts that do not originate from the same site as the Web page from accessing data and objects from the hosting page's site. In particular, it does not allow XMLHttpRequest calls from a Web page to access functionality on a different domain. In this case, this means that the hosting Web page from www.company.com would not be allowed to access proxy.company.com. The policy is well described in this
Wikipedia article.
4. The OpenAjax Hub tunnel file is in the Sametime Proxy SDK samples directory and can be copied to any location where it can be accessed by the browser. For this article, we'll assume that it's copied to the root of the Web application and can be addressed by the URL,
http://www.company.com/tunnel.html (see listing 1). This tunnel file is actually part of the OpenAjax Hub.
Listing 1. Basic Sametime code in a Web page
<script type="text/javascript">
// Sametime Proxy configuration
var stproxyConfig = {
server: "http://proxy.company.com",
tunnelURI: "http://www.company.com/tunnel.html"
};
var djConfig = {
isDebug : false
};
</script>
<script type="text/javascript" src="http://proxy.company.com/stbaseapi/baseComps.js">
</script>
<style rel="stylesheet">
.myFont{
font-family: 'Helvetica Neue',HelveticaNeue,Helvetica,Arial,sans-serif !important;
font-size: 0.8em !important;
}
.myDisplayName{
padding-left:5px;
}
.livenamecontainer{
cursor: pointer;
}
<style>
<script type="text/javascript">
// Error callback
function ErrorFunction(reason, error) {
alert("Something has gone wrong: " + reason + " (" + error + ")");
}
// Login success callback - typically used to set up the page
function loggedInOK() {
alert("Woo-hoo, we have logged in successfully!");
}
// Login to Sametime using SSO - wait for STProxy to be ready first
// You can also log in using username/password, or even as anonymous
stproxy.onLoad(function(){
stproxy.login.loginByToken("A.N.Other", stproxy.awareness.AVAILABLE,
"I'm available", loggedInOK, ErrorFunction);
});
</script>
If you prefer a different look, you should provide your own styles here. However, this solution assumes that you are using consistent stying, and it's important to create the three style classes if you want to use the solution with minimal changes.
If your application already uses the OpenAjax Hub, you do not need to include it a second time. Instead, you must tell IBM Sametime to use the one that's already loaded by adding the parameter noHub=true (note that this is case sensitive) to indicate this to the baseComps.js script tag (see listing 2).
Listing 2. Telling Sametime to not load its OpenAjax HubCreating the Livename object
The Livename JavaScript object
Since we want to reuse the Livename functions, we'll encapsulate the functionality in an object so we can create Livenames dynamically and embed them in the Web page.
There are three main parts to the Livename object:
- the markup used to display the Sametime presence awareness
- the management of status updates
- the functionality to launch a chat, etc.
Listing 3 shows the initial structure of the object, with a mechanism to store any supplied arguments, as well as an example flag to indicate whether double-clicking on the Livename should launch a chat.
Listing 3. Sametime Livename skeleton object
// Add a Livename at the specified node
myLivename = function(args,node) {
// Default - double-click does not start Chat
this.doubleClick = false;
// Default CSS classes
this.classFont = "myFont";
this.className = "myDisplayName";
// Store any arguments in the local object
for (var arg in args){
this[arg] = args[arg]
}
}
The Livename markup
Presence awareness in the form of Livenames is probably the most common use of IBM Sametime in Web applications. A Livename is actually an HTML <span> that contains an HTML <img> to show the status and another <span> that contains the user's name.
Although Livenames are quite easy to instantiate using the Sametime Proxy UI layer, they can be awkward to create using only the Base Components layer with plain JavaScript.
Listing 5 is an example of how we might create the code dynamically, adding the tags to the Document Object Model (DOM) and decorating them with the relevant classes. The code also shows the structure of the object, which you can enhance to include your own functionality.
Listing 5. Creating a Sametime Livename DOM node
// Create the nodes
this.domNode = document.createElement('span');
this.iconNode = document.createElement("img");
this.displayNameNode = document.createElement("span");
this.domNode.className = this.classFont;
this.displayNameNode.className = this.className;
this.domNode.appendChild(this.iconNode);
this.domNode.appendChild(this.displayNameNode);
// Add the nodes to the page at the specified node
// This can be specified as the ID or as the node itself
try{
if (node){
if(typeof node == "string"){
document.getElementById(node).appendChild(this.domNode);
}else{
node.appendChild(this.domNode);
}
}
}catch(e){
console.log("Cannot add Livename to the DOM");
}
Processing presence updates
The best way to create a Livename is to use the stproxy.LiveNameModel and process any update events on this JavaScript object to update the on-screen display.
When the Sametime code in the browser receives data from the server, it updates anything on the page that has been tagged as being interested in the data received. For example, when a user's status changes, the JavaScript updates whatever is associated with that user on the page.
It might be tempting to directly assign the Livename model's onUpdate() method to our own function; however, the reality is that we must instead chain the update functions so that they are all executed in turn, rather than terminating after our function and ignoring any other functions that might depend on the event.
Fortunately, we have a function already available in the stproxy.hitch object that lets us do this simply. The connect() method adds the provided method to the list of functions to be called when that object is updated, and the bind() method allows you to specify how this should occur.
When processing the Sametime data updates for presence awareness for this user, we must represent these updates in our DOM node on the page, using an image to dynamically represent the status, and positioned beside the user's display name, all encapsulated in a <span> element as described above (see listing 6).
Listing 6. Updating the Livename
this.model = stproxy.getLiveNameModel(this.userId);
// Updater function to make sure we have context and scope
this.updater = function(resp) {
this.iconNode.alt = stproxy.i18nStrings[
stproxy.awareness.i18nStrings[this.model.status]
];
this.iconNode.src = stproxy.getIconURL(this.model.status);
this.displayNameNode.innerHTML = (this.model.displayName || "");
}
// Note that this uses connect so as to not interfere with other functions.
stproxy.hitch.connect(this.model, "onUpdate", stproxy.hitch.bind(this, this.updater));
Adding functionality
The Livenames that are created using Dojo have a number of associated functions, and these can be replicated here, if you wish. As an example, the code in listing 7 supports launching a chat with the user by double-clicking on the Livename.
Listing 7. Launching a chat from the Livename
// Example for DoubleClick to Open Chat
if (this.doubleClick){
stproxy.hitch.event(this.domNode,"dblclick",function(){
stproxy.openChat(this.userId);
});
}
Creating Livenames on the page
Now that we have created our new myLivename object, we can use it to create Livenames on a Web page. There are a number of variations on how to do this:
- Specifying the required user ID, double-click, and the ID of a node:
var ln = new myLivename({"userId":"Heather Reeds",
"doubleClick":true},"myLiveNameContainer");
Providing the user ID only and specifying the node itself:
var ln = new myLivename({"userId":"Heather Reeds"},
document.getElementById("myLiveNameContainer"));
- Adding the node to the page in a separate step:
var ln = new myLivename({"userId":"Heather Reeds",doubleClick:true});
document.getElementById("myLiveNameContainer").appendChild(ln.domNode);
All the above will create the Livename that will automatically maintain its presence awareness as the user changes his/her status.
Conclusion
The current Sametime Proxy SDK documentation illustrates the various ways in which you can leverage the Dojo Toolkit to enhance your application, but it's not a requirement to include that framework in your application if you otherwise have no particular need for it. As this article shows, it's actually quite simple to create your own Dojo-independent JavaScript objects that you can integrate into your Web application to enable Sametime functions.
Download
Sample code discussed here is attached to the article.
Tell us what you think
Please visit this link to take a one-question survey about this article:
Resources
developerWorks® IBM Sametime product page:
http://www.ibm.com/developerworks/lotus/products/instantmessaging/
Sametime Standard V8.5.2 SDK IFR 1 Multiplatform:
http://www14.software.ibm.com/webapp/download/nochargesearch.jsp?q0=&k=ALL&S_TACT=104CBW71&status=Active&b=Lotus&sr=1&q=sametime+sdk&ibm-search=Search
The Dojo Toolkit:
http://dojotoolkit.org/
OpenAjax:
http://www.openajax.org/index.phpAbout the authors
Brendan Murray joined Lotus Development in 1991 and was acquired, along with the rest of the company, by IBM in 1995. Most recently he has been working on Sametime with a particular emphasis on its Web functionality. You can reach him at
brendan_murray@ie.ibm.com.
William Holmes has been with IBM since 2007 and is currently the Technical Lead for the Sametime Proxy Web client. You can reach him at
HOLMESW@ie.ibm.com.