Adding New Chart Styles

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.

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.

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 (-) .

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;
}

/** 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.

#
# 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 .

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.

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.

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.

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.