Chapter 15. Output and messages

⁠Chapter 15. Output and messages

Read this chapter for details on components that display messages and other feedback to the user.

⁠15.1. `<rich:chart>`

The <rich:chart> component allows the user to plot data and to create line, bar or pie charts. It uses up to five children tags: <rich:chartSeries>, <rich:chartLegend>, <rich:chartXAxis>, <rich:chartYAxis> and <rich:chartPoint>. Each child tag customizes a particular aspect of the chart. At least one <rich:chartSeries> tag is required and the others are optional.

Additionally, the <rich:chart> component allows one to handle events using either a client-side JavaScript or using server-side listeners.

⁠

Figure 15.1. <rich:chart> Component

⁠15.1.1. Basic Usage

The <rich:chart> tag and its optional children tags generate and customize the chart. The chart type is selected by a <rich:chartSeries> attribute. The only requirements for using the <rich:chart> are selection of the chart type and passing of at least one series of data. This is explained in more detail below.

⁠15.1.2. Data Input

The <rich:chart> component accepts data by two means: by facelet iteration, and by creating a DataModel object.

⁠15.1.2.1. Facelet Iteration

Use <a4j:repeat> and a collection of objects inside the <rich:chartSeries> tag and specify what you want to be plotted on the x and y axis using the <rich:chartPoint> tag. The <a4j:repeat> approach can also be used at the <rich:chartSeries> level.

⁠

Example 15.1. rich:chart facelet iteration example

<rich:chart id="barChart" title="Countries by vehicles per capita">
    <rich:chartSeries type="bar">
        <a4j:repeat value="#{bean.records}" var="record">
            <rich:chartPoint x="#{record.country}" y="#{record.count}"/>
        </a4j:repeat>
    </rich:chartSeries>
    <rich:chartYAxis label="Motor vehicles per 1000 people"/>
</rich:chart>

⁠15.1.2.2. Create a DataModel Object

When facelet iteration is used the ChartDataModel object is created by the ChartRenderer. An alternative to this is to create a ChartDataModel yourself and pass it using the <rich:chartSeries> data attribute. To do this, create an instance of one of the child classes of ChartDataModel - NumberChartDataModel, StringChartDataModel or DateChartDataModel (not yet fully supported). Select the class according to the data type used on the x-axis. Add values to the model using the put() method and pass it to the <rich:chartSeries> tag using the data attribute.

⁠

Example 15.2. rich:chart DataModel object example

<rich:chart id="barChart" title="Countries by vehicles per capita">
   <rich:chartSeries type="bar" data="#{bean.cars}"/>
   <rich:chartYAxis label="Motor vehicles per 1000 people"/>
</rich:chart>

cars = new StringChartDataModel(ChartDataModel.ChartType.bar);
cars.put("San Marino", 1263);
cars.put("United States", 797);
...

If there is a model passed using the <rich:chartSeries> data attribute, any nested <rich:chartPoint> tags are ignored. If the data attribute is not used, then nested <rich:chartPoint> tags are expected.

⁠15.1.3. Chart Customization

The chart configuration is split into multiple tags providing a clearer facelet API. To configure axes, their min/max values, and label, use the <rich:chartXAxis> or <rich:chartYAxis> tag. The <rich:chartLegend> allows you to set up the position of the legend and the order of the labels within it.

To adjust the chart component size, you can use CSS class .richfaces-chart-container. To customize the title, you can use .richfaces-chart-title. The chart itself is placed in the div with the CSS class .richfaces-chart.

⁠15.1.4. Advanced Customization

The <rich:chart> can also be customized directly through JavaScript to allow the use of plugins or objects that are not directly supported by the component.

There are two ways to define the customization: the hooks attribute or a facet named hooks. The facet takes precedence over the attribute when both are defined.

<h:outputScript>
    var hooks = {
        processOptions: [function(plot,options) {
                options.xaxes[0].tickFormatter = function (value, axis) {
                    return value.toLocaleString('en-US', {minimumFractionDigits: 2});
                };
        }]
    };
</h:outputScript>
<rich:chart hooks="hooks" />

<rich:chart>
    <f:facet name="hooks">
        {
            processOptions: [function(plot,options) {
                    options.xaxes[0].tickFormatter = function (value, axis) {
                        return value.toLocaleString('en-US', {minimumFractionDigits: 2});
                    };
            }]
        }
    </f:facet>
</rich:chart>

In the above samples, the <rich:chart> is configured to display the label on x-axis according to US locale (e.g. 45,324.23).

Note

For further configuration options, refer to Flot API - Hooks and Flot API - Plugins.

⁠15.1.5. Interactivity Options

The <rich:chart> component can create interactive charts.

It allows the user to zoom line charts when the <rich:chart> attribute zoom is set true. To reset zoom you can use the JavaScript API.
You can also add functions to handle events fired by components. Event handlers are set up using proper <rich:chart> attributes. They handle events fired by any series. If you want to handle an event only fired by a particular series, set up handlers using the <rich:chartSeries> attributes.

⁠15.1.6. `<rich:chart>` Server-side Events

The PlotClickEvent is fired when the user clicks a point in the chart. To set a listener use the ClickListener attribute.

⁠15.1.7. `<rich:chart>` Client-side Events

The plothover event points to the client-side function to execute when the mouse cursor is over the chart point.
The plotclick event points to the client-side function to execute when the user clicks the chart point.
The mouseout event points to the cient-side function to execute when the mouse cursor leaves the chart grid.

The plothover and plotclick handlers are given an event-object that contains the deatils of which point fired the event.

function log(e){
           	console.log("Series index: "+
                 	e.data.seriesIndex +" DataIndex: "+
                 	e.data.dataIndex+' ['+e.data.x+','+e.data.y+']');
}

⁠15.1.8. JavaScript API

To access the jQuery widget of the component, use the componentID and chart.

resetZoom() displays the chart without scaling.
getPlotObject() returns a JavaScript object containing chart data and options.

⁠

Example 15.3. jQuery Widget Example

<rich:chart id="priceChart">

$(document.getElementById("priceChart")).chart("resetZoom")

⁠15.1.9. Reference Data

component-type: org.richfaces.Chart
component-class: org.richfaces.component.UIChart
component-family: org.richfaces.Chart
renderer-type: org.richfaces.ChartRenderer
handler-class: org.richfaces.ChartTagHandler