Web AIM JavaScript Reference

This document will detail the JavaScript API written to support the Web AIM API. The main components 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.*

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 to which the application needs to subscribe. 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.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.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.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.transactions.startSession

Overview:

Starts a session with the host.

Arguments:

String eventList

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

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").

Returns:

n/a

AIM.ui.*

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 <textarea> 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 with which this window will be communicating.

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.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.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.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 which an IM should be sent.

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 attribute.

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 which visual notification should be applied.

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 sets 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.*

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 which the class should be applied.

String oClassName

The name of the class to be applied to the element.

Returns:

n/a

See also:

AIM.util.removeClass

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 whose offset is needed.

Returns:

Object offset

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

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.uti.cookie.get

Overview:

Gets the value of the specified cookie.

Arguments:

String cookieName

The name of the cookie whose 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 one 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 an <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 (e.g. – 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.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.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 whose wim_id matched the wimId argument.

See also:

AIM.util.getAIMIDCollection

AIM.util.getElementsByClassName

Overview:

Returns an HTML element array of elements whose 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.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.params.*

AIM.params.baseTransactionURI

The fully-qualifed URL to the transaction host.

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.sound

Boolean that defines if sounds are played in the application. Defaults to true.

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.text.*

Defines the text to be displayed to users (e.g. – sendButtonText: "Send").

AIM.params.text.errors.*

Defines error text for the application.

AIM.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.transactions.*

Defines the paths on the host to the transactions (e.g. – AIM.params.transactions.startSession is "aim/startSession")

AIM.params.user

The screen name of the user.

Parameter Constants

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.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.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.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.REQUEST_TIMEOUT

The value of the "timeout" argument passed to the host in milliseconds. Zero for never. Firefox uses 2000, all other browsers use 60000.

AIM.params.RETAIN_WINDOW

Determines if the application should hide a window when the user clicks its close button, or remove it from the DOM. 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.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.

Globals

baseResourceURI

Tells the API where to look for images, sounds, etc. Default is http://o.aolcdn.com/aim/web-aim/default-theme/

baseLang

Language to use. Default is en-us. Acceptable values are:

da-dk	Danish (Denmark)
de-at	German (Austria)
de-ch	German (Switzerland)
de-de	German (Germany)
en-ca	English (Canada)
en-gb	English (United Kingdom)
en-us	English (United States)
es-es	Spanish (Spain)
es-mx	Spanish (Mexico)
fr-ca	French (Canada)
fr-fr	French (France)
it-it	Italian (Italy)
nb-no	Norwegian (Norway)
nl-nl	Dutch (Netherlands)
pl-pl	Polish (Poland)
sv-se	Swedish (Sweden)