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.ui.* AIM.params.*
AIM.util.* Globals

AIM.transactions.*

A set of API to send commands to the host. 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 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.*

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

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 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.util.listen
Overview:
The callback method for the listener object. Any event notifications, including 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 Internet Explorer, uses the <embed> objects created by AIM.util.createSoundObjects. If Internet Explorer, 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.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-dkDanish (Denmark)
de-atGerman (Austria)
de-chGerman (Switzerland)
de-deGerman (Germany)
en-caEnglish (Canada)
en-gbEnglish (United Kingdom)
en-usEnglish (United States)
es-esSpanish (Spain)
es-mxSpanish (Mexico)
fr-caFrench (Canada)
fr-frFrench (France)
it-itItalian (Italy)
nb-noNorwegian (Norway)
nl-nlDutch (Netherlands)
pl-plPolish (Poland)
sv-seSwedish (Sweden)
Submitted by Developer Network on March 4, 2008 - 11:04pm.
»

 

Login | AOL.com | About Us | Site Map | Help
Contact Us | AOL Terms of Service | AOL Privacy Policy
© 2008 AOL LLC. All Rights Reserved.



AIM Gallery


Open your Apps to millions of users at the AIM Gallery!

What Do You Think?

Are you finding it easier to get the information you need on our new website? Is there something missing? Do you want to make a suggestion? Please send your feedback here.