免費的造型和服裝
    免費的房間和家具
    免費的門鈴和相簿
    免費贈送50枚金幣
    免費的基本會員制
    無需下載
應用程序界面
 
  Table of Content:
 
 
  1. Overview
 
  1.1 Item script is just javascript.
 
  1.2 ChatAny items are built with prototype.js and scriptaculous.
 
  1.3 onLoad() and onUnload() callback functions
 
  1.4 Versatile functions to concurrently update all participating browser clients.
 
  1.5 Sample Item Scripts
 
  2. Why do we provide this API?
  3. Who will use this API?
 
  4. API in a nutshell
 
  4.1 onLoad() and onUnload() callback functions:
 
  4.2 Inherited item properties
 
  4.3 Inherited item functions
 
  4.4 vcomAPI properties
 
  4.5 vcomAPI functions
 
  4.6 vcomAPI event and callbacks
 
  4.7 vcomLIB log message
 
  4.8 Adding right click menu on the item
 
  5. Why some javascript files are obfuscated?
 
  6. Development Tips
 
  6.1 Avoid using javascript alert function
 
  6.2 Use debug message window
 
  7. Question and Feedback
 
 
 
 
  1. Overview:
 

  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");
}
}
 

  5. Why application.js is obfuscated?
 
  application.js contains most item scripts and API calls. It is obfuscated to reduce the size of javascript needed to be downloaded to users. In the future, we plan to open up this file.
 
  6. Development Tips
 
  6.1 Avoid using javascript alert function
 
  Use vcomAPI.alert() function instead. The reason is as follows. Javascript script alert function will block all event processing in the IE browser(Firefox is fine) including the communication between the browser and ChatAny server. When javascript alert is called and the message window is popped up, ChatAny server can not notify or refresh the chat window. If alert window is not closed for a long time, all the messages sent back from the server will be queued up. This may cause adverse side effect such as losing chat message, out-of-sync items, etc.
 
  6.2 Use log message window
 
  In the chat message window, type 'vcom:show' to show the log message window. Type 'vcom:hide' to hide the log message window. Use 'vcom:debug', 'vcom:error', 'vcom:info' to control the logging level. Type 'vcom:reset' to clear the log. Log messages can be sent to log message window by log API.
 
  7. Question and Feedback
 
  Should you have any question or feedback, please post it on ChatAny forum under Advanced Discussion and topic API's.
 


常見問題 -  用戶協定 -  安全政策 -  應用程序界面 -  聯繫我們 -  關於我們 -  合作提案
Copyright © 2005-2008 巧天地 公司
版權所有.