Taken from Lukáš Macko's blog series on charts, this is an up-to-date version.


How to customize the chart look

 

This post explains how to customize chart created by RichFaces chart component. The first steps how to create basic chart and chart types supported can be found in previous posts. If you’ve read some of these blog or API design proposal, you know that chart component uses a hierarchical tag structure. It means that chart configuration is divided into several tags. Each of them customizes a part of the chart.

 

<rich:chart>
   <rich:chartSeries type="line">
      <a4j:repeat value="" var="">
         <rich:chartPoint x="" y=""/>
      </a4j:repeat>
   </rich:chartSeries>
   <rich:chartXAxis/>
   <rich:chartYAxis/>
   <rich:chartLegend/>
</rich:chart>

The general chart structure is shown above. I’ll run through tags and their attributes. All attributes are optional except the ones mentioned above type, x and y.

 

rich:chart

  • title – text shown above the chart (not styled properly yet)
  • styleClass – css class assigned to a chart div
  • zoom – set true to enable zooming (works on line chart) you can reset zoom throught JavaScript API
  • eventHandlers: onplotclick, onmouseover, onmouseout, clickListener explained in detail in event handling post

 

rich:chartSeries

  • type – required attribute selects the chart type. Allowed values are line, bar and pie
  • symbol – selects point symbol in line chart (the attribute is ignored by other chart type) allowed values are circle, square, cross, triangle, diamond
  • color – defines series color (works with line and bar chart)
  • data – it used to pass data into component when you fill dataModel by your self explained in data model post
  • eventHandlers for particular series. See event handler post

 

rich:chartXAxis, rich:chartYAxis

  • format – currently used only by date series
  • label – axis description show next to axis
  • min – the smallest value shown on axis
  • max – the biggest values shown on axis
  • pad – if you don’t want to set fixed min and max value you can use this attribute it definesthe fraction of margin that the scaling algorithm will add to avoid that the outermost points ends up on the grid border.

 

rich:chartLegend

  • position – where the legend should be placed. Allowed values are nw (top left), sw (bottom left), ne (top right), se (bottom right)
  • sorting – defines the rule how the labels in legend are ordered. If not set they are in order asi defined in facelet. If you want to order them alphabetically you can use ascending or descending option.

 

Chart JavaScript API

 

The chart component it is built above the jQuery widget factory, so it offers also JavaScript API. Handling JavaScript events I’ll cover in another post. Component’s JavaScript API offers for now two public methods.

 

getPlotObject – used for testing returns JavaScript plot object

 

resetZoom is used to reset axis ranges and display whole chart after zooming is done. I’ll demonstrate it in a small example.

 

<rich:chart id="myChart" zoom="true" >
  <rich:chartLegend sorting="ascending"/>
  <a4j:repeat value="#{bean.series}" var="s">
    <rich:chartSeries type="line" label="#{s.label}" >
       <a4j:repeat value="#{s.data}" var="point">
          <rich:chartPoint x="#{point.x}" y="#{point.y}" />
       </a4j:repeat>
    </rich:chartSeries>
  </a4j:repeat>
</rich:chart>

To call a method on a particular chart you use id attribute.

 

RichFaces.component("form:myChart").resetZoom()

Example above calls method resetZoom on a chart identified by ID myChart. You can see live example here. (Note: the example is not up-to-date)

 

There is one more method not implemented yet highlight. It should allow to programmatically highlight a point in a series.

 

Links