Skip to main content
Pentaho Documentation

Configuring a visualization

Parent article

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 examples on 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 Create a visualization.

Visualizations are comprised of a Model type and a IView type. You can configure both types. The Stock visualizations identifiers section contains the list of identifiers for stock model and view types. The Stock color palettes identifiers 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]};
});

Common model configurations

The following examples are for common model configurations.

  • Example: 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
      }
    };
  • Example: 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
          }
        }
      }
    };
  • Example: 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"
          }
        }
      }
    };
  • Example: 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.

Common 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.
  • Example: Increase 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
        }
      }
    };
  • Example: Change the font of axes labels in 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"
        }
      }
    };

Common color palette configurations

The following examples are for common color palette configurations.

  • Example: Change the colors of the default 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)"
        ]
      }
    };
  • Example: Change the colors in a specified 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)"]
            }
          }
        }
      }
    };
  • Example: Use a registered palette in a specified visualization

    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
            }
          }
        };
      }
    };