How to Use the ICEfaces OutputChart Component

The outputChart component uses the JCharts open source charting utility (http://jcharts.sourceforge.net/) to create charts. The two main types of charts that can be created with this component are axis charts and pie charts.

Axis OutputChart Component

There are 7 types of axis charts: area, areastacked, bar, barclustered, barstacked, line and point.

<ice:outputChart id="axisOutputChart"
                 type="bar"
                 chartTitle="Bar Chart"
                 yaxisTitle="Problems"
                 xaxisTitle="Years"
                 xaxisLabels="#{axisChartBean.labels}"
                 labels="#{axisChartBean.legendLabels}"
                 colors="#{axisChartBean.paints}"
                 data="#{axisChartBean.data}" />

The "colors" binding in the bean may return either a java.util.List of java.awt.Color, an array of java.awt.Color or a String array. You can also define the data statically in the jsf page:

colors="red, blue, green"

The "data" binding in the bean may return either a java.util.List of double array for each pair value, or a double array. You can also define the data statically in the page:

Defining the data for an axis type chart in the page for two data sets:

data="10, 30, 40, 33: 30, 20, 30, 40"

NOTE: the colon(":") is used as the identifier for a new data set.

The axis charts use the same underlying data structure which can allow you to change the chart type dynamically:

type="#{axisChartBean.type}"

The participation of the outputChart component with the jsf lifecycle allows developers to hook actionListeners to a clientSideImageMap. This feature can be harnessed to provide drill down behavior in all axis charts except area and areastacked. In the demo, when you click on a bar in the chart this will trigger the actionListener to display the value of that bar on the page.

actionListener="#{axisChartBean.imageClicked}"

By default the chart component renders only on the first render cycle and any further render requests will not cause it to be re-rendered unless specified. The rendering of a chart can be an expensive operation if it renders on every render phase. The renderOnSubmit attribute lets the developer decide when to render the chart.

renderOnSubmit="#{axisChartBean.newChart}"

Pie OutputChart Component

There are 2 types of pie charts: 2D and 3D.

<ice:outputChart id="pie2DOutputChart"
                 type="pie2D"
                 chartTitle="Pie2D Chart"
                 labels="#{pieChart.labels}"
                 data="#{pieChart.data}"
                 colors="#{pieChart.paints}"
                 actionListener="#{pieChart.action}"
                 renderOnSubmit="#{pieChart.newChart}" />

Pie Charts require a different data model (one dimensional versus the two dimensional model with axis charts) so we have a different bean for the pie charts.

The 2D demo shows a 2D Pie Chart with an actionListener that will show a further breakdown of the pie data. This shows the ability of any chart to pass the selected image map data into the bean for further processing. In this case, we have a separate ice:dataTable component showing a breakdown of the yearly sales selected from the 2D Pie Chart.

The 3D demo shows how you can dynamically manipulate any chart through the UI. The data, label and paint properties can each be bound to Lists in a backing bean. This feature allows developers to easily manipulate chart properties in the backing bean.

Combining with the OutputChart Component

You can create any type of chart or combine charts using the JCharts API in your bean. You can then pass this custom chart to the outputChart component which will allow the chart to participate in the JSF lifecycle.

The proper place for chart manipulation using the JCharts API is in the method binding which is bound to the renderOnSubmit attribute, which tells the component whether to render the chart:

<ice:outputChart type="custom" renderOnSubmit="#{combinedChart.newChart}" />

public boolean newChart(OutputChart component){
    try {
        .............
        .............
        org.krysalis.jcharts.axisChart.AxisChart axisChart= new org.krysalis.jcharts.axisChart.AxisChart( ......);
        component.setChart(axisChart);
        return true;
    } catch (Exception e) {
        e.printStackTrace();
        return false;
    }
}

Tutorial Source Code Downloads