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

Handling events of the chart component

My introduction set of posts about the chart component is coming to end. I have already covered creating a basic chart, chart types supported, customization of chart look and component’s JavaScript API. One of thing I haven’t explained is handling of the chart component events.

The chart component offers three events to be handled.

• plotclick – fired when point in a chart is been clicked
• plothover – mouse cursor is above  the point
• mouseout – mouse cursor leaves chart grid

Each of events can be handled by JavaScript function. The PlotClick event can be assigned a server-side listener also. A listener or JavaScript handling function is given information about fired event:

• seriesIndex – index of series whose point firing event belongs to
• dataIndex – point index inside the series
• x – point value on x-axis
• y – point values on y-axis
• item - javascript object holding other information about the event such as series label (only javascript)

Note: This information is not relevant for the mouseout event.

Let’s move to an example. I am going to use following chart.

<rich:chart>
    <a4j:repeat value="#{eventBean.countries}" var="country" >
         <rich:chartSeries label="#{country.name}" type="line">
             <a4j:repeat value="#{country.data}" var="record">
                 <rich:chartPoint x="#{record.year}" y="#{record.tons}" />
             </a4j:repeat>
         </rich:chartSeries>
    </a4j:repeat>
    <rich:chartXAxis  label="year"/>
    <rich:chartYAxis label="metric tons of CO2 per capita"/>
</rich:chart>

Client-side handlers

In first example I would like to show how to handle plotclick event. I am going to create a simple JavaScript function which will change the text in <span> element showing information about the point clicked.

At first add the span element, identify it with id attribute.

<span id='clickInfo'></span>

Create function which updates the span text.

<script type='text/javascript'>
        //<![CDATA[
           function log(e){
               $('#clickInfo').text("Series index: "+
                     e.data.seriesIndex +" DataIndex: "+
                     e.data.dataIndex+' ['+e.data.x+','+e.data.y+']');
           }

        //]]>
    </script>

Set handler in chart attribute attribute name is on+eventName, where eventName is one of plotclick, plothover or mouseout.

<rich:chart onplotclick="log(event)" >

JavaScript handler function is given an event object holding information mentioned above. They are located in data property. To access them use

e.data.seriesIndex
e.data.dataIndex
e.data.x
e.data.y
e.data.item.series.label

The similar approach might be used to handle plothover and mouseout events.

Server-side listener

To handle event you can also set server-side listener. I am going to use the same simple example setting a text after firing event.

<h:form>
    <rich:chart clickListener="#{eventBean.handler}">
         <a4j:repeat value="#{eventBean.countries}" var="country" >
             <rich:chartSeries label="#{country.name}" type="line">
                 <a4j:repeat value="#{country.data}" var="record">
                     <rich:chartPoint x="#{record.year}" y="#{record.tons}" />
                 </a4j:repeat>
             </rich:chartSeries>
         </a4j:repeat>
         <a4j:ajax event="plotclick" render="msg" execute="msg"/>
         <rich:chartXAxis label="year"/>
         <rich:chartYAxis label="metric tons of CO2 per capita"/>
    </rich:chart>
    <h:outputText id="msg" value="#{eventBean.msg}"/>
</h:form>

To be able to use server-side listener you have to surround the chart tag by the form. There is also added outputText showing the String updated by server-side listener. <a4j:ajax> tag set the outputText to be rerendered after the plotclick event.

The server-side listener is given an instance of plotclick object which contains the same information as client side object except item object.

public void handler(PlotClickEvent event){
    msg="Server's speaking:"+event.toString();
}

The setting of server-side listener is done by attribute clickListener.

Online demo can be found here and bean source code is on github.

Particular series handler

If you want to handle event fired by particular series only you can set handler for the one series only by using attribute in series tag. The name is the same as in chart tag.

Note: mouseout event handler is available only in chart tag.

Links

• Part 1 - Introduction
• Part 2 - Customization
• Part 3 - Event handling

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

Chart component

The chart component has landed in RichFaces. Let’s take a quick look how to use it.

I am going to show steps how to create chart like this. It shows countries carbon dioxide emissions per capita in several years. I am going to use following data. Data are stored in a list of Country objects in a backing bean.

public class Country{
    private String name;
    //CO2 production year-> metric tons per capita
    private List<Record> data;

    public Country(String name){
        this.name = name;
        this.data = new LinkedList<Record>();
    }
    public void put(int year, double tons){
        this.data.add(new Record(year, tons));
    }

    public List<Record> getData() {
        return data;
    }

    public String getName() {
        return name;
    }

    public class Record{
        private int year;
        private double tons;

        public Record(int year, double tons) {
            this.year = year;
            this.tons = tons;
        }

        public double getTons() {
            return tons;
        }

        public int getYear() {
            return year;
        }
    }
}

Country object has name and list of records (year and tons of C02 produced in that year by the country)

Prerequisite: Create JSF maven project (I am not going to dive in details.) with JBOSS public repository enabled.

Create chart

<rich:chart>
   <a4j:repeat value="#{bean.countries}" var="country" >
      <rich:chartSeries label="#{country.name}" type="line">
         <a4j:repeat value="#{country.data}" var="record">
            <rich:chartPoint x="#{record.year}" y="#{record.tons}" />
         </a4j:repeat>
      </rich:chartSeries>
   </a4j:repeat>
   <rich:chartXAxis label="year"/>
   <rich:chartYAxis label="metric tons of CO2 per capita"/>
</rich:chart>

I’ll explain these lines in details. You don’t have to create any extra java Object and fill it. You just pass what you gain from database or wherever and use it. In our case we have backing bean called bean and there is a list of Country objects storing data named countries.

Tag chartSeries represents one line in our chart – the values for one country. It has one mandatory attribute type defining the look of chart. It selects whether the chart displays line, bar or pie.

As you probably noticed, there is missing data in series tag. Data is passed into the series using tag chartPoint. It express one key-value pair/ x,y coordinates of a point in that line.

Tag repeat iterates over an array and it “generates” tags for you. That’s why you see only one series in a facelet and for lines in a chart. The same approach is used with points of each series.

Note: If you prefer more traditional  way. You can create chart data model by your self and pass it into the series tag using data attribute. It’ll be shown in another blog.

The source code of the shown example can be found here.

What chart type does component offer?

In this post I am going to describe what types of chart the component allow to create, how to switch among them and other things you should know about it.

The component supports line, bar and pie chart at the moment. The switching among chart type is easy, you change series tag attribute type to corresponding value.

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

Each type expects Number type in y attribute. Line chart allows to use Number and Date (not fully supported yet) type in x attribute. Bar chart allows to use Number, String and Date (not fully supported yet). Pie chart use only String in x attribute.

Line and bar chart allow to use more than one series in a chart if the same type is used in x axis. You can also combine bar and line chart.

Switching among chart types get a little more complicated when you create data model by your self but it is topic for another post.

Links

• Part 1 - Introduction
• Part 2 - Customization
• Part 3 - Event handling