Difference between revisions of "Client JavaScript Extension API"

From HSYCO
Jump to navigation Jump to search
Line 30: Line 30:
 
Executed on every submit request (from [[Submit]] objects).
 
Executed on every submit request (from [[Submit]] objects).
 
Syntax
 
Syntax
function userSubmit(rem, id) {
+
<syntaxhighlight lang="javascript">
...
+
function userSubmit(rem, id) {
}
+
  ...
 +
}
 +
</syntaxhighlight>
 
E.g.
 
E.g.
  
Line 38: Line 40:
 
Executed on every UISet received from the server.  
 
Executed on every UISet received from the server.  
 
Syntax
 
Syntax
function uiEvent(id, attr, value) {
+
<syntaxhighlight lang="javascript">
...
+
function uiEvent(id, attr, value) {
}
+
  ...
 +
}
 +
</syntaxhighlight>
 
E.g.
 
E.g.
  
Line 47: Line 51:
 
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.
 
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
 
Syntax
varSet(name,value);
+
<syntaxhighlight lang="javascript">
 +
varSet(name,value);
 +
</syntaxhighlight>
 
E.g.
 
E.g.
  
Line 53: Line 59:
 
Gets the value of a variable previously set with varSet.
 
Gets the value of a variable previously set with varSet.
 
Syntax
 
Syntax
varGet(name);
+
<syntaxhighlight lang="javascript">
 +
varGet(name);
 +
</syntaxhighlight>
 
E.g.
 
E.g.
  
Line 59: Line 67:
 
Sets a UI Attribute. See [[Project]], [[Page]] or [[UI Objects]] list of attributes.
 
Sets a UI Attribute. See [[Project]], [[Page]] or [[UI Objects]] list of attributes.
 
Syntax
 
Syntax
uiSet(id,attr,value);
+
<syntaxhighlight lang="javascript">
 +
uiSet(id,attr,value);
 +
</syntaxhighlight>
 
E.g.
 
E.g.
  
Line 66: Line 76:
 
One or more User objects can be declared to send requests from the client to the server.
 
One or more User objects can be declared to send requests from the client to the server.
  
var user = new User();  
+
<syntaxhighlight lang="javascript">
+
var user = new User();  
function StartupEvent() {  
+
 
user.setOnLoadedEvent(onUserLoaded);
+
function StartupEvent() {  
user.setOnErrorEvent(onUserError);
+
user.setOnLoadedEvent(onUserLoaded);
// send request
+
user.setOnErrorEvent(onUserError);
user.send("myname","myparam");
+
// send reques
+
user.send("myname","myparam");
varSet("myvar1","myvalue");
+
 
varSet("myvar2",5.3);
+
varSet("myvar1","myvalue");
varSet("myvar3",[1,2,3]);
+
varSet("myvar2",5.3);
varSet("myvar4",{"a":1,"b":2});
+
varSet("myvar3",[1,2,3]);
}
+
varSet("myvar4",{"a":1,"b":2});
 +
}
 +
</syntaxhighlight>
  
 
===Methods===
 
===Methods===
Line 128: Line 140:
 
====Example index.js: try one time, then fire onLoaded or onError====
 
====Example index.js: try one time, then fire onLoaded or onError====
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
var user = new User();
+
var user = new User();
+
 
function StartupEvent() {
+
function StartupEvent() {
user.setOnLoadedEvent(onUserLoaded);
+
user.setOnLoadedEvent(onUserLoaded);
user.setOnError(onUserError);
+
user.setOnError(onUserError);
  // send request
+
  // send request
  user.send("myname","myparam");
+
  user.send("myname","myparam");
}
+
}
+
 
function onUserLoaded() {
+
function onUserLoaded() {
  webLog("loaded "+user.getResponseText());
+
  webLog("loaded "+user.getResponseText());
  // do something with the response
+
  // do something with the response
  user.free(); // won't be using it again
+
  user.free(); // won't be using it again
}
+
}
function onUserError(errCode) {
+
function onUserError(errCode) {
  webLog("error");
+
  webLog("error");
  user.free(); // won't be using it again
+
  user.free(); // won't be using it again
}
+
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
====Example index.js: retry forever, until it succeeds====
 
====Example index.js: retry forever, until it succeeds====
 +
<syntaxhighlight lang="javascript">
 +
var user = new User();
  
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 StartupEvent() {
+
function onUserLoaded() {
  user.setOnLoadedEvent(onUserLoaded);
+
  webLog("loaded "+user.getResponseText());
  user.setRetryOnErrorDelay(1000); // wait one second before retrying on error
+
  // do something with the response
  // send request
+
  user.free(); // won't be using it again
  user.send("myname","myparam");
+
}
}
+
</syntaxhighlight>
 
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====
 
====Example index.js: retry 3 times, then fire onError====
  
var user = new User();  
+
<syntaxhighlight lang="javascript">
+
var user = new User();  
function StartupEvent() {
+
 
  // init user object
+
function StartupEvent() {
  user.setRetryOnErrorDelay(100); // retry almost immediately on error
+
  // init user object
  user.setMaxRetries(3); // retry 3 times, then fire error
+
  user.setRetryOnErrorDelay(100); // retry almost immediately on error
  user.setOnLoadedEvent(onUserLoaded);
+
  user.setMaxRetries(3); // retry 3 times, then fire error
  user.setOnError(onUserError);
+
  user.setOnLoadedEvent(onUserLoaded);
  // send request
+
  user.setOnError(onUserError);
  user.send("myname","myparam");
+
  // send request
}
+
  user.send("myname","myparam");
+
}
function onUserLoaded() {
+
 
  webLog("loaded "+user.getResponseText());
+
function onUserLoaded() {
  // do something with the response
+
  webLog("loaded "+user.getResponseText());
  user.free(); // won't be using it again
+
  // do something with the response
}
+
  user.free(); // won't be using it again
function onUserError(errCode) {
+
}
  webLog("error, already tried 3 times");
+
function onUserError(errCode) {
  if (errCode == user.ERROR_MAXWAITTIME)
+
  webLog("error, already tried 3 times");
  webLog("the last request failed because it exceeded the waiting time");
+
  if (errCode == user.ERROR_MAXWAITTIME)
  user.free(); // won't be using it again
+
  webLog("the last request failed because it exceeded the waiting time");
}
+
  user.free(); // won't be using it again
 +
}
 +
</syntaxhighlight>
  
 
----
 
----
  
 +
<syntaxhighlight lang="javascript">
 
function onUserLoaded() {
 
function onUserLoaded() {
 
webLog("loaded "+user.getResponseText());
 
webLog("loaded "+user.getResponseText());
Line 218: Line 234:
 
return null;
 
return null;
 
}
 
}
 +
</syntaxhighlight>

Revision as of 12:46, 29 January 2014


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(rem, id) {
   ...
}

E.g.

userSubmit

Executed on every submit request (from Submit objects). Syntax

function userSubmit(rem, id) {
  ...
}

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