Chart

Version 5 by Yip Ng
on Jul 26, 2012 14:21.

<< Changes from 4 to 5
compared with
Current by Judy Guglielmin
on Sep 28, 2017 16:13.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 29 changes. View first change.

 h2. Overview
 _Since 3.1_
  
Chart wraps jqPlot technologies for easy creation and display of data in graphical form.
  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.
  
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=chartBean] of this component, complete with source code.{tip}
  
 h2. Getting Started
  
 Xhtml:
 
 {code:xml|borderStyle=dashed}
 <ace:chart id="name" value="#{backing.dataForChart}"
 xAxis="#{backing.XAxis}"                   
 yAxes="#{backing.YAxes}"/>
  {panel}
 {code:xml|borderStyle=dashed}<ace:chart id="name" value="#{backing.dataForChart}"
  xAxis="#{backing.XAxis}"                   
  yAxes="#{backing.YAxes}"/>
 {code}
Backing Bean:
 {code}
 private List<SeriesType> dataForChart = new ArrayList<SeriesType>() {
         {
             add(new SeriesType() {
                 {
                     setType(SeriesType.GraphType);
                     add(xValue,yValue);
                     ***
                     add(finalXValue,finalYValue);
                 }
             });
         }
     };
  {panel}Backing Bean:
 {panel}
 {code:java|borderStyle=dashed}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 xAxis = new Axis() {
         {
         }
     };
  private Axis[] YAxes = new Axis[] {
  new Axis()
 };{code}
 {panel}
  
private Axis[] YAxes = new Axis[] { new Axis() {
         {
         }
     }};
 {code}
  For more advanced examples for each type of chart visit the [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=chartBean] for this component, which includes xhtml and Java source code as well as the actual charts generated from such code.
  
 h4. 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
  ** BUBBLE^
 * CartesianSeries
 ** BAR
** LINE
  ** LINE^
 * GaugeSeries
 ** GAUGE^
 * OHLCSeries
 ** CANDLESTICK
** OHLC
  ** OHLC^
 * SectorSeries
 ** DONUT
** PIE
  ** PIE^
  
h4.
  
  
 h2. 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|http://www.icefaces.org/docs/v3_latest/ace/tld/ace/chart.html]. |
 Value: Define the variable on the backing bean that will be displayed using this chart. Must be a collection of ChartSeries type objects.
  {tip:title=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|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/chart.html].{tip}
 {panel}
 *value*: Define the variable on the backing bean that will be displayed using this chart. Must be a collection of ChartSeries type objects.
 {panel}
 {panel}
 *xAxis*: Define the axis that will be used for the primary X-axis. Must be an element of chart.Axis.
 {panel}
 {panel}
 *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.)
 {panel}
 {panel}
 *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).
 {panel}
 {panel}
 *pointChangeListener*: returns a PointValueChangeEvent so users can dynamically update the values by dragging chart values--see Dynamic Chart example in showcase app.
 {panel}
 {panel}
 *imageExportListener*:- returns ChartImageExportEvent where getBytes() will provide an image of the chart.
 {panel}
  
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.)
  
 h2. Methods
  
| (/) | *Java Documentation* \\
 This section covers attributes involved in the typical use-cases for this component. For a complete reference, please consult the javadocs. |
  
  {tip:title=Java Documentation}This section covers attributes involved in the typical use-cases for this component. For a complete reference, please consult the [JavaDoc|http://res.icesoft.org/docs/v4_latest/ace/api/org/icefaces/ace/component/chart/package-summary.html]. {tip}
 h5. ChartSeries:
  
 setType(ChartSeries.ChartType&nbsp;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&nbsp;x, java.lang.Object&nbsp;y): Add a point of data to the graph to be created. Must be called once for each desired datapoint.
  
h5. Axis:
  h5. Axis
  
 setType(AxisType&nbsp;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.
  
h2. Advanced usage examples:
  h2. 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.
  
h4. Combined Charts:
  h2. Javascript API
 h4. 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.
  
 h4. 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.
  
 {code}var widget = ice.ace.instance('frm:componentId);{code}
  
 {tip}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">_).{tip}
  
 h2. 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.
  
 {panel}
 {code:xml|borderStyle=dashed}
 <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" />
 {code}
 {panel}
  
  
  
 h2. Advanced usage examples
  
 h4. Combined Charts
  
 This example will detail how to combine multiple sets of data onto a single displayed chart, using two different graph types.&nbsp; This example will use bar and line graphs. (Please note that you cannot combine two graph types from different series types.)
  
  
 Xhtml:
{panel}
 {code:xml|borderStyle=dashed}<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. -->
 {code}
<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.-->
 {code}
 Backing Bean:
 {code}
 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);
   }
  });
  {panel}Backing Bean:
 {panel}
 {code:java|borderStyle=dashed}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 xAxis = new Axis() {
 {
  setType(AxisType.CATEGORY);
  }
  };
  private Axis x2Axis = 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.
   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. */{code}
 {panel}
  
 h2. CSS Classes
  
 The following markup represents the basic HTML structure of the component. There are no CSS classes in use in this component.
  
 {code:xml}
 <div>
  <div style="[user defined styles]">
  <!-- This area is populated with canvas elements that compose the chart -->
  </div>
 </div>
 {code}

© Copyright 2021 ICEsoft Technologies Canada Corp.