Charts and Spreadsheets
1. Chart Processor
1.1 Introduction
PresentationServer 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. The
Chart
Example shows most of these options.
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"> <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"> </element> <optional> <element name="map"> </element> </optional> <optional> <element name="category-title"> </element> </optional> <optional> <element name="category-margin"> </element> </optional> <optional> <element name="serie-title"> </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"> </attribute> </optional> <empty/>
</element> </oneOrMore> <element name="x-size"> </element> <element name="y-size"> </element> <optional> <element name="background-color"> </element> </optional> <optional> <element name="title-color"> </element> </optional> <optional> <element name="bar-margin"> </element> </optional> <optional> <element name="tick-unit"> </element> </optional> <optional> <element name="category-label-angle"> <data type="positiveInteger"/>
</element> </optional> <optional> <element name="legend"> <optional> <attribute name="visible"> </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"> </attribute> <attribute name="label"> </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.
PresentationServer ships with the POI library which allows
import and export of Microsoft Excel documents. PresentationServer 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 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" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <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" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="request" href="#request"/>
<p:output name="data" id="xls"/>
</p:processor>