Orbeon Forms User Guide

Charts and Spreadsheets

1. Chart Processor

1.1. 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.

1.2. 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
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.
serie-title The label printed on the vertical (Y) axis
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
category-label-angle Controls the angle of the category axis labels. This value is a positive angle in degree.
legend Controls the legend box.
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 RelaxNG schema is shown below:

<grammar datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" xmlns="http://relaxng.org/ns/structure/1.0"><start><ref name="chart"/></start><define name="chart"><element name="chart"><interleave><element name="type"><choice><value>vertical-bar</value><value>horizontal-bar</value><value>vertical-bar-3d</value><value>horizontal-bar-3d</value><value>stacked-vertical-bar</value><value>stacked-horizontal-bar</value><value>stacked-vertical-bar-3d</value><value>stacked-horizontal-bar-3d</value><value>line</value><value>area</value><value>pie</value><value>pie-3d</value></choice></element><element name="title"><data type="string"/></element><optional><element name="map"><data type="string"/></element></optional><optional><element name="category-title"><data type="string"/></element></optional><optional><element name="category-margin"><data type="double"/></element></optional><optional><element name="serie-title"><data type="string"/></element></optional><oneOrMore><element name="value"><attribute name="title"/><attribute name="categories"/><attribute name="series"/><optional><attribute name="colors"/></optional><optional><attribute name="exploded-percents"/></optional><optional><attribute name="color"><ref name="color"/></attribute></optional><empty/></element></oneOrMore><element name="x-size"><data type="integer"/></element><element name="y-size"><data type="integer"/></element><optional><element name="background-color"><ref name="color"/></element></optional><optional><element name="title-color"><ref name="color"/></element></optional><optional><element name="bar-margin"><data type="double"/></element></optional><optional><element name="tick-unit"><data type="double"/></element></optional><optional><element name="category-label-angle"><data type="positiveInteger"/></element></optional><optional><element name="legend"><optional><attribute name="visible"><data type="boolean"/></attribute></optional><optional><attribute name="position"><choice><value>north</value><value>east</value><value>south</value><value>west</value></choice></attribute></optional><zeroOrMore><element name="item"><attribute name="color"><ref name="color"/></attribute><attribute name="label"><data type="string"/></attribute><empty/></element></zeroOrMore></element></optional></interleave></element></define><define name="color"><data type="string"><param name="pattern">#[0-9A-Fa-f]{6}</param></data></define></grammar>

1.3. 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" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"><img src="chartDisplay?filename={file}" usemap="#fruits" border="0" width="400" height="300"/><xsl:copy-of select="map"/></xsl:template>

2. Excel Processors

Note

These processors are deprecated. Please refer to the Converters section for up-to-date information.

Orbeon Forms ships with the POI library which allows import and export of Microsoft Excel documents. Orbeon Forms uses an Excel file template to define the layout of the spreadsheet. You define cells that will contain the values with a special markup.

2.1. Preparing the Spreadsheet

First, create an Excel spreadsheet with the formatting of your choosing. Values are taken from the data input document with an XPath expression. Apply a special markup to the cell you need to export values to:

  1. Select the cell
  2. Go to the menu Format->Cell
  3. In the Number tab, choose the Custom format and enter a format that looks like: #,##0;"/a/b|/c/d". In this example we have 2 XPath expressions separated by a pipe character ( |): /a/b and /c/d. The first XPath expression is used when creating the Excel file (exporting) and is run against the data input document of the XLS Serializer processor (see below). The second expression is optional and is used when recreating an XML document from the Excel file (importing).

2.2. Export

The XLS Serializer processor takes a config input describing the XLS template file, and a data input containing the values to be inserted in the template. The processor scans the template, and applies XPath expressions to fill in the template. The config input takes a single element with two attributes:

template A URL pointing to an XLS template file
filename The name under which the file is saved.

<p:processor name="oxf:xls-serializer"><p:input name="config"><config template="oxf:/excel/template.xls" filename="currency.xls"/></p:input><p:input name="data"><currency><value1>10</value1><value2>20</value2><value3>30</value3></currency></p:input></p:processor>

2.3. Import

The XLS Generator works in a similar way. It typically takes a file uploaded by a user, finds the special markup cells and reconstructs an XML document. The generator has one input request which must be connected to the output of the request generator, and a data output containing the generated XML document. You must include a form within the HTML code with an xls file upload control. The following code can be used to perform this task:

<form action="excel/import" method="post" enctype="multipart/form-data"><input type="file" name="xls"/><input type="submit" value="Import"/></form>

The XPL pipeline can then instantiate the XLS Generator with the following:

<p:processor name="oxf:xls-generator"><p:input name="request" href="#request"/><p:output name="data" id="xls"/></p:processor>