Pentaho web package
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
andversion
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.
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
.
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"} } } }