modules/fusioncharts/API.txt

FusionCharts Module API
================================================================================

Description
--------------------------------------------------------------------------------
The API for FusionCharts is quite simple and straight forward.  Creating a chart
requires two functions to be written.  One to render the graph, and another to
provide the data and settings.

To render the chart:
Call the function fusioncharts_render and pass in two or more parameters:
1. The type of data (FUSIONCHART_QUERY or FUSIONCHART_ARRAY)
2. Name of the callback function.
eg. fusioncharts_render(FUSIONCHART_QUERY, 'example1');
3. Optional.  A string used as the ID for the chart (useful if you want to access the chart with Javascript)
eg. fusioncharts_render(FUSIONCHART_QUERY, 'example1', 'jsexample1');
4. Optional. an array of variables you want passed to the callback function
eg. fusioncharts_render(FUSIONCHART_QUERY, 'example1', NULL, array('parameter1', 'parameter2'));

To provide data and settings:
Create a function specified above (with _fusionchart_callback on the end)
This function should return:
1. The SQL query OR the array of data (depending on the parameter in the first function)
2. The type of graph (see below)
3. An array of settings (see below)
4. An array of attributes (see below)
5. Width of the chart
6. Height of the chart

Types of graph
--------------------------------------------------------------------------------
This is the list of charts available in the FusionCharts free package.
Note: Not all of these are integrated yet.
      
Single Series Charts
--------------------
  Column 3D
  Column 2D
  Line 2D
  Area 2D
  Bar 2D
  Pie 2D
  Pie 3D
  Doughnut 2D

Multi-series Charts
-------------------
  Multi-series Column 2D
  Multi-series Column 3D
  Multi-series Line 2D
  Multi-series Bar 2D
  Multi-series Area 2D

Stacked Charts
--------------
  Stacked Column 3D
  Stacked Column 2D
  Stacked Bar 2D
  Stacked Area 2D

Combination Charts
------------------
  Multi-series Column 2D + Line - Dual Y Axis
  Multi-series Column 3D + Line - Dual Y Axis

Financial Charts
----------------
  Candlestick Chart

Funnel Chart
------------
  Funnel Chart

Gantt Chart
-----------
  Gantt Chart


Settings
--------------------------------------------------------------------------------
There are a large number of graph settings that can be set, and they vary depending
on the type of graph.  Check out the FusionCharts documentation for a complete list
http://www.fusioncharts.com/free/docs/?gMenuItemId=19

If you do not supply any values, sensible ones will be chosen by default.


Attributes
--------------------------------------------------------------------------------
A list of extra settings as listed below:
'callback'       The name of a fusionchart callback to be called when a bar on a graph is clicked.
                 The data in the graph will be updated with the data provided by callback function.

'callback_type'  The type of callback FUSIONCHART_QUERY or FUSIONCHART_ARRAY
'color'          An array of hex colors WITHOUT a # infront
'trendline'      An associative array specifying properties of a trendline/s (all properties are optional)
                 'startvalue'   The Y value of the line (starting point)
                 'endvalue'     The Y value of the line (end point)
                 'displayvalue' Text to display beside the line
                 'color'        Color of the line
                 'thickness'    Thickness of the line
                 'istrendzone'  Whenther the startvalue and endvalues define a line (0) or an area (1)
                 'showontop'    Display the line on top of the bars (1) or behind the bars (0)
                 'alpha'        Transparency of the trend line (0-100)


Notes
--------------------------------------------------------------------------------
When using a SQL query to provide data, the fields that are returned must have specific names:
In the case of Single Series Charts and Funnel Charts: name and value
In the case of Multi-series Charts and Stacked Charts: category, series, and value
In the case of Combination Charts: category, series, axis ("P" or "S"), and value

Example 1: Data provided by a SQL query
--------------------------------------------------------------------------------
function fusioncharts_example1() {
  return fusioncharts_render(FUSIONCHART_QUERY, 'example1');
}

function example1_fusionchart_callback($args = NULL) {
  $query = "SELECT t.name AS name, COUNT(*) as value FROM {term_data} t JOIN {term_node} tn ON t.tid = tn.tid WHERE t.vid=2 GROUP BY t.tid";
  $type = 'Column 3D';
  $settings = array('Caption' => 'Sample chart using the API and a query to generate the data');
  $attributes = array();
  $width = 500;
  $height = 300;
	
  return array($query, $type, $settings, $attributes, $width, $height);
}

Example 2: Data provided by a multi-dimensional array
--------------------------------------------------------------------------------
function fusioncharts_example2() {
  return fusioncharts_render(FUSIONCHART_ARRAY, 'example2');
}

function example2_fusionchart_callback($args = NULL) {
  $data = array(array('Cat', 1),
                array('Dog', 2),
                array('Pig', 3),
     		    array('Mouse', 4),
	         );
  $type = 'Column 3D';
  $settings = array('Caption' => 'Sample chart using the API and sample data');
  $attributes = array('callback' => 'example2',
                      'callback_type' => FUSIONCHART_ARRAY,
                      'color' => array('121212', 'ff0000'), //no # in front of color
                      'trendline' => array(
                                      'startvalue' => 5,
                                      'displayvalue' => 'Test',
                                      'color' => '0000ff'
                                     )
                      ); 
  $width = 500;
  $height = 300;
	
  return array($data, $type, $settings, $attributes, $width, $height);
}
1	FusionCharts Module API
2	================================================================================
3
4	Description
5	--------------------------------------------------------------------------------
6	The API for FusionCharts is quite simple and straight forward. Creating a chart
7	requires two functions to be written. One to render the graph, and another to
8	provide the data and settings.
9
10	To render the chart:
11	Call the function fusioncharts_render and pass in two or more parameters:
12	1. The type of data (FUSIONCHART_QUERY or FUSIONCHART_ARRAY)
13	2. Name of the callback function.
14	eg. fusioncharts_render(FUSIONCHART_QUERY, 'example1');
15	3. Optional. A string used as the ID for the chart (useful if you want to access the chart with Javascript)
16	eg. fusioncharts_render(FUSIONCHART_QUERY, 'example1', 'jsexample1');
17	4. Optional. an array of variables you want passed to the callback function
18	eg. fusioncharts_render(FUSIONCHART_QUERY, 'example1', NULL, array('parameter1', 'parameter2'));
19
20	To provide data and settings:
21	Create a function specified above (with _fusionchart_callback on the end)
22	This function should return:
23	1. The SQL query OR the array of data (depending on the parameter in the first function)
24	2. The type of graph (see below)
25	3. An array of settings (see below)
26	4. An array of attributes (see below)
27	5. Width of the chart
28	6. Height of the chart
29
30	Types of graph
31	--------------------------------------------------------------------------------
32	This is the list of charts available in the FusionCharts free package.
33	Note: Not all of these are integrated yet.
34
35	Single Series Charts
36	--------------------
37	Column 3D
38	Column 2D
39	Line 2D
40	Area 2D
41	Bar 2D
42	Pie 2D
43	Pie 3D
44	Doughnut 2D
45
46	Multi-series Charts
47	-------------------
48	Multi-series Column 2D
49	Multi-series Column 3D
50	Multi-series Line 2D
51	Multi-series Bar 2D
52	Multi-series Area 2D
53
54	Stacked Charts
55	--------------
56	Stacked Column 3D
57	Stacked Column 2D
58	Stacked Bar 2D
59	Stacked Area 2D
60
61	Combination Charts
62	------------------
63	Multi-series Column 2D + Line - Dual Y Axis
64	Multi-series Column 3D + Line - Dual Y Axis
65
66	Financial Charts
67	----------------
68	Candlestick Chart
69
70	Funnel Chart
71	------------
72	Funnel Chart
73
74	Gantt Chart
75	-----------
76	Gantt Chart
77
78
79	Settings
80	--------------------------------------------------------------------------------
81	There are a large number of graph settings that can be set, and they vary depending
82	on the type of graph. Check out the FusionCharts documentation for a complete list
83	http://www.fusioncharts.com/free/docs/?gMenuItemId=19
84
85	If you do not supply any values, sensible ones will be chosen by default.
86
87
88	Attributes
89	--------------------------------------------------------------------------------
90	A list of extra settings as listed below:
91	'callback' The name of a fusionchart callback to be called when a bar on a graph is clicked.
92	The data in the graph will be updated with the data provided by callback function.
93
94	'callback_type' The type of callback FUSIONCHART_QUERY or FUSIONCHART_ARRAY
95	'color' An array of hex colors WITHOUT a # infront
96	'trendline' An associative array specifying properties of a trendline/s (all properties are optional)
97	'startvalue' The Y value of the line (starting point)
98	'endvalue' The Y value of the line (end point)
99	'displayvalue' Text to display beside the line
100	'color' Color of the line
101	'thickness' Thickness of the line
102	'istrendzone' Whenther the startvalue and endvalues define a line (0) or an area (1)
103	'showontop' Display the line on top of the bars (1) or behind the bars (0)
104	'alpha' Transparency of the trend line (0-100)
105
106
107	Notes
108	--------------------------------------------------------------------------------
109	When using a SQL query to provide data, the fields that are returned must have specific names:
110	In the case of Single Series Charts and Funnel Charts: name and value
111	In the case of Multi-series Charts and Stacked Charts: category, series, and value
112	In the case of Combination Charts: category, series, axis ("P" or "S"), and value
113
114	Example 1: Data provided by a SQL query
115	--------------------------------------------------------------------------------
116	function fusioncharts_example1() {
117	return fusioncharts_render(FUSIONCHART_QUERY, 'example1');
118	}
119
120	function example1_fusionchart_callback($args = NULL) {
121	$query = "SELECT t.name AS name, COUNT(*) as value FROM {term_data} t JOIN {term_node} tn ON t.tid = tn.tid WHERE t.vid=2 GROUP BY t.tid";
122	$type = 'Column 3D';
123	$settings = array('Caption' => 'Sample chart using the API and a query to generate the data');
124	$attributes = array();
125	$width = 500;
126	$height = 300;
127
128	return array($query, $type, $settings, $attributes, $width, $height);
129	}
130
131	Example 2: Data provided by a multi-dimensional array
132	--------------------------------------------------------------------------------
133	function fusioncharts_example2() {
134	return fusioncharts_render(FUSIONCHART_ARRAY, 'example2');
135	}
136
137	function example2_fusionchart_callback($args = NULL) {
138	$data = array(array('Cat', 1),
139	array('Dog', 2),
140	array('Pig', 3),
141	array('Mouse', 4),
142	);
143	$type = 'Column 3D';
144	$settings = array('Caption' => 'Sample chart using the API and sample data');
145	$attributes = array('callback' => 'example2',
146	'callback_type' => FUSIONCHART_ARRAY,
147	'color' => array('121212', 'ff0000'), //no # in front of color
148	'trendline' => array(
149	'startvalue' => 5,
150	'displayvalue' => 'Test',
151	'color' => '0000ff'
152	)
153	);
154	$width = 500;
155	$height = 300;
156
157	return array($data, $type, $settings, $attributes, $width, $height);
158	}