Processors - Charts

Chart processor

Introduction

Orbeon Forms uses the JFreeChart to draw and display charts. The following features are supported:

  • Bar Chart
  • Stacked Bar Chart
  • Line Chart
  • Pie Chart
  • Area Chart
  • Customizable size, colors, title and legend
  • Output HTML image map and tool tips

A chart consists of two axes. The horizontal (X) axis is called the category axis. The vertical (Y) axis is called the value axis. The chart contains one or more values. Each value is a list of number to be charted. A value entry contains two lists:

  • the categories list, represented in the X axis
  • the series list, represented on the Y axis
The lists of value are created with XPath expressions evaluated against the XML document in the data input. These expressions must return a node set, and every expression must return a node set of the same length.

Chart input

The chart input contains the configuration information for the processor. The following table shows elements that are available inside the chart root element.

NOTE: The colors are always specified in RGB format, prefixed by a #. For instance, #FF0000 is a pure red.

type The chart type. The following value are supported vertical-bar; horizontal-bar; vertical-bar-3d; horizontal-bar-3d; stacked-vertical-bar; stacked-horizontal-bar; stacked-vertical-bar-3d; stacked-horizontal-bar-3d; line; area; pie; pie-3d; xy-line; time-series.
title The title, printed on top of the chart.
title-color The font title color
background-color Color of the background of the chart
x-size The horizontal size of the chart image, in pixels
y-size The vertical size of the chart image, in pixels
category-title The label printed on the horizontal (X) axis
category-margin Margin between two categories, in percentage of width. Applies only to the vertical-bar chart type.
category-label-angle Controls the angle of horizontal axis labels. This value is a positive angle in degree. For time-series charts, this value has to be either 0 (horizontal) or 90 (vertical).
serie-title The label printed on the vertical (Y) axis
serie-auto-range-include-zero Whether the vertical (Y) axis should include the value 0. This is true by default, and you might want to set it to false if all the values are in a "small" range "far" from 0, to avoid having all the values shown as being grouped together.
map Name of the HTML image map
bar-margin Margin between two vertical bars, in percentage of width. Applies only to the vertical-bar chart type.
tick-unit The vertical (Y) axis unit
legend Controls the legend box.
max-number-of-labels The maximum number of labels you want to have on the X axis.
legend/@visible Control if the legend is displayed. Can be true or false
legend/@position The position of the legend relative to the chart. Possible values are east, north, west or south
legend/item Forces manual legend. You can specify any number of items, each with a label and color attribute.
value Defines the values of the chart. At least one element must be present
value/@title The name of the value item
value/@categories XPath expression returning the category list
value/@series XPath expression returning the serie list
value/@colors XPath expression returning a color list
exploded-percent XPath expression returning a percentage list. Valid only for Pie charts and allows certain slices to be exploded from the pie.
value/color Manual override of the color for this value

The full Relax NG schema is available here.

Displaying the chart

The Chart Serializer outputs an XML document on its data output, which describes the rendered chart information. It contains the chart image name and an optional HTML image map. A typical document looks like below. The file element contains the unique name of the generated chart. The map element contains the image map.

<chart-info>
<file>jfreechart-20234.png</file>
<map name="fruits">
<area shape="RECT" coords="66,54,86,235" title="May, Apples = 10"/>
<area shape="RECT" coords="93,35,113,234" title="June, Apples = 11"/>
<area shape="RECT" coords="131,72,151,235" title="May, Oranges = 9"/>
<area shape="RECT" coords="158,90,178,235" title="June, Oranges = 8"/>
<area shape="RECT" coords="196,90,216,235" title="May, Bananas = 8"/>
<area shape="RECT" coords="223,126,243,235" title="June, Bananas = 6"/>
<area shape="RECT" coords="261,108,281,235" title="May, Berries = 7"/>
<area shape="RECT" coords="289,54,309,235" title="June, Berries = 10"/>
<area shape="RECT" coords="326,126,346,235" title="May, Pears = 6"/>
<area shape="RECT" coords="354,163,374,235" title="June, Pears = 4"/>
</map>
</chart-info>

You need to setup a special servlet in your Web application descriptor (web.xml) to serve the chart image file. The following line declares the servlet and maps it to /chartDisplay

<servlet>
<servlet-name>DisplayChart</servlet-name>
<servlet-class>com.jrefinery.chart.servlet.DisplayChart</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>DisplayChart</servlet-name>
<url-pattern>/chartDisplay</url-pattern>
</servlet-mapping>

The following XSLT template can be used to extract the chart information and generate HTML:

<xsl:template match="chart-info">
<img src="chartDisplay?filename={file}" usemap="#fruits" border="0" width="400" height="300"/>
<xsl:copy-of select="map"/>
</xsl:template>


Using the processor

Typically:

  1. From XForms, you run a submission, which posts to a service the data needed to generate the chart. The service returns the name of the generated chart file. Assuming you store the XML returned by the service in an instance called chart, you can then display the image with <xhtml:img src="/orbeon/chartDisplay?filename={instance('chart')/file}"/>.
  2. You implement the service called by XForms with a pipeline. You map that pipeline to a URL through the page-flow.xml, and in the pipeline use the oxf:chart processor. See below an example of such a pipeline. Here, the pipeline calls the oxf:chart processor directly with a static configuration, but in most cases you'll want to build that configuration with XSLT based on the instance input of the pipeline, which corresponds to the data posted from XForms.
<p:config xmlns:p="http://www.orbeon.com/oxf/pipeline"
          xmlns:xs="http://www.w3.org/2001/XMLSchema"
          xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
          xmlns:exist="http://exist.sourceforge.net/NS/exist"
          xmlns:oxf="http://www.orbeon.com/oxf/processors">

    <p:param name="data" type="output"/>

    <p:processor name="oxf:chart">
        <p:input name="config">
            <config/>
        </p:input>
        <p:input name="data">
            <data>
                <x-axis>
                    <value>1</value>
                    <value>2</value>
                    <value>3</value>
                    <value>4</value>
                    <value>5</value>
                </x-axis>
                <y-axis>
                    <value>1</value>
                    <value>3</value>
                    <value>5</value>
                    <value>3</value>
                    <value>6</value>
                </y-axis>
            </data>
        </p:input>
        <p:input name="chart">
            <chart>
                <type>vertical-bar</type>
                <title>vertical-bar Example</title>
                <category-title>X-axis title</category-title>
                <serie-title>Y-axis title</serie-title>
                <value title="test" categories="data/x-axis/value"
                                    series="data/y-axis/value"/>

                <x-size>400</x-size>
                <y-size>400</y-size>
                <background-color>#FFFFFF</background-color>
                <title-color>#000000</title-color>
            </chart>
        </p:input>
        <p:output name="data" ref="data"/>
    </p:processor>

</p:config>
Comments