Developing Charts in Action Sequences (ChartBeans Model)

Overview

As of Pentaho BI Server 3.x, a new charting engine is used to generate charts for action sequences. This charting engine is commonly referred to as "Chartbeans" and is still under feature development. This engine is superior to the chart code lines used in past versions of the BI server because it supports the rendering of charts from any charting package that a developer implements the interfaces to.

As of this writing, there are two implementations: JFreeChart and OpenFlashCharts. The JFreeChart engine renders static images of charts, with an optional image map for hover tips and links. The OpenFlashCharts rendering engine uses Flash technology for a bit of animation and a more live effect.

Rationale

The following documentation does not explain how to write the XML required to render a chart with the new chart engine (the method required to create a chart in past implementations). This document describes a set of tools and documentation you can use to GENERATE the XML you need to add in your action sequence. The developers feel this should require a little more technical guidance, but a lot less pain than the previous mode of writing the XML for a chart definition by hand, from scratch.

The Action Sequence

An action sequence consists of a series of actions that result in output that the writer has asked for. In our context, the action sequence would require two steps:

1. Generate data that you want to plot on a chart.
2. Define and generate a chart using the data from the previous action.

There are several actions that can accomplish step 1. In the following example, a SQL Query will be used that executes against the Pentaho sample data to generate a dataset to give to the chart.

The action that you want to include to accomplish step 2, using the Chartbeans engine, is the ChartBeansComponent. A complete listing of the action sequence that you need is shown below.

<?xml version="1.0" encoding="UTF-8"?>

<action-sequence>

  <name>Simple Vertical Bar Example</name>
  <title>Chartbeans: Simple Bar Chart Example</title>
  <version>1</version>
  <logging-level>debug</logging-level>
  <documentation> 
    <author>Gretchen Moran</author>  
    <description/>  
    <help/>
  </documentation>

  <inputs/>

  <outputs>
    <outputstream type="string"> 
      <destinations> 
        <response>content</response> 
      </destinations> 
    </outputstream> 
  </outputs>

  <resources> 
    <bar> 
      <solution-file> 
        <location>chartbeans_barchart.xml</location>  
        <mime-type>text/xml</mime-type> 
      </solution-file> 
    </bar>  
  </resources> 

  <actions> 

    <action-definition> 
      <component-name>SQLLookupRule</component-name>
      <action-type>New Chart Data Query</action-type>
      <action-outputs> 
        <query-result type="result-set" mapping="new_result"/> 
      </action-outputs>
      <component-definition> 
        <jndi><![CDATA[SampleData]]></jndi>  
        <live><![CDATA[true]]></live>  
        <query>
                <![CDATA[SELECT PRODUCTS.PRODUCTLINE AS LINE,
		ORDERFACT.YEAR_ID AS "YEAR",
                SUM(ORDERFACT.TOTALPRICE) AS "PRICE"
                FROM
     		PRODUCTS INNER JOIN ORDERFACT ON PRODUCTS.PRODUCTCODE = ORDERFACT.PRODUCTCODE
     		INNER JOIN CUSTOMER_W_TER ON ORDERFACT.CUSTOMERNUMBER = CUSTOMER_W_TER.CUSTOMERNUMBER 
     		GROUP BY LINE, YEAR
     		ORDER BY 2 ASC]]>
        </query> 
      </component-definition> 
    </action-definition>

    
    <action-definition>
      <component-name>ChartBeansComponent</component-name>
      <action-inputs>
	  <value-column type="string"/> 
	  <category-column type="string"/> 
	  <series-column type="string"/> 
        <chartdata type="result-set" mapping="new_result"/>
      </action-inputs>
      <action-resources> 
        <chart-model-xml type="resource" mapping="bar"/>
      </action-resources>
      <action-outputs>
        <outputstream/>
      </action-outputs>
      <component-definition/> 
      <action-name>ChartBeans Vertical Bar Chart</action-name>  
      <logging-level>DEBUG</logging-level> 
    </action-definition>

  </actions> 
</action-sequence>

ChartBeansComponent

The ChartBeansComponent is a BI platform component that allows you to create a variety of chart types. The list of chart types supported by the ChartBeanComponent is shorter today than its predecessor chart rendering code, but will quickly meet and surpass the historic feature set. The charts supported today are:

• Bar charts (horizontal and vertical)
• Line charts (including scatter charts)
• Pie charts
• Area charts

Here we describe the bits that should be included in the action sequence, with a discussion of the chart model definition (and where that comes from!) directly following.

The basic action XML you need to use the ChartBeansComponent is as follows:

    <action-definition>
      
      <component-name>ChartBeansComponent</component-name>

      <action-inputs>
	  <value-column type="string"/> 
	  <category-column type="string"/> 
	  <series-column type="string"/> 
          <chartdata type="result-set" mapping="new_result"/>
      </action-inputs>

      <action-resources> 
          <chart-model-xml type="resource" mapping="bar"/>
      </action-resources>

      <action-outputs>
          <outputstream/>
      </action-outputs>

      <component-definition/> 

      <action-name>ChartBeans Vertical Bar Chart</action-name>  

    </action-definition>

Inputs

The attributes listed below are the data that the ChartBeansComponent will look for to render the chart. While these attributes are described as inputs to the component, they each can be defined within the component definition or resource section as well.

Resources

The best practice for creating a ChartBeansComponent action is to include the action and its immediate inputs in your action sequence, but to create a separate file for your chart model definition, and reference it from your action sequence. This eases editing, as the action sequence can get long, as well as promotes reuse of your chart model definition.

In this example, the chart-model-xml is located in a resource called"bar". That resource is described in the upper portion of action sequence:

  <resources> 
    <bar> 
      <solution-file> 
        <location>chartbeans_barchart.xml</location>  
        <mime-type>text/xml</mime-type> 
      </solution-file> 
    </bar>  
  </resources>

   ...

      <action-resources> 
        <chart-model-xml type="resource" mapping="bar"/>
      </action-resources>
 
   ... 

The file, chartbeans_barchart.xml, is located in the same directory as the action sequence. You can also use a relative path to find a file in a directory relative to the action sequence within the solutions directories.

Outputs, Component Definition, etc.

The rest of the action sequence is pretty standard. The outputstream is the only output that the component requires, and the definition can be left blank. Let's move on to where the details of the chart, the Chart Model, come from.

The ChartBeans Chart Model

The chart model describes all of the details of the chart. This includes colors, labels, value delimiters, fonts, borders, tip formats, etc. The Chartbeans engine understands XML definitions, and XML is what you will need to populate the chart model definition file that we referenced in the action sequence. Fortunately, this is not a completely manual process.

We provide static chart model samples and a utility that allows you to generate a full-featured chart model definition on the fly. Refer to the chart model documentation to learn more about this utility. Once generated, you can reference the Java chart model's Javadoc (org.pentaho.chart.model.ChartModel) to determine which attributes you want to keep, modify or delete to produce the chart that you want. Save this XML in the file resource referenced in your ChartBeansComponent definition file, and your action sequence should be complete.