Scripting with JavaScript

The Storyboard JavaScript API (JS API) gives developers access to the Engine through a JavaScript scripting interface.  This API is a library of functions that allow interaction with the Engine by manipulating data and working with events and user interface components.  Through the Storyboard JS API developers can:

  • Get and set data values from the model

  • Inject application events

  • Manipulate model objects such as controls/layers

The Storyboard JS plugin is built on top of the 2.6 release of the Duktape JavaScript library available from

The Storyboard module (sb) is included which provides function extensions to manipulate and work with the currently active Storyboard model. This module also incorporates the Storyboard IO communication API that can be used to send events to external programs.

JavaScript Action Callback Function

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


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.


The application context of the current action


The screen context of the current action (the current screen)


The layer context of the current action (the current layer)


The group context of the current action (the current group)


The control context of the current action (the current control)


If the context_control is a table then this is the row index of the current cell


If the context_control is a table then this is the column index of the current cell


The fully qualified name of the model object that invoked the action. If that object is the application, this will be the empty string


The name of the event that triggered the action


A pointer to a JS object containing any event data. The event data is different for each event and is defined in the event definition

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)

JavaScript Execution Environment

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.

JavaScript Debugger

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.


The JavaScript debugger is configured such that it can only be used with the simulator runtimes on the host platforms that support Storyboard Designer. For assistance in configuring the debugger for embedded targets, contact Crank Software support (

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".



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.

Was this article helpful?
0 out of 0 found this helpful