Platform JavaScript APIs ^beta

The Pentaho Platform detects and manages OSGi bundles that are Pentaho Web Packages, collecting the information needed to build the AMD/RequireJS configuration and to setup the mappings needed to serve the package resources through HTTP.

The activation of the package is done by checking the existence of the META-INF/js/package.json file. The format of that file is based upon the package.json spec and is mostly compatible with files generated by tools like npm or yarn.

These are, for now, the relevant supported fields:

name and version

mandatory

The most important fields in package.json are the name and version fields. Those are required, and the package must not install without them.

• The name must be shorter than 214 characters;
• The name can’t start with a dot or an underscore;
• The name should not have uppercase letters;
• The name will end up being part of an URL; therefore, the name should avoid any non-URL-safe characters; however, forward-slashes, /, are allowed;
• The version must follow the the Semantic Versioning Specification (http://semver.org/).

The name and version together form an identifier that is assumed to be unique and is used both as the main AMD/RequireJS module identifier (separated by an underscore, like name_version) and as part of the HTTP location where the resources will be served from (separated by a forward slash, like /name/version).

Example:

{
  "name": "baz",
  "version": "1.0.0"
}

dependencies

Dependencies are specified in a simple object that maps a package name to a version range. The version range is a string which has one or more space-separated descriptors, as defined in https://github.com/npm/node-semver#ranges.

{
  "name": "baz", 
  "version": "1.0.0", 
  "dependencies": { 
    "bar": "~2.0" 
  }
}

This information is used by the platform to find out the dependency tree, do the runtime dependency resolution, and build the proper AMD/RequireJS mappings that will allow each package to request external modules that satisfy the dependencies’ version restrictions.

For instance, in the above example, the code in the "baz" package can require code from the "bar" dependency without the knowledge that it is available at the path /bar/2.1.4, or any other.

Unsupported identifiers

Only version ranges are supported. You can’t use:

• Local paths
• URLs
• Git URLs
• GitHub short URLs

config

A configuration object that is made available to AMD/RequireJS modules that match the absolute module identifier listed in the config object. Modules with a matching module identifier can access the configuration object via module.config.

In particular, this is used to configure the pentaho/service plugin, used as an inversion-of-control mechanism to inject the package resources into the system.

For instance, to declare that the resource "my-viz/model.js" implements the service named pentaho/visual/base, you would need:

{ 
  "name": "baz",
  "version": "1.0.0",
  "config": {
    "pentaho/service": {
      "baz_1.0.0/my-viz/model": "pentaho/visual/base"
    }
  }
}

packages

This field isn’t part of the package.json spec. It is based in RequireJS’s Packages and serves the same purpose.

Package configuration allows for CommonJS style path lookup rules, which are somewhat different from the default id-to-path lookup rules that are otherwise used by AMD loaders.

It is an array of package configurations. Each package configuration can either be:

• String: The package’s module identifier.
• Object: An object with the following properties:
  • name: String. The package’s module identifier.
  • location: String. Optional.
  • main: String. Optional. The identifier of the sub-module that is used as the “main module”, relative (appended) to the package module. Default value is “main”.

In the current implementation, each module identifier is relative (appended) to the Web Package’s main module identifier, unless if it starts with “/”. This might change in the final release.