Difference between revisions of "Client JavaScript Extension API"

From HSYCO
Jump to navigation Jump to search
 
(48 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category:INCOMPLETE]]
 
[[Category:INCOMPLETE]]
 +
[[Category:Advanced Programming]]
 +
<div style="color:#CC0000">'''{{Note|<center>WARNING! The client-side JavaScript extensions API is experimental and subject to changes.</center>}}'''
 +
</div>
  
−
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 to be 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.
  
 
== Events ==
 
== Events ==
 +
These are functions executed on specific events.
 +
 
=== StartupEvent ===
 
=== StartupEvent ===
−
E.g.
+
<syntaxhighlight lang="javascript">
−
function StartupEvent() {
+
function StartupEvent()
−
  ...
+
</syntaxhighlight>
−
}
+
 
 +
Executed when the interface is first loaded.
 +
It's a good place to set up the interface and set variables, for example.
  
 
=== userCommand ===
 
=== userCommand ===
−
E.g.
+
<syntaxhighlight lang="javascript">
−
function userCommand(rem, id) {
+
function userCommand(name, param)
−
...
+
</syntaxhighlight>
−
}
+
 
 +
Called by user clicks on user buttons: [[User]], [[UserMini]], [[UserMicro]], [[UserRGB]] or [[UserImage]] objects.
 +
 
 +
{{userCommand return values}}
 +
 
 +
'''Parameters:'''
 +
 
 +
* name: string - the name field of the user object
 +
* param: string - the param of the user object
 +
 
 +
 
 +
'''Returns:'''
 +
 
 +
* null: proceed to send the request to server as it is
 +
* "": assume the event was resolved. Don't send the request to the server
 +
* "page:page name": navigate to the specified page
 +
* "page:back": navigate to the previous page
 +
* "page:forward": navigate to the next page
 +
* "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
 +
* "copy:<text>": tells the browser or [[HSYCO App]] to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.
 +
* "share:<text>": tells the [[HSYCO App]] to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.
 +
* an object, to specify new name and param values to be sent to the server
 +
<syntaxhighlight lang="javascript">
 +
{name:"new name", param:"new param"}
 +
</syntaxhighlight>
  
 
=== userSubmit ===
 
=== userSubmit ===
−
E.g.
+
<syntaxhighlight lang="javascript">
 +
function userSubmit(name, param)
 +
</syntaxhighlight>
 +
Called on every submit request (from [[Submit]] objects).
 +
Parameters and return values are the same as the userCommand function.
  
 
=== uiEvent ===
 
=== uiEvent ===
−
E.g.
+
<syntaxhighlight lang="javascript">
 +
function uiEvent(id, attr, value)
 +
</syntaxhighlight>
 +
Executed on every UISet received from the server, intercepts a UISet and allows to change it, prevent its execution or execute any other custom code (e.g. set variables).
 +
 
 +
'''Parameters:'''
 +
 
 +
* id: string - id of the ui object
 +
* attr: string - attribute name
 +
* value: string - new value being set
 +
 
 +
 
 +
'''Returns:'''
 +
 
 +
* null: discard the UISet
 +
* <string>: set a new value for the UISet. To keep the UISet as it is, return the initial value
 +
 
 +
=== pageOpenEvent ===
 +
<syntaxhighlight lang="javascript">
 +
function pageOpenEvent(name)
 +
</syntaxhighlight>
 +
 
 +
Called when a page is opened.
 +
 
 +
'''Parameters:'''
 +
 
 +
* name: string - the page's id
 +
 
 +
'''Returns:'''
 +
 
 +
* false: don't open the page. A ''pageOpenEvent'' is called on the previous page, as if it was reopened.
 +
* null: proceed to open the page
 +
 
 +
<syntaxhighlight lang="javascript">
 +
// page open event
 +
function pageOpenEvent(name) {
 +
console.log("opening "+name);
 +
if (name =="wconfig") {
 +
console.log("nope 1");
 +
return false;
 +
}
 +
}
 +
</syntaxhighlight>
 +
 
 +
=== pageCloseEvent ===
 +
<syntaxhighlight lang="javascript">
 +
function pageCloseEvent(name)
 +
</syntaxhighlight>
 +
 
 +
Called when a page is closed.
 +
 
 +
'''Parameters:'''
 +
 
 +
* name: string - the page's id
 +
 
 +
'''Returns:'''
 +
 
 +
* false: don't close the page
 +
* null: proceed to close the page
 +
 
 +
<syntaxhighlight lang="javascript">
 +
// page close event
 +
function pageCloseEvent(name) {
 +
console.log("closing "+name);
 +
if (name =="sconfig") {
 +
console.log("nope 2");
 +
return false;
 +
}
 +
}
 +
</syntaxhighlight>
 +
 
 +
=== pageBackEvent ===
 +
<syntaxhighlight lang="javascript">
 +
function pageBackEvent(name)
 +
</syntaxhighlight>
 +
 
 +
Called when a page back is requested.
 +
 
 +
