Documentation

For version 1.0.5


Introduction

Black Box Chart is a powerful Flash application that enables you to easily embed interactive charts into a web page.

A Black Box Chart component can have multiple charts and legends. You specify the settings of a Black Box Chart component through XML code that is sent to the Black Box Chart Flash application either directly (the Flash argument: chartCode)or by giving the address where the code should be retrieved (the Flash argument: chartCodeSource).

You can either manually create a Black Box Chart code or use the editor provided on the web site (on the My Charts page). One easy method is to create the layout of the charts with the editor and to dynamically populate the code for the series with whatever server side tool you like.


Your first chart

Here is one of the easiest instance of chart code:

<BlackBoxChart xAxisMin='0' xAxisMax='50'>
<Chart>
<PlotSeries name='My Series'>
<Point x='0' y='0' />
<Point x='10' y='20' />
<Point x='20' y='10' />
</PlotSeries>
</Chart>
</BlackBoxChart>

So what have we done here? First we created the BlackBoxChart root XML node and specified the X axis range thanks to xAxisMin and xAxisMax. Then we added a chart by adding a Chart node to the BlackBoxChart root node. Then we added a new plot series to our chart by adding a PlotSeries node to the Chart node, we also specified the name of the new series (although this name won't be displayed in this simple example). Populating a series is very easy, you simply add as many Point nodes as you want to a Chart node. Don't forget to specify the x coordinate and the y coordinate for each point!

Adding a chart to a web page

Now it is time to add that Black Box Chart Flash component to a web page. One easy way to do this is to add the following code to your HTML web page:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab" width="400" height="310">
<param name="movie" value="BlackBoxChart.swf?chartCode=<BlackBoxChart xAxisMin='0' xAxisMax='50'><Chart><PlotSeries name='My Series'><Point x='0' y='0' /><Point x='10' y='20' /><Point x='20' y='10' /></PlotSeries></Chart></BlackBoxChart>">
<embed src="BlackBoxChart.swf?chartCode=<BlackBoxChart xAxisMin='0' xAxisMax='50'><Chart><PlotSeries name='My Series'><Point x='0' y='0' /><Point x='10' y='20' /><Point x='20' y='10' /></PlotSeries></Chart></BlackBoxChart>"
type="application/x-shockwave-flash"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>

Notice that we pass the chart code to the Flash object by setting the chartCode argument with our code. Also note that you have to write the setting code twice (once in the param node and once in the embed node).

Note that this code will sucessfully embed a Flash object only if the user has an appropriate Flash version installed on its computer. If you want to learn more about how to embed Flash in HTML pages, please have a look at the following web sites:

W3Schools: Flash in HTML
Adobe: Flash OBJECT and EMBED tag syntax
Adobe: Preparing your website to handle the Microsoft changes to Internet Explorer
Google: swfobject

Here is the result of the code:



Passing code to Black Box Chart

There are two ways to pass setting code to Black Box Chart.


Static code

The static code way to the same as the one presented in the You first chart section. It consists in settings up the chartCode Flash parameter.

Here is an example of how to embed a chart and set the chartCode parameter:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab" width="450" height="360">
<param name="movie" value="BlackBoxChart.swf?chartCode=<BlackBoxChart xAxisMin='0' xAxisMax='50'><Chart><PlotSeries name='My Series'><Point x='0' y='0' /><Point x='10' y='20' /><Point x='20' y='10' /></PlotSeries></Chart></BlackBoxChart>">
<embed src="BlackBoxChart.swf?chartCode=<BlackBoxChart xAxisMin='0' xAxisMax='50'><Chart><PlotSeries name='My Series'><Point x='0' y='0' /><Point x='10' y='20' /><Point x='20' y='10' /></PlotSeries></Chart></BlackBoxChart>"
type="application/x-shockwave-flash"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>


Retrieve code from address

Sometimes you don't want to put long settings code in the middle of a web page. Fortunately Black Box Chart allows you to pass the address where the setting code should be retrieved (that is Black Box Chart will download the content of the address and use it as the setting code). To do this you just have to set up the chartCodeAddress Flash parameter with the address of the setting code.

Here is an example of how to embed a chart and set the chartCodeAddress parameter:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab" width="450" height="360">
<param name="movie" value="BlackBoxChart.swf?chartCodeAddress=http://www.mywebsite.com/chartcode.xml">
<embed src="BlackBoxChart.swf?chartCodeAddress=http://www.mywebsite.com/chartcode.xml"
type="application/x-shockwave-flash"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>


Configuration nodes

Here is a list of all XML nodes that can be used to set up Black Box Chart.

BlackBoxChart node

Description
This is the root node. There you can specify settings that will be shared by each chart present there. All charts and groups of charts that will be added to the BlackBoxChart node will share the same X axis range, that is the X axis ranges of all charts will be synchronized when the user modifies one.
Accepted nodes
Chart, ControlChart, Legend
Parameters
Parameter
Default Value
Mandatory?
Description
version
1.0.1
No
The version of the charts code to use
backgroundColor
14474460
No
The background color in integer value (see RGB to int calculator)
xAxisIndicator
Date
No
The type of the X axis indicator
xAxisMin
0
No
The minimum of the X axis range
xAxisMax
1
No
The maximum of the X axis range
xAxisScrollingEnabled
true
No
Whether user can scroll the X axis range with his mouse

Chart node

Accepted node
PlotSeries, BarSeries
Parameters
Parameter
Default Value
Mandatory?
Description
name
Chart
No
The name of the chart
width
400
No
The width of the chart
height
300
No
The height of the chart
chartAreaColor
16777215
No
The color of the chart area in integer value (see RGB to int calculator)
yAxisIndicator
Number
No
The type of the Y axis indicator
showXAxisIndicator
true
No
Wether the Y axis indications should be displayed
showYAxisIndicator
true
No
Wether the X axis indications should be displayed
autoYAxisRange
true
No
Wether the Y axis range should be automatically set
yAxisMin
0
No
The minimum of the Y axis range. Only used if autoYAxisRange is set to false.
yAxisMax
1
No
The maximum of the Y axis range. Only used if autoYAxisRange is set to false.
showSelectedPointIndicator
true
No
Wether to display an indicator on the point selected by the user's mouse

ControlChart node

Description
The control chart displays the currently selected X axis range and let users easily modify it.
Accepted nodes
PlotSeries, BarSeries
Parameters
Parameter
Default Value
Mandatory?
Description
name
Control Chart
No
The name of the control chart
width
400
No
The width of the control chart
height
300
No
The height of the control chart
chartAreaColor
16777215
No
The color of the chart area in integer value (see RGB to int calculator)
selectedAreaColor
9881840
No
The color of the selected area in integer value (see RGB to int calculator)
yAxisIndicator
Number
No
The type of the Y axis indicator
showXAxisIndicator
true
No
Wether the Y axis indications should be displayed
showYAxisIndicator
true
No
Wether the X axis indications should be displayed
xAxisMin
If no values in xAxisMin and xAxisMax, the range will fit the data
No
The minimum of the initial X axis control range
xAxisMax
If no values in xAxisMin and xAxisMax, the range will fit the data
No
The maximum of the initial X axis control range
autoYAxisRange
true
No
Wether the Y axis range should be automatically set
yAxisMin
0
No
The minimum of the Y axis range. Only used if autoYAxisRange is set to false.
yAxisMax
1
No
The maximum of the Y axis range. Only used if autoYAxisRange is set to false.

Legend node

Description
A legend displays the names of the series for a parent chart.
Parameters
Parameter
Default Value
Mandatory?
Description
width
400
No
The width of the legend
height
15
No
The height of the legend
parentChart
 
No
The name of the parent chart: the legend will display the series from this chart

Text node

Description
A text displays some arbitrary text.
Parameters
Parameter
Default Value
Mandatory?
Description
width
400
No
The width of the text
text
No
The text to be displayed
align
left
No
The alignment of the text:
"center", "left" or "right"
fontSize
11
No
The size of the font
color
0
No
The color of the text in integer value (see RGB to int calculator)
bold
false
No
Whether the text should be in bold
italic
false
No
Whether the text should be in italic
underline
false
No
Whether the text should be underlined

PlotSeries node

Accepted nodes
Point, Note
Parameters
Parameter
Default Value
Mandatory?
Description
name
Series
No
The name of the series
color
0
No
The color of the series in integer value (see RGB to int calculator)
lineThickness
2
No
The thickness of the plot line
indicatorSize
5
No
The size of the selected point indicator
showPointsIndicators
false
No
Whether each point should have a little indicator

BarSeries node

Accepted nodes
Point, Note
Parameters
Parameter
Default Value
Mandatory?
Description
name
Series
No
The name of the series
color
0
No
The color of the series in integer value (see RGB to int calculator)
barWidth
10
No
The width of the bars (time should be expressed in milliseconds, ie:
1 hour = 60 * 60 * 1000)

Point node

Description
Defines a point in a PlotSeries or a bar in a BarSeries.

You can put either a number or a date (format is: HH:MM:SS DD/MM/YYYY) as a coordinate.

Examples:

<Point x='10' y='50' />
<Point x='22:15:00 10/02/2008' y='50' />
<Point x='30' y='01:29:00 28/11/2008' />

Parameters
Parameter
Default Value
Mandatory?
Description
x
 
Yes
The X coordinate of the point
y
 
Yes
The Y coordinate of the point

Note node

Description
A note is a little indication that will be displayed on the top of its parent series at a specific X coordinate. When the user moves his mouse over a note, the note will be expanded to display a longer description.
Parameters
Parameter
Default Value
Mandatory?
Description
x
 
Yes
The X coordinate of the note
shortDescription
 
Yes
A short description of the note that will be displayed on the chart
longDescription
 
No
A long description of the note that will be displayed when user moves the mouse over the note

Axis indicator types

For a given chart, whatever the kind of values used for the series (dates or numbers) you can independently select the type of axis indications you want to see. In fact, all kind of values for points are internally converted into specific data and therefore can be easily displayed through any kind of formatter.

Please have a look below at the available formatters so that you can choose the ones that are best suited to your needs.


Date

The axis indications displayed will be dates:


Number

The axis indications displayed will be numbers:


FormattedNumber

The axis indications displayed will be formatted numbers (that is 10 000 will be displayed as 10k for example):