WebAIM Part 1

by Christian Wenz
May 10, 2007

AOL's WebAIM API provides a very comfortable means to incorporate a JavaScript-powered AIM client in a web page. With some extra effort it is also possible to control most of WebAIM's features using a server-side technology. This article shows how to setup an ASP.NET environment with ASP.NET AJAX. Further installments of this article series will then show you how to bring ASP.NET, ASP.NET AJAX and WebAIM together.

ASP.NET Basics

When ASP.NET was initially released, Microsoft's new web framework received quite positive reviews, but the market impact was rather minimal. One of the reasons was that the code and markup ASP.NET 1.x was created was "optimized" for Internet Explorer, whereas modern web development demands that web sites work seamlessly on as many clients as possible, but at least on the big two: Internet Explorer and Firefox (which includes other Mozilla derivates, as well).

The next version, ASP.NET 2.0, created much more buzz. Not only was the HTML markup and JavaScript code generated more or less browser-agnostic, but ASP.NET 2.0 ships with a lot of really useful server controls that provide on-the-spot solutions for common web scenarios. For instance, creating a web site that requires users to login is just a matter of mouse clicks and adding a few controls; however practically no code is required.

ASP.NET is one part of Microsoft's .NET strategy. The heart of .NET is the .NET Framework, a huge class library with solutions for all kind of programming challenges, comparable to the Java class library. Since most of the functionality resides in the .NET Framework, there are not so many demands regarding the programming language itself. This is one of the reasons why .NET developers can choose their language, as long as it is .NET compliant. Among the languages that are supported in .NET are Visual Basic, C# (a new language, quite similar to C and Java), C++, JScript (Microsoft's JavaScript clone), and many more. And while this article series is using the C# language, it is quite easy to port the code to other .NET languages.

One of the most important concepts of ASP.NET is the use of server-side controls. They provide a convenient server API, but are rendered to HTML, CSS and JavaScript on the client. A good example for that is a control called Calendar. It represents, as the name suggests, a calendar which allows the user to select a day, navigate between months, and so on. Of course HTML does not have a calendar element. Therefore a client receives quite a lot of HTML and JavaScript code when an ASP.NET developer uses a Calendar control on the server. The advantages for the development process are obvious: It is just quicker to use a predefined control and tweak it to one's needs than to write all functionality on one's own, again and again and again. Additionally, you have a server API that provides you with common calendar functionality like, for instance, selecting and highlighting a certain day on the calendar.

ASP.NET AJAX Basics

Although the term Ajax is only a bit over two years old (Jesse J. Garrett coined the term in in February 2005), the technologies involved have taken the web world by storm since then. It was therefore only a matter of time until Microsoft would have their own offering for developers. The result was first called Atlas, but the product team ultimately settled for the name ASP.NET AJAX. This is an Ajax framework that is very tightly integrated into ASP.NET 2.0. (By the way, do not worry about the different versions of Ajax/AJAX. Originally AJAX was thought of as an acronym, but in the meanwhile even Garrett admitted that one should use it as a regular noun: Ajax. Microsoft uses both versions.)

