The ChartBeans Chart Model
Overview
The ChartBeans 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.
Important Note Regarding Feature Set Support
It is important to understand that the feature set described by the chart model is a SUPERSET of all supported rendering chart engines. So not every attribute will be honored by every rendering engine. The Javadoc for the renderers are a great place to look for the supported subset for the engine you are attempting to use. Also, check out the chartEngine attribute, which allows you to quickly switch between renderers to test attribute support.
Generating a Chart Model XML Definition
A variety of full-featured chart model definitions are attached to this documentation. You may use these definitions as templates to get started on creating your own custom detailed charts, or use the #ChartBeans Model Generator Utility to create a model with the latest set of features.
You may also see these samples in action by running the action sequences in the BI Server samples under the folder bi-developers|chartbeans.
Sample Template Models
- bar chart
- line chart
- horizontal bar chart
- pie chart
- area chart
- dial chart (only JFreeChart renders a dial. No OpenFlashCharts dial rendering in open source.)
Once you have your model definition, you will want to refer to the ChartBeans chart model Javadoc, to investigate each attribute and decide which attributes to keep, modify or delete.
Key Attributes
While you can hunt through the Javadoc to read about the chart model, many of the elements and attributes of the model are named intuitively enough to deduce their meaning. Included here are some key attributes and their valid values that will speed your progress in getting the chart you are looking for.
Switching the Rendering Engine
At the start of this doc, we mentioned there are two renderer implementations for ChartBeans, JFreeChart and OpenFlashChart. You can easily switch between the two renderers using the chartEngine attribute of the chartModel element. This is convenient especially when you want to quickly (and visually) determine which attributes are supported by which renderer.
Element |
Attribute |
Description |
---|---|---|
chartModel |
chartEngine |
Valid values are: JFreeChart, OpenFlashChart.Optional |
If you do not specify the chartEngine attribute, the system default renderer is used reference doc explaining the default config in chartbeans_config.xml.
Disabling Themes
Themes is a feature that is currently under development. A theme is a preset, named set of attributes that can be applied to a chart by setting the theme attribute. For now, you will want to REMOVE the theme attribute from your generated chart definition, in order to have your palette color selections honored.
Element |
Attribute |
Description |
---|---|---|
chartModel |
theme |
Valid values are: Theme1, Theme2, Theme3, etc.*Optional |
ChartBeans Model Generator Utility
The ChartBeans model generator utility is packaged with the ChartBeans Java library (pentaho-chartbeans-x.x.x.jar). This library can be found in the WEB-INF/lib directory of the Pentaho BI Server.
The utility is a Java command line application that allows you to input any number of chart types, and will generate the full-featured XML chart definition for each type and output it to the console. Recognized string parameters for the chart types are:
- BAR
- HBAR (for horizontal bar)
- LINE
- PIE
- AREA
- DIAL
- SCATTER (not fully functional as of this writing)
The following example would generate chart model definitions for a bar, line and pie chart and output the models to the console:
java -cp .;xstream-1.3.1.jar;jettison-1.0.1.jar;pentaho-chartbeans-TRUNK-SNAPSHOT.jar org.pentaho.chart.model.util.GenChartDefinition BAR LINE PIE
Note that the following libraries need to be included on the Java classpath, and your classpath may look different from the example, depending on where you are trying to run the utility from:
- xstream-1.3.1.jar
- jettison-1.0.1.jar
- pentaho-chartbeans.x.x.x.jar (fromt he platform)
All of these libraries can be found in the WEB-INF/lib directory of the Pentaho BI Server.