Scripting with JavaScript

When a JavaScript callback function is invoked by the JS action it will be invoked with a single parameter as in the following prototype:

script_function_name(context)

The function argument context  is a JavaScript object whose variables provide the context in which the action is being invoked along with any action-specific argument and parameters. This context includes the application, screen, and control the action was associated with, the currently focused control, any arguments provided to the action as well as all of the event data that cause the action to fire.

The following variables are available inside the context’s object but may be nil if not applicable to the context.

Functions created by Storyboard will automatically be prepended with this comment. Example of using context data:

/**
* @param context 
**/
function CBGetContext( context ) {
    print("Triggered by event : " + context.event)    
    print("Event was targeting : " + context.activeContext)
}

The Storyboard Engine JavaScript plugin provides a slightly different execution environment when compared to normal JavaScript execution.

Normally a single JavaScript file serves as the starting point of script execution and all other scripts would be included using the JavaScript require() declaration. The Storyboard JavaScript plugin provides a slightly different loading behavior in that it will pre-load all of the JavaScript files contained in the scripts directory at engine initialization time. The load ordering can be controlled by using the require statement to explicitly order dependencies. Care should be taken with JavaScript and asset file naming standards with respect to portability as some OSes are case-sensitive whereas others are not. I

t should be noted that in most OSes the filesystem directory API does not apply any ordering and only utilities like ls and dir apply sorting logic primarily for display purposes. When the Storyboard engine loads JavaScript files, it loads them based on unsorted content in a directory, and hence to manage dependencies as mentioned above the use of JavaScript require() declarations is recommended good practice.

A side effect of this early module loading and execution is that any JavaScript file that is located outside of function blocks will have the opportunity to run before the application is fully initialized. This can be used to seed early execution environments or load preferences before the UI is in place and ready to render. Alternatively, this early initialization is possible by binding a callback to the gre.init event.

The Storyboard JavaScript Debugger enables the developer to monitor the flow of execution of JavaScript used by the Storyboard application. Using the debugger it is possible to step line by line through a JavaScript file while examining the variable values that are being used by the JavaScript functions.

Communication between the storyboard designer debugging platform and the Duktape debugging engine is done through a Duktape-provided proxy server on port 9093. The messages are sent in JSON format.

Simulate with JS Debugger

1. Create a Storyboard application launch configuration. This topic is discussed in more detail in the chapter

2. Set extra engine options value as “-ojs, dbg” in the Storyboard Simulator configuration. Click on "Apply" then "Run".

Functions

To have access to any of the debugging functions below the user must change the storyboard perspective to “Debug” perspective, by clicking the button in the main toolbar

View current variables

Once the breakpoint has been hit and script execution stops on the highlighted line, the user can see the variables available and their value when opening the “Variables” tab to the right of the window.  

Evaluate expressions

Once the breakpoint has been hit and script execution stops on the highlighted line, the user can evaluate expressions and display the result based on the current status and context when opening the “Expressions” tab to the right of the window.

Performing stepping-through execution

Step Into

This is triggered with the button marked as #1 in the figure above. The Step Into action continues execution in the 1st line of the next function to execute.

Step Over

This is triggered with the button marked as #2 in the figure above. The Step Over action executes the current line execution and pauses execution again on the next line.

Step Return

This is triggered with the button marked as #3 in the figure above, The Step Out action resumes execution and pause when execution exits the current function or an error is thrown past the current function (in which case execution pauses in the error catcher, if any).  

Add breakpoint

To add the breakpoint to the script,

1.      Open the JavaScript file.

2.      Navigate the mouse to the line where the breakpoint is supposed to be and double-click on the side annotation bar

3.      The breakpoint marker is displayed on the line and in the breakpoint tab, the filename and line number of the newly added breakpoint.

Remove breakpoint

To remove the breakpoint from the script, there are 2 ways.

Option 1

Open the breakpoints tab and select the breakpoint that matches the filename and line number to remove. 2.      In the JavaScript file, the breakpoint marker, matching the filename and line number of the breakpoint removed from the list, is removed as well.

Option 2

In the JavaScript file, navigate the mouse to the breakpoint marker at the line where the breakpoint is to be removed and then double-click the marker. The breakpoint marker is removed after the double click and in the breakpoints tab, the corresponding breakpoint is removed.