Toggle menu

JavaScript Editors

The forms designer includes two different editors you can use to write JavaScript. Both are available in all of your form's functions and handlers.

When and Where Scripts are Executed

As described in Form Functions, Handlers and Signatures, different functions are executed at different points in your form's lifecycle. The JavaScript editors are aware of this and displays different icons for code executed server-side and client-side.

Server-side Scripts
  - The script will only be executed server-side (as the form or page loads, and on submit)

Client-side Scripts
  - The script will only be executed on the user's browser (handler functions for example)

Client and Server Script
  - The script will be executed both server-side and on the user's browser (most commonly found with validation functions)

Visual Script Editor

Built on Google's Blockly Editor, the Visual Script Editor provides a simple interface to generate working JavaScript.

10060 Visual Script Editor
 

The left hand menu contains over one hundred Blockly Blocks, covering much of the Form Helper Library as well as many standard JavaScript statements and expressions. Blocks are dragged onto the work area and will fit together to form valid JavaScript.

The blocks that appear in the left hand menu are context aware. That is, if you are writing a handler which will only be executed client-side, all of the blocks that only work server-side will be hidden.

Once a block has been added, right-clicking on it brings up a menu of actions, including copy, duplicate, disable, delete and collapse the block.

You can see the JavaScript your blocks have generated on the "Generated Code" tab.

Copying and Pasting Blocks

You can copy blocks, and stacks of blocks, from one property editor to another, and between forms. Copying a "container" type block, like the if-else logic block, create map block, or the repeat-while loop block, automatically copies all of the blocks within it too.

When blocks are stacked one below the other you can either copy an individual block or select "copy stack" to copy all of the blocks in the stack beneath the block you clicked on.

Right-clicking on a function and selecting "copy stack" will copy the entire function, which can then be pasted into another field, property or form.

Calling End Points

The API Server block is designed to make calling end points easier.

10060 API Server Call Block
 

Clicking the "name" property launches an explorer window that lets you select the end point you'd like to call. All of the end points your user has access to are available, and it's possible to select either the latest published version, or a specific version number, just like when manually writing the call.

The parameters drop-down can automatically generate blocks of the correct type, based upon the schema and saved tests present in the selected end point.

For example, selecting "all possible":

All Possible Parameters
 

Could load:

Example Parameter Map
 

JavaScript Editor

When you open the script editor it will be populated with a basic function signature relevant to that field.

10060 Script Editor
 

The code editor includes tools that can undo and redo your previous actions, copy paste and format your script, and check that it is valid.

Intelligent Code Completion

Common to most IDEs, intelligent code completion is a feature that provides hints and suggestions intelligently as you type.

For example, when using the helper library, a list of the available functions appears and updates as you type additional characters:

Intelligent Code Completion - Helper Library
 

Similar suggestions have been implemented for jQuery, various DOM functions and, when working server-side, published JavaScript libraries like apiclient:

Intelligent Code Completion - apiclient
 

Use the up and down keyboard arrows followed by the tab or enter key to select a suggestion.

Keyboard Shortcuts

The following keyboard shortcuts are available in the script editor.

KeystrokeDescription
Ctrl+spaceShow suggestions
Alt+iShow type
Alt+oshow documentation
Alt+.Jump to definition
Alt+,Jump back to instance
Ctrl+qRename/refactor variable
Ctrl+.Select all instances of name
Ctrl+/Toggle comment

End Point Request Builder

The end point request builder is launched using the end point toolbar icon in the script editor:

End Point Request Builder
 

It allows you to select an end point that your user has access to, and then view its associated help text and parameter and return schemas.

The "Examples" tab operates in three modes (parameters only, standard invocation, advanced invocation), each of which can show a number of different parameter or test examples. The examples can be copied and pasted into your JavaScript.

Parameters Only

This mode generates the request "params" object, in the same way as the "Get request parameters JSON" action when working in the end point editor. You'll be presented with all of the parameters defined in the end point's schema, just the "required" parameters defined in the schema, and any saved tests that have also been flagged to be used in documentation. This mode is most useful if you only need to know the correct parameter names.

Standard Invocation

The standard invocation mode takes the same parameter options described above and places them correctly in the helper.utilServerAPIServerCall function. Note that the library (ajax, server or remote) that the end point is deployed to will be automatically included. If deployed to more than one library, the serverlibrary will take precedence (which is where the majority of end points should be deployed).

Advanced Invocation

Advanced invocation is very similar to the standard invocation, but uses the apiclient JavaScript library to construct the call, rather than the helper library function.

JavaScript Validation

All of the JavaScript editors in the forms designer check that the script you have entered is valid using JSHint (opens new window). The editors are configured to check using ECMAScript 6 in strict mode.

The strict validation can sometimes cause problems with JavaScript you know to be correct. For example, the following will fail validation:

function (helper, pageName, pageInstance) {
// Repeat every 5 seconds
    (function(){
        helper.invokeCustomFieldFn('BCDATA', 'makeDataRequest');
        setTimeout(arguments.callee, 2000);
    })();   
}

It is possible to bypass the validation checking using the comments /* jshint ignore:start */ and /* jshint ignore:end */. For example:

function (helper, pageName, pageInstance) {
// Repeat every 5 seconds
    (function(){
        helper.invokeCustomFieldFn('BCDATA', 'makeDataRequest');
        /* jshint ignore:start */
        setTimeout(arguments.callee, 2000);
        /* jshint ignore:end */
    })();   
}

Last modified on 02 August 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon