Hitachi Vantara Pentaho Community Wiki
Child pages
  • Adding New Chart Styles
Skip to end of metadata
Go to start of metadata

The following documentation explains the process of adding new style-sheet styles to the charting API. It will work through one example of this process and some steps may be shortened since some of the classes mentioned will already be created.

Conventions

NOTE: This process will work for adding style sheet styles to anything that uses the libcss library for style processing.
NOTE: The charting package at the time of this writing is "org.pentaho.experimental.chart..." and this will change in the future.

Identify the Need for a New Style 

If possible, an existing style-sheet style (from w3c) should be used. However, if the name is not intuitive or the list of valid values does not match, it would be time to create a new style.

Charting Example

With line charts, we need to define the line style (solid, dashed, etc.) for the line on the chart. Since nothing similar could be found, we will need to create a new style.

Create a New Style Name

Since a new style is needed, a new style name will need to be created. By convention (and an easy way to avoid conflicting style names), the new style should start with -x- and have the format -x-{company}-{category}-{style-name} and all spaces should be replaced with dashes (-) .

Charting Example

For our example, we decided on the style name -x-pentaho-chart-line-style

Create an Initial Style Sheet

An initial style sheet defines all the "additional" styles (beyond the W3c standard) that will be used with a project. It also defines the default values for the new styles.
The format for the file is:

*{
  -x-company-category-style-name: default_value;
}

Charting Example

For our example, we created the file initial.css in the charting/src/org/pentaho/experimental/chart/css directory.

initial.css
/** Series Styles */
* {
  -x-pentaho-chart-line-style: solid;
}

Tell libcss About the Initial Style Sheet

libcss will need to know that it needs to load the new Initial Style Sheet that was created. This is accomplished by adding an entry in the libcss.properties file in the root directory of the source tree. The property name must start with org.pentaho.reporting.libraries.css.styles.initial. and the value will be the location of the Initial Style Sheet.

Charting Example

We created the file charting/src/libcss.properties and added the following lines:

libcss.properties
#
# Add the charting styles to the list of initial styles
#
org.pentaho.reporting.libraries.css.styles.initial.charting=res://org/pentaho/experimental/chart/css/initial.css

Create Defaults Style Values for XML Tags

While a top-level default has been established in the initial.css file, the default value for the styles can change for different XML tags. These defaults should be defined in another css file where the tag identifier is specified instead of using the asterisk wildcard (star) .

Charting Example

We created the file charting/src/org/pentaho/experimental/chart/css/chart.css which defines the default styles for all our XML tags (W3C standard tags and our own tags). We set the default line style to solid for the \<series\> tag with the following:

chart.css
series {
  -x-pentaho-chart-line-style: solid;
}

Create and Register the Style Keys

Internally, there needs to be a Java class which knows how to register the style keys. By convention, the style keys need to be constants created in a simple java class.

Charting Example

We created the class org.pentaho.experimental.chart.css.keys.ChartStyleKeys...

ChartStyleKeys.java
package org.pentaho.experimental.chart.css.keys;

import org.pentaho.reporting.libraries.css.model.StyleKey;
import org.pentaho.reporting.libraries.css.model.StyleKeyRegistry;

/**
 * Defines all the charting specific style keys
 */
public class ChartStyleKeys {
  /**
   * The line style for line charts (solid, dashed, etc.)
   */
  public static final StyleKey LINE_STYLE = StyleKeyRegistry.getRegistry().
      createKey("-x-pentaho-chart-line-style", false, true, StyleKey.All_ELEMENTS);
}

Create the Style Parser (a.k.a. Style Read Handler)

When the style information is read in, there needs to be a class which knows how to parse the style's value (or ignore it if the value is not valid). This is called a StyleReadHandler, and each style needs one. Since there are many different categories of styles (some represent colors, others have boolean information, and some have numeric values), there are plenty of existing read handlers in the org.pentaho.reporting.libraries.css.parser.stylehandler package from which we can derive a new read handler.

ChartStyleKeys

Since the style we are using supports a list of values, we extended the OneOfConstantsReadHandler and only had to provide the set of valid values.

LineStyleReadHandler
package org.pentaho.experimental.chart.css.parser.stylehandler;

import org.pentaho.reporting.libraries.css.parser.stylehandler.OneOfConstantsReadHandler;
import org.pentaho.experimental.chart.css.styles.ChartLineStyle;

/**
 * The style parser for the <code>-x-pentaho-chart-line-style</code> style.
 */
public class LineStyleReadHandler extends OneOfConstantsReadHandler {
  public LineStyleReadHandler() {
    super(false); // does not support the "auto" functionality
    addValue(ChartLineStyle.SOLID);
    addValue(ChartLineStyle.DASHED);
    addValue(ChartLineStyle.DOTTED);
    addValue(ChartLineStyle.DOT_DASH);
    addValue(ChartLineStyle.DOT_DOT_DASH);
  }
}

Create the Constants for the Style Read Handler

If the implementation of the Style Read Handler depends on the use of constants (as in the case of a set of defined values), a class should be created which holds those constant values. This can be done in a very simple Java class for simplicity.

We defined the constants in a class called ChartLineStyle (as seen in the code fragment above). This class contains the exact string we will accept as valid values for our style.

ChartLineStyle.java
package org.pentaho.experimental.chart.css.styles;
import org.pentaho.reporting.libraries.css.values.CSSConstant;

/**
 * Defines the only valid values for the -x-pentaho-chart-line-style style
 */
public class ChartLineStyle {
  public static final CSSConstant SOLID = new CSSConstant("solid");
  public static final CSSConstant DOTTED = new CSSConstant("dotted");
  public static final CSSConstant DASHED = new CSSConstant("dashed");
  public static final CSSConstant DOT_DASH = new CSSConstant("dot-dash");
  public static final CSSConstant DOT_DOT_DASH = new CSSConstant("dot-dot-dash");
}

Tell libcss About StyleKeys and StyleReadHandler

The last step is to again update the libcss.properties file to give the class name of the StyleKeys and the StyleReadHandler to the libcss parser.

  • The StyleKeys entry must begin with org.jfree.layouting.stylekeys.default. and list the name of the StyleKeys class
  • The StyleReadHandler entry must begin with org.jfree.layouting.parser.handlers., end with the name of the style, and list the name of the StyleReadHandler class.

    Again we edited the libcss.properties file and added the following entries:

    libcss.properties
    #
    # Add the charting style keys to the list of supported style keys
    #
    org.jfree.layouting.stylekeys.default.Chart=org.pentaho.experimental.chart.css.keys.ChartStyleKeys
    
    
    #
    # Style Parse Handlers for the Charting Styles
    #
    org.jfree.layouting.parser.handlers.-x-pentaho-chart-line-style=org.pentaho.experimental.chart.css.parser.stylehandler.LineStyleReadHandler
    

Test

The last step is to test the implementation and make sure the proper XML tag contains the new style information.