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.

3D Mode Support

3D mode in charts can be enabled or disabled using the enable3D attribute of a corresponding chart view tag. This attribute can be specified as a boolean literal, or a value binding expression that points to a property of type boolean.

<o:chart model="#{PopulationBean.population}">
    <o:barChartView enable3D="true"/>
</o:chart>

In bar charts and line charts, it is also possible to customize the color of left and bottom "walls" that are displayed in 3D mode for these charts. It can be done using the wallColor attribute of <o:barChartView> and <o:lineChartView> tags. The wallColor attribute can be specified as a literal color value such as "red", "green", or "#8040ff", or as a value binding expression that points to a property of type java.awt.Color.

<o:chart model="#{PopulationBean.population}">
    <o:lineChartView enable3D="true" wallColor="dimgray"/>
</o:chart>

Chart Background and Title Background

It is possible to customize the backgrounds of the chart itself and its title. This can be done using the backgroundPaint and titlePaint attributes of chart view tags. Both of these attributes can be specified as a literal color value such as "red", "green", or "#8040ff", or as a value binding expression that points to a property of type java.awt.Paint.

<o:chart model="#{PopulationBean.population}">
      <o:chartTitle text="Chart Title" style="font-size: 14px; color: black;"/>
      <o:barChartView backgroundPaint="#{PopulationBean.backgroundGradientPaint}"
                      titlePaint="green">
      </o:barChartView>
</o:chart>

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>

Customizing Bar Chart Appearance

Using the showGradient attribute of the <o:barChartView> tag, it is possible to turn on or off painting bars' content with gradient fill. The showGradient attribute can be set to "true", "false" or defined as a value binding expression that points to a property of type boolean.

<o:chart model="#{ChartView.barChartModel}}">
  <o:barChartView showGradient="false">
  </o:barChartView>
</o:chart>

In addition, it is possible to customize the parameters used to display the bar's gradient. These parameters allow customizing how the "shiny" part of the bar gradient is displayed. It can be done using three attributes of <o:barChartView> tag: g1WhitePosition, g2FullIntensityPosition, g3LightIntensityPosition. These attributes should be specified as numbers in range [0..1], which correspond to the position of the appropriate gradient portion within a bar.

Here's a more detailed description of how these attributes are processed. Let's consider a chart with vertical bars. The background for each of the bars is in fact always painted with several adjacent gradients, and it's possible to customize the size of each gradient. Positions within a bar are specified as double numbers in range [0..1], where 0 corresponds to the left bar's edge and 1 corresponds to the right bar's edge. The colors for gradients are derived from the current series' color, referred to as main color below. Here's a list of gradients from left to right with their positions:

  • a gradient from the main color to white, which spans from 0 to g1WhitePosition;
  • a gradient from white to the main color, which spans from g1WhitePosition to g2FullIntensityPosition;
  • a gradient from the main color to a lightened main color, which spans from g2FullIntensityPosition to g3LightIntensityPosition;
  • a gradient from the lightened main color to the main color, which spans from g3LightIntensityPosition to 1.

Here's an example of customizing these gradient parameters:

<o:chart model="#{ChartView.barChartModel}">
    <o:barChartView showGradient="true"
                    g1WhitePosition="0.01"
                    g2FullIntensityPosition="0.05"
                    g3LightIntensityPosition="0.85">
    </o:barChartView>
</o:chart>

Lines

Lines in a line chart can be customized using the defaultLineStyle or lineStyles attribute of the <o:lineChartView> tag. The defaultLineStyle attribute can be specified with a simple CSS-like declaration, such as "3px dotted green", or using a value biding expression that points to a property of type org.openfaces.component.chart.LineStyle , which allows specifying an arbitrary line pattern using the java.awt.BasicStroke class (or other java.awt.Stroke implementation), which is the standard way of specifying line styles in Java2D. See the BasicStroke JavaDoc}} for instructions on constructing its instances.

