| |
One of the powerful features of ChatAny services is that ChatAny provides very sophisticated Application Programming Interface(API) for users to build and customize their items inside the room. Each item has its own script that controls its appearance and behavior. First, here are a few sample items as follows. |
| |
| |
1.1. Item script is just javascript. |
| |
| |
Item script is just the plain, ubiquitous javascript so whoever knows javascript supposedly should be able to build his or her item with little extra effort. In order to have the item look and change at the same time in all viewers' room, some concurrent call API has to be understood and called accordingly. Please see the API below for details. |
| |
| |
1.2 ChatAny items are built with prototype.js and scriptaculous. |
| |
| |
1.3 onLoad() and onUnload() callback functions |
| |
Every item script inherits built-in properties and functions from its parent class. Here are documentation for prototype.js. For scriptaculous, please refer to this. |
| |
| |
Basically, the item script will be a hash of functions. Those functions will be added to the inherited items functions. All item functions have to be referred by this keyword in javascript such as this.functionName. Below is a dummy example of item script. Please notice the "this" keyword before "onLoadAction" and "text" |
| |
{ text: 'Inside unload function', onLoad: function () { this.onLoadAction() { vcomAPI.alert(this.text); } }, onUnload: function () { }, onLoadAction: function() { } // no ',' here. }
|
| |
| |
1.4 Versatile functions to concurrently update all participating browser clients. |
| |
| |
The reason for using ChatAny API is mainly to make items behave the same way in all participating client browsers. ChatAnt API use the following three ways to achieve this in a simple, organized way. |
| |
| |
- configXML
- The configXML can be set to display a list of configuration values that can be changed at the run time by item menu item "Edit Configuration".
- persistentXML
- The states for the item can be persistently stored in the item database if they are stored in persistentXML.
- vcomConcurrentCall
- This function can be used to call a remote function for all other browser clients or all browser clients including the one containing the caller. It can update the configXML and persistentXML at the same time.
|
| |
| |
1.5 Sample Item Scripts |
| |
|
| |
| |
2. Why do we provide this API? |
| |
| |
ChatAny is a web site to promote virtual community with more adventure, fun and real-time interaction. In order for us to achieve that, we have to be open and invite more participation and help from every member. So, all members world wide are encouraged to write their own items that they think fit their need and even better, they can be exchanged or just cloned and sold to make a profit. |
| |
| |
|
| |
| |
3. Who will use this API? |
| |
| |
Any developer with basic HTML and javascript knowledge should be able to write a simple item after browsing through this documentation. The item written can be cloned with a fee of 250 gold coins and put in the shop for sale. |
| |
| |
4. API in a nutshell |
| |
| |
4.1 onLoad() and onUnload() callback functions: |
| |
| |
When an item is added to the room or the room is loaded the first time, the onLoad() function will be called. This is the entry point for the execution of the item script. |
| |
| |
When an item is removed from the room or when user is leaving the room page, the onUnload() function will be called. This is the exit point for the execution for the item script. |
| |
| |
4.2 Inherited item properties: |
| |
| |
The following is a list of inherited item properties. All these properties are available for item script to access with a "this." prefix. |
| |
this.element Usage: This is the div element for the item. It contains the item image by default. The id of this element can be accessed by this.element.id. By changing the innerHTML of this element, the html code of the item can be accessed or altered. Example: As below is a brief html example for an item.
<div id="ItemDiv_10_97"><img id="IMG_ItemDiv_10_97" /></div>
|
| |
4.3 Inherited item functions: |
| |
| |
The following is a list of inherited item functions. All these functions are available for item script to access with a "this." prefix. |
| |
this.vcomMoveTo(x, y) Usage: Move an item to location x px, y px in the room. The room is 620 px by 620 px. Params: x -> horizontal location in px after move y -> vertical location in px after move Return: None
|
| |
this.vcomMoveToAvatar(avatarId) Usage: Move an item to location x px, y px in the room. The room is 620 px by 620 px. Params: The avatarId to move to. If not set, the item will move to the current avatar. Return: None
|
| |
this.vcomResize(width, height) Usage: Resize an item to width px and height px. Params: width -> width in px after resize height -> height in px after resize Return: None
|
| |
this.vcomIsLocked() Usage: Check if the item is locked Params: None Return: true if the item is locked false if the item is not locked
|
| |
this.vcomConcurrentCall(functionName, funcationArgs, [mode], [onCompleteCallback], [onFailureCallback]) Usage: This function is used to communicate with ChatAny server cluster for concurrently call a remote function for all browser clients in the same room as that of the current item. While calling the remote function, certain local data such as this.configXML, this.persistentXML, and this.cacheXML(not implemented yet) can be updated to all browser client at the same time. Here are the possible values of mode. All values can be combined with bit-wise or '|' in a single parameter.
Params: functionName -> the function to be called on remote browser window. functionArgs -> the function arguments for the function. It can be a string or an xmlDoc or a string of XML. When it is a string of XML, XML_ARG has to be passed in mode parameter. mode -> Default: String Arg vcomAPI.XML_ARG: functionArgs is an XML Default: No config xml update vcomAPI.CONFIG_XML: Pass and update config xml Default: No persistent xml update vcomAPI.PERSISTENT_XML: Pass and update persistent xml
Default: No cache xml update vcomAPI.CACHE_XML: Pass and update cache xml (Not implemented yet)
Default: No reload. vcomAPI.RELOAD: Reload is to call onUnload then call onLoad. This is usually used together with CONFIG_XML Default: Notify all but self vcomAPI.NOTIFY_ALL: Notify all including self Default: Asynchronous vcomAPI.SYNCHRONUS: Waiting for all remote calls to complete. (Not implemented yet)
Default: No Lock. This is an item specific lock. vcomAPI.LOCK_FIRST: Lock the item first. To release the lock, this.releaseLock() can be called. Note: NOTIFY_ALL mode will be enforced if LOCK_FIRST is used. This is because to lock an item, it has to lock all items at the same time to avoid racing condition in the server. onCompleteCallback -> callback function for successful execution of the vcomConcurrentCall. Note: There is no support of returning the status of the remote function call now. onFailureCallback -> callback function for successful execution of the vcomConcurrentCall. Return: None. But, two callback functions can be set for success and failure case of the call. Example: this.vcomConcurrentCall('onBullLevel2only', '', vcomAPI.PERSISTENT_XML); This call will trigger a function call 'onBullLevel2only' without arguments in all remote browser clients except the local client. Meanwhile, the local this.persistentXML will be copied and passed to both database in server and all remote browser clients except the local client.
|
| |
this.vcomReleaseLock() Usage: release the item lock on this item. This is the lock for item synchronization control. It is not the lock in the item menu. Params: None Return: None
|
| |
4.4 vcomAPI properties: |
| |
| |
vcomAPI is a set of utility functions ChatAny has provided for writing item scripts more effectively. The following is a list of vcomAPI properties. All these properties are available for item script to access via the prefix "vcomAPI.". |
| |
vcomAPI.isRoomOwner Usage: Check if the current user is the room owner. room owner has more permissions to operate on the item. Value: true if the current user is the room owner. false if the current user is NOT the room owner.
|
| |
vcomAPI.isUserInRoom Usage: Check if the current user is in room. The script then can pop up an alert message window to ask user to enter the room first. Value: true if the current user is in the room. false if the current user is NOT in the room.
|
| |
vcomAPI.isVisitor Usage: Check if the current user has not logged in, i.e., a visitor. Value: true if the current user is a visitor. false if the current user is NOT a visitor.
|
| |
vcomAPI.avatarId Usage: The ID of the Avatar of the current user. Value: A string indicate the current Avatar ID.
|
| |
vcomAPI.userName Usage: This is the user name if the user has registered and logged in. Value: A string of the user name of the current user. null if the user has not logged in yet.
|
| |
vcomAPI.avatarWidth Usage: The width of the avatar in the room. Value: integer value. The value is 94 now. The unit is px.
|
| |
vcomAPI.avatarHeight Usage: The height of the avatar in the room. Value: integer value. The value is 150 now. The unit is px.
|
| |
vcomAPI.roomWidth Usage: The width of the room. Value: integer value. The value is 620 now. The unit is px.
|
| |
vcomAPI.roomHeight Usage: The height of the avatar in the room. Value: integer value. The value is 620 now. The unit is px.
|
| |
| |
4.5 vcomAPI functions: |
| |
| |
The following is a list of vcomAPI functions. All these functions are available for item script to access via the prefix "vcomAPI.". |
| |
vcomAPI.parseXML(text) Usage: Check if the current user is the room owner. room owner has more permissions to operate on the item. Params: text -> a text string Return: object -> an XML object
|
| |
vcomAPI.XMLToString(xmlObject) Usage: Check if the current user is the room owner. room owner has more permissions to operate on the item. Params: xmlObject -> an xml object Return: a string representation of the input XML object
|
| |
vcomAPI.XMLGetFirstNodeValue(xmlObject, nodeName) Usage: In xmlObject, get the value of the first node with name that equals to nodeName. Params: xmlObject -> an xml object nodeName -> name of the first node Return: a string of the node value
|
| |
vcomAPI.XMLGetNodeValue(xmlObject, nodeName, nth) Usage: In xmlObject, get the value of the nth node with name that equals to nodeName. Params: xmlObject -> an xml object nodeName -> name of the nth node nth -> sequence of the node Return: a string of the node value
|
| |
vcomAPI.alert(thisItem, message) Usage: Pop up a message window from an item Params: thisItem -> 'this' (Inside item script, 'this' is the instance of the item.) message -> the message to be shown in the pop up window
Return: None
|
| |
vcomAPI.confirm(element_id, OKFunction, CancelFunction, message) Usage: Pop up a confirmation message window with OK and Cancel buttons for an item OKFunction will be called if user clicks OK button. CancelFunction will be called if user clicks Cancel button. Params: element_id -> 'this.element.id' (Inside item script, 'this' is the instance of the item.) OKFunction -> name of the function called if user clicks OK button. CancelFunction -> name of the function called if user clicks Cancel button. message -> the message to be shown in the pop up window
Return: None
|
| |
vcomAPI.prompt(thisItem, promptMessage, okFunction, cancelFunction, promptDefaultValue) Usage: Pop up a confirmation message window with OK and Cancel buttons for an item OKFunction will be called if user clicks OK button. CancelFunction will be called if user clicks Cancel button. Params: thisItem -> 'this' (Inside item script, 'this' is the instance of the item.) promptMessage -> the message to be shown in the pop up window OKFunction -> name of the function called with prompt value if user clicks OK button. CancelFunction -> name of the function called if user clicks Cancel button. promptDefaultValue -> the text to be shown inside the prompt. Return: None
|
| |
| |
4.6 vcomAPI event and callbacks: |
| |
| |
vcomAPI also provides event notification interface for room events. As for now, user can register their callback function for enter or exit room event. |
| |
vcomAPI.registerEvent(event, callback) Usage: Register room event with callback function. Params: event -> room events. Multiple room events can be combined with bit-wise or '|'. current events: vcomAPI.EVENT_ENTER_ROOM, vcomAPI.EVENT_EXIT_ROOM, vcomAPI.EVENT_MOVE, vcomAPI.EVENT_ITEM_LOCK, vcomAPI.EVENT_ITEM_UNLOCK, vcomAPI.EVENT_AVATAR_CHAT, vcomAPI.EVENT_ITEM_CHAT, vcomAPI.EVENT_ITEM_RESIZE, vcomAPI.EVENT_ALL Note: if the itemClass or 'this' needs to be accessed inside the callback function. The convenient bind function from prototype.js should be used. Return: None Callback: callback function will have two parameters event and data passed back. event: vcomAPI.EVENT_ENTER_ROOM, vcomAPI.EVENT_EXIT_ROOM, data: a hash {name:userNameValue, id:userIDValue} Example: onLoad: function() { vcomLIB.debugMessage("onLoad"); this.myAllEventCallback = this.allEventCallback.bind(this); vcomAPI.registerEvent(vcomAPI.EVENT_ALL, this.myAllEventCallback); }, allEventCallback: function(event, data) { vcomLIB.debugMessage("event:" + event); for (var dataItem in data) { vcomLIB.debugMessage(dataItem + ":" + data[dataItem]); } if (event == vcomAPI.EVENT_MOVE && data['type'] == 'Avatar' && data['isOriginator'] == 'yes') { vcomAPI.kickOut(data['id']); } }, onUnload: function() { vcomLIB.debugMessage("onunload"); vcomAPI.unregisterEvent(vcomAPI.EVENT_ALL, this.myAllEventCallback ); }
|
| |
| |
4.7 vcomLIB log message: |
| |
| |
Log message API can show log message in the log message window. There are four levels from lowest to highest- error, warning, info, and debug. Messages can be sent by vcomLIB.errorMessage, vcomLIB.warningrMessage, vcomLIB.infoMessage, and vcomLIB.infoMessage to respective levels.
There are also exact match log level - LOG_INFO1, LOG_INFO2, LOG_INFO3, LOG_DEBUG1, LOG_DEBUG2, and LOG_DEBUG3.
More on show/hide log message window. |
| |
vcomLIB.setLogMessageOptions(logLevel, logMethod) Usage: Set up log message window. It can be set up in two way, by_level or by_match. By level -> this.LOG_ERROR < this.LOG_WARN < this.LOG_INFO < this.LOG_DEBUG By match -> only log that matches exactly will be shown. Params: logLevel (by level) -> this.LOG_ERROR this.LOG_WARN this.LOG_INFO this.LOG_DEBUG logLevel (by match) -> this.LOG_INFO1 this.LOG_INFO2 this.LOG_INFO3 this.LOG_DEBUG1 this.LOG_DEBUG2 this.LOG_DEBUG3 logMethod -> 'by_level' or 'by_match' Note: When combined with 'by level', this.LOG_INFO1, this.LOG_INFO2, this.LOG_INFO3 are the same as this.LOG_INFO. When combined with 'by level', this.LOG_DEBUG1, this.LOG_DEBUG2, this.LOG_DEBUG3 are the same as this.LOG_DEBUG. Return: None Example: vcomLIB.setLogMessageOptions(this.LOG_DEBUG, 'by_level'); vcomLIB.setLogMessageOptions(this.LOG_DEBUG1, 'by_match');
vcomLIB.errorMessage(message) Usage: Show error message in debug window Params: message -> message string Return: None Example: vcomLIB.errorMessage('item configuration is invalid.');
vcomLIB.warnMessage(message) Usage: Show error message in debug window Params: message -> message string Return: None Example: vcomLIB.warnMessage('item configuration is invalid.');
vcomLIB.infoMessage(message) Usage: Show error message in debug window Params: message -> message string Return: None Example: vcomLIB.infoMessage('item configuration is invalid.');
vcomLIB.debugMessage(message) Usage: Show error message in debug window Params: message -> message string Return: None Example: vcomLIB.debugMessage('item configuration is invalid.');
vcomLIB.showLogMessage() Usage: Show the log message window Params: None Return: None Example: vcomLIB.showLogMessage();
vcomLIB.hideLogMessage() Usage: Hide the log message window Params: None Return: None Example: vcomLIB.hideLogMessage();
vcomLIB.resetLogMessage() Usage: Clean up all log messages in log message window Params: None Return: None Example: vcomLIB.resetLogMessage();
|
| |
| |
4.8 Adding right click menu on the item: |
| |
| |
Mulit-level user menus can be added by a conveninent naming convention. First, add an first level 'vcomOnMenuUx' (x is any character) with menu text into this.vcomItemMenu object. Then, define the menu callback function the same as the menu name 'vcomOnMenuUx'. The second level menu can be defined as vcomOnMenuUxy. The order of the user menu will be sorted alphabetically and put below system menu items. |
| |
Sample code of an item with user menus:
{ onLoad: function() { vcomLIB.debugMessage("test evemt"); this.vcomItemMenu['vcomOnMenuU0']='test U menu0'; this.vcomItemMenu['vcomOnMenuU1']='test U menu1'; this.vcomItemMenu['vcomOnMenuU11']='test U menu11'; this.vcomItemMenu['vcomOnMenuU12']='test U menu12'; this.vcomItemMenu['vcomOnMenuU121']='test U menu121'; this.vcomItemMenu['vcomOnMenuU122']='test U menu122'; this.vcomItemMenu['vcomOnMenuU2']='test U menu2'; this.vcomItemMenu['vcomOnMenuU3']='test U menu3'; this.vcomItemMenu['vcomOnMenuUA']='vcomOnMenuA'; this.vcomItemMenu['vcomOnMenuUA1']='vcomOnMenuA1'; this.vcomItemMenu['vcomOnMenuUA2']='vcomOnMenuA2'; }, vcomOnMenuU0: function() { vcomLIB.debugMessage("click menu vcomOnMenuU0"); }, vcomOnMenuU1: function() { vcomLIB.debugMessage("click menu vcomOnMenuU1"); }, vcomOnMenuU11: function() { vcomLIB.debugMessage("click menu vcomOnMenuU11"); }, vcomOnMenuU12: function() { vcomLIB.debugMessage("click menu vcomOnMenuU12"); }, vcomOnMenuU121: function() { vcomLIB.debugMessage("click menu vcomOnMenuU121"); }, vcomOnMenuU122: function() { vcomLIB.debugMessage("click menu vcomOnMenuU122"); }, vcomOnMenuU2: function() { vcomLIB.debugMessage("click menu vcomOnMenuU2"); }, vcomOnMenuU3: function() { vcomLIB.debugMessage("click menu vcomOnMenuU3"); }, vcomOnMenuUA: function() { vcomLIB.debugMessage("click menu vcomOnMenuUA"); }, vcomOnMenuUA1: function() { vcomLIB.debugMessage("click menu vcomOnMenuUA1"); }, vcomOnMenuUA2: function() { vcomLIB.debugMessage("click menu vcomOnMenuUA2"); } }
|
| |