'''Parameters:'''
 +
 
 +
* name: string - the page's id
 +
 
 +
'''Returns:'''
 +
 
 +
* false: don't close the page
 +
* null: proceed to close the page
 +
 
 +
<syntaxhighlight lang="javascript">
 +
// page back event
 +
function pageBackEvent(name) {
 +
console.log("backing from "+name);
 +
if (name =="sconfig") {
 +
console.log("nope 3");
 +
return false;
 +
}
 +
}
 +
</syntaxhighlight>
  
−
== Methods ==
+
== Functions ==
 
=== varSet ===
 
=== varSet ===
−
E.g.
+
<syntaxhighlight lang="javascript">
 +
varSet(name,value)
 +
</syntaxhighlight>
 +
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 the page or closing and reopening the browser.
  
 
=== varGet ===
 
=== varGet ===
−
E.g.
+
<syntaxhighlight lang="javascript">
 +
varGet(name)
 +
</syntaxhighlight>
 +
Gets the value of a variable previously set with varSet.
  
 
=== uiSet ===
 
=== uiSet ===
−
E.g.
+
<syntaxhighlight lang="javascript">
 +
uiSet(id,attr,value)
 +
</syntaxhighlight>
 +
Sets a UI Attribute. See [[Project]], [[Page]] or [[UI Objects]] list of attributes.
 +
 
 +
=== webLog ===
 +
<syntaxhighlight lang="javascript">
 +
webLog(string)
 +
</syntaxhighlight>
 +
Adds a line to the daily log file, viewable from the Manager's [[Log Viewer]].
 +
 
 +
== Examples ==
 +
=== Using varget and varset ===
 +