The lineStyles attribute can be specified as a value binding expression that points to a property that represents a collection of org.openfaces.component.chart.LineStyle type. This attribute can be used instead of the defaultLineStyle if a chart displays multiple series and you'd like to specify different line styles for each of the series. The usage of the lineStyles attribute will override the settings defined in defaultLineStyle attribute.

Also, 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>

Shapes Fill and Outline Customization

It is possible to customize fill and outline styles of shapes used to represent chart items in line charts. Shape outline style can be customized using defaultOutlineStyle or outlines attributes of <o:lineChartView> tag, if you'd like to specify outline styles for multiple series. Similar to the line style customization the defaultOutlineStyle attribute can be specified with a simple CSS-like line style declaration, like "3px dotted green", or using the value biding expression that points to the property of type org.openfaces.component.chart.LineStyle class, which allows a more flexible line style customization because of using any java.awt.BasicStroke (or other java.awt.Stroke) implementation, which is the standard way of specifying line styles in Java2D.

The outlines attribute can be specified with a value binding expression that points to a property that represents a collection of org.openfaces.component.chart.LineStyle type. The usage of the outlines attribute will override the settings defined in defaultOutlineStyle attribute.

Shape fill paint can be customized using defaultFillColor, or fillPaints attributes in case of customizing multiple series, of <o:lineChartView> tag. The defaultFillColor attribute can be specified with an in-place color literal, like "green", "red", or "#8040ff", or as a value biding expression that points to a property of type java.awt.Paint.

The fillPaints attribute can be specified as a value binding expression that points to a property that represents a collection of java.awt.Paint instances. The usage the fillPaints attribute will override the settings defined in defaultFillColor attribute.

Line Area Fill

Line charts has an advanced customization that enables an ability to fill the area below the line with a gradient or a flat color. This functionality can be enabled by adding either <o:gradientLineAreaFill> or <o:solidLineAreaFill> tag as a child of <o:lineChartView> tag.

The <o:gradientLineAreaFill> tag is used to fill the area with a gradient from current line's color to the chart's background color.

It is possible to customize the level of transparency of both sides of a gradient using the maxValueTransparency and minValueTransparency attributes.

The <o:solidLineAreaFill> tag can be used as an alternative to <o:gradientLineAreaFill> in order to fill the area with current line's color. It is also possible to customize the transparency of the color using the transparency attribute of <o:solidLineAreaFill> tag.

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.

Bar Outline Customization

It is possible to customize outline styles for bars in bar charts. Bar outline style can be customized using defaultOutlineStyle or outlines attributes of <o:barChartView> tag. The defaultOutlineStyle attribute can be specified with a simple CSS-like declaration, such as "3px dotted green", or using the value biding expression that points to a property of type org.openfaces.component.chart.LineStyle. The org.openfaces.component.chart.LineStyle class has color and stroke properties. The stroke property sallows specifying an arbitrary line pattern by creating appropriate java.awt.BasicStroke instances, which is the standard way of specifying line styles in Java2D. See the BasicStroke JavaDoc}} for instructions on constructing its instances.

The outlines attribute can be used when a chart displays several series, and it should be specified as a value binding expression that points to a collection of org.openfaces.component.chart.LineStyle instances. The usage of the outlines attribute will override the settings defined in defaultOutlineStyle attribute.

Shadow customization

Using the showShadow attribute of the <o:barChartView> or <o:pieChartView> tag, it is possible to turn on or off shadows displayed on the chart. The showShadow attribute can be set to "true", "false" or defined with a value binding expression that points to a property of type boolean.

Both <o:barChartView> and <o:pieChartView> tags have a shadowColor attribute that can be used to customize the color of shadow. This attribute can be defined with as in-place CSS color literals, like "red", "blue", or "#8040ff", or defined as a value binding expression that points to a property of type java.awt.Color.

