manual:appendix:preprocessing:javascript

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
manual:appendix:preprocessing:javascript [2020/06/19 10:31]
marinagen removed
— (current)
Line 1: Line 1:
-==== 3 Javascript preprocessing ==== 
  
-=== Overview === 
- 
-This section provides details of preprocessing by Javascript. 
- 
-=== Javascript preprocessing === 
- 
-Javascript preprocessing is done by invoking JavaScript function with a single parameter '​value'​ and user provided function body. The preprocessing step result is the value returned from this function, for example, to perform Fahrenheit to Celsius conversion user must enter 
- 
-  return (value - 32)  * 5 / 9 
- 
-in JavaScript preprocessing parameters, which will be wrapped into a JavaScript function by server: 
- 
-<code java> 
-function (value) 
-{ 
-   ​return (value - 32) * 5 / 9 
-} 
-</​code>​ 
- 
-The input parameter '​value'​ is always passed as a string. The return value is automatically coerced to string via ToString() method (if it fails then the error is returned as string value), with a few exceptions: 
- 
-  * returning undefined value will result in an error 
-  * returning null value will cause the input value to be discarded, much like '​Discard value' preprocessing on '​Custom on fail' action. 
- 
-Errors can be returned by throwing values/​objects (normally either strings or Error objects). 
- 
-For example: 
- 
-<code java> 
-if (value == 0) 
-    throw "Zero input value" 
-return 1/value 
-</​code>​ 
- 
-Each script has a 10 second execution timeout (depending on the script it might take longer for the timeout to trigger); exceeding it will return error. Also a 10 megabyte heap limit is enforced. 
- 
-The JavaScript preprocessing step bytecode is cached and reused when the step is applied next time. Any changes to the item's preprocessing steps will cause the cached script to be reset and recompiled later. 
- 
-Consecutive runtime failures (3 in a row) will cause the engine to be reinitialized to mitigate the possibility of one script breaking the execution environment for the next scripts (this action is logged with DebugLevel 4 and higher). 
- 
-JavaScript preprocessing is implemented with Duktape (https://​duktape.org/​) JavaScript engine. 
- 
-== Using macros in scripts == 
- 
-It is possible to use user macros in JavaScript code. If a script contains user macros, these macros are resolved by server/​proxy before executing specific preprocessing steps. Note, that when testing preprocessing steps in the frontend, macro values will not be pulled and need to be entered manually. ​ 
- 
-<​note>​ Macro context is ignored when a macro is replaced with its value. Macro value is inserted in the code as is, it is not possible to add additional escaping before placing the value in the JavaScript code. Please be advised, that this can cause JavaScript errors in some cases. </​note>​ 
- 
-In an example below, if received value exceeds a {$THRESHOLD} macro value, the threshold value (if present) will be returned instead: 
- 
-<code java> 
-var threshold = '​{$THRESHOLD}';​ 
-return (!isNaN(threshold) && value > threshold) ? threshold : value; 
-</​code>​ 
- 
- 
-=== Global Javascript functions === 
- 
-Additional global Javascript functions have been implemented with Duktape: 
- 
-  * btoa(string) - encodes string to base64 string 
-  * atob(base64_string) - decodes base64 string 
- 
-<code java> 
-try { 
-    b64 = btoa("​utf8 string"​);​ 
-    utf8 = atob(b64); 
- 
-catch (error) { 
-    return {'​error.name'​ : error.name, '​error.message'​ : error.message} 
-} 
-</​code>​ 
- 
-See also: [[:​manual/​appendix/​preprocessing/​javascript/​javascript_objects|Additional Javascript objects]]