Pentaho Web Package

The Pentaho Platform detects and manages OSGi bundles that contain 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 package is described by a package.json file, based upon the package.json spec and 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 not 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/modules module, used as a basic inversion-of-control mechanism to inject the package resources into the system.

For instance, to declare that the resource "my-viz/config.js" is an instance of type "pentaho/config/spec/IRuleSet", you would need:

{ 
  "name": "baz",
  "version": "1.0.0",
  "config": {
    "pentaho/modules": {
      "baz/my-viz/config": {"type": "pentaho/config/spec/IRuleSet"}
    }
  }
}

Another use is to declare that a type such as that exported by the module "my-viz/Model.js" is a visualization model type.

{ 
  "name": "baz",
  "version": "1.0.0",
  "config": {
    "pentaho/modules": {
      "baz/my-viz/Model": {"base": "pentaho/visual/base/Model"}
    }
  }
}