AIM Web API | Javascript API Documentation

This document will detail the javascript API written to support the Web AIM API. The main compontents of the Javascript are AIM.core.*, AIM.params.* and AIM.transactions.*. The remainder of the code is intended to support various widgets and is not required to use the API.

AIM.transactions.*

A set of API to send commands to the host.

Note: Transaction functions do not return anything. To use their data, register a callback for each method in the AIM.params.callbacks object.

AIM.transactions.endSession

Overview:: Ends the session with the host and invalidates the token.
Arguments:: n/a

AIM.transactions.getPresenceInfo

Overview:: Collects presence widget data from the page and requests the presence info from the service for the ids found.
Arguments:: n/a
Returns:: n/a

AIM.transactions.getToken

Overview:

Requests a token identifier from the service.

Arguments:

String eventList: A comma delimited list of event notifications the application needs to subscribe to. This will be passed to AIM.transactions.startSession.

Returns:

n/a

Notes:

getToken is the first transaction any application should call, as subsequent transactions may require the token. See AIM.transactions.startSession for details on the eventList argument.

AIM.transactions.startSession

Overview:

Starts a session with the host.

Arguments:

String eventList

A comma delimited list of event notifications the application needs to subscribe to.

Allowable Event Subscriptions

buddylist: Subcribes the application to a one-time buddy list update.
presence: Subscribes the application to buddy updates, i.e., a user changing their status to "away".
im: Subscribes the application to incoming Instant Message events for the user.
typing: Subscribes the application to typing status events, i.e., "so and so is typing"
imData: Subscribes the application to data im events.

Returns:

n/a

AIM.transactions.sendDataIM

Overview:

Sends a data IM.

Arguments:

String aimId: The aim ID of the user for whom the data IM is intended.
String data: The data to be sent.
String cap: 32 character UUID that represents the capability.
String type: The type of data being sent. Values are invite,accept,deny,data and end.

Returns:

n/a

AIM.transactions.sendTextIM

Overview:

Sends an instant message.

Arguments:

String screenName: The screen name of the user for whom the Instant Message is intended.
String message: The Instant Message text to be sent.

Returns:

n/a

AIM.transactions.setAwayMessage

Overview:

Sets a custom away message and puts the user's status to "away".

Arguments:

String msg: The custom away message.

AIM.transactions.setState

Overview:

Sets the availability state of the user with the host.

Arguments:

String status: The status of the user. Allowable values are "away" and "online".

AIM.transactions.setTyping

Overview:

Notifies the host of the user's typing status.

Arguments:

String tStatus: The users typing status. Allowable values are "typing", "typed" and "none".
String screenName: The screen name of the user who should be notified of the user's typing status.

AIM.ui.*

A set of user-interface API for managing IM windows, buddy lists, etc.

AIM.ui.acceptIncomingMessage

Overview:

Accepts incoming messages for the user. Creates an IM window if needed, and populates the window with the incoming message. Will also fire an auto-reply if needed.

Arguments:

JSON Object response: The IM notification from the host.

Returns:

n/a

AIM.ui.clearVisualNotification

Overview:

Stops the visual notification timer and sets the H2 element's class back to normal. Is called when an IM window recieves focus.

Arguments:

String windowId: The id attribute value of the IM window for which the notification should be cleared.

Returns:

n/a

See Also:

AIM.ui.showVisualNotification

AIM.ui.createAvailabilityMenu

Overview:: Creates the availability menu as defined by the AIM.params.text.availabilityMenuItems construct.
Arguments:: n/a
Returns:: n/a

AIM.ui.createAwayMessage

Overview:: Creates a window with a text area and button to allow a user to specify their away message.
Arguments:: n/a
Returns:: n/a

AIM.ui.createBuddyList

Overview:

Renders a Buddy List to the web page.

Arguments:

Object data: A JSON object created with AIM.transactions.getBuddyList

Returns

n/a

AIM.ui.createIMWindow