In this example we declare a persistent variable (stored in the browser's local storage) the first time any user button is pressed, we increment it each time up to 10 and then we reset it to 0. When the variable equals 3, the page "page1" is shown. When the variable equals 7, the request isn't forwarded to the server.
 +
<syntaxhighlight lang="javascript">
 +
function userCommand(name, param) {
 +
var a = varGet("!counter"); // get the variable value
 +
 
 +
if (!a) // first time and when a is 0
 +
a = 1;
 +
else if (a < 10)
 +
a++;
 +
else // reset
 +
a = 0;
 +
 
 +
varSet("!counter",a); // set the variable value
 +
 
 +
webLog("usercommand:"+name+","+param+". Counter:"+a)
 +
if (a == 3)
 +
return "page:page1";
 +
else if (a == 7)
 +
return "";
 +
else
 +
return null;
 +
}
 +
</syntaxhighlight>
  
 
== User Object ==
 
== User Object ==
 
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.
  
 +
<syntaxhighlight lang="javascript">
 +
var user = new User();
  
−
var user = new User();
+
function StartupEvent() {  
−
+
user.setOnLoadedEvent(onUserLoaded);
−
function StartupEvent() {  
+
user.setOnErrorEvent(onUserError);
−
user.setOnLoadedEvent(onUserLoaded);
+
// send reques
−
user.setOnErrorEvent(onUserError);
+
user.send("myname","myparam");
−
// send request
+
 
−
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 88: Line 262:
  
 
===Error codes===
 
===Error codes===
−
.ERROR_GENERAL : general error
+
*'''.ERROR_GENERAL''' : general error
−
.ERROR_CONNECTION : no connection
+
*'''.ERROR_CONNECTION''' : no connection
−
.ERROR_MAXWAITTIME : max waiting time exceeded
+
*'''.ERROR_MAXWAITTIME''' : max waiting time exceeded
−
.ERROR_LOGOUT  : client is logged out
+
*'''.ERROR_LOGOUT''' : client is logged out
−
.ERROR_LOCK : client is locked out
+
*'''.ERROR_LOCK''' : client is locked out
−
.ERROR_NOACCESS : request returned noaccess
+
*'''.ERROR_NOACCESS''' : request returned noaccess
  
 
===Examples===
 
===Examples===
−
====Example index.js: try one time, then fire onLoaded or onError====
+
====Try one time, then fire onLoaded or onError====
 +
<syntaxhighlight lang="javascript">
 +
var user = new User();
 +
 
 +
function StartupEvent() {
 +
user.setOnLoadedEvent(onUserLoaded);
 +
user.setOnError(onUserError);
 +
  // send request
 +
  user.send("myname","myparam");
 +
}
  
−
var user = new User();
+
function onUserLoaded() {
−
+
  webLog("loaded "+user.getResponseText());
−
function StartupEvent() {
+
  // do something with the response
−
user.setOnLoadedEvent(onUserLoaded);
+
  user.free(); // won't be using it again
−
user.setOnError(onUserError);
+
}
−
  // send request
+
function onUserError(errCode) {
−
  user.send("myname","myparam");
+
  webLog("error");
−
}
+
  user.free(); // won't be using it again
−
+
}
−
function onUserLoaded() {
+
</syntaxhighlight>
−
  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====
+
====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====
+
====Retry 3 times, then fire onError====
  
−
var user = new User();
+
<syntaxhighlight lang="javascript">
−
+
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 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() {
 
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, already tried 3 times");
−
user.free(); // won't be using it again
+
  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 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;
 
 
}
 
}
 +
</syntaxhighlight>

Latest revision as of 12:34, 31 August 2020

WARNING! The client-side JavaScript extensions API is experimental and subject to changes.

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

function StartupEvent()

Executed when the interface is first loaded. It's a good place to set up the interface and set variables, for example.

userCommand

function userCommand(name, param)

Called by user clicks on user buttons: User, UserMini, UserMicro, UserRGB or UserImage objects.

If you want to navigate to a specific page when the button is pressed (it would be like pressing a Link object), return a string starting with "page:" followed by the page name; in this case, userCommand() will be called again when that popup or page is closed, with "/close" appended to param.

You can also use "page:back" or "page:forward" to move back and forth along the pages' navigation history. Use "page:close" to close a popup.

When the interface is loaded inside the HSYCO App (iOS or Android), you can send a specific command to the app by returning a string that starts with “app:“ followed by the command; the commands currently supported are “speech“, which enables the speech recognition, and “codescan“ which enables qr/bar code scanning.

Use "copy:<text>" to copy a text in the clipboard. In the HSYCO App you can also use "share:<text>" to open a popup with various options. This will behave like "copy" on browser.

Parameters:

  • name: string - the name field of the user object
  • param: string - the param of the user object


Returns:

  • null: proceed to send the request to server as it is
  • "": assume the event was resolved. Don't send the request to the server
  • "page:page name": navigate to the specified page
  • "page:back": navigate to the previous page
  • "page:forward": navigate to the next page
  • "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
  • "copy:<text>": tells the browser or HSYCO App to copy the text in the clipboard. On browser it will display a confirm popup with the text to be copied.
  • "share:<text>": tells the HSYCO App to show a share popup with various options (copy, send through email, save to files etc.). On browser it will behave like copy.
  • an object, to specify new name and param values to be sent to the server
{name:"new name", param:"new param"}

userSubmit

function userSubmit(name, param)

Called on every submit request (from Submit objects). Parameters and return values are the same as the userCommand function.

uiEvent

function uiEvent(id, attr, value)

Executed on every UISet received from the server, intercepts a UISet and allows to change it, prevent its execution or execute any other custom code (e.g. set variables).

Parameters:

  • id: string - id of the ui object
  • attr: string - attribute name
  • value: string - new value being set


Returns:

  • null: discard the UISet
  • <string>: set a new value for the UISet. To keep the UISet as it is, return the initial value

pageOpenEvent

function pageOpenEvent(name)

Called when a page is opened.

Parameters:

  • name: string - the page's id

Returns:

  • false: don't open the page. A pageOpenEvent is called on the previous page, as if it was reopened.
  • null: proceed to open the page
// page open event
function pageOpenEvent(name) {
	console.log("opening "+name);
	if (name =="wconfig") {
		console.log("nope 1");
		return false;
	}
}

pageCloseEvent

function pageCloseEvent(name)

Called when a page is closed.

Parameters:

  • name: string - the page's id

Returns:

  • false: don't close the page
  • null: proceed to close the page
// page close event
function pageCloseEvent(name) {
	console.log("closing "+name);
	if (name =="sconfig") {
		console.log("nope 2");
		return false;
	}
}

pageBackEvent

function pageBackEvent(name)

Called when a page back is requested.

Parameters:

  • name: string - the page's id

Returns:

  • false: don't close the page
  • null: proceed to close the page
// page back event
function pageBackEvent(name) {
	console.log("backing from "+name);
	if (name =="sconfig") {
		console.log("nope 3");
		return false;
	}
}

Functions

varSet

varSet(name,value)

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 the page or closing and reopening the browser.

varGet

varGet(name)

Gets the value of a variable previously set with varSet.

uiSet

uiSet(id,attr,value)

Sets a UI Attribute. See Project, Page or UI Objects list of attributes.

webLog

webLog(string)

Adds a line to the daily log file, viewable from the Manager's Log Viewer.

Examples

Using varget and varset

In this example we declare a persistent variable (stored in the browser's local storage) the first time any user button is pressed, we increment it each time up to 10 and then we reset it to 0. When the variable equals 3, the page "page1" is shown. When the variable equals 7, the request isn't forwarded to the server. 

function userCommand(name, param) {
	var a = varGet("!counter"); // get the variable value

	if (!a) // first time and when a is 0
		a = 1;
	else if (a < 10)
		a++;
	else // reset
		a = 0;

	varSet("!counter",a); // set the variable value

	webLog("usercommand:"+name+","+param+". Counter:"+a)
	if (a == 3)
		return "page:page1";
	else if (a == 7)
		return "";
	else
		return null;
}

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

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
}

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
}

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
}
Retrieved from "https://wiki.hsyco.com/3.7/index.php?title=Client_JavaScript_Extension_API&oldid=8903"