Platform JavaScript APIs

Use these APIs to configure Pentaho platform JavaScript modules.

Configuration API

Use the Configuration API to configure JavaScript modules.

Pentaho uses JavaScript objects called configurations. Configurations conform to pentaho.config.spec.IRuleSet. Each configuration is a set of rules defined by pentaho.config.spec.IRule.

Register the configuration module with pentaho/modules as an instance of pentaho/config/spec/IRuleSet.

Configurations (rules) include these parts:

• select

  • Targets a module.

  • Optionally targets one or more Pentaho environment variable values.

  • Use an array to specify alternate values for a variable.

  • application is the most common variable.

  • See Known values of Pentaho platform environment variables.

• apply

  • Defines configuration properties and values.

  • Can also be a function.

  • The function runs only if the selected module loads.

• deps

  • Optional array of additional module identifiers.

  • Loads only if the selected module loads.

  • When apply is a function, dependency values are passed as arguments.

• priority

  • Optional number. Defaults to 0.

  • Higher values win when rules target the same module.

Configuration module example

This AMD/RequireJS configuration module contains four rules:

define(function() {
  "use strict";
  // The value of the module is an IRuleSet.
  return {
    rules: [
      // IRule 1
      {
        select: {
          module: "my/Car",
          application: "my/vehicleEditor"
        },
        apply: {
          tireSize: 18,
          exteriorColor: "caribbean-blue"
        }
      },
    
      // IRule 2
      {
        priority: 1,
        select: {
          module: "my/Candy"
        },
        apply: {
          cocoaPercentage: 0.9,
          fillingFlavour: "orange"
        }
      },
      
      // IRule 3
      {
        select: {
          module: [
            "my/friends/john", 
            "my/friends/marie"
          ]
        },
        apply: {
          empathyLevel: 0.6
        }
      },
      
      // IRule 4
      {
        select: {
          module: "my/houses/main"
        },
        deps: [
          "lodash", 
          "./baseHouseSchematics"
        ],
        apply: function(_, baseHouseSchematics) {
          return _.merge(baseHouseSchematics, {
            averageSummerTemperature: 23
          });
        }
      }
    ]
  }
});

Rule summary:

• Rule 1 targets my/Car when used by my/vehicleEditor.

• Rule 2 targets my/Candy and sets a higher priority.

• Rule 3 targets two instance modules.

• Rule 4 targets my/houses/main and uses dependencies.

Global configuration file

System integrators and administrators can add ad hoc rules in the global configuration file. This file is pre-registered.

File location:

• PDI: data-integration/system/karaf/config/web-client/config.js

• Pentaho Server: pentaho-server/pentaho-solutions/system/karaf/config/web-client/config.js

The system reloads configurations after you save the file. You do not need to restart the product.

The shipped file includes a small set of illustrative rules (commented out).

You can also deploy a Pentaho web package that registers a configuration module. See Pentaho web package.

Known values of Pentaho platform environment variables

These values are already defined:

• application

  • CDF: pentaho/cdf

  • Analyzer: pentaho/analyzer

  • Analyzer in Dashboard Designer: pentaho/dashboardDesigner

  • PDI: pentaho/det

• theme

  • sapphire

  • crystal

  • ruby

• locale

  • Values defined by RFC 5646.

Pentaho web package

Pentaho detects and manages OSGi bundles that contain Pentaho web packages. It collects package metadata to build AMD/RequireJS configuration. It also maps package resources for HTTP serving.

A package is described by package.json. The file is based on the package.json spec. It is mostly compatible with npm-generated files.

Supported fields:

• name and version

• paths

• dependencies

• config

Name and version

name and version are required. The package will not install without them.

Rules:

• name must be shorter than 214 characters (including scope).

• name cannot start with . or _.

• name should be lowercase.

• name becomes part of a URL. Avoid non-URL-safe characters. / is allowed.

• version must follow Semantic Versioning.

Together, name and version form a unique identifier. Pentaho uses it as:

• The base AMD/RequireJS module identifier.

• Part of the HTTP resource location.

Example:

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

Scoped example:

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

paths

Use paths to expose package resources under a base module identifier.

If you omit paths, Pentaho maps the package root using the package name. This example is equivalent to the default mapping:

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

AMD module identifiers must also be valid JavaScript identifiers. If your package name is scoped and hyphenated, define a root module explicitly:

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

dependencies

Use dependencies to map a package name to a version range. The range is a string of one or more space-separated descriptors.

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 supported range formats.

Pentaho uses dependencies to:

• Resolve runtime dependencies.

• Build AMD/RequireJS mappings.

This lets your code load external modules without hard-coding versioned paths.

Unsupported identifiers:

• Local paths

• URLs

• Git URLs

• GitHub short URLs

config

Use config to expose configuration to matching AMD/RequireJS modules. Matching modules can access it through module.config.

Use this to configure pentaho/modules. This injects package resources into the system.

Example: declare a module that exports an IRuleSet:

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

Example: declare a type as a subtype of 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"}
    }
  }
}

visualization-api-cp

Deploying a visualization

After creating a visualization, deploy it to a Pentaho product. This includes Pentaho Server and PDI.

The Pentaho platform runs on an OSGi container. It uses Apache Karaf.

Example: to deploy the sample D3 bar chart visualization to Analyzer, copy the TGZ file to pentaho-solutions/system/karaf/deploy.

OSGi artifacts deployment

You can deploy artifacts by dropping files into the deploy folder. Artifacts are installed and activated automatically. This also applies after you restart the product.

Replacing a file reinstalls it. Deleting a file uninstalls it.

The deployer supports ZIP and TGZ files. These archives can include web resources described by package.json.

Multiple web packages can be bundled in one archive. This can provision visualization dependencies.

Karaf deploy folder locations:

• PDI: system/karaf/deploy

• Pentaho Server: pentaho-solutions/system/karaf/deploy

Inspecting tutorial results

After deploying the tutorial project, the D3 bar chart appears in Analyzer and PDI. It is also available in a CDE dashboard.

In Analyzer

• The menu and placeholder icon appear on the canvas:

  

  Bar/D3 visualization example in Analyzer, showing the menu and placeholder icon
• The visualization renders:

  

  Rendered Bar/D3 visualization example in Analyzer

In PDI

• The menu and placeholder icon appear on the canvas:

  

  Bar/D3 visualization example in PDI, showing the menu and placeholder icon
• The visualization renders:

  

  Rendered Bar/D3 visualization example in PDI

In CTools

The D3 bar chart is available for use in a dashboard. You can obtain the dashboard from pentaho/pentaho-engineering-samples:

Bar/D3 visualization example in CTools