The Pentaho BI platform currently employs JFreeChart as its charting engine.
Component Name: ChartComponent
The ChartComponent is a BI component that can create a variety of charts including:
- bar charts
- line charts
- bar line combination charts
- pie charts
- multi-pie charts (also known as pie grids)
- area charts
- bubble charts.
Inputs
REQUIRED
chart-data
The dataset that you want the chart to render. Often, this is the output of a SQLLookupRule action, but can come from a number of source actions.
chart-attributes
The chart component expects several chart properties in order to render the proper chart and display your data appropriately. There are several ways to define chart attributes in an action sequence. You can specify the attributes in an input, as a resource, or in-line in the component definition section of the action sequence.
| Note | ||
|---|---|---|
| ||
While you can access the chart component through Design Studio's graphical UI, Design Studio does not provide a nice interface for defining all of your attributes yet, nor does it provide the appropriate UI for determining how and where you are going to specify your chart attributes (as an input or resource - Design Studio puts the chart attributes in the component definition by default). These enhancements will come (or you can contribute them!), but for now, you will need to use the XML editing tab of the action sequence to add your chart attributes. |
Chart Attributes as an Input
You can specify your chart attributes as a String input parameter. The caveat to this input is that the chart attributes need to be represented in the string in XML format, inside of a CDATA section.
The string input parameter to the chart component must be named chart-attributes.
Here is an example of specifying your chart attributes as an input string. You of course can also derive this string in a prior action, say, possibly a JavaScript rule.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<inputs>
<attributes type="string">
<sources>
<request>attributes</request>
</sources>
<default-value>
<![CDATA[
<chart-attributes>
<chart-type>BarChart</chart-type>
<border-visible>false</border-visible>
<is-clickable>false</is-clickable>
<include-legend>true</include-legend>
... more chart attributes here ...
</chart-attributes>
]]>
</default-value>
</attributes>
</inputs>
...
<action-definition>
<component-name>ChartComponent</component-name>
<action-type>Bar Chart</action-type>
<action-inputs>
<chart-data type="result-set" mapping="query_result"/>
*<chart-attributes type="string" mapping="attributes"/>*
</action-inputs>
...
|
Chart Attributes as a Resource
You can place the chart attribute XML in a file, then reference that file as a resource in your action sequence.
The resource reference name in the chart component must be chart-attributes. The XML in the file is the chart attribute XML you would find as an input or as a part of the component definition, starting with a root node of <chart-attributes>. Click here for an example of a file containing valid chart attribute XML.
The action sequence XML for this looks similar to below:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<resources>
<chart_resource>
<solution-file>
<location>testchart.xml</location>
<mime-type>text/xml</mime-type>
</solution-file>
</chart_resource>
</resources>
<actions>
...
<action-definition>
<component-name>ChartComponent</component-name>
<action-type>Bar Chart</action-type>
...
<action-resources>
<chart-attributes type="resource" mapping="chart_resource"/>
</action-resources>
...
|
Chart Attributes in the Component Definition
By default, the Design Studio will put the chart attributes XML node in the component definition. This in-line mode of describing the chart is fine, but can be problematic if you want to dynamically add or change a chart attribute in the process of your action sequence. Which is why we added the ability to define the chart attributes in a resource or input definition.
Chart attributes described in-line in the component definition look similar to this:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<action-definition>
<component-name>ChartComponent</component-name>
<action-type>Bar Line Chart</action-type>
...
<component-definition>
<chart-attributes>
<chart-type>BarLineChart</chart-type>
<border-visible>true</border-visible>
<include-legend>false</include-legend>
<is-3D>false</is-3D>
<markers-visible>false</markers-visible>
... more chart attributes here ...
</chart-attributes>
</component-definition>
</action-definition>
|
OPTIONAL
Chart Row Dimension -- Indicates the chart data is to be aggregated along the row dimensions.
Title -- The chart title.
Subtitle -- The chart subtitle.
Title Font Style -- The font style to be used with the title and subtitle.
Title Font Size -- The font point size to be used with the title and subtitle.
Border Color -- The color of the chart border.
Chart Width -- The chart width.
Chart Height -- The chart height.
Title Position - Describes the position of the chart title. Valid positions are TOP, BOTTOM, LEFT, and RIGHT.
Range Title - Optional node that describes the chart range (usually the y-axis).
Chart Background - The color or image to be used as the chart background. This replaces the background of the chart itself and NOT the plot area. So if you set the image here you will probably see your image under the axis labels and scales and not in the plot area.
Plot Background - The color or image to be used as the plot background. This replaces the background of the plot area only.
Orientation -- The chart orientation. This can be either "Horizontal", "Vertical". Defaults to "Vertical".
Is 3D - If true the charting engine does it best to render a 3-D view of the chart.
Is Stacked - If true the charting engine will create a stacked version of this chart type (if possible).
Color Pallette - Singleton that contains a list of colors that make up the series palette.
Outputs
The ChartComponent can return both the chart and its image map (if drill URLs are defined via the URLTemplate) several different ways. Here are the legitimate outputs you can specify, and what the result of each is:
- CHART_OUTPUT (<chart-output type="content"/>)
- Stores the chart in the content repository for use in a subsequent action or process, or displays if the output destination is response and the name is content.
- CHART_FILE_NAME_OUTPUT (<chart-filename type="string"/>)
- Returns the name of the chart file, including the file extension (with no path information) as a String.
- HTML_MAPPING_OUTPUT (<chart-mapping type="string"/>)
- Returns the name of the file that the map has been saved to, including the file extension (with no path information) as a String.
- HTML_MAPPING_HTML (<chart-map-html type="string"/>)
- Returns the chart image map HTML as a String.
- BASE_URL_OUTPUT (<base-url type="string"/>)
- Returns the web app's base URL (ie., http://localhost:8080/pentaho) as a String.
- HTML_IMG_TAG (<image-tag type="string"/>)
- Returns an HTML snippet including the image map, image (<IMG />) tag for the chart image with src, width, height and usemap attributes defined.
Example Action Sequence
The following action sequence uses the output from a SQL lookup rule ( a Relational data source) as the input for a ChartComponent. See the Chart Tag Reference for an explanation of the chart attributes.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<action-sequence>
<name>Chart.xaction</name>
<title>Default Title</title>
<version>1</version>
<logging-level>DEBUG</logging-level>
<documentation>
<author>William E. Seyler</author>
<description>Default Description</description>
<icon>JFree-quadrant-budget-hsql.png</icon>
<help>Help</help>
<result-type>rule</result-type>
</documentation>
<inputs>
<chart-type type="string">
<default-value>.png</default-value>
<sources>
<request>type</request>
</sources>
</chart-type>
</inputs>
<actions>
<action-definition>
<action-outputs>
<result-set type="list" />
</action-outputs>
<component-name>SQLLookupRule</component-name>
<action-type>rule</action-type>
<component-definition>
<source>sql</source>
<live>true</live>
<jndi>SampleData</jndi>
<query>
<![CDATA[select QUADRANT_ACTUALS.REGION, QUADRANT_ACTUALS.DEPARTMENT,
QUADRANT_ACTUALS.POSITIONTITLE, QUADRANT_ACTUALS.ACTUAL, QUADRANT_ACTUALS.BUDGET
from QUADRANT_ACTUALS order by QUADRANT_ACTUALS.REGION,QUADRANT_ACTUALS.DEPARTMENT]]>
</query>
</component-definition>
</action-definition>
<action-definition>
<action-inputs>
<output-type type="string" mapping="chart-type" />
<result-output type="file" />
<chart-data type="list" mapping="result-set" />
</action-inputs>
<action-outputs>
<chart-output type="string" />
<base-url type="string" />
</action-outputs>
<component-name>ChartComponent</component-name>
<action-type>report</action-type>
<component-definition>
<by-row>false</by-row>
<chart-attributes>
<chart-type>PieChart</chart-type>
<title>Actual vs Budget by Region</title>
<title-position>TOP</title-position>
<title-font>
<font-family>Serif</font-family>
<size>36</size>
<is-bold>false</is-bold>
<is-italic>false</is-italic>
</title-font>
<range-title>US Dollars</range-title>
<chart-background type="color">#FFFFFF</chart-background>
<plot-background type="color">#FF0000</plot-background>
<orientation>Horizontal</orientation>
<height>400</height>
<width>800</width>
<is-3D>true</is-3D>
<is-stacked>false</is-stacked>
<category-label-rotation>90</category-label-rotation>
<border-visible>false</border-visible>
<border-paint>#3399FF</border-paint>
<include-legend>true</include-legend>
</chart-attributes>
</component-definition>
</action-definition>
</actions>
</action-sequence>
|