Chart

Overview

The Chart component is used to present data in a graphical form enabling the user to see trends, make comparisons, or view percentage of the whole. The component represents the entire chart area, including the chart graph and all pertinent elements (title, legend, background). The Chart component is based on the JFreeChart engine and exposes a friendly API with JSF-specific features and enhancements.


API Reference | Tag Reference
Online Demo

Key Features

Quick Start

There is support for the three chart types in OpenFaces library: pie, bar, and line charts. Let's start creating a pie chart using a simple example. Then, we will improve it step-by-step.

Step 1

Add the <o:chart> tag to where you want to place the chart on the JSP page. To specify the chart type, use the view attribute. In this example the "pie" value for the view attribute is used. This example also works if specify the "line" or "bar" value (for more details please see the section Specifying Chart Types).

<o:chart model="#{PopulationBean.population}" view="pie"
         titleText="Largest Cities of the European Union by Population" />

In the backing bean, specify the method that will provide data for the chart. The data for the chart is provided in the backing bean as shown in the example below:

public ChartModel getPopulation() {

    Map data = new HashMap();
    data.put("London, United Kingdom", new Integer(7615000));
    data.put("Berlin, Germany", new Integer(3396990));
    data.put("Madrid, Spain", new Integer(3155359));
    data.put("Rome, Italy", new Integer(2542003));
    data.put("Paris, France", new Integer(2142800));

    PlainSeries series = new PlainSeries();
    series.setData(data);
    series.setKey("Largest cities of the European Union");

    PlainModel model = new PlainModel();
    model.addSeries(series);
    return model;
  }

As a result, you will see the following pie chart on your page:

In this example, the background color, font and color of labels will be rendered based on the default values provided by the Chart component.

Step 2

An alternative way to specify the same chart is by using the <o:pieChartView> tag instead of the view attribute of the <o:chart> tag. It gives you the ability to customize the chart type in many ways. For example, you can hide percentage labels or apply specific style attributes to the plot area. For more information about the chart areas and their styling, see the section Customizing Chart Elements.

Now let's change the way the chart type is declared. Instead of the view attribute, we will use a specific <o:pieChartView> tag. Unless we provide any additional information, the output will be the same as in the previous example. However, in this case, you will be given more options to change the chart display.

<o:chart model="#{PopulationBean.population}"
         titleText="#{PopulationBean.title}">
  <o:pieChartView />
</o:chart>

If necessary, you can turn off the visibility of slice labels and display this information as a tooltip for each slice.

<o:chart model="#{PopulationBean.population}"
         titleText="#{PopulationBean.title}">
  <o:pieChartView labelsVisible="false"
              tooltip="#{sector.key} - #{sector.value}" />
</o:chart>

The sector variable is a request-scope variable which is provided by the engine and accesses each pie slice one after another when it is requested. This means that for different pie slices, the tooltip value will be calculated separately. In our example, the following tooltip values will be shown:
1) London, United Kingdom - 7615000
2) Berlin, Germany" - 3396990
3) Madrid, Spain - 3155359
4) Rome, Italy - 2542003
5) Paris, France - 2142800

If you want to specify a different function for calculating tooltip values, you can use the standard JSF expression language or a method specified in the backing bean. For example:

public String getTooltip(){
    PieSectorInfo sector = Faces.var("sector", PieSectorInfo.class);
    DecimalFormat format = new DecimalFormat("#,###");
    return (String)sector.getKey() + " - " + format.format(sector.getValue());
}

In this case, the tooltip values will be shown in the following formatted way:
1) London, United Kingdom - 7,615,000
2) Berlin, Germany - 3,396,990
3) Madrid, Spain - 3,155,359
4) Rome, Italy - 2,542,003
5) Paris, France - 2,142,800

To know whether an attribute is calculated dynamically, like a tooltip, or its value is the same for all pie slices (i.e. labelsVisible is a common attribute for all the slices), see the section Pie Slices.

Creating a Chart

