Description

The widget APIs is set of functions that used by widget developer to create interaction and communication.
widget API consists of two parts. 1, the global functions that used to get widget context from the DOM. 2, the database and communication APIs, which has a general form call widgetApi, please see below for details.
The database and communication function has the general form as below

function widgetApi (api, context, object, callback);

api is a string of api name.
context is the memory context of the widget. getContext(object) will return the context of the widget that contains the object component. When user click a button in the widget, the onclick handler can call getContext(this) to get the context of the widget, here “this” is the reference to the button.
object is a javascript object that contains key-value pairs. widgetApi try to handle multiple key-value get and set in single request, the programmer can put multiple key-value pairs inside the object to executed the api is single request. All widgetApi associates to note and current user. If you want to set/get a key that does not associate to current user, use uid:”*” in Object to tell the system the operation will associates to note only, and user is all (means not associate to a specific user).
callback will be called with the return in the first parameter.

Global Function List

getNTPOffset()
function return the diff in ms that related to NTP time. After get the system time in javascript, add the diff to the system time everytime you get the system time.
getDisplayName()
function return display name for current login user.
getContext(obj)
function will return the context that will be used by widgetApi. The context is the widget owned memory, belong to widget itself. obj is any component inside the widget. We use obj to find the context of this widget.
getAction(obj)
function will return the Action variable of this widget, the Action variable contains all the custom api of this widget, like init, destroy and rest of the functions that used by widget. obj is any component inside the widget. We use obj to find the Action of this widget.
getRootDiv(obj)
function return the DOM element of the widget. It is the element that the widget html is inserted. Says, the element is myWidget, then the widget template html is set as
myWidget.innerHTML = html;
getStatus(obj, name)
function get the widget status. widget status name includes “favorite”, “template”. return true if status is set, false otherwise. obj is the component object that trigger this function.
setStatus(obj, name, value)
function set the widget status, and also change the menu bar. widget status name refer to getStatus(). value true means set the status. If setStatus(obj, “favorite”, true), then the widget will highlight the favorite flag and also will be added to favorite list.
sendMail(obj, title, description, thumb, widget, receivers, category, callback)
function send mail to others. receivers is an array of objects, each object contains a necessary id field. For example [{id:104}, {id:156}] is a valid receivers. If receivers set to null or not defined, function will use owner ID of the widget (the person who create and publish the widget) as receiver. obj is any component inside the widget. the widget parameter is an object that follow the widget definition. Category is the category of this mail. Sample of the function call. callback(newCreatedId) will be called after the new created mail id is returned from server. It is useful if you want to display the sent mail right after send mail.
sendMail(obj, "hello", "description 1", null, {template:"template6",context:{title:"hello", imageURL:"http://www.airnorth.com.au/sites/default/files/Car%20hire%20-%20Budget%20Hyundai%20i30%20-%20LR.jpg"}}, null);
for the widget parameter, template and context field is must if define the send mail’s template name and widget context.
getMailForNote(obj, sendOrReceive, dataCallback)
Function will show the mails in a new page that were sent by itself by calling sendMail(). sendOrReceive can be “sent” ore “received”. “sent” means all the mails sent from this widget. “received” means all the mails that were sent by others using the exact the same widget as this one.
if dataCallback is provided, the function will not show the mails on a new page. Instead, the function will just return the mails as an array parameter to the dataCallback function.
isOwner(obj)
function return true if the widget that contains the obj belong to current user that view this widget.
isWidgetEditing(obj)
function return the global status that whether the widget is under editing status. obj is not used at current version.
getWidgetContext(obj)
function return the current widget’s content context. It is different from the getContext which return the working context. Use widgetContext to modify the widget content.
updateWidgetContext(obj, c);
function update the current widget with the new widgetContext. Example:
var c = getWidgetContext(obj);
c.title="hello123";
updateWidgetContext(obj, c);
saveWidgetData(obj, data)
function save data to local storage and associate with this widget. Each widget has it own data storage. The data is java object, can be a number, a string, an object or array.
getWidgetData(obj)
function retrieve the data from local storage that is associated with this widget.
toggleUserCredit(obj, operation, currentCredit, newCredit)
function toggle the user credit system
operation is "purchase" or "reservation"
currentCredit is the currently assigned credit
newCredit is the credit you want to change to.
currentCredit and newCredit can have values "good" or "bad" or "none".
function widgetOn(obj, eventName, context, callback)
function register callback to listen to custom event
obj: any object (DOM object) inside the widget. This is used to bind the callback to the widget
eventName: can be any string. Be sure to call widgetTrigger using the same string in order to trigger
context: the context will send to the callback as the first parameter "event" and inside event.data. context is any object, for example {"foo":23}. when callback is called, event.data.foo will be 23
callback: callback(event, arg1, arg2...)
function scrollToWidgetClass(obj, className, offset)
function scroll the page to a specific DOM div that has the class (className) inside the widget. Scroll offset will apply related to the position of the div. -200 means scroll to the specific div minus 200 px.
function widgetTrigger(eventName, args)
function trigger event
args: an array of arguments. User should pass [obj1, obj2] for example, then the listener's callback should called as callback(event, obj1, obj2)
giveUserCredit(obj, operation, successOrFail, addOrRemove)
operation: "purchase" || "reservation"
successOrFail: Tell the system whether the operation is successful passed or the operation fail. Failed means the customer didn't fullfill the operation, so it is a bad credit. On the other hand, success means a good credit for the customer. If success, this parameter should set to "success" or true. If failed to fulfill, the parameter should set to "fail" or false.
addOrRemove: Tell the system add the credit or remove the previously assigned credit. If want to give the credit (says, "successfully purchased", or "fail to fullfill the reservation"), the parameter is "add" or true. If want to revert a previous assigned credit, use "remove" or false.
getUserCredit(obj, callback)
Example of callback(data) return data is as below.
{uid: 102, successful_purchase: 2, successful_reservation: 1, failed_purchase: 1, failed_reservation: 0}
The uid is the customer ID of this widget. The number of each field is the count of the field for this customer.
redrawPanel();
the panel will be redrawed. This will help on when the widget change its size, then widget should call redrawPanel() right after it change the size of the widget. If not called, the system will still redraw the panel periodically, however, the user experience will not be good because of the delay.
getDeviceId()
return the device unique ID. It is device-browser unique Id, which is different from each browser instance and will change everytime when the page refresh. It is in general used to verify a posted message belonging to self or not.
getUid()
return the user ID.
showWidgetPopup(obj, html)
html is the html that insert into the popup. obj is the object inside the widget.
closeWidgetPopup()
called to close the popup.
popupWidget(obj, parameters, callback, css)
function display a widget as a popup. In general, it is used from widget to popup another widget, e.g. message widget. parameters is the widget object.
Example: popupWidget(rootDiv, {template:"snapchat.White",context:{message_text:"訊息欄", _widget_send:"發送", _widget_append_photo:"+"}});
closeWidget(data)
called to close the widget. If caller of popupWidget provides the callback, then callback(data) will be called.
popupGetObj()
get the original object that trigger the showWidgetPopup.
To create a popup outside of the widget, call showWidgetPopup will display the html to the popup. Pass the obj to showWidgetPopup, where obj is the reference inside the widget that trigger the calling of showWidgetPopup. the html pass to the popup can callback to original widget by reference the original trigger object. Get the reference of original trigger object by popupGetObj(). Rest of the implementation is the same as normal widget.