Overview:

Creates a new IM window on the document.

Arguments:

String screenName: The screen name of the user that this window will be communicating with.

Returns:

n/a

AIM.ui.createWindowFrame

Overview:

Creates the basic elements required for a window, including the draggable window title and close button.

Arguments:

String identifier: The prefix for the window's id attribute. Will have "_AIMwindow" appended.
String clsName: The value of the class attribute to be applied to the window.
String winTitle: The title text of the window.

Returns:

HTMLObject win: An HTML Element that acts as a container for content that needs to be placed in a window.

AIM.ui.destroyAllIMWindows

Overview:: Removes all IM Windows from the DOM. Should be called when a user ends a session. Ignore AIM.params.RETAIN_WINDOW.
Arguments:: n/a
See Also:: AIM.ui.removeIMWindow, AIM.ui.removeAllIMWindows

AIM.ui.getIMWindows

Overview:: Provides a reference to each open IM window on the document.
Arguments:: n/a
Returns:: Object array of all IM windows.

AIM.ui.populateMessageWindow

Overview:

Formats user initiated message content and updates IM windows with that content.

Arguments:

JSON Object response: The sendTextIM response from the host.

Returns:

n/a

AIM.ui.populateIncomingMessageWindow

Overview:

Formats incoming message content and updates IM windows with that content.

Arguments:

JSON Object response: The response from the host when an IM event is recieved.

Returns:

n/a

AIM.ui.removeAllIMWindows

Overview:: Hides or removes all IM windows from the DOM.
Arguments:: n/a
Returns:: n/a
Notes:: If AIM.params.RETAIN_WINDOW is true, the windows will have their display set to none. Otherwise, the windows are removed from the DOM.
See Also:: AIM.removeIMWindow, AIM.ui.destroyAllIMWindows

AIM.ui.removeIMWindow

Overview:

Hides or removes an IM window from the DOM

Arguments:

String windowID: The value of the window's "id" attribute: screenName_AIMwindow

Returns:

n/a

Notes:

If AIM.params.RETAIN_WINDOW is true, the window will have its display set to none. Otherwise, the window is removed from the DOM.

See Also:

AIM.removeIMWindow, AIM.ui.destroyAllIMWindows

AIM.ui.screenNamePrompt

Overview:: Allows the user to specify a screen name to send an IM to.
Arguments:: n/a
Returns:: n/a

AIM.ui.setHeaderState

Overview:

Sets the collapsed state of a buddy list group and sets a cookie to persist that state.

Arguments:

HTMLObject header: The object that is the previousSibling of the block of elements to be hidden.

Returns:

n/a

AIM.ui.setIMWindowZIndex

Overview:

Raises the zIndex of a given IM window above that of other existing windows.

Arguments:

String activeWin: The value of the IM window's "id" attriibute.

Returns:

n/a

AIM.ui.showBuddyInfo

Overview:

Fills the "AIMBuddyListBuddyInfo" element with presence data content. Called when a screen name is moused-over.

Arguments:

JSON Object buddyInfo: The presence object response from the host. Is stored in AIM.ui.storedBuddyInfo[screenName] and updated whenever a presence update is recieved.

Returns:

n/a

AIM.ui.showVisualNotification

Overview:

Toggles the class of the IM window's H2 element from "AIMBuddyListIMWindowNotifyOff" to "AIMBuddyListIMWindowNotifyOn". Runs in an interval over AIM.params.NOTIFICATION_THROB milliseconds. Called when an incoming IM is recieved - it is not called if AIM.params.VISUAL_NOTIFICATION is false.

Arguments:

String windowId: The value of the id attribute for the IM window to apply the visual notification to.

Returns:

n/a

See Also:

AIM.params.VISUAL_NOTIFICATION, AIM.params.NOTIFICATION_THROB, AIM.ui.clearVisualNotification

AIM.ui.toggleSound