To add the Chart component to a page, use the <o:chart> tag. There are two basic things that essentially affect the final chart visualization: a data model and a chart type. The data model is a dataset that is used for processing and displaying in the chart (see the section below). The Chart component provides three chart types for plotting data: pie, bar, line (see the section Specifying Chart Types).

Specifying a Data Model

To specify a data model for a chart, use the model attribute of the <o:chart> tag. This attribute should be specified as a value-binding expression that references a org.openfaces.component.chart.ChartModel instance.

The data model represents a set of the org.openfaces.component.chart.Series instances and their series IDs. The series ID is used as the description of a single data series and also serves to sort series in the order they will be displayed in the legend. By default, they are shown as a legend in a chart. Each series represents a set of org.openfaces.component.chart.Tuple instances that is sorted by the key (a key is plotted in the key axis). Every tuple is a pair of key and value.

Specifying Chart Types

There are three chart types supported by the Chart component: pie, bar, and line charts. The easiest way to specify a chart type is through the view attribute of <o:chart> tag. In this case, the default properties that are available for a specific chart type will be used for rendering this chart, and you will not be able to customize it. The view attribute can take values of "pie", "line", "bar" for a corresponding chart type.

If you want to have more fine-grained control over chart customization, use specific chart type tags: <o:pieChartView>, <o:lineChartView>, <o:barChartView>. There is no difference in specifying a model for each chart type. Note, however, that you can use a pie chart for only one data series.

No matter whether you use the view attribute or specific chart type tags, the data will be treated in the same way.

Line and bar charts can be vertically or horizontally oriented. To specify the orientation, set the orientation attribute to "vertical" (default) or "horizontal".

The following example demonstrates the one of the ways to specify a chart type:

<o:chart model="#{PopulationBean.population}" view="pie"/>

The data for the chart is provided in the backing bean as shown in the example below:

public ChartModel getPopulation() {

    Map data = new HashMap();
    data.put("London, United Kingdom", new Integer(7615000));
    data.put("Berlin, Germany", new Integer(3396990));
    data.put("Madrid, Spain", new Integer(3155359));
    data.put("Rome, Italy", new Integer(2542003));
    data.put("Paris, France", new Integer(2142800));

    PlainSeries series = new PlainSeries();
    series.setData(data);
    series.setKey("Largest cities of the European Union");

    PlainModel model = new PlainModel();
    model.addSeries(series);
    return model;
  }

Request-Scope Variables

When customizing the Chart component, you can use request-scope variables that reference a particular slice or data point. There are two such variables:

  • point - References a data point of a line or bar chart. This variable has the org.openfaces.component.chart.view.GridPointInfo type.
  • sector - References a slice of a pie chart. This variable has the org.openfaces.component.chart.view.PieSectorInfo type.

The point variable has the following properties:

  • series - The data series the data point belongs to.
  • key - The key of the data point.
  • value - The value of the data point.

The sector variable has the following properties:

  • series - The data series the slice belongs to.
  • key - The key of the slice.
  • value - The value of the slice.
  • proportionalValue - The percentage of the slice's value relative to the entire data series' value.
  • seriesTotal - The total value of the entire data series.
  • index - The number of the slice in the data series.

Moreover, the sector.series and point.series objects have the following properties:

  • key - the description of the series.

Customizing Chart Elements

The major output of the Chart component is a graph which is rendered on the server side and then is embedded in the page within a standard HTML <img> tag. The graph represents an entire chart area which includes the following:

  • Plot area (for the line and bar charts only)
  • Slices and data point label areas (for a pie chart only)
  • Chart legend area
  • Chart title area

The plot area is an area bound by the chart axes with all data series. A pie chart doesn't have axes.

Chart Areas

Each chart area can be styled separately, but if no explicitly defined style for a certain area is provided, its parent style will be used. A standard CSS-like style definition is used for setting a visual property for the chart elements. Also, the CSS principle is applied, i.e. if you specify style="background: red;" for the chart area and do not use any style definition for the plot area which is nested in the chart area, style="background: red;" will be used for the plot area too.

The same principle applies to the standard HTML document. If you provide a set of nested <div> elements and style properties are provided for an outer <div> , an inner <div> element will be rendered following the rules of the outer <div>. So, for a better understanding of the chart area styling, you can interpret these areas as a set of nested HTML block elements like <div> or <span>.

