Creating a JavaScript bundle

This documentation shows how to use extensibility scenarios that are experimentally deployed in update 9. The APIs described here are manually deployed, which currently prevents installation in the Cloud. They are usable only in an Early adopter program context.

JavaScript bundles are the building blocks for many extensibility scenarios. This article describes the steps to create a JavaScript bundle.

Bundle name

First, you need to choose a name for your bundle. The bundle name should start with your reserved prefix (starting with X, Y or Z) and should only contain letters, digits, and hyphens (-). JavaScript tradition is to use only lowercase letters. So a typical bundle name would be:

xa1-my-first-bundle

Bundle directory

The SAFE X3 'node.js' web server contains a special bundles directory where all the bundles are deployed. Your bundle is deployed in a subdirectory that has your chosen bundle name. Typically:

$WEB_SERVER_ROOT/bundles/xa1-my-first-bundle

All the files that comprise your bundle are deployed into this subdirectory. This way, the bundle can be updated with a simple unzip operation.

package.json file

The bundle subdirectory must contain a special file called package.json that describes the extension points implemented by the bundle:

$WEB_SERVER_ROOT/bundles/xa1-my-first-bundle/package.json

The 'node.js' web server discovers the capabilities of your bundle by reading this manifest file.

The structure of the package.json file is an extension of a standard JSON structure defined by NPM, 'node.js' package manager, and which is described on the URL https://docs.npmjs.com/files/package.json.

Here is a typical package.json file:

CODECODE CODE json{"name": "xa1-my-first-bundle","description": "My first bundle","version": "1.0.0","author": "ACME Corp.","dependencies" : { "my-favorite-js-lib" : "1.0.0"},"private": true,"sage": {"x3": {"extensions": {"4gl-apis": [{"module": "./lib/my-api1",}, {"module": "./lib/my-api2", }],"widgets": [{"module": "./public/js/my-widget","type": "application/x-my-payload"}]}}}}

The dependencies tag allows you to reference the public JavaScript packages that you use in your JavaScript code. You do not need to include the source code for these public packages in your bundle; they are downloaded automatically from NPM when your bundle is installed. See the package.json documentation for details.

The private tag is optional. It indicates that your bundle is a closed source that prevents accidental publication to NPM. Of course, you can also create public bundles that can be publicly (and freely) downloaded through NPM.

The sage tag and x3 subtag are a proprietary JSON markup that describes the extensions that your bundle implements. Each extension is introduced by a special key (4gl-apis, widgets, etc.) followed by a list of extension modules. In the example above, the bundle provides two 4GL API extension modules and one widget extension module.

Extension keys

The following extension keys can be used in a package.json file:

• 4gl-apis: describes JavaScript APIs that can be called from the SAFE X3 4GL language. A typical example is an API that exposes functions to create and verify digital signatures.
• widgets: describes widgets that extend the web user interface toolkit. Typical examples are custom graphs and charts, diagramming tools, etc.
• http: describes handlers for HTTP requests. This is used, for example, to integrate with a payment service that uses an HTTP callback to signal the success or failure of the operation.
• contracts: describes an extension of the SAFE X3 web administration/collaboration platform.

Bundle substructure

The bundle substructure is relatively free, but it is good to align with a standard directory structure. The recommended substructure is the following:

xa1-my-first-bundle/package.json # manifestpublic/# browser filesjs/# browser-side javascript fileshtml/ # HTML filescss/ # CSS fileslib/# server-side javascript filestest/ # unit tests