WTF is WIM?

Steven G. Chipman

Principal Software Engineer, AOL

WIM is...

WIM ain't...

What can I do with it?

First, the super-easy stuff:

Ok, how?

We'll use the Buddy List widget as an example.

  1. Add a reference to aimapi.js to the head of your document.
  2. Add an element with an id of "AIMBuddyListContainer" with an attribute named "wim_key" with your developer key as its value.
  3. Add an anchor element with an onclick handler that fires "AIM.widgets.buddylist.launch();".
  4. Done.

In other words, just this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script type="text/javascript" src="http://o.aolcdn.com/aim/web-aim/aimapi.js"></script>
</head>
<body>
<div id="AIMBuddyListContainer" wim_key="12345678"></div>
<a href="nojavascript.html" onclick="AIM.widgets.buddylist.launch(); return false;">Launch My Buddy List</a>
</body>
</html>

An Example.

Great, I have a Buddy List. Now what?

Well, you could make it look however you want with just CSS...

The XOXO Theme for WIM The Minima Theme for WIM The Urban Legend Theme for WIM

Speaking of CSS

We've provided loads of design hooks in the CSS to make skinning as flexible as possible, such as:

Every aspect of the list is customizable.

Or you could add new functionality...

After all, this is just HTML and easily accessible via the DOM. As such, it is infinately hackable and mashup-able.

An example:

You could check if a person in the buddy list has a public gallery on pictures.aol.com, and if so - add a link next to their name to that gallery.

Another example:

What if a popular online shop stored your AIM id with your information, and the service provided a "wishlist" feature? That shop could add links to the buddy list that go off to that user's wishlist, or only display buddies with wishlists in a side menu.

Or do things that aren't Buddy List related at all...

How it works - a WIM Walkthrough.

What follows is a step by step examination of what happens from the time a user clicks "Launch my Buddy List" until they see their list render.

(Its not as boring as it sounds, really.)

AIM.widgets.buddylist.launch

Does generic checks and environment setup.

A moment for client/host communications

Those URL arguments are...

The Host Response

A response for a client to host transaction would look like this: 

AIM.core.acceptData({
	statusCode:200, 
	statusText:"Ok", 
	requestId:"2", 
	data:{
		aimsid:"13.1271104237:iheartwim", 
		fetchBaseURL:"http://64.12.162.163:80/aim/fetchEvents?aimsid=13.1271104237:iheartwim", 
		myInfo:{
			aimId:"iheartwim", 
			displayId:"I Heart WIM", 
			state:"online", 
			onlineTime:0, 
			idleTime:0, 
			presenceIcon:"http://o.aolcdn.com/aim/img/online.gif", 
			profileMsg:"yo"
		}
	}
})

From Host to Client

If the host has something it needs to tell the client, it does so through the "listener" script via AIM.core.listen. An event update would look like this: 

AIM.core.listen({
	fetchBaseURL:"http://64.12.162.163:80/aim/fetchEvents?aimsid=14.1727053795:iheartwim&seqNum=53", 
	timeToNextFetch:500, 
	events:[{
		type:"presence", 
		eventData:{
			aimId:"slayeroffice2",
			displayId:"slayeroffice2", 
			state:"online", 
			presenceIcon:"http://o.aolcdn.com/aim/img/online.gif"
		}
	}]
})

How does the client know what to do?

This model makes it very easy to modify or overwrite the default behavior of the API.

The Listener

Final notes on client/host communication

AIM.transactions.getToken

The entry point that starts up communication between client and host. Takes a list of event subscriptions as its argument.

In case of a 401 or 450

The iframe is created, but how do we know that the user has authenticated? Or canceled? Or done nothing at all?

For example, when the user successfully completes the login process, #AUTHDONE is sent to the parent document.

Now that the user has logged in...

We can call getToken again, and this time we'll get a successful response with a token. Now we can start a session with the host.

AIM.transactions.startSession

Mother May I...

Now that thats outa the way

We'll start getting events coming down the pipe.

How Does the API Break Down?

The API is broken out into several objects:

AIM.transactions

Provides client to host communication methods.

AIM.params

Defines various parameters that direct how the API behaves.

AIM.core

Contains all of the methods that the Javascript API can't live without.

AIM.ui

Provides methods for creating a buddy list, windows, and accessing parts of the UI.

AIM.util

A series of utility methods.

AIM.widgets

Methods to handle Whimsical setup.

Resources

Questions?

Thanks for coming!