MBS Xojo Developer Conference and Training
Join us from 3rd to 6th May 2017 in Berlin, Germany.

Platforms to show: All Mac Windows Linux Cross-Platform

FAQ.ChartDirector: Parameter Substitution and Formatting
Feedback.

Answer: ChartDirector: Parameter Substitution and Formatting
Notes:
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.
Format Strings
In parameter substitution, format strings are used to specify the entities to be include into labels and how to format numbers and dates.

For example, when drawing a pie chart with side label layout, the default sector label format string is:

"{label} ({percent}%)"

When the sector label is actually drawn, 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%)".

You may change the sector label format by changing the format string. For example, you may change it to:

"{label}: US${value|2}K ({percent}%)"

The sector label will then become something like "ABC: US$123.00 (34.56%)".

In general, in ChartDirector parameter substitution, parameters enclosed by curly brackets will be substituted with their actual values when creating the texts.

For parameters 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.
Parameter Expressions
ChartDirector supports numeric expressions in format strings. They are denoted by enclosing the expression with curly brackets and using "=" as the first 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 "+", "-", "*", "/", "%" (modulo) 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.
Parameters for Pie Charts
The following table describes the parameters available for pie charts.

ParameterDescription
sectorThe sector number. The first sector is 0, while the nth sector is (n-1).
dataSetSame as {sector}. See above.
labelThe text label of the sector.
dataSetNameSame as {label}. See above.
valueThe data value of the sector.
percentThe percentage value of the sector.
fieldNThe (N + 1)th extra field. For example, {field0} means the first extra field. An extra field is an array of custom elements added using BaseChart.addExtraField or BaseChart.addExtraField2.

Parameters for All XY Chart Layers
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.

ParameterDescription
xThe 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).
xLabelThe bottom x-axis label of the data point.
x2LabelThe top x-axis label of the data point.
valueThe value of the data point.
accValueThe sum of values of all data points that are in the same x position and same data group as the current data point, and with data set number less than or equal to the current data point. This is useful for stacked charts, such as stacked bar chart and stacked area chart.
totalValueThe sum of values of all data points that are in the same x position and same data group as the current data point. This is useful for stacked charts, such as stacked bar chart and stacked area chart.
percentThe percentage of the data point based on the total value of all data points that are in the same x position and same data group as the current data point. This is useful for stacked charts, such as stacked bar chart and stacked area chart.
accPercentThe accumulated percentage of the data point based on the total value of all data points that are in the same x position and same data group as the current data point. This is useful for stacked charts, such as stacked bar chart and stacked area chart.
gpercentThe percentage of the data point based on the total value of all data points in a layer.
dataSetThe data set number to which the data point belongs. The first data set is 0. The nth data set is (n-1).
dataSetNameThe name of the data set to which the data point belongs.
dataItemThe data point number within the data set. The first data point is 0. The nth data point is (n-1).
dataGroupThe data group number to which the data point belongs. The first data group is 0. The nth data group is (n-1).
dataGroupNameThe name of the data group to which the data point belongs.
layerIdThe layer number to which the data point belongs. The first layer is 0. The nth layer is (n-1).
fieldNThe (N + 1)th extra field. For example, {field0} means the first extra field. An extra field is an array of custom elements added using Layer.addExtraField, Layer.addExtraField2, BaseChart.addExtraField or BaseChart.addExtraField2.

{fieldN} means the extra field is indexed by the data point number. The Pth data point corresponds to the Pth element of the extra field.
diFieldNSame as fieldN. See above.
dsFieldNSimilar to fieldN, except that dsFieldN means the extra field is indexed by data set number. The Pth data set corresponds to the Pth element of the extra field.
dsdiFieldNSimilar to fieldN, except that dsdiFieldN means the extra fields are indexed by both the data set number and data point number. The Pth data item of the Qth data set corresponds to the Pth element of the (N + Q)th extra field.

