Configuring a visualization

Last updated
Save as PDF

A visualization can be configured by third parties using rules in external configuration files. These configurations are merged with any default configuration included in the visualization. This article shows you how to create a configuration for your API visualization.

Before starting, you should have some basic knowledge about how to configure JavaScript modules on the Pentaho platform and what constitutes a visualization. If not, you should first read Creating a visualization.

Visualizations are comprised of a Model type and a IView type. You can configure both types. The Identifiers of stock visualizations section contains the list of identifiers for stock model and view types. The Identifiers of stock color palettes section contains the list of identifiers for stock color palettes.

The following sections show examples of typical model and view type configurations. A single IRule object is provided in each example, but it should be interpreted as part of a generic configuration ruleset module, as shown in the folllowing code:

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

Examples of typical model configurations

The following examples are for common 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 from Analyzer's visualizations menu, which prevents the user from creating new visualizations of this type:

varruleSpec = {
  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 to be 2 pixels for both the Line and the Column/Line Combo stock visualizations. This rule also hides it from Analyzer’s properties panel, preventing the user from changing its default value:

varruleSpec = {
  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 to be the diamond shape for both the Line and the Column/Line Combo stock visualizations:

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

Changing the menu name of a visualization

The following rule changes the label type attribute of the Bar stock visualization:

var ruleSpec = {
  select:{
    module:"pentaho/visual/models/Bar"
  },
  apply:{
    label:"Vertical Bars"
  }
};

NoteA best practice is to load localizable text from a resource bundle. See Localization API for more details.

Examples of typical view configurations

The views of stock visualizations are implemented using the CCC charting library. These views can be customized by specifying their set of extension points in an object of the extension configuration property.

NoteView configuration is typically tied to the technology with which views are built. You should consult the View documentation of your third-party visualuzation to find out about which configuration properties are supported.

Thicken the axes rules of stock visualizations

The following sample code illustrates the rule which changes the lineWidth property of the baseAxisRule_ and orthoAxisRule_ extension points for 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 sample code illustrates the rule which changes the font property of the baseAxisLabel_ and orthoAxisLabel_ extension points for 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

The following examples are for common color palette configurations.

Change the colors of the default discrete color palette

The following sample code illustrates the rule which changes the colors of the 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 sample codes illustrates the rule which changes the default value of the palette property of the stock 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)"]
        }
      }
    }
  }
};

The following sample code is for when 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 following table contains identifiers for stock visualizations in Analyzer:

Local Module ID	Description
`Abstract`	All stock visualizations
`AreaStacked`	Area Stacked
`Line`	Line
`Bar`	Column
`BarStacked`	Column Stacked
`BarNormalized`	Column Stacked 100%
`BarHorizontal`	Bar
`BarStackedHorizontal`	Bar Stacked
`BarNormalizedHorizontal`	Bar Stacked 100%
`BarLine`	Column/Line Combo
`Scatter`	X/Y Scatter
`Bubble`	Bubble
`HeatGrid`	Heat-Grid
`Pie`	Pie
`Donut`	Donut
`Sunburst`	Sunburst

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.

The following identifiers are for the stock color palettes of the local module:

nominalPrimary
nominalNeutral
nominalLight
nominalDark
quantitativeBlue3
quantitativeBlue5
quantitativeGray3
quantitativeGray5
divergentRyb3
divergentRyb5
divergentRyg3
divergentRyg5

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at docs.hitachivantara.com.