<o:chart model="#{PopulationBean.population}">
    <o:barChartView showShadow="true" shadowColor="blue"/>
</o:chart>

Also, it is possible to customize offsets for the shadow by specifying the shadowXOffset and shadowYOffset attributes of <o:barChartView> or <o:pieChartView> tags. These attributes should be specified as double-type values or as a value binding expression that points to the property of type double.

<o:chart model="#{PopulationBean.population}">
    <o:pieChartView showShadow="true" shadowColor="blue"
                    shadowXOffset="10.0" shadowYOffset="5.0"/>
</o:chart>

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.

In addition to the above customization, it is possible to customize label positions for <o:lineChartView> and <o:barChartView> chart types. It can be done using the defaultLabelsPosition, positiveLabelsPosition, negativeLabelsPosition attributes. Each of these attributes specifies label alignment for the appropriate group of items (all, positive and negative respectively) using one of the following values:

  • "center"
  • "outsideTop"
  • "outsideLeft"
  • "outsideRight"
  • "outsideBottom"
  • "insideTop"
  • "insideLeft"
  • "insideRight"
  • "insideBottom"

In addition, it is possible to define these attributes as a value binding expression that points to a property of type org.openfaces.component.chart.ChartLabelPosition.

Markers support

In Line and Bar charts it is possible to add chart markers in order to highlight specific value or range of values on a chart.

Marker is a sub-component, represented by <o:marker> tag, that provides a support for displaying markers on line and bar charts.

In order to display markers on a chart, the appropriate <o:marker> tags should be placed inside of one of the following two container tags:

  • <o:domainMarkers> tag – represents a container for markers of chart's key axis;
  • <o:rangeMarkers> tag – represents a container for markers of chart's value axis.

Both of these container tags should in turn be added as a children of <o:barChartView> or <o:lineChartView> tags, and, as mentioned above, filled with a <o:marker> tags in order to display them on the chart.

You can use the startValue and endValue attributes of the <o:marker> tag to specify a range that should be displayed by this marker, or just a value attribute, which allows displaying a single value instead of a range. You can specify a text label that should be displayed for the marker using the label attribute of <o:marker> tag. Label style can be customized with the textStyle attribute, and its position relative to the marker itself is specified using the labelAnrchor attribute, which can take the following values:

  • center
  • top
  • bottom
  • left
  • right
  • topLeft
  • topRight
  • bottomLeft
  • bottomRight

Please also refer to the the <o:marker> tag reference for the full list of customization attributes.

Here's an example of defining a bar chart with two markers – one domain marker that highlights a bar with a key of "twenty" as a vertical stripe labeled with "Special" text, and one range marker, which highlights value of 35.0 as a horizontal line.

<o:chart model="#{DefaultTestBean.defaultChartModel}" width="400" height="400">
  <o:barChartView>
    <o:domainMarkers>
      <o:marker value="twenty" label="Special"/>
    </o:domainMarkers>
    <o:rangeMarkers>
      <o:marker value="35.0"/>
    </o:rangeMarkers>
  </o:barChartView>
</o:chart>

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.

Built In Context Menu Support

It is possible to enable the standard chart context menu to allow performing useful actions on chart, like saving and printing the chart. The context menu support can be turned on by adding the <o:chartMenu> tag inside of the <o:chart> tag.

<o:chart model="#{PopulationBean.population}">
    <o:chartMenu/>
    <o:barChartView/>
</o:chart>

It is possible to customize the content and appearance of the standard menu by customizing the <o:chartMenu> tag's attributes and child tags. Adding any menu item tags inside of the <o:chartMenu> tag will replace the standard structure with the custom menu item hierarchy. This provides the full flexibility for reordering, restyling or removing the standard items and adding the custom ones. The standard menu items can be specified with the following tags:

  • saveChartMenuItem tag as the name says allows saving the chart as an image;
  • printChartMenuItem tag provides a functionality for displaying the print dialog in order to print the chart.

