Work with the JavaScript Editor

Use the JavaScript editor to add custom JavaScript functions that meet your business requirements, for example, a JavaScript function to validate whether required fields in a form have values.

Any JavaScript code that you add will have a defined scope based on the editor where you write the code. If your code will only be called from within a specific page (for example, to load some data when the page loads), you can write your code in the page-level JavaScript editor. If you want a JavaScript function to be used on multiple pages (for example, to load libraries for customizing navigation elements or custom web components), then you'll need to use the JavaScript editor for the flow or the application. You can also define JavaScript functions at the layout and fragment level.

The JavaScript editor displays a particular artifact's JS file. So if you open the main flow's JavaScript editor (for example), you're seeing the contents of the main-flow.js file. Each artifact has its own JS file: an application artifact uses the app-flow.js file, a flow uses flow-name-flow.js, and a page uses page-name-page.js. A layout uses layout.js and a fragment uses fragment-name-fragment.js.

The JavaScript editor provides extensive suggestions as you enter text to provide code-completion capabilities. This includes code snippets for common JavaScript structures, such as "for" and "while" loops and conditional statements. For example, typing for in the JavaScript editor will show you various "for" loop structures:
Description of js-code-complete-example.png follows
Description of the illustration js-code-complete-example.png

Selecting a structure will let you easily switch the variables in the structure.

The editor also provides code validation and identifies the lines that contain syntax warnings and errors in the right margin of the editor. A light bulb icon in the left margin indicates a hint for correcting invalid JavaScript code. Note that the auto-save function will not save a JavaScript file that has invalid code. For help with JavaScript syntax, see https://developer.mozilla.org/en-US/docs/Web/JavaScript#reference. These additional resources can be helpful as well:

Add a Custom JavaScript Function

To add a custom JavaScript function, you define the function within the class provided in the JavaScript editor for your page, flow, or application. You can also add JavaScript functions to layouts and fragments.

Select the artifact for which you want to add a JavaScript function, then click its JavaScript tab.

For example, to open the JavaScript editor for the main flow, select the main node, then click the JavaScript tab. Or go directly to the main-flow.js file in the Navigator's Source, as shown here:

Description of the illustration page-functions-editor.png

An application uses the app-flow.js file, a flow uses flow-name-flow.js, and a page uses page-name-page.js. A layout uses layout.js and a fragment fragment-name-fragment.js.
Define your JavaScript function within the class provided in the JavaScript editor. Visual Builder supports RequireJS (a JavaScript file and module loader that simplifies managing library references), so when defining a new flow-level function, define your function in the editor as shown here:
```
define([], () => {
  'use strict';

  class FlowModule {
  // write your function here
  }
 
  return FlowModule;
});
```
Just as flow-level functions use FlowModule, application functions use AppModule and page-level functions use PageModule.
If any of the functions within the class need to access the application context, create a constructor for the class and include the context as an input parameter:
```
constructor(context){}
```
In this example, two functions have been created in the PageModule class: a constructor and a custom JavaScript function (module function). When the page, main-some-page, is opened, the corresponding instance of the PageModule class (shown below) is created for the page. Also, the instance's constructor is automatically called and the application context is automatically passed to the constructor:

Description of the illustration javascript-function-example.png

After you've defined your custom JavaScript functions, you can call them in action chains as well as UI components:

In an action chain, use the Call Function action. See Add a Call Function Action.
In a component's Properties pane, select the function in the Expression editor or Variables picker of a property:

Description of the illustration js_functions_variablepicker.png

To write efficient expressions that handle situations where a referenced field might not be available or the field's value could be null, see How Do I Write Expressions If a Referenced Field Might Not Be Available Or Its Value Could Be Null?

Use RequireJS to Reference External JavaScript Files

If you want to use RequireJS to refer to external JavaScript libraries in your application, you can add a requirejs statement to your application's definition, then import the library.

Open the app-flow.json file for your application.
- In the Web Apps pane, select your application node, then click the JSON tab, or
- In the Source view, locate the file for your application under webapps.
Add a requirejs statement to the application's definition. For example, if you've added myLib.js to your application's resources under …/applications/<your-app-id>/resources/js/, add:
```
  "requirejs": {
    "paths": {
      "myLib": "resources/js/myLib"
    }
  }
```
You can also use an expression as the value. For example, instead of resources/js/myLib, enter:
```
  "requirejs": {
    "paths": {
      "myLib": "{{ 'resources/js/' + $initParams.resourceFolder }}"
    }
  }
```
Either way, make sure the requirejs entry is a sibling of the id or description entries. If a requirejs section already exists, simply add your entry under paths.
To load and use your library in a module, use the define statement to make your library a dependency for your module. In your JS file, enter, for example:
```
define(['myLib'], (MyLib) => { 
          'use strict';
 ...
```

Use Variables with a JavaScript Module

You can't directly get or set variables from within your JavaScript modules. However, you can use the Call Module Function action to access your JS module. This action takes an array of parameters which can include variables and can return a result that you can assign to a variable.

This approach ensures that the variable has a consistent state from the beginning to the end of your action chain's execution.

To "get" a value, pass the variable in as a parameter to the module function that you are calling using a callModuleFunction action in the action chain.

To "set" a variable based on the return value from that callModuleFunction, use an Assign Variables action to copy the result of the function into the desired variable in whatever scope.