Chart

Table of Contents

Overview

Since 3.1

Chart transforms Java data objects into a variety of graphical client representations. User data and series-specific configuration is input via ChartSeries subclasses and passed as the 'value' property of the Chart component. This way multiple series of different types can be plotted on the same Chart.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

Xhtml:

<ace:chart id="name" value="#{backing.dataForChart}"
           xAxis="#{backing.XAxis}"                   
           yAxes="#{backing.YAxes}"/> 
Backing Bean:

private List<SeriesType> dataForChart = new ArrayList<SeriesType>() {{
    add(new SeriesType() {{
        setType(SeriesType.GraphType);
        add(xValue,yValue);
        add(finalXValue,finalYValue);
    }});
}};
    
private Axis xAxis = new Axis() {};

private Axis[] YAxes = new Axis[] { 
    new Axis()
};

For more advanced examples for each type of chart visit the Live Demo for this component, which includes xhtml and Java source code as well as the actual charts generated from such code.

Legal values for Series and Graph Types

A type is an alternate representation of the same data that a series may render. Each series has a default type indicated below with a ^.

  • BubbleSeries
    • BUBBLE^
  • CartesianSeries
    • BAR
    • LINE^
  • GaugeSeries
    • GAUGE^
  • OHLCSeries
    • CANDLESTICK
    • OHLC^
  • SectorSeries
    • DONUT
    • PIE^

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

value: Define the variable on the backing bean that will be displayed using this chart. Must be a collection of ChartSeries type objects.

xAxis: Define the axis that will be used for the primary X-axis. Must be an element of chart.Axis.

yAxes: Define the collection of axes that will be used for the y-axis. Must be an array of chart.Axis. (For single y-axis charts, define a single entry array.)

selectListener: returns SeriesSelectionEvent that the user can get integer values (seriesIndex and pointIndex) or String values if chart does not contain integers (pointLabel and seriesLabel).

pointChangeListener: returns a PointValueChangeEvent so users can dynamically update the values by dragging chart values--see Dynamic Chart example in showcase app.

imageExportListener:- returns ChartImageExportEvent where getBytes() will provide an image of the chart.

Methods

Java Documentation
This section covers attributes involved in the typical use-cases for this component. For a complete reference, please consult the JavaDoc.
ChartSeries:

setType(ChartSeries.ChartType type): The style of graph that the data is to appear as, in the form of SeriesType.GraphType. For information on valid combinations, please check above.

add(java.lang.Object x, java.lang.Object y): Add a point of data to the graph to be created. Must be called once for each desired datapoint.

Axis

setType(AxisType type): Define the type of axis that this axis will be. Valid types are:

  • LINEAR: Straightforward plotting
  • LOGARITHMIC: Plotting on a logarithmic scale
  • CATEGORY: Treats each individual entry as it's own separate category, rather than an actual value. Use if you wish to have strings in the axis.
  • DATE: Tracks a series of dates over time.

IE 7 & 8 Caveats

The ace:Chart is rendered on IE 7 & 8 using a compatibility library that emulates HTML Canvas functionality in SVG. This is an imperfect solution, so some mild rendering difference are bound to exist.

Additionally some installs of these browser return inexplicable negative dimension values in Javascript when rendering an ace:Chart via an ajax page update, this results in a misrendered chart and an 'Invalid Argument' exception being raised. However, a workaround is available by giving a height and width to the charts in question, at least when viewing them in IE 7 & 8, this bug is avoided.

Javascript API

ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the widgetVar attribute. You can use downloadAsImage(), exportToImage(), and exportToServer(), as described in the next section.

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use. You can use downloadAsImage(), exportToImage(), and exportToServer(), as described in the next section.

var widget = ice.ace.instance('frm:componentId);
The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).

Export

To export a Chart, you must use the Chart JS api and the client must be running a browser more modern than IE 7 or 8. Otherwise a compatibility library is used which doesn't support this functionality. It might be prudent to disable the export control and notify users of this via server side user-agent detection, an example of which can be found in the ace:chart Export example of the Component Showcase.

<h:form id="exportForm">
    <h:commandButton id="exportButton" value="Export as Image"
                     onclick="exportChart.exportToImage(ice.ace.jq('.chartExport')); 
                              return false;" />

    <ace:chart ...
               widgetVar="exportChart" />
</h:form>
<h:graphicImage styleClass="chartExport" />

Advanced usage examples

Combined Charts

This example will detail how to combine multiple sets of data onto a single displayed chart, using two different graph types.  This example will use bar and line graphs. (Please note that you cannot combine two graph types from different series types.)

Xhtml:

<ace:chart id="name" value="#{backing.dataForChart}"
           xAxis="#{backing.XAxis}" x2Axis="#{backing.X2Axis}" 
           highlighter="true" highlighterBringSeriesToFront="true"
           yAxes="#{backing.YAxes}"/>

<!-- As a note: highlighter and highlighterBringSeriesToFront are 
     not strictly nessecary, but they serve to make it much easier 
     to view the dataset in the back. -->
Backing Bean:

private List<SeriesType> dataForChart = new ArrayList<SeriesType>() {{
    add(new SeriesType() {{
        setType(CartesianType.BAR);
        add(xValue,yValue);
        add(finalXValue,finalYValue);
        setLabel("First Value");
    }});
    add(new SeriesType() {{
        setType(CartesianType.LINE);
        add(xValue,yValue);
        add(finalXValue,finalYValue);
        setLabel("Second Value");
        setYAxis(2);
        setXAxis(2);
    }});
}};

private Axis xAxis = new Axis() {{
    setType(AxisType.CATEGORY);
}};

private Axis x2Axis = new Axis() {{
    setType(AxisType.CATEGORY);
}};

private Axis[] YAxes = new Axis[] {
    new Axis() {{
        setAutoscale(true);
        setLabel("Y1");
    }},
    new Axis() {{
        setAutoscale(true);
        setLabel("Y2");
    }}
};
    
/* All of these axes have method calls within them to modify
   the way they display, but none are truly required. These are   
   here to show the way to get an easy to view chart. */

CSS Classes

The following markup represents the basic HTML structure of the component. There are no CSS classes in use in this component.

<div>
	<div style="[user defined styles]">
		<!-- This area is populated with canvas elements that compose the chart -->
	</div>
</div>
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2017 ICEsoft Technologies Canada Corp.