Creating an AIM Lite Plugin

by Doug Schwartz
March 21, 2007

Introduction

In my last article, "Creating an AIM Plugin in C# with the .NET Framework," I discussed how you can create a simple plugin in C# using the Microsoft .NET framework. That plugin let the user translate their message using a scheme where letters are shifted 13 places--"a" becomes "n" and so on. What that plugin really demonstrated is how to intercept the instant message (IM) before it is sent by the user, and do whatever you want with the text.

But what if you don't know C# or the Microsoft Common Object Model (COM) and want to create a plugin? AOL has a new IM client, AIM Lite, that supports OpenAIM plugins that are written in Boxely markup and JavaScript. This article discusses how to create the same plugin as in the previous article using this technology.

Plugins are typically created from a couple of XML files and a JavaScript file. Deployment is slightly different compared to C# or COM plugins. You deploy an AIM Lite plugin as an AWI file, which is a ZIP file with an .awi extension. AWI files typically contain at least three files:

• A plugin.xml metadata file.
• A content directory with a main.box XML file.
• A JavaScript file with a .js extension that is referenced in main.box.

The simplest structure is something like that in Figure 1:

Figure 1. A typical plugin structure

AWI files are extremely easy to install. Once someone has AIM Lite and the AWI file, they double-click the AWI file, and voila! The plugin is installed.

What Do I Need to Develop a Plugin?

This section has one additional step compared to my last article--step one, download and install AIM Lite. After that step, if you already understand how to get a developer key and the SDK, you can skip to the next section, Creating the Plugin.

1. Download and install AIM Lite.

2. Get an account on the AIM Developer website.

3. Next, get a developer key for your plugin. There are different keys for different stages of development. For now, you need only a developer key. Later on, if you decide to make your plugin available to others, you will need a deployment key. To get a key, go to the AIM Plugin Registration web page and follow the instructions. You will need the key value to run your plugin.

4. Once you have registered, you can download the SDK. This article leads you through creating a JavaScript plugin, Scramble. For the complete source for this article, see Resources.

Note: I know I am probably preaching to the choir, but I strongly recommend that you use tools that understand XML and JavaScript. Stubborn me, I was using my old favorite, Xemacs, as just a vanilla text editor and burned hours trying to figure out why my plugin did not work. Of course it was a silly syntax error that I found in minutes when I fired up an editor that understands JavaScript.

Downloading and Installing AIM Lite

1. Go to the AIM Lite web page.
2. Click the Download Now button.
3. Read the license agreement. (Does anyone really read these things?)
4. Click Accept.
5. Save the aim-et-setup.exe application installer file to your machine.
   It should be about 1.6MB.
6. Navigate to the folder where you saved the application installer file.
7. Double-click the application installer file.

Creating the Plugin

We are going to create the plugin in the following order:

1. Create the plugin.xml file.
2. Create the main.box file.
3. Create the main.js file.

For this plugin, let's create the folder C:\Plugins\Scramble.

Creating the plugin.xml File

The plugin.xml file contains a single widget element. This element can contain a number of subelements, but the only required subelement is the uuid, which is a developer or deployment key. Replace YOUR_DEVELOPER_KEY with your developer key in the following code, and save it as C:\Plugins\Scramble\plugin.xml. Feel free to keep, delete, or modify any of the other subelements.

<?xml version="1.0" encoding="utf-8" ?>
<widget
    uuid = "{YOUR_DEVELOPER_KEY}"
    version = "1.0"
    name = "Scramble"
    description = "This plugin scrambles text"
    vendor = "Me, Myself, and I Inc."
/>

Creating the main.box File

The main.box file contains a single window element. This element defines the user interface (UI) for the plugin. A plugin can be visible, invisible (no UI), or only visible in response to an event. Our plugin is invisible, and main.box contains the following text:

<?xml version="1.0" encoding="utf-8" ?>
<window
    xmlns="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"
    xmlns:on="http://www.aol.com/boxely/reaction.xsd"
    on:constructed="onConstructed();"
    on:destroyed="onDestroyed();"
    s:height="0"
    s:width="0"
    hidden="true"
    collapsed="true"
    floating="true"
