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:

Create an archive (for example, a functions.zip file) that contains your JavaScript files and a related functions.json file.
You can structure your files any way you want, meaning they can be a flat list of files or in subfolders of any depth, as long as the functions.json file uses the correct file paths. Here's an example of the structure you can use:
```
functions
| functions.json
| someFunction.js
| subfolder1/
|   |  myFunction.js
| subfolder2/
|   |  otherFunction.js
```
Make sure your JavaScript files do not have any dependencies. See Example JS Module Defined As a Global Function.

The functions.json file defines the context name, label, description, and other necessary metadata and is required to expose the functions properly. See Example functions.json to Declare Global Functions.
Import the archive to your extension at the global resources level.

Note:
Global functions can only be defined at the extension level. You cannot add them to an App UI's resources or any other folder, including those meant for the Unified Application.
1. In the App UIs pane, right-click the global Resources folder and click Import. If you're using Source view, go to extension1/sources/ui/self/resources/ and click Import.
2. Drag your archive (for example, functions.zip) from your local file system and drop it onto the target area.
3. Click Import.
Once the functions folder is created in your extension, you can add or delete files as needed. Here's an example of the functions.zip imported with the calculator.js and functions.json files:

Description of the illustration global-functions.png

The functions now become available to you as follows:

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-name>.<function-name>(...), for example, $modules.calculator.add:

Description of the illustration globalfunction-bizrule.png

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 <artifact-scope>.modules.<module-id>.<function-name>(...), for example, $application.modules.calculator.add:

Description of the illustration globalfunction-jsactionchains.png

For information on how to use the Call Function action, see Add a Call Function Action.

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 `calculator` module allows access to all dependent extensions (`"referenceable": "extension"`), whereas the `multiply` method only allows access to the current extension (`"referenceable": "self"`) . This definition means a dependent extension that imports the `calculator` module will not be able to call the `multiply` function. Consider another example: `"dateLocalUtils": { "path": "date/dateUtils", "label": "Date Utility Functions", "referenceable": "self", "functions": { "dateToIsoString": { "referenceable": "extension"` 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 `referenceable`, it assumes the access set on the module. The default access for a module is `self`.

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.

Example JS Module Defined As a Global Function

Example functions.json to Declare Global Functions

Example `functions.json` to Declare Global Functions