Charts and Spreadsheets
- 1. Chart Processor
- 1.1. Introduction
- 1.2. Chart Input
- 1.3. Displaying the Chart
- 2. Excel Processors
- 2.1. Preparing the Spreadsheet
- 2.2. Export
- 2.3. Import
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
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.
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:
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.
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
The following XSLT template can be used to extract the chart information and generate HTML:
2. Excel Processors
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:
- Select the cell
- Go to the menu
Format->Cell
-
In the
Number
tab, choose theCustom
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 thedata
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. |
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:
The XPL pipeline can then instantiate the XLS Generator with the following: