Skip to main content
Pentaho Documentation

Pentaho web package

Parent article

Pentaho detects and manages OSGi bundles that contain Pentaho web packages, collecting the information needed to build the AMD/RequireJS configuration and to set up the mappings needed to serve the package resources through HTTP. A 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.

You create a web package to define your configurations and mappings through the following supported fields:

  • name and version
  • paths
  • dependencies
  • config

The name and version fields

You must specify the name and version fields. These fields are the most important in the package.json file. The package will not install without these fields.

These fields must adhere to the following rules:

  • The name must be shorter than 214 characters, including the scope, for scoped packages.
  • The name cannot start with a dot or an underscore.
  • The name should not have uppercase letters.
  • The name will end up being part of an URL. You must avoid any non-URL-safe characters, except forward-slashes (/) are permitted.
  • The version must follow the Semantic Versioning Specification (http://semver.org/).

The name and version fields together form a unique system identifier for the package. This unique system identifier is used internally as the base AMD/RequireJS module identifier and as part of the HTTP location where the resources are served.

Example

The following lines of code are an example of specifying the mandatory name and version fields:

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

You can specify an organization in the name field, as shown in the following sample lines of code:

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

The paths field

You can use the paths field to expose the resources of a given package path under a base module identifier.

If you do not specify a value for the paths field, the package name is used to map the package’s root path, as if, you specified the package name for the path, as shown in the following example:

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

You would normally specify scoped and hyphenated package name, yet the AMD module identifiers are also valid JavaScript identifiers. For this case, you would explicitly specify a root module, as shown in the following example:

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

The dependencies field

You can use the dependencies field to map a package name to a version range in a simple object. The version range is a string that has one or more space-separated descriptors, as shown in the following example:

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

See https://github.com/npm/node-semver#ranges for the definitions of available space-separated descriptors.

The dependencies field is used by Pentaho to determine the dependency tree, resolve runtime dependencies, and build the proper AMD/RequireJS mappings to 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 the following identifiers:

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

The config field

You set the config field to the module identifier listed your configuration object that is made available to AMD/RequireJS modules that match. Modules with a matching identifier can access the configuration object via module.config. You use this object to configure the pentaho/modules module, which is a basic inversion-of-control mechanism to inject the package resources into the system.

For example, to declare that the JavaScript module package in config.js exports a value that is an instance of the pentaho/config/spec/IRuleSet type, you would use the following sample lines of code:

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

You can also use the config field to declare that a type (such as that exported by the JavaScript module in Model.js) is a subtype of the visualization base type, pentaho/visual/Model, as shown in the following example:

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