When you visit the Microsoft Ajax homepage (http://ajax.asp.net/), you will find several Ajax-related packages for download:

• ASP.NET AJAX Extensions: The "core" ASP.NET AJAX package, providing useful server controls and powerful JavaScript APIs to access selected ASP.NET features like user profiles and user authentication. It also extends the JavaScript language and enriches some JavaScript objects with new features.

• ASP.NET AJAX Futures CTP (Community Technology Preview): An (unsupported) package of new extensions for ASP.NET AJAX. These extensions are subject to change, the package is experimental.

• ASP.NET AJAX Control Toolkit: A massive collection of Ajax server controls for a lot of common and not-so-common scenarios.

• Microsoft Ajax Library: A JavaScript-only subset of the ASP.NET AJAX Extensions. Since it is only client-side script, it can be used without JavaScript, as well.

Figure 1. Microsoft's AJAX Homepage

Generally, you will want to use the ASP.NET AJAX Extensions which lay the groundwork for developing Ajax-y websites with ASP.NET 2.0; the ASP.NET AJAX Control Toolkit may contain some controls which might just solve the scenario you are currently working on. This article series will use these two packages.

Setting up a Development System

In theory, you can develop ASP.NET websites (and ASP.NET AJAX websites as well) with a plain and simple text editor; you furthermore need the Microsoft web server IIS (Internet Information Services) to host your ASP.NET site. When you install the .NET Framework and IIS is already present, ASP.NET is automatically integrated in the web server; IIS is configured to support ASP.NET immediately.

But back to the editor in question: It is quite obvious that developers can nowadays expect some software support during implementation. The logical choice here is to use Microsoft Visual Studio 2005, a very powerful commercial IDE (Integrated Development Environment) that supports the development of ASP.NET websites and also of all kinds of .NET applications.

Figure 2. Visual Studio 2005

However it is getting better. Microsoft has also released a set of stripped-down version of Visual Studio, so called Express Edition. Each Express Edition is tailored for a specific development scenario: There is an Express Edition for C#, one for Visual Basic, one for C++, even one for game development,and one for web development. The web Express Edition is called Visual Web Developer Express Edition, or short: VWD. It lacks some of the most advanced features of Visual Studio and can only be used to implement web content. However, it is completely free! You can download VWD from http://msdn.microsoft.com/vstudio/express/vwd/. After a (free) registration and activation of the product, you receive some further benefits, for instance a selection of Corbis images. Right after that you should visit Microsoft Update and install the latest Service Pack for Visual Studio/VWD; as of time of writing this, SP1 is the most recent version which fixes some nasty bugs and also brings new features.

After installing either Visual Studio or VWD, it is time to install ASP.NET AJAX on top of it (all other requirements, including the .NET Framework 2.0, are automatically installed by the Visual Studio/VWD installer). The installer from http://go.microsoft.com/fwlink/?LinkID=77296 does not ask many questions but installs the ASP.NET AJAX library on the system.

Figure 3. The ASP.NET AJAX Installer

When you launch VWD, you will notice that the installer created a new web site template: Choose File -> New Web Site and notice the entry ASP.NET AJAX-Enabled WebSite. The ASP.NET AJAX Futures CTP, by the way, creates its own template.

Figure 4. The ASP.NET AJAX Web Site Template

But this is not the time yet to create a new web site; first, the ASP.NET AJAX Control Toolkit must be installed. It does not matter which version from http://www.codeplex.com/Release/ProjectReleases.aspx?ProjectName=AtlasControlToolkit you install, but the "no source" one is a smaller download. Both are just fine for this example.

In the AjaxControlExtender folder of the Control Toolkit ZIP archive you will find the file AjaxControlExtender.vsi. This installs a couple of templates into Visual Studio or Visual Web Developer; you only need the two with "Website" in the name (actually, VWD throws an error message when you try to install one of the remaining four items).

Figure 5. The Control Toolkit Template Installer for Visual Studio

Now launch VWD, if you haven't done so already, and choose File -> New Web Site. Choose the template called "AJAX Control Toolkit Web Site".

Figure 6. Choose the AJAX Control Toolkit Web Site Template

You will notice that the Location dropdown menu offers three choices where to put the web site. The default is the local file system. This may sound surprising, but VWD and Visual Studio come with a built-in web server. So when you choose to save the web site on the local file system and not directly in IIS, the development test web server starts when you are viewing or debugging the site. This test server is somewhat limited, for instance does not allow access from remote, but is an excellent choice for testing. However for reasons that will be covered in more detail later, you should either choose the HTTP option and provide an IIS URL (for instance, http://localhost/WebAIM), or choose FTP and connect with the ASP.NET hosting provider of your choice.

Visual Web Developer (or Visual Studio) will now set up a new site for you. You will notice that there are already a few files. Two of them are of special interest:

• Web.config: This is the site's ASP.NET configuration file, in XML format. Among other things, this file configures ASP.NET AJAX for your site, and also sets up the ASP.NET AJAX Control Toolkit support.

• Bin/AjaxControlToolkit.dll: This file contains the actual ASP.NET AJAX Control Toolkit, including all server controls and the associated JavaScript code (as embedded resources).

In the next part of the article, we will add a couple of new files that will make up our WebAIM application.

Starting as a WebAIM Developer

Before we can actually dive into coding, we must first register with the WebAIM service. The AIM API uses a similar approach as other popular APIs in the web: users need to apply for a license key to access the API. This allows the API makers to control the access; some of them even have a business model where you have to pay a fee if you want to commercially use the API.

So go to http://developer.aim.com/manageKeys.jsp to apply for such a license key. You need to login to AIM; an existing, "regular" AIM or AOL account suffices for that. Then you can generate a (more or less) arbitrary number of keys. Every WebAIM key is tied to a special URL. So you do have to provide a real URL and the WebAIM service will later check whether the API request came from that URL or at least from the same directory.

For instance, assume that you provided the URL http://mysite.tld/WebAIM/Default.aspx for the license key. Then, obviously, WebAIM API requests from http://mysite.tld/WebAIM/Default.aspx are allowed, as are requests from http://mysite.tld/WebAIM/myWebAIM.aspx. However the page http://mysite.tld/WebAIM/v1/Default.aspx resides in another directory (although it is "just" a subfolder!), so you would need a new license key for that.

Figure 7. Apply for Keys Online

A current limitation of the WebAIM service makes choosing the correct URL a very important step. At the moment, local URLs (such as http://localhost/...) are not supported. The WebAIM service happily generates keys for these URLs, but when you send API calls from them, you get strange error messages at one point.

Therefore you need a "real" URL. There are several ways to achieve that, each of them with advantages and disadvantages:

• When creating the project, use the FTP option. Directly edit the ASP.NET pages on a remote FTP server (which is an IIS) and then access it using the remote URL. Apply for the WebAIM key providing the remote URL.

• When creating the project, use the HTTP option. The HTTP server must have a non-local domain name and must of course also be remotely accessible. Apply for the WebAIM key providing the remote URL.

• When creating the project, use the local file system option. Before testing the application, publish the web site to an IIS server that is remotely accessible (Visual Web Developer even comes with a tool for that). Apply for the WebAIM key providing the remote URL.

• When creating the project use a local IIS HTTP server. Then, go to a service like DynDNS.org and apply for a domain name there. This domain name (for instance, http:/webaim.dyndns.org/) can then be redirected to your current IP address and thus to your local IIS. Of course you have to open up your firewall so that the IIS is then remotely accessible; you should also take extra security precautions since your server is then open to the world (among other things, checking the state of Windows Update is a must). Apply for the WebAIM key providing the remote URL (e.g. the one provided by DynDNS).

So you see, there are some extra steps required, but finally you do have a working system. The coding will start in the next part of the article, but until then, you may want to test WebAIM by using the JavaScript libraries provided by the service.

In order to do so, you have just to create a rather shortish HTML page:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
  <title>WebAIM</title>
  <script type="text/javascript" src="http://o.aolcdn.com/aim/web-aim/aimapi.js"></script>
</head>
<body>
  <div id="AIMBuddyListContainer" wim_key="****************">
  </div>
  <a onclick="AIM.widgets.buddyList.launch();return false;" href="#">Launch my Buddy
    List</a>
</body>
</html>

A couple of things are noteworthy in the preceding listing:

• The <script> tag is used to load the WebAIM JavaScript library from an AOL server. This contains the complete code to mimick an impressive AIM client within the web browser.

• The <div> element with ID AIMBuddyListContainer will be used to display the buddy list. Note the wim_key attribute: It holds the WebAIM key you created (for obvious reasons, **************** is not a valid key, replace this with your own key).

• The hyperlink executes the AIM.widgets.buddyList.launch() method which is defined in the JavaScript library loaded with the <script> tag. It starts the whole WebAIM workflow which includes signing on to the system, allowing the system to access the account data, and actually displaying the buddy list and more.

Launch this page and play a little bit with the system. If everything works, you know for sure that the license key works and are ready to proceed to use the WebAIM API on your own,in the next article installment. See you then!

Figure 8. The JavaScript-based WebAIM client

References

• http://ajax.asp.net/ - the Microsoft Ajax homepage
• http://msdn.microsoft.com/vstudio/express/vwd/ - the free Microsoft Visual Web Developer Express Edition page
• http://www.codeplex.com/Release/ProjectReleases.aspx?ProjectName=AtlasControlToolkit - the ASP.NET AJAX Control Toolkit
• http://developer.aim.com/manageKeys.jsp - AIM Developers Manage Keys page
• DynDNS.org - Dynamic Network Services, provider of dynamic domain name redirection services