>
    <code id="main" language="jscript" src="main.js"/>
</window>

You can easily tell our plugin is invisible by the hidden="true" element.

Let's deconstruct this XML line by line.

1. Defines the text encoding.
2. Creates the opening window element tag.
3. Creates the default namespace for this window element. Namespaces are a handy way to save a boatload of typing in an XML file.
4. Creates the s namespace for this window element.
5. Creates the on namespace for this window element.
6. Identifies onConstructed as the function to which the constructed event notification is sent. This event is fired whenever the plugin is created. onConstructed should create any resources that are needed for the plugin.
7. Identifies onDestroyed as the function to which the destroyed event notification is sent. This event is fired whenever the plugin is destroyed. onDestroyed should release any resources that were created in the onConstructed function.
8. Defines the height of our UI window.
9. Defines the width of our UI window.
10. Defines whether the window is visible.
11. Defines whether the window is collapsed.
12. Defines whether the window can be moved.
13. Closes the window element attributes.
14. Defines the JavaScript file where our code resides.
15. Closes the window element.

Creating the main.js File

The main.js file contains the following sections:

• Two global variables.
• The onConstructed function that is called when the plugin is created.
• The onDestroyed function that is called when the plugin is finished.
• The BeforeImSend event handler that is called before the message is sent.
• The function that scrambles the IM text.
• The function that handles the plugin command.

The first two lines of main.js contain two global variables: kCommandId, which defines the integer value of our plugin command, and xlate, which defines whether the user wants us to scramble the IM text. This code is as follows:

var kCommandId = 0;
var xlate = false;

One of the challenges of developing a plugin in JavaScript is that the existing plugin documentation is written for COM. Let's spend a couple of minutes examining the association between AIM Lite JavaScript objects and the related COM interfaces, so we can use the SDK documentation.

All AIM functionality, including user preferences, is accessed through a session object. This object is an implementation of the IAccSession interface, and is accessed through the scene.paramsDictionary property's valueForKey function using the session key.

Information about a plugin is accessed through a pluginInfo object. This object is an implementation of the IAccPluginInfo interface, and is accessed through the scene.paramsDictionary property's valueForKey function using the pluginInfo key.

Once we have the pluginInfo object, we can create the plugin command using the pluginInfo object's addCommand function, and assign the text we present to the user with the text property of the command.

Event handling begins with a call to the scene.connectObject function. The first parameter is our IAccSession object, and the second parameter is a prefix to be used when defining event callbacks. Our plugin uses the session_ prefix; therefore, the handler for the DAccEvents::BeforeImSend event is session_BeforeImSend.

Adding commands is done as with COM plugins, using the IAccPluginInfo::AddCommand function. To receive commands from the application, the plugin must create a JavaScript object that implements the QueryStatus and Exec methods, and set this object to the commandTarget key of the supplied paramsDictionary.

function onConstructed() {
   var dict = scene.paramsDictionary;
   var session = dict.valueForKey("session");

   var pInfo = dict.valueForKey("pluginInfo");
   var cmd = pInfo.addCommand(kCommandId);
   cmd.text = "(un)scramble";

   scene.connectObject(session, "session_");
   dict.setValueForKey(new commandListener(), 
   "commandTarget");
}

function onDestroyed() {
   scene.disconnectObject("session_");
}

function session_BeforeImSend(session, imSession, recipient, im) {
   if(xlate) {
      // Convert IM to plain text, in place
      im.ConvertToMimeType("text/plain");
      im.Text = scramble(im.Text); 
   }
}

function scramble(s) {
   var output = "";

   for(var i = 0; i < s.length; i++) {
      var c = s.charAt(i);

      switch(c) {
         case "a":
            output += "n";
            break;
         // ...
         default:
            output += c;
            break;
      }
   }

   return output;
}

function commandListener() {}

commandListener.prototype.QueryStatus=function(id, users) {
   return (id == kCommandId) ? true : false;
}

commandListener.prototype.Exec=function(id, users) {
   if (id == kCommandId) {
   // We have a command, so toggle translation
      xlate = !xlate;
   }
}