Note
As the Chart component generates the chart image on the server side, it's possible to use only the style attributes (or the textStyle attribute for the <o:chart> tag). Use of styleClass attributes for specifying CSS class names is not allowed. CSS styles and classes defined for the entire page and other HTML elements on the page do not affect the chart area. The cascading rules are applied starting with the chart area.

The following CSS properties are supported:

Name Example Variations Description
background backgound: #ff0000; background-color: #ff0000; The color used to draw the background of the area for which it is defined.
border border: 1px solid #0000ff;   The color used to draw the border of the area for which it is defined. If this property is used for a line style, it describes the visual property of the line.
color color: #0000ff;   The color used for the text within the area.
margin margin: 5px 5px 5px 5px;   The margin of the area.

If you use other CSS properties, no error will occur but they will take no effect.

By default, the Chart component has the width and height equal to 400px. To change them, use the width and height attributes. You can also define these attributes as value-binding expressions that reference int values.

Chart Axes

You can specify which axes are shown on the chart with the showAxes attribute of the <o:lineChartView> and <o:barChartView> tags. The pieChartView component cannot have axes. The showAxes attribute can take the following values:

  • "key" - only the "key" axis is shown.
  • "value" - only the "value" axis is shown.
  • "both" (default) - both axes are shown.
  • "none" - there is no any axis on the chart.

If you specify axes with the showAxes attribute, the axes will have default look-and-feel. If you need more customization options, you can use the following tags:

  • <o:chartAxis> - a chart axis of any type.
  • <o:numberAxis> - an axis with numeric values or keys.
  • <o:dateAxis> - an axis with date values or keys.
  • <o:categoryAxis> - an axis for a chart with discrete data.

These tags should be nested within a particular chart type component: lineChartView and barChartView.

You can specify both axes with the same parameters or customize each axis separately. The domain attribute lets you specify to which axes the values of the attributes specified in the axes tags are actually applied. The attribute can take the following values:

  • "both" (default) - attribute values are applied for both axes.
  • "value" - attribute values are applied for the "value" axis only.
  • "key" - attribute values are applied for the "key" axis only.

For the <o:numberAxis> and <o:dateAxis> tags, you can specify the minimum and maximum scale values on the axis by using the lowerBound and upperBound attributes. These attributes should be used if you need that axes are displayed in the same way, independent of data.

In the following example, you can see NumberAxis and CategoryAxis specified and a style applied to both axes:

<o:chart width="350" height="300"
                 model="#{AverageTemp}">
  <o:barChartView binding="#{ChartDemo.barView}">
    <o:categoryAxis domain="key" position="up_45"/>
    <o:numberAxis domain="value" lowerBound="-30" upperBound="45"/>
    <o:chartAxis domain="all" style="color:#4747B3"/>
  </o:barChartView>
  <o:chartTitle text="Average Temperature During the Year"/>
</o:chart>

Pie Slices

One of the slices in a pie chart can be pulled out on a mouse click or according to some condition. The <o:pieSectorProperties> tag is used to apply a style to pie slices and specify whether or not a pie slice is pulled out upon a mouse click. This tag should be placed inside the pieChartView component.

The condition according to which a style is applied to pie sector and pie sector is pulled out is specified in the condition attribute. This attribute should be specified as value-binding expression. When you define the condition attribute, you can use request-scope variables that are described in the appropriate section.

A pie slice that meets the condition specified in the condition attribute can be pulled out. You can specify whether or not a pie sector that meets the condition is pulled out by using the pulled attribute. It defines the distance at which this sector is moved away from the center of the pie. To indicate how far from the center a pie slice should be pulled out, set the pulled attribute to a float-pointing value from "0" to "1", as a percentage of the radius. Setting a value greater than 1 will move the pie slice outside the chart graph.

The following example shows the usage of the <o:pieSectorProperties> tag:

<o:chart width="500" height="300"
               model="#{ChartView.pieChartModel}">
  <o:pieChartView binding="#{ChartView.pieView}">
     <o:pieSectorProperties condition="#{ChartView.selectedSector || ChartView.defaultSector}"
                           pulled="0.1f">
      </o:pieSectorProperties>
   </o:pieChartView>
   <o:chartTitle text="Total Income"/>
</o:chart>

Lines

Lines in a line chart can be customized by declaring the <o:lineProperties> tag. This tag should be defined as a child for <o:lineChartView> tag.

The condition according to which the properties from the <o:lineProperties> tag are applied can be specified by using the condition attribute. This attribute should be specified as a value-binding expression. When you define the condition attribute, you can use request-scope variables that are described in the appropriate section.

The data series that meets the condition can be hidden on a chart. You can specify whether or not to show the series using the hideSeries boolean attribute. By default, it is "false".

You can also specify whether or not to show the legend for the lines of the data series that meet the condition by using the showInLegend attribute. By default, it is set to "true". The shapesVisible attribute specifies whether or not data markers on the lines of data series that meets the condition are visible. By default, it is set to "true".

You can also specify whether or not to show data markers on the line chart for all visible data series by using the shapesVisible attribute. By default, it is set to "true".

The following example shows the usage of the <o:lineProperties> tag:

<o:chart width="500" height="400"
           model="#{WeatherData}">
  <o:lineChartView shapesVisible="true"
                 binding="#{TestView.lineView}">
    <o:lineProperties condition="#{point.series.key=='Ukraine'}"
                          shapesVisible="true"
                          showInLegend="true"
                          style="border:none;">
    </o:lineProperties>
  </o:lineChartView>
  <o:chartTitle text="Temperature Distribution During a Year for #{TestView.pieInfo.key}"/>
</o:chart>

Gridlines

Gridlines for a line and bar chart can be customized with the <o:chartGridLines> tag which you should place inside <o:lineChartView> or <o:barChartView>. To specify whether the gridlines are visible or not, use the visible attribute. By default, it is "true".

You can customize both vertical and horizontal gridlines at the same time or separately. The domain attribute specifies to which gridlines a style is applied. This attribute can take the "key", "value" and "both" values. By default, the domain attribute is set to "both".

A style for the gridlines can be applied by setting the style attribute of the <o:chartGridLines> tag.

Data Series

By default, data series use default colors of the JFreeChart component. You can apply custom colors to the data series with the colors attribute, by specifying a comma-separated list of colors. The colors attribute can be specified for all chart types supported by the Chart component: <o:pieChartView>, <o:lineChartView>, and <o:barChartView>.

For a line and bar chart, colors will be applied in the order the data series are defined in the backing bean. For a pie chart, colors are applied clockwise.

Note
Colors for data series and pie slices can be specified only as RGB values.

The following example shows a pie chart with custom colors for each slice:

<o:chart model="#{PopulationBean.population}"
         titleText="#{PopulationBean.title}">
  <o:pieChartView colors="#3E8EB3, #5ACAFF, #B3773E, #FFC559" />
</o:chart>

Labels

To identify data plotted in the chart, the Chart component provides the following labels:

  • Data labels displayed next to data points of the data series (in the line and bar charts).
  • Callouts, or percentage labels, that point to the slices of a pie chart.
  • Axis title that identify each axis on the line or bar charts.
  • Tick-mark labels that identify values on the axis on the line or bar charts.

You can specify whether or not to show labels with the labelsVisible boolean attribute of a corresponding chart type: <o:lineChartView>, <o:barChartView>, or <o:pieChartView>. By default, data labels are hidden. To apply a style to data labels, nest the <o:chartLabels> tag within a required chart type.

To specify whether to show axis titles, use the labelVisible attribute of any axis type: <o:chartAxis>, <o:numberAxis>, <o:dateAxis>, <o:categoryAxis>. By default, it is set to "true". Text for the axis titles can be set with the keyAxisLabel and valueAxisLabel attributes of the <o:lineChartView> or <o:barChartView> tags. For more information about the axes, read the section Chart Axes.

