Adding Web AIM Presence and Buddies to Your Web Pages
by James Turner
February 2, 2007
Introduction
There are any number of reasons you might want to add AOL Instant Messaging functionality to your web pages. You might have a small business and want to implement a quick and inexpensive solution for live customer service. You might want your friends to be able to see if you're logged in and available for chat. Luckily, with the new Web AIM API and AIM Whimsicals, it's extremely easy to enable this functionality on a web page.
Initial Requirements
Really, all you need to begin with is an AOL screen name, a web page that you have edit access to, and a Web AIM registration key. The first of these is self-evident; you can't show AIM presence without having an AIM account. You obviously also need a web page that you can modify the contents of, so that you can place the web widgets somewhere. The last item is the only formal requirement that involves AOL; you need to register for a key. The key thing (as it were) to remember is that the key you get is only good for one directory level in your website.
For example, let's consider Larry Woolgathers, owner of Llarry's House of Llamas. Here's Larry's current website at http://www.larrysllamas.com/homesite/index.html:
Llarry's House of Llamas initial design
As you can see, Llarry, I mean Larry, is not a master of visual design. Still, with just a few lines of HTML, he can make his site AIM-capable. To begin with, Larry wants to let people know when he's online on AIM (what Web AIM refers to as presence). So as a first step, he needs to get a registration key for the http://www.larrysllamas.com/homesite/ directory path of his website. If he later wanted to add similar functionality to http://www.larrysllamas.com/specials/, he'd need to get a separate registration key for it. That's because, as has already been mentioned, registration keys only work for one specific directory level of one specific domain.
So Larry needs to go to the registration page at developer.aim.com/wimReg.jsp:
Hopefully, anyone adding this functionality to a website has already signed up for an AIM screen name; if not, they need to get one before they can add Web AIM to their pages. If you're going to be using Web AIM on your business site, you may want to get a separate AIM screen name specifically for business use.
Once Larry has gone through a simple registration process (which is only done once) he is brought to the WIM Registration screen:
From here, all Larry needs to do is enter the full URL of the page that he wishes to embed Web AIM onto, agree to the terms and conditions, and hit Submit. This will bring him to the following page:
AIM WIM Key
The key (literally) item on the page is the key that has been generated (la164e7yTTCS5C-z). This key is what enables the Web AIM widgets to work correctly on the page. With this in hand, Larry is ready to make his page AIM presence-aware.
Adding AIM Presence
The presence widget requires a couple of changes to the page. To begin with, it is going to need some real estate to place the widget in. Luckily, there's a nice empty white space on the right side of the page just begging for some content. Let's look at Larry's original HTML for his page.
<!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>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Simple Presence Example</title>
<link href="/css/presence-1.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div class="toppage">Llarry's House of Llamas</div>
<div class="leftbar">
<p class="llamaheadline">This month's Llama Specials</p>
<p class="llamaspeciala">Buy one Llama at the regular price, get two more of the same
color at half-price</p>
<p class="llamaspecialb">Save 10% on Llama-chow and Llama-litter.</p>
</div>
<div class="main">
<p>This month's featured Llama: Karl!
<img src="/images/article_images/adding-web-aim-presence-buddies/llama1.jpg"
alt="Llama" width="300" height="402"
longdesc="The Might Llama" /></p>
<p> </p>
</div>
</body>
</html>
Larry may not have much on the ball as far as as design skills go, but at least he's got enough on the ball to use cascading style sheets (CSS). As currently designed, Larry has a div at the top of the page for the page title, a div for the left side bar, and another one for the center with the main content. Here's a look at the CSS definitions for these divs:
.toppage {
font-family: "Times New Roman", Times, serif;
font-size: 42px;
text-align: center;
height: 50px;
width: 100%;
border: none;
position: absolute;
visibility: visible;
top: 0px;
}
.leftbar {
font-family: "Times New Roman", Times, serif;
font-size: 22px;
position: absolute;
text-align: center;
top: 50px;
left: 30px;
width: 200px;
border: none;
position: absolute;
visibility: visible;
}
.main {
font-family: "Times New Roman", Times, serif;
font-size: 20px;
position: absolute;
text-align: center;
top: 50px;
left: 250px;
width: 500px;
border: none;
position: absolute;
visibility: visible;
}
.llamaheadline {
font-family:Verdana, Arial, Helvetica, sans-serif;
font-size:24px;
color:#0000FF;
text-align:center;
}
.llamaspeciala {
font-family:Verdana, Arial, Helvetica, sans-serif;
font-size:20px;
color:#FF66FF;
text-align:left;
}
.llamaspecialb {
font-family:Verdana, Arial, Helvetica, sans-serif;
font-size:20px;
text-align:left;
color:#993366;
}
As you can see, Larry is using absolute positioning to place the various top, side, and main content divs where he wants them. He starts by added a new div to hold the AOL sidebar.
<div class="aolbar"> Larry's AOL Instant Messanger Status: </div>
Along with this, he adds the corresponding CSS entry to position it correctly:
.aolbar {
font-family: "Times New Roman", Times, serif;
font-size: 20px;
position: absolute;
text-align: center;
top: 50px;
left: 750px;
width: 200px;
border: none;
position: absolute;
visibility: visible;
}
Now it's time for Larry to hook up all the AOL JavaScript that makes the presence widget work. First, he needs to import the appropriate JavaScript file from the AOL website and add a JavaScript onLoad call that will make the widget run. This needs to go in the HEAD section of his HTML file, which will now look like this:
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Simple Presence Example</title>
<link href="/css/presence-1.css" rel="stylesheet" type="text/css" />
<script type="text/javascript"
src="http://o.aolcdn.com/aim/web-aim/aimapi.js"></script>
<script type="text/javascript">
AIM.widgets.presence.launch();
</script>
</head>
The first script tag loads aimapi.js, which contains all the Web AIM JavaScript code. The second script tag causes the presence widget to run when the page first loads.
Finally, Larry needs to add the actual tags that make the widget appear. These will go inside the div that he just added on the right side of the page.
<div class="aolbar"> Larry's AOL Instant Messanger Status: <div id="AIMBuddyListContainer" wim_key="la164e7yTTCS5C-z"></div> <div class="AIMPresenceWidget larrysllamas">Larry's Llamas</div> </div>
There's a few things to note here. The first div is set to the ID of
AIMBuddyListContainer and has an attribute called wim_key, which should be the same as the key that was generated during the registration on the Web AIM site. After it, Larry can put one or more divs with the class of AIMPresenceWidget followed by the AIM handle of the user they are to display presence for. Inside the content of the div, he places the name to be displayed in the box. Notice that the displayed name doesn't need to match the AIM handle.
Styling Your AIM Presence
If Larry just uploads this HTML without any CSS changes, he'll get all the functionality he wanted, but not the look he might have expected:
Presence with no CSS
It may not look like it's working, but if Larry is logged into AIM and holds his mouse over "Larry's Llamas," this is what he'll see:
Mouseover with no CSS
So how does Larry make things more user-friendly? With some CSS styles, of course. He needs to define an overall style for the individual users, and one for each of the three possible states (away, logged off, and online.)
.AIMPresenceWidget {
text-indent:32px;
background-repeat:no-repeat;
background-position:left center;
height:32px;
font:bold 14px arial,verdana;
padding-top:5px
width:180px;
border:2px solid #000;
}
.AIMPresenceWidget_offline {
background-image:ur/images/article_images/adding-web-aim-presence-buddies/redllama.jpg);
}
.AIMPresenceWidget_online {
background-image:ur/images/article_images/adding-web-aim-presence-buddies/greenllama.jpg);
}
.AIMPresenceWidget_away {
background-image:ur/images/article_images/adding-web-aim-presence-buddies/greenllama.jpg);
background-color:#CCFF66;
}
For the widgets as a whole, Larry has decided to make the entries 32 pixels high by 180 pixels wide, with a two-pixel solid black border. He's also decided that offline users should get a red Llama next to their name, online ones a green Llama, and away users a green Llama with a yellow background. Ah Larry, that's the same sharp design sense that won you the "Ugliest Animal Website, 2002-2005."
With the new CSS in place, things look much more like you might expect. Here are Larry's updated status indicators (online, away, and offline):
With CSS
A couple of important things to mention here: first off, the presence widget isn't an active one; it represents the state of the users when the page is first loaded. Once the page is done, the icon isn't going to change, regardless of whether Larry were to log in or out.
Also, because anyone can be put into the list of users to display, it is possible to display someone's status without their permission. This isn't a true privacy violation, because the same information is available directly via AIM, but it is still polite to ask before adding someone's status on your web page.
Beyond Presence: Web AIM Buddy Lists and Chat
Displaying the fact that Larry is online is all nice and good, but what Larry would really like is to be able to let his customers (and more importantly, potential customers!) IM him right from the web page. The Web AIM widgets allow you to implement that feature as well, and without much more code.
To let people send messages to Larry, all he needs to do is add the following highlighted line of HTML under his presence data:
<div class="aolbar">
Larry's AOL Instant Messanger Status:
<div id="AIMBuddyListContainer" wim_key="la164e7yTTCS5C-z"></div>
<div class="AIMPresenceWidget larrysllamas">Larry's Llamas</div>
<a href="nojavascript.html" onclick="AIM.widgets.IMMe.launch('larrysllamas');return false;">
Contact Me About Llamas!</a>
</div>
This will result in a web page that looks like this:
Chat link
Clicking on the link will fire up an on-page AIM client. If the user is logged into AIM, it will ask if they want to use that handle. At least under Firefox, you're also going to get four or five screens either warning you that Firefox is not a fully supported browser, or asking for various permissions to access AIM functionalities. Once that's all done, Larry's page looks like this (customer's name obscured in accordance with the Llama Privacy Act of 2005):
Chat without CSS
Although the chat window initially appears next to the link, it can be dragged by the title bar to appear anywhere on the page.
As a last convenience to his customers, Larry would like to let them also run their full buddy lists on the web page, making it into a general purpose portal page. (If all you ever wanted in a portal page was a picture of a Llama and your buddy list, but it's a start, at least.)
Again, with the same JavaScript file, he can add buddy list functionality in a few minutes. Just below the link he just added, he adds another line of HTML:
<a onclick="AIM.widgets.buddyList.launch();return false;" href="nojavascript.html"> Launch my Buddy List</a>
Now, when a visitor to his page clicks on the new link, they're given a chance to log in, and another floating window becomes available:
Buddy list
You can change the theme of any of these widgets by inserting a few lines into the HEAD of the document. For example, to change the widgets to use the "Urban Legend" theme, you simply add the following into the head:
<script type="text/javascript">
var baseResourceURI = "http://o.aolcdn.com/aim/web-aim/urban-legend/";
AIM.widgets.buddyList.appearance.styleSheetURI =
"http://o.aolcdn.com/aim/web-aim/urban-legend/urban-legend.css";
AIM.widgets.IMMe.appearance.styleSheetURI =
"http://o.aolcdn.com/aim/web-aim/urban-legend/urban-legend.css";
AIM.widgets.presence.launch();
</script>
The example given changes the buddyList and IMMe widgets to use the theme. A full list of themes and what they look like can be found at the AIM web developer page.
Conclusion
In summary, adding AIM functionality is simple from a code perspective. The interesting part lies in designing your page and your style sheets to make the most of what the Widgets offer.
Example Code
You can download the code for this article here: adding-web-aim-presence-buddies.zip
References
- Web AIM: The Web AIM home page
- Web AIM Reference: How to get started with the Web AIM JavaScript API
- "Fun with Web AIM Using Whimsicals": Blog post introducing AIM Whimsicals