Chart Reference

Unknown macro: {scrollbar}

Overview

The Pentaho platform supports a number of different charts through two platform charting components, one that wraps the JFreeChart engine (ChartComponent) and one that wraps the Open Flash Charts engine (OpenFlashChartComponent).

Report Charts and Analysis Charts Do Not Follow This Reference!

There are 5 different places that you may specify a chart in your Pentaho solution. Only three of them follow this reference: dashboard charts, portal charts, and action sequence charts. To get details about /wiki/spaces/ServerDoc2x/pages/1498940829 or /wiki/spaces/ServerDoc2x/pages/1498940830, follow their respective links.

Pentaho charts deliver a different output depending on the type of solution you are building. For example, an action sequence chart can be delivered via an HTML snippet or image URL, with or without a drill-through map. Dashboard charts are streamed directly to HTML after being processed using a template and an XSL stylesheet.

The good news is that in the case of dashboarding, portal charts and action sequence charts, they all share a common definition language. The chart definition is described in XML, and instructs the chart engine on what kind of chart you want to build and what you want it to look like. In most cases, you save the chart definition XML to a file and reference that file in your solution (with some exceptions where the definition can be processed in-line). This reference documents the format of the chart definition XML file.

The Chart Data

In the simplest of charts, you can hand over a standard two dimensional dataset and the chart engine will do its best to plot the data you've given. However, there are several supported charts that have specific guidelines for the format and type of data they are expecting. The chart definition file does very little (in many cases, nothing at all) to ensure that the data you've passed is renderable by the type of chart you have specified. This leads to great frustration when you believe you have the chart definition correct, yet the chart doesn't render.

In the PentahoDoc:Supported Chart Types section of this reference, we've documented the type of dataset that each chart type is expecting. This should help alleviate some of the frustration associated with rendering some of the more advanced charts.

Bringing the Chart and Data Together

Invariably, each of our methods of rendering charts retrieve data input differently.

For action sequences, the chart data is built in a previous action step and handed to the chart action as an input parameter.

For dashboards and portlet charts, the chart definition supports the embedded <data> element, which allows the user to define necessary parameters to an action sequence that will generate the dataset, then hand it to the dashboard or portlet chart.

Here is an example of the <data> element:

<data>
	<!-- Specify the path to the action sequence that provides the data -->
	<data-solution>samples</data-solution>
	<data-path>charts/samplesDashboard</data-path>
	<data-action>timeserieschart_data.xaction</data-action>
	<!-- Specify the output of the action sequence that contains the data -->
	<data-output>results</data-output>
	<!-- Specify whether to get the chart series from the rows or columns -->
	<data-orientation>columns</data-orientation>
</data>

The Chart Definition

The <chart></chart> Element

Every chart definition starts with a top level chart element. For each property that you want to include in your chart, there is a corresponding XML element. These elements are nested inside the chart element.

"What About the Element??"

The <chart-attributes> element is supported as the root level node of action sequence charts, and by default, is the element that the Design Studio will generate (and expects) when building a chart definition in-line in an action sequence. This dual support is not carried over to dashboard or portal charts however.

The rule of thumb, until we have some deprecations and backward-compatability support, is to use the <chart> root element whenever you are defining your chart in an external file, and to leave the <chart-attributes> element in place in the action sequence.

Here is a first sample of a Pentaho chart definition. Don't worry too much about the individual elements just yet, they are described in more detail in the Chart Properties Reference.

<chart>

	<!-- This file defines the bar chart that shows the actual-to-budget variance for each department -->

	<!-- Define the chart type -->
	<chart-type>BarChart</chart-type>

	<!-- Specify the title of the chart -->
	<title>Headcount Variance</title>

	<!-- Specify the location of the title -->
	<title-position>top</title-position>

	<chart-background type="color">#FFFFFF</chart-background>
	<plot-background type="color">#EEEEEE</plot-background>

	<!-- Specify the orientation of the bars -->
	<orientation>vertical</orientation>

	<!-- Specify the 3D-ness of the bars -->
	<is-3D>false</is-3D>
	<max-bar-width>.01</max-bar-width>

	<!-- Specify if the bars are stacked -->
	<is-stacked>false</is-stacked>

</chart>

The <chart-type> Element

The one element that is required for all charts is the chart-type element. At the very least, you need to tell the chart engine what type of chart to build. The Chart Properties Reference lists the valid list of values for the chart-type element.

Below is a list of the charts that are currently supported. Follow the link to see what type of data each chart expects, and the elements that are required in order to build a specific type of chart.

BI Platform