Overview:: Toggles the sound preference and set or updates the preference in a cookie.
Arguments:: n/a
Returns:: n/a

AIM.ui.updateBuddyList

Overview:

Updates the buddy list when update notifications are recieved, i.e., a buddy changes status to "away" or signs on.

Arguments:

JSON Object response: The update notification from the host.

Returns:

n/a

AIM.ui.updateTypingStatus

Overview:

Updates the typing status area of an IM window with the defined text for the event.

Arguments:

JSON Object response: The update notification from the host.

Returns:

n/a

See Also:

AIM.params.text.userTyping, AIM.params.text.userTyped, AIM.params.text.userStoppedTyping

AIM.ui.zebraStripeList

Overview:

Adds alternating classes of "even" and "odd" to a collection of HTML objects.

Arguments:

HTMLObjectCollection objectCollection: An array of elements to which the classes should be applied.

Returns:

n/a

AIM.util.*

A set of utility methods for destroying objects, I/O and other more generic functionality.

AIM.util.acceptData

Overview:

The callback for the JSON responses. Is passed as argument "c" in the URL to the host.

Arguments:

JSON Object response: The response as defined by the host.

Returns:

n/a

Note:

This is only used as the callback wrapper for host responses. See AIM.params.callbacks to define what this method should do with the data it accepts.

See also:

AIM.params.callbacks

AIM.util.addClass

Overview:

Adds a class value to the class attribute of an HTML element.

Arguments:

HTMLElement oElement: The HTML element to apply the class to.
String oClassName: The name of the class to be applied to the element.

Returns:

n/a

See Also:

AIM.util.removeClass

AIM.util.captureOffset

Overview:

Determines the mouse cursor offsets and applies the values to AIM.util.offsetX and AIM.util.offsetY.

Arguments:

Event e: The mousedown event from the object for which this is an onmousedown handler.

Returns:

n/a

AIM.util.calculateOffset

Overview:

Calculates the offset top and offset left of the object relative to its parent hierarchy.

Arguments:

HTMLObject obj: The HTML element who's offset is needed.

Returns:

Object offset: Object with x and y properties defining the object's offsets.

AIM.uti.cookie.get

Overview:

Gets the value of the specified cookie.

Arguments:

String cookieName: The name of the cookie whos value you need.

Returns

String cookieValue: The value of the cookie.

AIM.util.cookie.set

Overview:

Sets a cookie with name cookieName, value cookieValue and an expiration of session or never.

Arguments:

String cookieName: The name of the cookie to be set.
String cookieValue: The value of the cookie to be set.
Boolean session: If true, sets the cookie only for the current session. Otherwise, sets an expiration of 1 year from the current date.

Returns:

n/a

AIM.util.createListenerObject

Overview:: Creates a script element that opens a connection to the event notification host.
Arguments:: n/a
Returns:: n/a
Note:: This method is called by AIM.transactions.startSession, and is then called when needed by the API. You will rarely, if ever, need to call this manually.

AIM.util.createSoundObjects

Overview:: Creates am embed object for each sound file specified by AIM.params.sounds. This function is not used by Internet Explorer, as a different method for playing sounds is used in that browser.
Arguments:: n/a
Returns:: n/a

AIM.util.createStyleSheet

Overview:

Creates a style sheet with the specified URI and appends it to the head of the document.

Arguments:

String URI: The URI to the style sheet to be created.

Returns:

n/a

AIM.util.destroyDataObject

Overview:

Destroys the specified script element that acts as request/response to the host once it is no longer needed. I.E, once its callback is complete.

Arguments:

Integer objIndex: The index (usually requestId) in Array AIM.util.AIMData that defines the script.

Returns:

n/a

AIM.util.destroyListenerObject

Overview:: Removes the script element that acts as the listener for host events from the DOM.
Arguments:: n/a
Returns:: n/a

AIM.util.elapsedFromSeconds

Overview:

Calculates the hours and minutes elapsed from the onlineTime response in seconds.

