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 is mostly compatible with files generated by the npm tool.

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, including the scope, for scoped packages;
• 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 a unique system identifier for the package which is used internally as the base AMD/RequireJS module identifier and as part of the HTTP location where the resources are served.

Example:

{
  "name": "my-viz-lib",
  "version": "1.0.0"
}

Names can also be scoped to an organization, as in:

{
  "name": "@my-org/viz-lib",
  "version": "1.0.0"
}

paths

Exposes the resources under a given package path under a base module identifier.

When unspecified, the literal package name is used to map the package’s root path, as if the following had been specified:

{
  "name": "@my-org/viz-lib",
  "version": "1.0.0",
  "paths": {
    "@my-org/viz-lib": "/"
  }
}

While it is common to specify scoped and hyphenated package names, AMD module identifiers are, more commonly, valid JavaScript identifiers. So, in this case, it would make more sense to explicitly specify a root module, such as in:

{
  "name": "@my-org/viz-lib",
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  }
}

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": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "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 @my-org/viz-lib package can use modules from the bar dependency without the knowledge that it is available at a path such as /bar@2.1.4/foo.

Unsupported identifiers

Only version ranges are supported. You cannot use:

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

config

A configuration object that is made available to AMD/RequireJS modules that match the 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 package JavaScript module at config.js exports a value which is an instance of the type pentaho/config/spec/IRuleSet, you would do:

{ 
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "config": {
    "pentaho/modules": {
      "myOrg/visual/config": {"type": "pentaho/config/spec/IRuleSet"}
    }
  }
}

Another use is to declare that a type such as that exported by the JavaScript module at Model.js is subtype of the visualization base type, pentaho/visual/Model:

{ 
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "config": {
    "pentaho/modules": {
      "myOrg/visual/Model": {"base": "pentaho/visual/Model"}
    }
  }
}