Additionally, you can place a <o:menuSeparator> tag to insert separators and a <o:menuItem> tag to add custom menu items.

Custom Item Popups

It is possible to add custom popups to the charts to allow displaying extended content for each chart item, which can be useful for example when implementing a drill down functionality. Custom item popups can be enabled by specifying the <o:chartPopup> tag as a child of chart view tags.

<o:chart model="#{PopulationBean.population}">
    <o:pieChartView>
        <o:chartPopup>
             <o:chart model="#{PopulationBean.detailedPopulation}">
                 <o:chartTitle text="#{sector.key}"/>
                 <o:barChartView/>
             </o:chart>
        </o:chartPopup>
    </o:pieChartView>
</o:chart>

As a container, the ChartPopup lets you place any kind of JSF components inside it to build its content. You can use the "sector" (for pie charts) and "point" (for bar and line charts) request scope variables when defining the child components of <o:chartPopup> tag to specify the item-dependent content. For example the PopulationBean.getDetailedPopulation() function can retrieve the "sector" variable using the Faces.var("sector", PieSectorInfo.class) function and return different model for each respective sector.

By default, the ChartPopup component is adjusted to accommodate its content. However, you can set fixed width and height in any units (px, mm, em, etc) by using the width and height attributes of <o:chartPopup> tag.

You can customize a style for the ChartPopup component in the normal and rollover states using the style and styleClass and the rolloverStyle and rolloverClass attributes respectively.

The ChartPopup component supports a set of standard client-side events such as onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onkeydown, onkeypress, onkeyup.

Note
Note that the keyboard events such as onkeydown, onkeypress, and onkeyup are fired only if the ChartPopup component contains elements that provide these events, for example HTMLInputText .

Interactive Selection Support

Adding the <o:chartSelection> tag <o:chart> tag turns on an ability for interactive chart item selection. This means that a user can select a chart item (sector in pie charts, bar in bar charts, or shape in line charts) by clicking on it, and application developer has an ability to detect the selected item and optionally update the dependent content with Ajax on selection change.

Here's a simple example:

<o:chart model="#{PopulationBean.population}">
    <o:chartSelection item="#{PopulationBean.selectedCategory}" render="detailTable"/>
    <o:pieChartView/>
</o:chart>

<o:dataTable id="detailTable" ...>

When the user clicks on a chart item to select it, an appropriate Ajax request is issued to the server to load a chart with the new selection. There is a possibility of invoking a server action during this Ajax request. This can be done using the actionListener attribute. This attribute should be specified as a method binding expression pointing at an action listener to be invoked. The referred method should receive one parameter of type javax.faces.event.ActionEvent. The other possible way to invoke server-side listener is to use the action attribute. This attribute should be specified as a method binding expression pointing to an action listener to be invoked. In this case the referred method shouldn't receive any arguments.

Chart item selection performed using the Ajax component may need some additional data entered on the page to be submitted to the server for processing. Here are the rules that are used to determine the components whose data should be submitted and processed on the server:

  • All reloaded components specified in the render attribute are submitted to the server.
  • It is possible to specify the list of components that should be submitted in addition to the ones mentioned above by explicitly specifying their ids in the execute attribute. These components will be submitted to the server for processing their data, but they won't be reloaded as a result of Ajax request. This feature is useful for a quite common case when the reloaded components and/or the executed action depends on the data entered elsewhere on the page.

Using the lineStyle and fillPaint attributes of the <o:chartSelection> tag it is possible to customize the selection highlighting displaying. The lineStyle attribute can be specified as a CSS-like line style, for example "3px solid red", or as a value binding expression that points to the property of type org.openfaces.component.chart.LineStyle.

The fillPaint attribute can be specified as a simple color name, like "yellow" or with a value binding expression that points to the property of type java.awt.Paint.

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 does not work on Jetspeed-2 Enterprise Portal server.
OpenFaces