Additional Parameters for Line Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.

ParameterDescription
zxThe symbol scale in the x dimension. Applicable for layers with symbol scales set by LineLayer.setSymbolScale.
zyThe symbol scale in the y dimension. Applicable for layers with symbol scales set by LineLayer.setSymbolScale.
zThe symbol scale without distinguishing the dimension to use. Applicable for layers with symbol scales set by LineLayer.setSymbolScale.

Additional Parameters for Trend Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.

ParameterDescription
slopeThe slope of the trend line.
interceptThe y-intercept of the trend line.
corrThe correlation coefficient in linear regression analysis.
stderrThe standard error in linear regression analysis.

Additional Parameters for Box-Whisker Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.

ParameterDescription
topThe value of the top edge of the box-whisker symbol.
bottomThe value of the bottom edge of the box-whisker symbol.
maxThe value of the maximum mark of the box-whisker symbol.
minThe value of the minimum mark of the box-whisker symbol.
medThe value of the median mark of the box-whisker symbol.

Additional Parameters for HLOC and CandleStick Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.

ParameterDescription
highThe high value.
lowThe low value.
openThe open value.
closeThe close value.

Additional Parameters for Vector Layers
The followings are parameters that are in additional to the parameters for all XY Chart layers.

ParameterDescription
dirThe direction of the vector.
lenThe length of the vector.

Parameters for All Polar Layers
The followings are parameters that are apply to all Polar Chart layers in general. Some layer types may have additional parameters (see below).

ParameterDescription
radiusThe radial value of the data point.
valueSame as {radius}. See above.
angleThe angular value of the data point.
xSame as {angle}. See above.
labelThe angular label of the data point.
xLabelSame as {label}. See above.
nameThe name of the layer to which the data point belongs.
dataSetNameSame as {name}. See above.
iThe data point number. The first data point is 0. The nth data point is (n-1).
dataItemSame as {i}. See above.
zThe symbol scale. Applicable for layers with symbol scales set by PolarLayer.setSymbolScale.
fieldNThe (N + 1)th extra field. For example, {field0} means the first extra field. An extra field is an array of custom elements added using Layer.addExtraField, Layer.addExtraField2, BaseChart.addExtraField or BaseChart.addExtraField2.

{fieldN} means the extra field is indexed by the data point number. The Pth data point corresponds to the Pth element of the extra field.
diFieldNSame as fieldN. See above.
dsFieldNSimilar to fieldN, except that dsFieldN means the extra field is indexed by layer index. The Pth layer corresponds to the Pth element of the extra field.
dsdiFieldNSimilar to fieldN, except that dsdiFieldN means the extra fields are indexed by both the data set number and data point number. The Pth data item of the Qth layer corresponds to the Pth element of the (N + Q)th extra field.

Additional Parameters for PolarVector Layers
The followings are parameters that are in additional to the parameters for all Polar Chart layers.

ParameterDescription
dirThe direction of the vector.
lenThe length of the vector.

Parameters for Axis
The following table describes the parameters available for pie charts.

ParameterDescription
valueThe axis value at the tick position.
labelThe axis label at the tick position.

Number Formatting
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:

ParameterDescription
[param]The name of the parameter
[a]If this field a number, it specifies the number of decimal places (digits to the right of the decimal point).

If this field starts with "E" or "e", followed by a number, it means formatting the value using scientific notation with the specified number of decimal places. If the "E" or "e" is not followed by a number, 3 is assumed.

For example, {value|E4} will format the value 10.3 to 1.0300E+1, and {value|e4} will format the same value to 1.0300e+1.

If this field starts with "G" or "g", followed by a number, it means formatting the value using the scientific notation only if the value is large and requires more than the specified number of digits, or the value is less than 0.001. If scientific notation is used, the number following "G" or "g" also specifies the number of significant digits to use. If the "G" or "g" is not followed by a number, 4 is assumed.