Arguments:

Number oElapsed: The seconds online returned by the onlineTime response from the host.

Returns:

String: The formatted string of elapsed time, i.e. "4 hours, 21 minutes".

AIM.util.formatMessage

Overview:

Performs a series of regular expression on incoming or outgoing text strings. Example: adding "target="_blank"" to incoming messages containing links.

Arguments:

String oString: The string of text to be formatted.

Returns:

String: The formatted string.

AIM.util.formatTimeStamp

Overview:

Takes the UTC time stamp response from the host and converts it into an HH:MM format. Will use a 24 hour clock if AIM.params.TWENTY_FOUR_HOUR_CLOCK is true, and will not be called if AIM.params.SHOW_TIMESTAMP is false.

Argument:

Date oTimeStamp: A Date object to be converted to HH:MM

Returns:

String: The date formatted as [HH:MM]

AIM.util.getElementsByClassName

Overview:

Returns an HTML element array of elements who's class name matches the supplied argument.

Arguments:

HTMLElement oElm: The parent element to execute the search on.
String strTagName: Limit the search to specific tag name. Use "*" for all element types.
String strClassName: The class name to search for.

Returns:

HTMLElement Array

An array of HTML elements who matched the search criteria.

Note:

This is an adaptation of Snook/Nyman's getElementsByClassName found here.

AIM.util.getElementsByAIMID

Overview:

Provides access to all elements representing a specific screen name. For example, if a user is in more than one group, this will provide a pointer to both.

Arguments:

String wimId: The screenName to look for.
HTMLElement oContainer: The parent element that contains the screen name. For example, in the case of AIM, this would be document.getElementById("AIMBuddyListContainer")

Returns:

HTMLElement Array: An array of HTML elements who's wim_id matched the wimId argument.

See Also:

AIM.util.getAIMIDCollection

AIM.util.getPresenceContainers

Overview:

Returns an object collection of all defined "presence" elements on the page, i.e., those with a class name of "AIMPresenceWidget".

Arguments:

n/a

Returns:

Object Array

Has two properties:

element: A pointer to an element that has the AIMPresenceWidget class name.
screenName: The screen name the widget is for.

AIM.util.getAIMIDCollection

Overview:

Provides access to every element in a Buddy List that represents a screen name.

Arguments:

HTMLElement parentObj: The parent element that contains the screen name list. In the case of AIM for example, this would be document.getElementById("AIMBuddyListContainer")

Returns:

HTMLElement Array: An array of HTML elements that have a "wim_id" attribute.

See Also:

AIM.util.getElementsByAIMID

AIM.util.listen

Overview:

The callback method for the listener object. Any event notifications, i.e., incoming IMs or presence changes, are routed through this method.

Arguments:

JSON Object response: The event notification from the host.

Returns:

n/a

Note:

This is passed as parameter "c" on the url that sends event notifications, and you needn't call this method directly. Use AIM.params.callbacks.listener to define what method this method should call to handle event updates.

See Also:

AIM.params.callbacks.listener

AIM.util.playSound

Overview:

Plays the specified sound. If not MSIE, uses the embed objects created by AIM.util.createSoundObjects. If MSIE, removes any existing BGSOUND elements and creates a new one to play the sound.

Arguments:

String sndType: The type of sound to play. Value correlates to the value used to define the sound in AIM.params.sounds.

Returns:

n/a

AIM.util.removeClass

Overview:

Removes the specified class from the specified element.

Arguments:

HTMLElement oElement: The element to remove the class from.
String oClass: The class to remove from the element.

Returns:

n/a

See Also:

AIM.util.addClass

AIM.params.requestData

Overview:

Sends a request to the host in reaction to a user triggered event, i.e., sending an IM.

Arguments:

Object transactionObj: The object that defines the transaction type and transaction URI and any other data the transaction requires. Is defined by AIM.transactions.*

Returns:

n/a

Note:

