Configuring a Visualization

This article shows you how to create a configuration for a Visualization API visualization.

It is assumed that you have some basic knowledge on how to configure JavaScript types and instances on the Pentaho platform and on what constitutes a visualization. If not, you should first read Configuration API and Creating a visualization.

Visualizations are constituted by one Model type and (at least) one View type, any of which can be seamlessly configured.

Section Identifiers of Stock Visualizations contains the list of identifiers of stock Model and View types. Additionally, section Identifiers of Stock Color Palettes contains the list of identifiers of stock color palettes.

The following sections show examples of typical Model and View configurations. A single IRule object is provided in each example, but it should be interpreted as being part of the following generic configuration module:

define(function() {
  
  "use strict";
  
  var ruleSpec = { /* ... */ };
  
  return {rules: [ruleSpec]};
});

Examples of typical Model configurations

Hiding a visualization from an application’s visualization list

The following rule configures the isBrowsable type attribute to hide the stock Pie visualization (and any visualizations that derive from it) from the Analyzer application’s visualizations menu, effectively preventing the user from creating new visualizations of this type:

var ruleSpec = {
  select: {
    module: "pentaho/visual/models/Pie",
    application: "pentaho-analyzer"
  },
  apply: {
    isBrowsable: false
  }
};

Setting the default line width of a line chart and hiding the property

The following rule configures the default value of the lineWidth property, of both the Line and the Column/Line Combo stock visualizations, to be 2 pixels and, additionally, hides it from the Analyzer application’s properties panel, effectively preventing the user from changing its default value:

var ruleSpec = {
  select: {
    module: [
      "pentaho/visual/models/Line",
      "pentaho/visual/models/BarLine"
    ],
    application: "pentaho-analyzer"
  },
  apply: {
    props: {
      lineWidth: {
        defaultValue: 2,
        isBrowsable: false
      }
    }
  }
};

Setting the default shape of points of a line chart

The following rule configures the default value of the shape property of both the Line and the Column/Line Combo stock visualizations, when in any application, to be the diamond shape:

var ruleSpec = {
  select: {
    module: [
      "pentaho/visual/models/Line",
      "pentaho/visual/models/BarLine"
    ]
  },
  apply: {
    props: {
      shape: {
        defaultValue: "diamond"
      }
    }
  }
};

Changing the name of a visualization, as shown in the menu of an application

The following rule changes the label type attribute of the Bar stock visualization, affecting how it is displayed in the visualizations menu of the Analyzer and PDI applications:

var ruleSpec = {
  select: {
    module: "pentaho/visual/models/Bar",
    application: [
      "pentaho-analyzer",
      "pentaho-det"
    ]
  },
  apply: {
    label: "Vertical Bars"
  }
};

Note that it is a best practice to load localizable text from a resource bundle. See pentaho/i18n.

Examples of typical View configurations

Note that view configuration is typically tied to the technology with which views are built. The ViewType#extension attribute exists to satisfy the pass-through of such options of the underlying technology. You should consult the view type documentation to find out about which extension properties it supports.

The views of stock visualizations are implemented using the CCC charting library, and can be customized using its rich set of extension points.

Thicken the axes rules of stock visualizations

The following rule changes the lineWidth property of the baseAxisRule_ and orthoAxisRule_ extension points, of any applicable stock visualizations, in any application:

var ruleSpec = {
  select: {
    module: "pentaho/ccc/visual/Abstract"
  },
  apply: {
    extension: {
      baseAxisRule_lineWidth: 2,
      orthoAxisRule_lineWidth: 2
    }
  }
};

Change the default label font of axes’ ticks of stock visualizations

The following rule changes the font property of the baseAxisLabel_ and orthoAxisLabel_ extension points, of any applicable stock visualizations, when in the PDI application:

var ruleSpec = {
  select: {
    module: "pentaho/ccc/visual/AreaStacked",
    application: "pentaho-det"
  },
  apply: {
    extension: {
      baseAxisLabel_font: "12px OpenSansRegular",
      orthoAxisLabel_font: "12px OpenSansRegular"
    }
  }
};

Examples of color palette configurations

Change the colors of the default discrete color palette

The following rule changes the Palette#colors property of default nominal color palette, pentaho.visual.color.palettes.nominalPrimary, in any application:

var ruleSpec = {
  select: {
    module: "pentaho.visual.color.palettes.nominalPrimary"
  },
  apply: {
    colors: [
      "red", "#00FF00", "rgb(0,0,255)"
    ]
  }
};

Change the colors used by a certain visualization

The following rule changes the default value of the “palette” property of the bar chart visualization, in any application, so that a specific ad hoc palette is used:

var ruleSpec = {
  select: {
    module: "pentaho/visual/models/Bar"
  },
  apply: {
    props: {
      palette: {
        defaultValue: {
          level: "nominal",
          colors: ["red", "#00FF00", "rgb(0,0,255)"]
        }
      }
    }
  }
};

If, instead, you want to use a registered palette:

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

Identifiers of Stock Visualizations

The models of stock visualizations are all sub-modules of the pentaho/visual/models module. For example, pentaho/visual/models/Line, is the identifier of the stock Line visualization model.

The corresponding CCC-based view of a stock visualization is a sub-module of the pentaho/ccc/visual module. For example, pentaho/ccc/visual/Line, is the identifier of the CCC view corresponding to the stock Line visualization model.

The Geo Map visualization is the exception to these rules. Its model’s identifier is pentaho/geo/visual/Model and its view’s identifier is pentaho/geo/visual/View.

Identifiers of Stock Color Palettes

All stock color palettes are sub-modules of the pentaho/visual/color/palettes module. For example, pentaho/visual/color/palettes/nominalPrimary, is the identifier of the default discrete color palette.