Base Components. The guide i wish that where made when i began developing Sametime Proxy.

As stated before, we are in the middle of "porting" our support solution IM-Support from Sametime Links to Sametime Proxy.
As we already had a fully functional user interface (UI), we "only" wanted to replace the Sametime calls to and from the customer, not replacing the UI with the DOJO widgets.
On that decision, we decided to go with the Base Components.
For a developers perspective with the "almost" new STProxy, IBM had steped the game up.
Providing 103 pages of introduction/documentation to the SDK, alongside with 11 examples of how you could use STProxy on your website etc. they cover the most basic use of the SDK.
That's a big step forward, compared to the older STLinks, which in it's SDK had 36 pages and 4 examples.
By saying new to something that has been with us for aproximately three years, i'm meaning new in the sence that it seams like there's a big lack of developer knowledge outside of the documentation.
There are only a couple of blogs talking in depth about the capabillities of Sametime Proxy, the biggest/best being Carl Tylers blog.

But but but. As with many other things, the documentation has flaws, bugs, and unintentional confusion build in.
I spent a long time trying to get my head around how the Base Components work, and will here try to give some tips that i wished i have had:

The Asyncronous way of life: Aka. how to know who is who.
many of the methods that demands something of the Sametime server is build with an asyncronous callback method, one for success, and one for error.

function loginUser() {
	stproxy.login.loginByPassword(
		userID,						//The user ID credentials 
		password, 					//The users password
		stproxy.awareness.AVAILABLE, 	            //Status eg. Available, In a meeting, etc.
		"I'm available", 				//Status message
		loggedInOK, 					//The function to be called if login is successfull
		loginFailed);					//The function to be called if login fails in some way
}

The Async aproach is quite nice, since you:
1. Obviously should do two different things if eg. your login failed or not.
2. Speed up the process of having several methodcalls calling the server because your code don't have to wait for answer, it just goes on and make other things.

But there are some places in the code where your code can loose track of what actually comes back to it. May I present: getStatus:

stproxy.watchlist.getStatus(userId, gotStatus, generalErrorHandler);

The method takes the userID as input, and gives you the status through the gotStatus function. But when your callback code gets the answer, it does not contain the userID that the status is concerning.
My solution to this problem is by parsing the userID along with it as follows:

( function(uid) {
	stproxy.watchlist.getStatus(
	user_id, 
	function(resp) {
		// your code here: 
		// remember that you now know who you are dealing with through the
		// uid variable, since it has been mashed into the scope of the function.
		// The other information like status, and status message can now be retrieved
		// through the resp variable.
	},
	getStatusErrorHandler);
}(user_id))

Allright, we can now login, and get a friend to chat with, so let's do that.
Looking at the documentation, you'll see a paragraph telling you that the only thing you need to do is:

stproxy.openChat(userId);

But when you do, a popup window containing the chat appears.. See that wasn't what I thought I ordered....


Ok, but how about this then:

stproxy.createChat(userId);

Same popUp...
The thing is that what the doc. is not telling you is that it all comes down to the chatmodel.
Personally I think that the chatmodel could use a little more wording in the documentation since this is pretty much the most important thing when using Sametime Proxy.

function createIMWithUser(userID) {
	var chatModel = stproxy.getChatModel(
		userID,					//The user who you want to chat with. 
		{'isIncoming' : false}	//An object containing different arguments. 
								//the 'isIncoming' i'm telling that i'm the initigator
		);
	
	chatModel.onMessage = function(message) {	//You need to tell the chatmodel what to do so that it 
												// delivers the content of the chat to the right HTMLplace
		console.log("Recived message from: " + this.userId + " with message: " + message);
		//Remember that 'this' here reffers to the chatmodel, so everything that is in that object is
		//reachable by calling 'this.'something.
		
	};
}

You can se alot of other functions in the chatmodel, many of them described in the documentation from page 47 and forward.
Allright, so now we got a 1 to 1 chat going but what about multiway?
Again, look at the API, and be confused:)

stproxy.getGroupChatModel(args, isCallApi);

Args we know from the 1-1 chat, but isCallApi? If you then go down and read the table of parameters, the confusion makes a level up :):

The correct thing is the snapshot above:

function createNWayChat(userIDs,topic){
	var args = {'userIds':userIDs, 	//An array containing all the userID's that are going to be invited to the chat.
		      'topic':topic};	//The topic of the chat. The PlaceID you get in return will be the topic combined 
					//with the timestamp of the creation.
	
	var nWayChatModel = stproxy.getGroupChatModel(args,false);
	nWayChatModel.onMessage = function(userID,message) {
	 	//your code here.... Again remember 'this' gives you additional information such as placeId
	};
return nWayChatModel;

}
The functions provided by the chatmodels for 1-1 and multiway chats are very similar, so you know the drill there.

So what you get back from creating a multiway chat is what they call placeID.
It has nothing to do with the old places(LINK) that Sametime Links offer.
We tried for the fun of it to join a place in STLinks that STProxy has made, but no luck there.... So if you, like us, have build functionality that utillizes places, then you have to rethink the way to achieve that purporse.

I personally think that the SDK is very solid, and once you learn how it's ment to be used it is quite straight forward.
I truly hope that this has given you some tricks that you can take with you in developing a new and improved Sametime solution.
-Sofus