Tick marks on the axes can be specified with the ticksVisible and ticksLabelsVisible boolean attributes of a specific axis type. The ticksVisible attribute defines whether to show ticks on the axis, and the ticksLabelsVisible attribute is responsible for displaying tick-mark labels. By default, both attributes are set to "true". A style for the ticks can be specified with the <o:chartAxisTicks> tag that should be defined as a child of <o:barChartView> and <o:lineChartView> chart types.

If your chart has a time-scale axis, you can specify the date format of tick-mark labels by using the dateFormat attribute of the <o:dateAxis> tag. The dateFormat attribute should be bound to an java.text.DateFormat instance.

The following example shows all the chart labels specified:

<o:chart model="#{PopulationBean.population}"
         titleText="#{PopulationBean.title}">
  <o:lineChartView labelsVisible="true"
               keyAxisLabel="Cities"
               valueAxisLabel="Population">
    <o:chartLabels style="color:gray; font-size: 8pt;"/>
    <o:chartAxis labelsVisible="true"
                 ticksVisible="true"
                 ticksLabelsVisible="true"/>
  </o:lineChartView>
</o:chart>

You can change the way axis labels are aligned and rotated by using the position attribute of the <o:categoryAxis> tag. The attribute can take the following values:

  • "standard" (default) - Data labels are aligned horizontally.
  • "up_90" - Data labels are rotated bottom-up by 90 degrees.
  • "up_45" - Data labels are rotated bottom-up by 45 degrees.
  • "down_90" - Data labels are rotated top-to-bottom by 90 degrees.
  • "down_45" - Data labels are rotated top-to-bottom by 45 degrees.

Legend

You can specify whether or not to show the chart legend by setting the legendVisible attribute of the Chart component. By default, it is set to "true".

To apply a style to the legend and specify its position, use the <o:chartLegend> tag. The legend position relative to the chart is specified by setting the position attribute to one of the following values: top, bottom (default), left, and right.

Chart Title

The chart title is specified by setting the text in the title attribute of the Chart component. If you want to customize the chart title, use the text attribute of the <o:chartTitle> tag.

There are also the tooltip, url, action, and actionListener attributes which you can use for making the chart title respond to user actions (for more details, see the section Chart ToolTips).

Chart ToolTips

Certain chart elements can respond to user actions. For example, when the mouse pointer is placed over a specific chart element, a tooltip can appear. To specify text for the tooltip, use the tooltip attribute. It can be also specified as a value-binding expression.

The user can be redirected after clicking on a specific chart element. To specify the destination URL, use the url attribute. The action and actionListener attributes are similar to the corresponding attributes of the HTMLCommandButton component, i.e. are specified as a method-binding.

Almost all chart elements have the tooltip, url, action, actionListener attributes. You can specify them for the <o:pieChartView>, <o:lineChartView>, <o:barChartView>, <o:chartTitle> tags.

The following example shows the usage of all these attributes:

<o:chart model="#{PopulationBean.population}"
         titleText="#{PopulationBean.title}">
  <o:pieChartView tooltip="#{sector.key}"
              action="#{TestView.onSectorClickAction}"
              actionListener="#{TestView.onSectorClickActionListener}"
              url="detailInfo.jsp"/>
</o:chart>

Specifying Transparency

You can specify transparency for the plot area or pie graph with the foregroundAlpha attribute of the <o:lineChartView> , <o:barChartView> or <o:pieChartView> tag. Transparency should be specified as a percentage, from "0" to "1". The default value is "1".

Displaying a Message for Empty Data

If there is no data to be plotted in a chart, the Chart component is not displayed. You can specify message text to be displayed in place of the chart using the text attribute of the <o:chartNoDataMessage> tag. To apply a style to the text, use the style attribute. The <o:chartNoDataMessage> tag should be placed inside any chart type: pieChartView, barChartView, lineChartView.

Client-side Events

You can specify onclick, onmouseover and onmouseout client-side events for the plot areas for each chart type:<o:pieChartView>, <o:lineChartView> and <o:barChartView>.

Known Issues

  • The Chart component do not work on Jetspeed-2 Enterprise Portal server.
OpenFaces