It is not necessary to call this method directly. It is a helper function for the transaction methods.

AIM.util.resetUserNotified

Overview:: Sets the AIM.util.userNotified array values back to false. This will allow users who have already recieved the user's away message to recieve it again.
Arguments:: n/a
Returns:: n/a
See Also:: AIM.util.userNotified

AIM.util.returnScrollDimensions

Overview:

Returns the horizontal or vertical scroll dimensions of the window.

Arguments:

Boolean which: Returns horizontal scroll if true, vertical if false.

Returns:

Integer: The vertical or horizontal scroll offset of the window.

AIM.params.*

Parameters that define how the various components of the application should behave.

AIM.params.assertCaps: Comma delimited string of the capabilities the client is able to take advantage of.
AIM.params.interestCaps: Comma delimited string of the capabilities the client is interested in receiving from other clients.
AIM.params.user: The screen name of the user.
AIM.params.baseTransactionURI: The fully qualifed URL to the transaction host.
AIM.params.transactions.*: Defines the paths on the host to the transactions. e.g., AIM.params.transactions.startSession is "aim/startSession",
AIM.params.sounds.*: Defines the path to the sound files used for various sounds in the application. e.g, IM:"im.wav". The name of the property should be used as the argument to AIM.util.playSound()
AIM.params.callbacks.*: Defines the callback functions for application events, e.g., sendTextIM:"AIM.callbacks.sendTextIM". The name of the property should be used as the value of the "type" property on the object passed to AIM.util.requestData.
AIM.params.text.*: Defines the text to be displayed to users, e.g., sendButtonText: "Send".
AIM.params.text.errors.*: Defines error text for the application.
ABl.params.text.availabilityMenu: Defines the contents and the onclick event handlers of items in the availability menu. The property can be anything you like, though it should have a meaningful name. The subproperties are "text", which defines the text to be displayed in the menu, and "method" which defines the javascript function to be called from that items onclick event. If you'd like a divider line in the menu, simply define both subproperties as null and a horizontal rule element will be inserted.
AIM.params.sound: Boolean that defines if sounds are played in the application. Defaults to true.

Parameter Constants

AIM.params.DEBUG: Boolean var that tells the API to output debug data or not. Default is false.
AIM.params.DEFAULT_ICON: The buddy icon to be used if the service doesn't specify one. Default value is baseResourceURI + "default_icon.png".
AIM.params.AWAY_MSG_LIMIT: The maximum character length of an away message. Default is 1024.
AIM.params.BUDDY_LIST_DRAG: If true, allows the buddy list to be draggable. Default is false.
AIM.params.REQUEST_TIMEOUT: The value of the "timeout" argument passed to the host in milliseconds. 0 for "never". Firefox uses 2000, all other browsers use 60000.
ABl.params.NOTIFICATION_THROB: The amount of time in milliseconds that the visual notification interval should run. Default is 1000.
AIM.params.RENDER_SEND_BUTTON: Defines if the application should include a "send" button when it creates IM windows. Default is true.
AIM.params.SHOW_OFFLINE: Determines if the application should show users in the buddy list that are currently not signed on. Default is false.
AIM.params.CREATE_AVAILABILITY_MENU_BL: Determines if the application should create the Availability Menu when it creates the Buddy List. Default is true.
AIM.params.CREATE_AVAILABILITY_MENU_IM: Determines if the application should create the Availablity Menu on the IM window. Default is true.
AIM.params.RETAIN_WINDOW: Determines if the application should hide a window when the user clicks it's close button, or remove it from the DOM. Default is true.
AIM.params.SHOW_TIMESTAMP: Determines if the application should display a timestamp for IMs. Default is true.
AIM.params.TWENTY_FOUR_HOUR_CLOCK: Determines if the application should use a 24 hour clock for timestamps. Default is false.
AIM.params.VISUAL_NOTIFICATION: Determines if the application should display the defined visual notifications when an IM is recieved. Default is true.