For example, consider the format string {value|G4}. The value 10 will be formatted to 10. The value 100000 will be formatted to 1.000E+5. Similarly, for {value|g4}, the value 10 will be formatted to 10, while the value 100000 will be formatted to 1.000e+5.

If you skip this argument, ChartDirector will display the exact value using at most 6 decimal places.
[b]The thousand separator. Should be a non-alphanumeric character (not 0-9, A-Z, a-z). Use '~' for no thousand separator. 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 [b][c][d]. In this case, the default will be used.

Date/Time Formatting
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) that is not "G", "g", "E" or "e", and may contain any characters except '}'. (If it starts with "G", "g", "E" or "e", it will be considered as a number format string.)

Certain characters are substituted according to the following table. Characters that are not substituted will be copied to the output.

ParameterDescription
yyyyThe year in 4 digits (e.g. 2002)
yyyThe year showing only the least significant 3 digits (e.g. 002 for the year 2002)
yyThe year showing only the least significant 2 digits (e.g. 02 for the year 2002)
yThe year showing only the least significant 1 digits (e.g. 2 for the year 2002)
mmmThe 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.
mmThe month formatted as 2 digits from 01 - 12, adding leading zero if necessary.
mThe month formatted using the minimum number of digits from 1 - 12.
MMMThe first 3 characters of the month name converted to upper case. The names can be configured using BaseChart.setMonthNames.
MMThe first 2 characters of the month name converted to upper case. The names can be configured using BaseChart.setMonthNames.
MThe first character of the month name converted to upper case. The names can be configured using BaseChart.setMonthNames.
ddThe day of month formatted as 2 digits from 01 - 31, adding leading zero if necessary.
dThe day of month formatted using the minimum number of digits from 1 - 31.
wThe 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.
hhThe 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 01 - 12.
hThe 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 01 - 12.
nnThe minute formatted as 2 digits from 00 - 59, adding leading zero if necessary.
nThe minute formatted using the minimum number of digits from 00 - 59.
ssThe second formatted as 2 digits from 00 - 59, adding leading zero if necessary.
sThe second formatted using the minimum number of digits from 00 - 59.
aDisplay 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.

If you want to include characters in the format string without substitution, you may enclose the characters in single or double quotes.

For example, the format {value|mmm '<*color=dd0000*>'yyyy} will display a date as something like Jan <*color=dd0000*>2005 (the <*color=dd0000*> is a CDML tag to specify red text color). Note that the <*color=dd0000*> tag is copied directly without substitution, even it contains "dd" which normally will be substituted with the day of month.
Escaping URL/HTML/CDML characters
Parameter substitution is often used to create HTML image maps. In HTML, some characters has special meanings and cannot be used reliably. For example, the '>' is used to represent the end of an HTML tag.

Furthermore, if the field happens to be used as an URL, characters such as '?', '&' and '+' also have special meanings.

By default, ChartDirector will escape template fields used in URL and query parameters when generating image maps. It will modify URL special characters to the URL escape format "%XX" (eg. "?" will become "%3F"). After that, it will modify HTML special characters to the HTML escape format "&amps;#nn;" (eg. ">" will become "&amps;#62;".). Similarly, it will escape other attributes in the image map using HTML escape format (but not URL escape format).

In addition to escaping HTML and URL special characters, ChartDirector will also remove CDML fields in creating image maps. It is because CDML is only interpreted in ChartDirector, should not be useful outside of ChartDirector (such as in browser tool tips).

In some cases, you may not want ChartDirector to escape the special characters. For example, if the parameters have already been escaped before passing to ChartDirector, you may want to disable ChartDirector from escaping them again.

ChartDirector supports the following special fields to control the escape methods - "{escape_url}", "{noescape_url}", "{escape_html}", "{noescape_html}", "{escape_cdml}" and {noescape_cdml}". These fields enable/disable the escape methods used in the template fields that follow them.




Links
Christians Software aus Nickenich