ChartDirector charts often contain a lot of text strings. For example, sector labels
in pie charts, axis labels for x and y axes, data labels for the data points, HTML
image maps, etc, are all text strings.
ChartDirector uses parameter substitution to allow you to configure precisely
the information contained in the text and their format.
For example, when drawing a pie chart with side label layout, the default sector
label format is:
"{label} ({percent}%)"
In drawing the sector labels, ChartDirector will replace "{label}" with the
sector name, and "{percent}" with the sector percentage. So the above label
format will result is a sector label similar to
"ABC (34.56%)".
If you want to change the sector label format by changing the format string.
For example, you can change it to:
"{label}: US${value}K ({percent}%)"
The sector value will then become something like
"ABC: US$123 (35.56%)".
In general, in ChartDirector parameter substitution, fields enclosed by curly
brackets will be substituted with their actual values when creating the texts.
ChartDirector supports parameter expressions. They are fields enclosed by curly
brackets and starts with the "=" character. For example:
"USD {value} (Euro {={value}*0.9})"
In the above, "{value}" will be substituted with the actual value of the sector.
The expression "{={value}*0.9}" will be substituted with the actual value of the
sector multiplied by 0.9.
ChartDirector parameter expressions support operators "+", "-", "*", "/" and "^"
(exponentiation). Operators "*", "/", "^" is computed first, followed by "+" and
"-". Operators of the same precedence are computed from left to right).
Parenthesis "(" and ")" can be used to change the computation order.
For fields that are numbers or
dates/times,
ChartDirector supports a special syntax in parameter substitution to allow
formatting for these values. Please refer to the
Number Formatting and
Date/Time Formatting sections below for details.
The following tables descirbe the fields available for various chart objects.
The followings are parameters that are apply to all XY Chart layers in general.
Some layer types may have additional parameters (see below).
Note that certain parameters are inapplicable in some context. For example, when
specifying the aggregate label of a stacked bar chart, the {dataSetName}
parameter is inapplicable. It is because a stacked bar is composed of multiple
data sets. It does not belong to any particular data set and hence does not have
a data set name.
Parameter | Description |
x
|
The x value of the data point. For an enumerated x-axis (see Axis.setLabels
on what is an enumerated axis), the first data point is 0, and the nth data
point is (n-1).
|
xLabel
|
The bottom x-axis label of the data point.
|
x2Label
|
The top x-axis label of the data point.
|
value
|
The value of the data point.
|
accValue
|
The accumulative value of the data point. This is useful for stacked charts,
such as stacked bar chart and stacked area chart.
|
totalValue
|
The total value of all data points. This is useful for stacked charts, such
as stacked bar chart and stacked area chart.
|
percent
|
The percentage of the data point based on the total value of all data points.
|
accPercent
|
The accumulated percentage of the data point based on the total value of
all data points. This is useful for stacked charts, such as stacked bar chart
and stacked area chart.
|
dataSet
|
The data set number to which the data point belongs. The first data set
is 0. The nth data set is (n-1).
|
dataSetName
|
The name of the data set to which the data point belongs.
|
dataItem
|
The data point number within the data set. The first data point is 0.
The nth data point is (n-1).
|
dataGroup
|
The data group number to which the data point belongs. The first data group is 0.
The nth data group is (n-1).
|
dataGroupName
|
The name of the data group to which the data point belongs.
|
layerId
|
The layer number to which the data point belongs. The first layer is 0.
The nth layer is (n-1).
|
field{N}
|
The (N + 1)th extra field (the first extra field is field0), assuming the
extra field is associated with data items. In other words, the Pth data
item corresponds to the Pth element of the extra field.
|
diField{N}
|
Same as field{N}. See above.
|
dsField{N}
|
The (N + 1)th extra field (the 1st extra field is dsField0), assuming
the extra field is associated with data sets. In other words, the Pth data
set corresponds to the Pth element of the extra field.
|
dsdiField{N}
|
Expand to an extra field element, assuming the extra fields are indexed
by both the data set and data item. The Pth data item of the Qth data set
will corresponds to the Pth element of the (N + Q)th extra field.
|
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Parameter | Description |
high
|
The high value of the data representation.
|
low
|
The low value of the data representation.
|
open
|
The open value of the data representation.
|
close
|
The close value of the data representation.
|
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Parameter | Description |
top
|
The value of the top edge of the box-whisker symbol.
|
bottom
|
The value of the bottom edge of the box-whisker symbol.
|
max
|
The value of the maximum mark of the box-whisker symbol.
|
min
|
The value of the minimum mark of the box-whisker symbol.
|
med
|
The value of the median mark of the box-whisker symbol.
|
The followings are parameters that are in additional to the parameters for all XY Chart layers.
Parameter | Description |
slope
|
The slope of the trend line.
|
intercept
|
The y-intercept of the trend line.
|
corr
|
The correlation coefficient in linear regression analysis.
|
stderr
|
The standard error in linear regression analysis.
|
For parameters that are numbers, ChartDirector supports a number of formatting
options in parameter substitution.
For example, if you want a numeric field
{value} to have a precision of
two digits to the right of the decimal point, use ',' (comma) as the thousand
separator, and use '.' (dot) as the decimal point, and you may use
{value|2,.}. The number
123456.789 will then be displayed as
123,456.79.
For numbers, the formatting options are specified using the following syntax:
{[param]|[a][b][c][d]}
where:
Parameter | Description |
[param]
|
The name of the parameter
|
[a]
|
An integer specifying the number of digits to the right of the decimal point.
The default is automatic. To use the default, simply skip this parameter.
|
[b]
|
The thousand separator. Should be a non-alphanumeric character (not 0-9, A-Z, a-z).
Use '~' for no thousand separater. The default is '~', which can be modified using
BaseChart.setNumberFormat.
|
[c]
|
The decimal point character. The default is '.', which can be modified using
BaseChart.setNumberFormat.
|
[d]
|
The negative sign character. Use '~' for no negative sign character. The
default is '-', which can be modified using BaseChart.setNumberFormat.
|
You may skip the trailing formatting options if they are needed. For example,
{value|2} means formatting the value with two digits to the right, where
the thousand separator, decimail point character, and negative sign character
are all using the default settings of the chart.
For parameters that are
dates/times, the formatting
options can be specified using the following syntax:
{[param]|[datetime_format_string]}
where [datetime_format_string] must start with an english character
(A-Z or a-z), and may contain any characters except '}'. Certain characters are
substituted according to the following table:
Parameter | Description |
yyyy
|
The year in 4 digits (e.g. 2002)
|
yyy
|
The year showing only the least significant 3 digits (e.g. 002 for the year 2002)
|
yy
|
The year showing only the least significant 2 digits (e.g. 02 for the year 2002)
|
y
|
The year showing only the least significant 1 digits (e.g. 2 for the year 2002)
|
mmm
|
The month formatted as its name. The default is to use the first 3 characters of the
english month name (Jan, Feb, Mar ...). The names can be configured using
BaseChart.setMonthNames.
|
mm
|
The month formatted as 2 digits from 01 - 12, adding leading zero if necessary.
|
m
|
The month formatted using the minimum number of digits from 1 - 12.
|
dd
|
The day of month formatted as 2 digits from 01 - 31, adding leading zero if necessary.
|
d
|
The day of month formatted using the minimum number of digits from 1 - 31.
|
w
|
The name of the day of week. The default is to use the first 3 characters of the
english day of week name (Sun, Mon, Tue ...). The names can be configured using
BaseChart.setWeekDayNames.
|
hh
|
The hour of day formatted as 2 digits, adding leading zero if necessary. The 2 digits will be
00 - 23 if the 'a' option (see below) is not specified, otherwise it will be 00 - 12.
|
h
|
The hour of day formatted using the minimum number of digits. The digits will be
0 - 23 if the 'a' option (see below) is not specified, otherwise it will be 0 - 12.
|
nn
|
The minute formatted as 2 digits from 00 - 59, adding leading zero if necessary.
|
n
|
The minute formatted using the minimum number of digits from 00 - 59.
|
ss
|
The second formatted as 2 digits from 00 - 59, adding leading zero if necessary.
|
s
|
The second formatted using the minimum number of digits from 00 - 59.
|
a
|
Display either 'am' or 'pm', depending on whether the time is in the morning or afternoon. The
text 'am' and 'pm' can be modified using BaseChart.setAMPM.
|
For example, a parameter substitution format of
{value|mm-dd-yyyy} will
display a date as something similar to
09-15-2002. A format of
{value|dd/mm/yy hh:nn:ss a}
will display a date as something similar to
15/09/02 03:04:05 pm.
© 2004 Advanced Software Engineering Limited. All rights reserved.