Add JavaScript Modules As Global Functions
When different parts of your application routinely use similar JavaScript functions to transform or manipulate data, you can extract those functions as global functions and reuse them.
To make these functions reusable in pages, you can define their implementation as global functions and make them available in all pages (fragments or any other container), both within and across extensions.
Let's say extA
defines two JavaScript utilities, dateUtils.js
and standardUtils.js
, shared by containers (page, fragment, and dynamic layout artifacts) in the extension. Rather than copy the code for the utilities into every extension that requires the same logic, you can add them as global functions (at the extension1/sources/ui/self/resources/
level) and declare rules for their usage in an associated functions.json
metadata file. This way, dependent extensions (and their App UIs) can import the functions as resources and use them with minimal effort.
To add JavaScript modules as global functions to your extension:
- In the Advanced Expressions editor for business rules, validation rules, and default values, where you can drag these functions from the Actions palette. To edit the code directly, use the format
$modules.<module-id>.<function-name>(...)
, for example,$modules.calculator.add
:For information on how to build expressions, see Build Advanced Expressions.
- In the JavaScript Action Chains editor, where you can drag these functions from the Actions palette. To edit the code directly, use the format
$modules.<module-id>.<function-name>(...)
, for example,$modules.calculator.add
:For information on how to use the Call Function action, see Add a Call Function Action.
Manage Global Functions
Use the Functions editor to manage global functions added to your extension, where you can edit the functions.json
file as well as create new JavaScript files that contain global functions.
Example JS Module Defined As a Global Function
Here's an example of a calculator.js
module, which defines two global functions:
define([], () => {
'use strict';
function add(num1, num2) {
return num1 + num2;
}
function multiply(num1, num2) {
return num1 * num2;
}
return { add, multiply };
});
The functions.json
file would include the calculator.js
file in its list of JS modules in the files
section.
Example functions.json
to Declare Global Functions
The functions.json
file is used to declare JavaScript modules as global functions and specifies the metadata of functions, such as module name, function name and parameters it takes, as well as the implementation file path. Here's an example of a functions.json
file that references the calculator.js
module:
{
"files": {
"calculator": {
"path": "oracle/calculator",
"label": "Calculator",
"description": "Calculator Utilities",
"iconClass": "oj-ux-ico-airport",
"referenceable": "extension",
"functions": {
"add": {
"label": "Add Numbers",
"description": "Add two numbers",
"params": {
"num1": {
"label": "First Number",
"description": "First Number",
"type": "number"
},
"num2": {
"label": "Second Number",
"description": "Second Number",
"type": "number"
}
},
"return": "number",
"referenceable": "extension"
},
"multiply": {
"label": "Multiply Numbers",
"description": "Multiply two numbers",
"params": {
"num1": {
"label": "First Number",
"description": "First Number",
"type": "number"
},
"num2": {
"label": "Second Number",
"description": "Second Number",
"type": "number"
}
},
"return": "number",
"referenceable": "self"
}
}
}
}
}
File Metadata Object
The files
section can include one or more JS files. Each file path (relative to dynamicLayouts/self/resources/functions/
) maps to a metadata object that describes a group of functions.
Name | Type | Description |
---|---|---|
path |
string | Relative path of the implementation file. In the example above, the path to the .js file is oracle/calculator . When the file is a RequireJS module, the .js extension can be dropped.
|
label |
string | A string or an i18n bundle key to the string for naming this function group. |
description |
string | A string or an i18n bundle key to the string for describing this function group. |
referenceable |
self | extension |
(Optional) Whether the module is accessible to the current extension or dependent extensions. For example, the calculator module is set to "referenceable": "extensible" , meaning the file is accessible to dependent extensions. If referenceable isn't defined, its value defaults to self , which means only the current extension (where the module is defined) can access its functions.
|
functions |
Object<String,Function> | (Required) An object that maps function name to function metadata. See Function Metadata Object. |
Function Metadata Object
The functions
section can be used to list functions that are available to callers.
Name | Type | Description |
---|---|---|
label |
string | A string or an i18n bundle key to the string for naming this function group. |
description |
string | A string or an i18n bundle key to the string for describing this function group. |
params |
Object<String,Function> | (Required) An object that maps parameter name to a param object. See Param Metadata Object. |
return |
string | The return type of the function. Only primitive types, array, object, and any are supported.
|
referenceable |
self | extension |
Whether the function can be referenced from the current or a dependent extension. A function can be less permissive about its access, but it cannot supersede the access set on the module. For example, the Consider another example:
where the dateLocalUtils module is only accessible to the current extension ("referenceable": "self" ), but the dateToIsoString function within dateLocalUtils expands its access beyond what the module allows. This is not allowed, so the function can only be called by artifacts in the current extension.
If a function does not define |
Param Metadata Object
Name | Type | Description |
---|---|---|
label |
string | A string or an i18n bundle key to the string for naming this function group. |
description |
string | A string or an i18n bundle key to the string for describing this function group. |
type |
string | (Required) The type of the parameter. Only primitive types, array, object, and any are supported.
|