What's new and changed in the Platform JavaScript APIs beta 4

Platform JavaScript APIs

Modules API^⭐

The new Modules API brings easy access to functionalities such as configuration and inversion of control to any AMD module. You can check the reference documentation at
pentaho.module

The Modules API levels the ground between regular AMD modules and those that export Type API types, by removing the magic by which configurations were automatically applied to the latter, via its old custom module format. All AMD modules now consume configurations explicitly via the Modules API (or, alternatively, explicitly via the global configuration service module, pentaho/config/service).

1. An AMD module will now typically request its Modules API module object by using the pentaho/module! AMD loader plugin, like in the following example:

    // Obtain the "self" module.
    define(["pentaho/module!_"], function(module) {
       
      if(module.config) {
        // Do something with the module's configuration object.
      }
    });
   

2. The way in which inversion of control is performed has changed, and now it solely circles around the module concept. Instead of advertising type and instance modules separately, via AMD configuration of the old pentaho/instanceInfo and pentaho/typeInfo modules, both of these kinds of modules are now advertised by configuring the single pentaho/modules module, such as in the following example:

    require.config({
      config: {
        "pentaho/modules": {
          // An interface is an abstract type.
          "IHomeScreen": {base: null, isAbstract: true},
             
          // An module which returns an instance of `IHomeScreen`.
          "mine/homeScreen": {type: "IHomeScreen"},
             
          // Another instance of `IHomeScreen`, yet with a higher ranking.
          "yours/proHomeScreen": {type: "IHomeScreen", ranking: 2}
        }
      }
    });
   

3. Obtaining the registered instance modules of a given module type, or the registered type modules descending from a given base type, is now done through the one of the following new AMD loader plugin modules, effectively replacing and extending the old pentaho/service module:

   • pentaho/module/instanceOf!
   • pentaho/module/instancesOf!
   • pentaho/module/subtypeOf!
   • pentaho/module/subtypesOf!

   The following example illustrates the use of pentaho/module/instanceOf to obtain a registered instance of the IHomeScreen interface:

    define(["pentaho/module/instanceOf!IHomeScreen"], function(homeScreen) {
      // Use `homeScreen`.
    });
   

Configuration API

1. Configuration rules no longer distinguish if a type or an instance module is being configured. These must now use the new module property, indistinguishably.

2. Configuration rules have become more powerful as now these can specify dependency modules, through the deps^⭐ property. Configurations can now also be built dynamically, by specifying a function^⭐ in the apply property.

   The following example illustrates the use of the new features, in a configuration rule that changes the default color palette used by the stock bar chart visualization:

   var configRule = {
     select: {
       module: "pentaho/visual/models/Bar"
     },
     deps: [
       "pentaho/visual/color/palettes/nominalLight"
     ],
     apply: function(nominalLightPalette) {
       return {
         props: {
           palette: {
             defaultValue: nominalLightPalette
           }
         }
       };
     }
   };
   

3. Configuration rules can now reference modules (or dependencies) with a module id relative to the rule set configuration file.

4. When registering configuration rules with the modules system, you should now use the identifier: pentaho/config/spec/IRuleSet. For example:

   require.config({
     config: {
       "pentaho/modules": {
         "my/viz/config": {type: "pentaho/config/spec/IRuleSet"}
       }
     }
   });
   

Type API

The use of Type API types and instances has been greatly simplified.

1. Types and instances are no longer defined using a special module format. Now, they’re defined just like any regular class or instance would be defined in an AMD module.

   The following example shows how it now looks like to define a visualization model type (which is a Type API type):

    define([
      "pentaho/module!_",
      "pentaho/visual/base/Model"
    ], function(module, BaseModel) {
         
      return BaseModel.extend({
        $type: {
          id: module.id,
          defaultView: "./View",
          props: [
            {
              name: "category",
              base: "pentaho/visual/role/Property",
              modes: ["string"],
              fields: {isRequired: true}
            }
          ]
        }
      })
      .configure({$type: module.config});
    });
   

2. It is now each type’s responsibility to apply its own configuration. It is nonetheless advisable to use the new configure method.

3. The identifiers of all standard type modules have been renamed to using CamelCase, to match the exported value kind, a type.

4. The old Type API Context is gone! For the rare cases in which you’ll need to create Type API types given a type reference, or instances given their specification, you can use the new pentaho.type.loader service.

Visualization API

See What’s new and changed in the Visualization API beta 4.