Analyzer and the Visualization API
Pentaho Analyzer displays visualizations that are based on the Pentaho Visualization API.
Pentaho 8.3 ships with Visualization API 3.0 along with the previous 2.0 version. Analyzer supports visualizations of both API versions, allowing you to convert any custom visualizations made with Visualization API 2.0 to Visualization API 3.0 at your own pace. All stock visualizations, with the exception of the Geo Map, are available in Visualization API 3.0.
- New Pentaho installations are configured to use the stock visualizations for Visualization API 3.0
- Upgrade installations are configured to keep using the previous Visualization API 2.0 stock visualizations.
You can choose which stock visualizations Analyzer uses by configuring an Analyzer setting as described in Changing the API version of stock visualizations. This setting does not affect Analyzer reports that use a custom (non-stock) visualization. Your custom visualizations will continue to use their related API version.
Moving to Visualization API 3.0
Once you move to Visualization API 3.0 for stock visualizations, viewing a previously saved Analyzer report with a visualization from Visualization API 2.0 will change the way the visualization is displayed but not the saved report file. However, if you save it, it will be irreversibly upgraded to use the stock visualizations of Visualization API 3.0. If you later decide to switch back to using the stock visualizations of the previous Visualization API 2.0 in Analyzer, the visualization of your report will not be available. The report will display in the Pivot table view.
When you choose to try the stock visualizations of Visualization API 3.0:
- As a precaution, create a backup of your existing Analyzer reports.
- Ensure you are satisfied with the new experience by testing all of your existing Analyzer reports before saving.
Differences between the stock visualizations in Visualization API 2.0 and 3.0
The stock visualizations for Visualization API 3.0 are not completely identical to the corresponding visualizations in Visualization API 2.0. Consider the differences listed in each of these categories.
Usability and style
- Visualizations scroll horizontally and vertically when too many axis categories exist instead of shrinking to available space.
- Selection is either enabled or disabled, depending on whether gems are present in the Pivot “Column” gem bar. An intermediate selection state no longer exists where partial selections are possible when one gem was in the Pivot “Column” gem bar.
- General styling of visualizations now aligns across the Pentaho platform.
- Standard color palettes now align across the Pentaho platform.
Cautions
- Moving to 3.0, custom visualizations must be manually converted.
- Visualization configuration in 3.0 is a different process. Existing Analyzer visualization configurations must be migrated. See Migrate visualization settings.
- Custom translations for properties of stock visualizations may no longer work in 3.0.
Printing
- Printing of scrolled charts shrinks to fit while preserving their aspect-ratio.
- Printing only reflects custom configurations that are located in the Global Configuration File.
Changing the API version of stock visualizations
Procedure
Go to the Analyzer plugin folder, located at pentaho-server/pentaho-solutions/system/analyzer and open the settings.xml file.
Find the <viz-api-version> setting and change its value according to the following desired API version:
- To use Visualization API 2.0, set <viz-api-version> to 2.0, as
shown
below:
<viz-api-version>2.0</viz-api-version>
- To use Visualization API 3.0, set <viz-api-version> to 3.0, as
shown
below:
<viz-api-version>3.0</viz-api-version>
- To use Visualization API 2.0, set <viz-api-version> to 2.0, as
shown
below:
Save the file and restart the Pentaho Server.
Migrate visualization settings
Visualizations created in Visualization API 2.0 can be configured in Analyzer. You will need to update the analyzer.properties file located in the pentaho-server/pentaho-solutions/system/analyzer directory.
Visualizations created in Visualization API 3.0 are configured using the platform-wide JavaScript configuration system.
You must migrate the following Analyzer visualization settings in Visualizatio API 2.0 work with Visualization API 3.0:
The default value of the Line width property in Line chart visualizations.
The maximum number of results possible in the Bar chart visualizations.
The default discrete color palette.
To perform this migration, you need to know the API version correspondence between visualization identifiers and property values.
General visualization property example
The following example changes the default value of the Line width property in Line chart visualizations.
Visualization API 2.0
in analyzer.properties,
viz.ccc_line.args.lineWidth=1
Visualization API 3.0
in a platform configuration file,
define(function(){ return[ { select:{ application:"pentaho/analyzer", module:"pentaho/visual/models/Line" }, apply:{ props:{ "lineWidth":{defaultValue:1} } } } ]; });
The Maximum Values property example
The following example changes the maximum number of results possible in the Bar chart visualizations.
Visualization API 2.0
in analyzer.properties,
viz.ccc_bar.maxValues=250,500,1000,5000
Visualization API 3.0
in a platform configuration file,
define(function(){ return[ { select:{ application:"pentaho/analyzer", module:"pentaho/visual/models/BarHorizontal", annotation:"pentaho/analyzer/visual/Options" }, apply: {maxValues:[250,500,1000,5000] } } ]; });
The Chart Series Colors property example
The following example changes the default discrete color palette.
Visualization API 2.0
in
analyzer.properties
,chart.series.colors=#0045a1,#5f9e00,#ffc20f,#ff6600,#3c008f
Visualization API 3.0
in a platform configuration file,
define(function(){ return[ { select:{ application:"pentaho/analyzer", module:"pentaho/visual/color/palettes/nominalPrimary" }, apply:{ colors:[ "#0045a1","#5f9e00","#ffc20f","#ff6600","#3c008f" ] } } ]; });
Correspondence between visualization identifiers
The following table contains differences between the visualization identifiers of Visualization API 2.0 as compared to the identifiers in Visualization API 3.0:
Visualization ID in API 2.0 | Visualization ID in API 3.0 | Description |
ccc_area | pentaho/visual/models/AreaStacked | Area Stacked |
ccc_line | pentaho/visual/models/Line | Line |
ccc_bar | pentaho/visual/models/Bar | Column |
ccc_barstacked | pentaho/visual/models/BarStacked | Column Stacked |
ccc_barnormalized | pentaho/visual/models/BarNormalized | Column Stacked 100% |
ccc_horzbar | pentaho/visual/models/BarHorizontal | Bar |
ccc_horzbarstacked | pentaho/visual/models/BarStackedHorizontal | Bar Stacked |
ccc_horzbarnormalized | pentaho/visual/models/BarNormalizedHorizontal | Bar Stacked 100% |
ccc_barline | pentaho/visual/models/BarLine | Column/Line Combo |
ccc_scatter | pentaho/visual/models/Bubble | X/Y Scatter/Bubble |
ccc_heatgrid | pentaho/visual/models/HeatGrid | Heat-Grid |
ccc_pie | pentaho/visual/models/Pie | Pie |
ccc_sunburst | pentaho/visual/models/Sunburst | Sunburst |
Correspondence between visualization property values
The following table contains differences between the visualization property values of Visualization API 2.0 as compared to the property avlues in Visualization API 3.0:
Property name | Example value in API 2.0 | Example value in API 3.0 |
labelsOption | inside_end | "insideEnd" |
inside_base | "insideBase" | |
outside_end | "outsideEnd" | |
pattern | ryg_3 | "ryg-3" |
ryg_5 | "ryg-5" | |
blue_3 | "blue-3" | |
blue_5 | "blue-5" | |
lineWidth | In both 2.0 and 3.0, the number in the properties file passes verbatim to a JSON number value. | |
trendLineWidth | ||
emptySlicesHidden | In both 2.0
and 3.0, the value of true or
false in the properties file passes verbatim to a JSON boolean
value. | |
reverseColors | ||
colorSet | In both 2.0
and 3.0, textual values in the properties file are wrapped in
quotation marks to form a JSON string value. For example, circle
becomes "circle" . | |
lineLabelsOption | ||
shape | ||
sliceOrder | ||
trendName | ||
trendType |