Difference between revisions of "Client JavaScript Extension API"
Line 1: | Line 1: | ||
[[Category:INCOMPLETE]] | [[Category:INCOMPLETE]] | ||
+ | |||
+ | {{Note:WARNING! This extension is still experimental!}} | ||
A project can have specific javascript code that runs on the client-side and manages various events. This code has to be written in an index.js file located inside the project's directory. | A project can have specific javascript code that runs on the client-side and manages various events. This code has to be written in an index.js file located inside the project's directory. |
Revision as of 12:00, 7 February 2014
Template:Note:WARNING! This extension is still experimental!
A project can have specific javascript code that runs on the client-side and manages various events. This code has to be written in an index.js file located inside the project's directory.
Events
These are functions executed on specific events.
StartupEvent
Executed when the interface is first loaded. It's a good place to set up the interface and set variables, for example.
E.g.
function StartupEvent() {
...
}
userCommand
Executed on every user command request (from User, UserList objects or Gestures). Syntax
function userCommand(name, param) {
...
}
userCommand can return:
- null: proceed to send the request to server as it is
- "ack": assume the event was resolved. Don't send the request to the server. This answer can also specify other actions:
- 'ack{"page":"page name"}': navigate to the specified page
- 'ack{"page":"back"}': navigate to the previous page
- 'ack{"page":"forward"}': navigate to the next page
- 'ack{"page":"close"}': if the user button that generated the call has an open popup linked to it, close it
- "error": error. Don't send the request to the server
- an object, to specify new name and param values to be sent to the server
{name:"new name", param:"new param"}
E.g.
userSubmit
Executed on every submit request (from Submit objects). Syntax
function userSubmit(name, param) {
...
}
E.g.
uiEvent
Executed on every UISet received from the server. Syntax
function uiEvent(id, attr, value) {
...
}
E.g.
Methods
varSet
Sets the value of a variable. If the name begins with !, the variable will be stored in the browser's cache, so that it'll available even after reloading or closing and reopening the browser. Syntax
varSet(name,value);
E.g.
varGet
Gets the value of a variable previously set with varSet. Syntax
varGet(name);
E.g.
uiSet
Sets a UI Attribute. See Project, Page or UI Objects list of attributes. Syntax
uiSet(id,attr,value);
E.g.
User Object
One or more User objects can be declared to send requests from the client to the server.
var user = new User();
function StartupEvent() {
user.setOnLoadedEvent(onUserLoaded);
user.setOnErrorEvent(onUserError);
// send reques
user.send("myname","myparam");
varSet("myvar1","myvalue");
varSet("myvar2",5.3);
varSet("myvar3",[1,2,3]);
varSet("myvar4",{"a":1,"b":2});
}
Methods
.send(name, param)
sends a virtualremote (name and param will be url encoded)
.setMaxWaitingTime(msec)
set max waiting time in msec. If a request exceeds this time, it will be aborted (and fire an onError event, if set).
.setMaxRetries(n)
set max number of retry attempts. If a a request fails, it will keep on retrying until it succeeds or the max number of retries is reached. Before retrying it will fire an onRetry event, if set. If n is 0, and retryOnErrorDelay is not 0, it will keep on retrying forever (it will never fire an onError event, if set).
.setRetryOnErrorDelay(msec)
set msec of delay before retrying after a request has failed. If msec is 0 it won't retry (and will fire an onError event, if set).
.setOnLoadedEvent(f)
f is a function that is called when the request is successful. To get the response text or xml, use .getResponseText() and .getResponseXML()
.setOnErrorEvent(f)
f is a function called when the request fails. f is called with an error code parameter: function(errCode) error codes are enumerated as .ERROR_GENERAL, .ERROR_CONNECTION ...
.setOnRetryEvent(f)
f is a function that is called when the last request failed, before retrying. To get the response text or xml, use .getResponseText() and .getResponseXML()
.getResponseText()
get the last response text
.getResponseXML()
get the last response XML
.free()
free the memory and reset the behaviour. It will be reinitialized if any method is called.
Error codes
.ERROR_GENERAL : general error .ERROR_CONNECTION : no connection .ERROR_MAXWAITTIME : max waiting time exceeded .ERROR_LOGOUT : client is logged out .ERROR_LOCK : client is locked out .ERROR_NOACCESS : request returned noaccess
Examples
Example index.js: try one time, then fire onLoaded or onError
var user = new User();
function StartupEvent() {
user.setOnLoadedEvent(onUserLoaded);
user.setOnError(onUserError);
// send request
user.send("myname","myparam");
}
function onUserLoaded() {
webLog("loaded "+user.getResponseText());
// do something with the response
user.free(); // won't be using it again
}
function onUserError(errCode) {
webLog("error");
user.free(); // won't be using it again
}
Example index.js: retry forever, until it succeeds
var user = new User();
function StartupEvent() {
user.setOnLoadedEvent(onUserLoaded);
user.setRetryOnErrorDelay(1000); // wait one second before retrying on error
// send request
user.send("myname","myparam");
}
function onUserLoaded() {
webLog("loaded "+user.getResponseText());
// do something with the response
user.free(); // won't be using it again
}
Example index.js: retry 3 times, then fire onError
var user = new User();
function StartupEvent() {
// init user object
user.setRetryOnErrorDelay(100); // retry almost immediately on error
user.setMaxRetries(3); // retry 3 times, then fire error
user.setOnLoadedEvent(onUserLoaded);
user.setOnError(onUserError);
// send request
user.send("myname","myparam");
}
function onUserLoaded() {
webLog("loaded "+user.getResponseText());
// do something with the response
user.free(); // won't be using it again
}
function onUserError(errCode) {
webLog("error, already tried 3 times");
if (errCode == user.ERROR_MAXWAITTIME)
webLog("the last request failed because it exceeded the waiting time");
user.free(); // won't be using it again
}
function onUserLoaded() {
webLog("loaded "+user.getResponseText());
// do something with the response
user.free(); // won't be using it again
}
function onUserError(errCode) {
webLog("error");
user.free(); // won't be using it again
}
function userCommand(rem, id) {
var a = varGet("counterz!");
if (!a)
a = 1;
else
a++;
varSet("counterz!",a);
console.log(rem+" "+id+" "+a)
if (a == 3)
return "";
else if (a == 4)
return "page:ciao";
else
return null;
}