Define Global Functions

Global functions JavaScript modules must be defined under resources/functions for an extension, and the metadata for each JavaScript resource to be declared in resources/functions/functions.json.

Note:

Global functions can only be defined for an extension. They cannot be defined under an App UI or other resources folders, including in a unified app.

For example, ext-layout, is an extension that defines two JavaScript files that are shared by all containers, like page, fragment or dynamic layout artifacts, in the current extension. The files - dateUtils.js and standardUtils.js are located under ext-layout/ui/self/resources/functions.

The JavaScript files are meant to be utilities style classes so that when the module is loaded (using requireJS) it returns a map of function names to function callbacks.

Example 1-66 Global function JS module

The resources/functions folder contains a functions.json, a configuration file that defines the list of JavaScript modules (in the 'files' section).

In this example, the standardUtils.js, defined in the location above, defines several static methods, and returns the methods that are allowed for general use:

'use strict';

define([], () => {
  class StandardFunctions {
    static join(arr = []) {
      if (arr.length === 0) {
        return '';
      }
      const newArr = (arr.slice(1, arr.length).map((o) => (${o})));
      return [arr[0]].concat(newArr).join(' ');
    }

    /**
     * Returns true if the field provided as parameter #1 contains the characters provided as parameter #2, else
     * returns false.
     * @param {string} field
     * @param {string} characters
     * @returns {boolean}
     */
    static contains(field = '', characters) {
      return field.indexOf(characters) >= 0;
    }

    /**
     * Returns a string converted from a decimal.
     * @param {number} field
     * @returns {string}
     */
    static convertNumberToString(field) {
      return field.toString();
    }

    /**
     * Convert string to number
     * @param {string} field
     * @return {number}
     */
    static convertStringToNumber(field) {
      return parseInt(field, 10);
    }

    /**
     * Returns the number of characters in a string.
     * @param {string} field
     * @return {number}
     */
    static lengthOfString(field = '') {
      return field.length;
    }
  }

  return {
    contains: StandardFunctions.contains,
    convertNumberToString: StandardFunctions.convertNumberToString,
    convertStringToNumber: StandardFunctions.convertStringToNumber,
    join: StandardFunctions.join,
    lengthOfString: StandardFunctions.lengthOfString,
  };
});

Declaring global functions in functions.json metadata

In the sample above, the standardUtils JavaScript module exports an Object with five properties mapped to the function callback. These methods can be declared in the metadata, and then exposed to the current extension and downstream extensions using the functions.json metadata configuration.

{
  "files": {
    "utils": {
      "path": "standardUtils",
      "label": "Standard Utility Functions",

      "referenceable": "extension",

      "functions": {
        "contains": {
          "params": {
            "field": {
              "label": "field",
              "description": "",
              "type": "string"
            },
            "characters": {
              "label": "characters",
              "description": "",
              "type": "string"
            }
          },
          "return": "boolean"
        },
        "convertNumberToString": {
          "referenceable": "self"
        },
        "convertStringToNumber": {
          "referenceable": "self"
        },
        "join": {},
        "lengthOfString": {}
      }
    },
    "dateLocalUtils": {
      "path": "date/dateUtils",
      "label": "Date Utility Functions",

      "referenceable": "self",
      "functions": {
        "dateToIsoString": {
          "referenceable": "extension"
        }
      }
    }
  }
}

Note:

The metadata in the sample JSON above is edited to show the relevant details. It is not a complete configuration.

The "files" section includes one or more JavaScript files. "utils" is an alias to the JavaScript file "standardUtils.js", defined under the "path" property (the .js extension can be dropped because it is a requireJS module).

The "referenceable": "extensible" declares that the file is accessible to downstream dependent extensions. The file alias "dateLocalUtils", with the path "date/dateUtils", is set to "referenceable": "self", which means it is only accessible to artifacts in the current extension.

The "functions" section can be used to list functions that are available to callers. The function name can be used in expressions, if present (see below). Additionally, function metadata can define whether it can be referenced from the current extension or a dependent downstream extension. While a function can be less permissive about its access, it cannot supersede the access set on the file.

For example, the file "utils" allows access to all dependent extensions (it is set to "referenceable": "extension"), whereas the method "convertNumberToString" within "utils" only allows access to the current extension (it is set to "referenceable": "self") . This is allowed because a function can be less permissive. This means a dependent extension that imports this module, will not be able to call the "convertNumberToString" function (it will result in a log error).

Another example, is where the file "dateLocalUtils" that defines a function "dateToIsoString", which expands its access beyond what the file allows. This is not allowed and ignored. The function can only be called by artifacts in the current extension.

When a function does not define "referenceable", access is set on the file. The default access for a file is "self".