FusionCharts Knowledge Base

Glossary | | Favorites | Login

Search the Knowledge Base


[Advanced Search]

Browse by Category



What are the FusionCharts JavaScript API Functions?

FusionCharts JavaScript class API provides a number of functions to ease implementation. The list below shows details on each function :

API Method signature Purpose Example and what it returns?
JavaScript global functions
FusionCharts( chartId: string ) This function helps in accessing the JavaScript Object reference of a chart. A reference of a chart is necessary to perform all available API functions, use all available properties and listen to events.

When a chart-id is passed, it tries to return (if available) the reference of the instance of the FusionCharts object.

This is same as FusionCharts.items[] static array which also provides the reference of the chart object. 		It returns the chart object reference which you can use to call all API functions, use API all properties and listen to API events.

var chartReference = FusionCharts( "myChartId" );

getChartFromId ( chartId: string ) This function helps in accessing the JavaScript reference of a chart.  Same as FusionCharts() static function.

getChartFromId is deprecated.

 It returns the chart object reference which you can use to call all API functions, use API all properties and listen to API events.

var chartReference = getChartFromId( "myChartId" );
 
FusionCharts class - static functions
getObjectReference ( chartId: string ) This function helps in accessing the HTML Object reference of a chart. HTML Object is the actual chart object that physically gets rendered on the web page. The HTML object helps in direct communicate between the chart and JavaScript.

It is recommended not to use this function unless absolutely needed. 		Returns the HTML object that has been rendered.
In case of Flash renderer, this will return the reference to the HTML node where the SWF is rendered.


var chartHTMLReference =
FusionCharts.
getObjectReference ( "myChartId" );
setCurrentRenderer(renderer: string) Sets the renderer for all the charts. Presently you can pass either 'javascript' or 'flash' as the value of renderer parameter.
All the charts that get rendered, after this function call, will abide by this setting. 		FusionCharts.
setCurrentRenderer
('javascript');
_fallbackJSChartWhenNoFlash() Sets the current renderer as 'javascript' when Flash Player is not detected. FusionCharts.
_fallbackJSChartWhenNoFlash();
render ( chartParameters: Object )

or

render ( swfUrl, chartId , width, height, renderAt, dataSource, dataFormat, otherParameters: Object )

or

render ( chartParameters: mixed )
This function acts as a compact constructor for FusionCharts. It is a static function that helps rendering a chart using a single line of code.

It can take an Object as parameter containing all chart parameters mentioned here.

It can take linear string parameters (second example on right) as listed below:
  • swfUrl : Path to the chart swf file
  • id : DOM id to be set to the chart
  • width : Width of the chart
  • height : Height of the chart
  • renderAt : Container HTML element's (normally a DIV) Id or HTMLNode object where the chart would be rendered
  • dataSource : XML or JSON chart data. It can be an Url for XML or JSON, it can be XML or JSON in string or it can be a JSON object
  • dataFormat : Defines the format of the dataSource.
    • It is xmlurl when data source is an url to XML data
    • It is xml when the data source is an XML String
    • It is jsonurl when data source is an url to JSON data
    • It is json when the data source is a JOSN String or JSON object
  • otherParameters : It contains other chart parameters mentioned earlier in this article.

Additionally, it can take a mixture of linear parameters and an Object parameter at the end. The linear parameters should be in order. You can pass any one or more (up to no. 7 in the list above) linear parameters before you can pass the Object parameter. See the third example on right.

NOTE: You must pass the values for swfUrl, dataSource and dataFormat to render a chart. The chart will fail to render if any one of these parameters are missing.

This function fires up the chart rendering processes. Hence, a number of events are fired after this function call. The events are listed in sequence below:

  • Loaded ( or FC_Loaded )
  • DataLoadRequested
  • DataLoadCancelled
  • BeforeDataLoad
  • DataLoaded ( or FC_DataLoaded )
  • Rendered ( or FC_Rendered )
  • DrawComplete

On various issues when chart does not get rendered these error events are fired:

  • NoDataToDisplay (FC_NoDataToDisplay)
  • DataLoadError (FC_DataLoadError)
  • DataXMLInvalid (FC_DataXMLInvalid)
It returns a javascript chart object.

e.g.

var myChart = FusionCharts.render( { swfUrl : "FusionCharts/Column3D.swf", id : "myChartId", renderAt : "chartContainer", dataSource : "Data.xml" } )

or

var myChart = FusionCharts.
render( "FusionCharts/Column3D.swf", "myChartId", "400", "300", "chartContainer", "Data.xml" , "xmlurl" );

or

var myChart = FusionCharts.
render( "FusionCharts/Column3D.swf", "myChartId", "400", "300", "chartContainer", {dataFormat : "xmlurl", dataSource : "Data.xml" });

addEventListener ( event:string, listener: function ) This function acts as advanced event registration model. You give it two arguments: the event type or name of the event and the function to be executed.

This function, when called as static method using FusionCharts.addEventListener(), registers the global events of all the charts present in a page.

In the listener argument you can pass a named-function or the name of a function (see example at the top on right column) which will listen to the event or you can directly define an anonymous function as the argument (see example at bottom on the right column).
It returns nothing.

Example:

FusionCharts.
addEventListener ( "Rendered", doSomething )

or

FusionCharts.
addEventListener ( "Rendered", function(e,p) { alert( e.sender.id ); } )
removeEventListener ( event:string, listener: function ) This function removes a named event-listener function for a particular event that was defined using addEventListener. This function when called as static method using FusionCharts.removeEventListener() removes a named events-listener from all the charts on a page.

The name of the event type is passed as the first parameter.

The second parameter is the name of the function which was added as the event listener for that event by addEventListener 		It returns nothing.

Example:

FusionCharts.
removeEventListener ( "Rendered", doSomething )
 
FusionCharts class - constructor
FusionCharts This is the constructor method of FusionCharts JavaScript class. It allows you to create new instance of FusionCharts using legacy set of linear parameters as well as a Object parameter.

It can take an Object as parameter containing all chart parameters. See, first example on right.

Chart Parameters

It can take linear string parameters (second example on right) as listed below:
  • swfUrl : Path to the chart swf file
  • id : DOM id to be set to the chart (optional)
  • width : Width of the chart  (optional - default is 400)
  • height : Height of the chart (optional - default is 300)
  • debugMode : Sets the chart debug window on. Can take "0" or "1". "1" sets debug window on. T(optional - default value is "0")
  • registerWithJS : Allow chart to communicate with JavaScript. This should be set to "1". This parameter is deprecated and is kept for backward compatibility issues. (optional)
  • bgColor : A String containing hex coded color value. This sets the color of the flash player's background on which a chart gets drawn. This background color is not same as the background color of a chart. This background is visible while showing chart messages or when chart's bgAlpha is set to less than 100. (optional - default value is "#FFFFFF" i.e., white)
  • scaleMode : Flash player's mode of scaling a chart. "NoScale" should be the value. There are other options like showAll, ExactFit, noBobrder. But these are not supported and might result into distorted charts.
      (optional)
  • lang :Sets the language. The It presently supports English only. The value is "EN". (optional)
  • detectFlashVersion :Set to "1" to make FusionCharts Class check whether Flash Player 8 is present in the Browser. (optional - Default value is "0' )
  • autoInstallRedirect :Set to "1" with detectFlashVersion set to "1" and FusionCharts redirects to Flash Player installation page of Adobe's Web site. (optional - default is "0')

Apart from these parameter you can add additional parameters to the object based parameter. Those additional parameters are :

  • renderAt : Container HTML element's (normally a DIV) Id or HTMLNode object where the chart would be rendered
  • dataSource : XML or JSON chart data. It can be an Url for XML or JSON, it can be XML or JSON in string or it can be a JSON object
  • dataFormat : Defines the format of the dataSource.
    • It is xmlurl when data source is an url to XML data
    • It is xml when the data source is an XML String
    • It is jsonurl when data source is an url to JSON data
    • It is json when the data source is a JOSN String or JSON object
  • renderer : Sets the chart renderer engine. Its value can be 'flash' or 'javascript'. The default value is flash which generated Flash based charts. When set to javascript FusionCharts JavaScript class renders pure JavaScript based charts.

Additionally, it can take a mixture of linear parameters and an Object parameter at the end. The linear parameters should be in order. You can pass any one or more (up to no. 11 in the list above) linear parameters before you can pass the Object parameter. See the third example on right.

NOTE: You must pass the values for swfUrl, dataSource and dataFormat to render a chart. The chart will fail to render if any one of these parameters are missing.

It returns a javascript chart object.

e.g.

var myChart = new FusionCharts( { swfUrl : "FusionCharts/Column3D.swf", id : "myChartId", renderAt : "chartContainer", dataSource : "Data.xml" } )

or

var myChart = new FusionCharts ( "FusionCharts/
Column3D.swf", "myChartId", "400", "300" );

or

var myChart = new FusionCharts ( "FusionCharts/
Column3D.swf", "myChartId", "400", "300", "chartContainer", {dataFormat : "xmlurl", dataSource : "Data.xml" });

 
FusionCharts class - instance functions
configure(name:string , value:string)
or
 configure(configurations: Object)		 Sets a chart configuration before rendering the chart. You can mainly use this function to set chart messages or grid parameters using this function.
The name of the configuration and the value of the configuration are passed as parameters. See first example on the right.You can also pass a collection of configurations as Object to the function. The parameter object would contain name and value pairs of the configuration name and the corresponding values. See second example on the right.  		 myChart.configure("ChartNoDataText",
"Please select a record above");
or
myChart.configure(
{ "ChartNoDataText" : "Please select a record above" , "InvalidXMLText" : "Please validate data" });
addVariable(name:string , value:string) Sets a chart configuration before rendering the chart. You can mainly use this function to set chart messages or grid parameters using this function.
addVaraible is deprecated.
myChart.addVariable( "ChartNoDataText",
 "Please select a record above" );
render ( renderAt: String )

or

render ( renderAt: HTMLNode )		 This functions renders a chart inside a container element reference to which has passed as a parameter of this function.

This function is called after the chart gets instantiated as JavaScript object new FusionCharts. It takes a string containing the id of a HTML container Element like DIV or SPAN.

You can also pass the HTMLNode object of a container element to this function.

This function fires the chart rendering process. Hence, a number of events are fired after this function call. The events are listed in sequence below:

  • Loaded ( or FC_Loaded )
  • DataLoadRequested
  • DataLoadCancelled
  • BeforeDataLoad
  • DataLoaded ( or FC_DataLoaded )
  • Rendered ( or FC_Rendered )
  • DrawComplete

On various issues when chart does not get rendered these error events are fired:

  • NoDataToDisplay (FC_NoDataToDisplay)
  • DataLoadError (FC_DataLoadError)
  • DataXMLInvalid (FC_DataXMLInvalid)

myChart.render( "chartContainer");


or


myChart.render( document.getElementById ("chartContainer") );
setXMLUrl ( Url: String ) Sets or changes the XML data of the chart to a specified Url. The Url has to be relative to the web page where the chart is deployed. By default, cross-domain Url-s are not allowed. Again, absolute Url-s are not allowed. myChart.render( "chartContainer")
setXMLData ( XML: string ) Changes the data of the chart to the specified XML string.

Note of caution: When specifying XML as string, please make sure that there are no conflicts in quotes between the JS function call and the quotation mark used to enclose attributes in XML string. 		myChart.render( "chartContainer")
setJSONUrl ( Url: String ) Sets or changes the data of the chart to a specified Url. The Url has to be relative to the web page where the chart is deployed. By default, cross-domain Url-s are not allowed. Again, absolute Url-s are not allowed. myChart.render( "chartContainer")
setJSONData ( JSON:Object )
or
setJSONData ( JSON:String ) 		Changes the data of the chart to the specified JOSN string or JSON Object.

Note of caution: When specifying JOSN as string, please make sure that there are no conflicts in quotes between the JS function call and the quotation mark used to enclose JSON properties and values. 		myChart.render( "chartContainer")
setChartDataUrl ( Url:String, dataFormat: string ) Sets or changes the data of the chart to a specified Url. The Url has to be relative to the web page where the chart is deployed. By default, cross-domain Url-s are not allowed. Again, absolute Url-s are not allowed.

This function takes two parameters. The first is Url of the data. The second is the dataFormat in string, which can be "xml" or "json". 		myChart.render( "chartContainer")
setChartData ( dataSource: string, dataFormat: string ) Sets or changes the data of the chart.

This function takes two parameters. The first is dataSource of the data. The second is the dataFormat. The data source can be a Url to XML source, Url to JSON source, XML as string, JSON as string and JSON as object. Hence, to identify the format correctly dataFormat is passed as second parameter.

dataFormat : Defines the format of the dataSource.
  • It is xmlurl when data source is an url to XML data
  • It is xml when the data source is an XML String
  • It is jsonurl when data source is an url to JSON data
  • It is json when the data source is a JOSN String or JSON object
myChart.render( "chartContainer")
setDataURL ( Url:string ) This function helps in setting or updating chart XML data for chart from Url. This function takes a Url as string.

setDataURL is deprecated.

 myChart.render( "chartContainer")
setDataXML ( dataSource: string ) This function helps in setting or updating chart XML data for a string.

setDataXML is deprecated.

 myChart.render( "chartContainer")
getChartData( dataFormat: string ) This function returns chart data as per dataFormat provided as parameter. When xml is passed as dataFormat it provides XML data as string. When json is passed as dataFormat, data is returned as JSON Object. myChart.render( "chartContainer")
getXMLData() Returns the XML data of chart as string.
myChart.render( "chartContainer")
getJSONData() Returns the JSON data of chart as Object.
myChart.render( "chartContainer")
getDataAsCSV() Returns the data of chart as CSV string. The output CSV string can be configured using XML parameters. String representing data of chart in CSV format. myChart.render( "chartContainer")
getXML() Returns the XML data of chart.

getXML is deprecated.

 myChart.render( "chartContainer")
getChartAttribute() Returns the value of the attribute as specified in chart XML Node or "chart" property of JSON data.

Value of the attribute; or "null" if the attribute was empty or not found in XML/SON.		 myChart.render( "chartContainer")
setChartAttribute ( name:string , value:string )

or

setChartAttribute ( AttributeCollection: Object)

 Sets chart attribute and update the chart with the new value. It takes two parameters. The name of the attribute and the value of the parameter.
The name suggests chart's root properties (also known as "chart attributes" which are passed through <chart> element in chart XML data or through chart property in chart's JSON data)

You can also pass a collection of attribute name and value pairs to the function by passing them as an Object. See second example on the right. 		myChart.
setChartAttribute ( "caption" , "Latest sales report" );

or

chartReference.
setChartAttribute( { "palette" : "2", paletteColors : "ACBF72", useRoundEdges : 1 } );
configureLink ( objConfiguration: Object, level:Number )

or

configureLink ( arrConfiguration: Array )		 Through this function you can pass all your desired configurations for the LinkedCharts. You can pass all the properties that a FusionCharts constructor function accepts. Those chart properties will be applied to the LinkedCharts. If not provided, the LinkedCharts will inherit properties from the parent chart.

Additionally, you can also configure the overlay button using overlayButton property. These settings also go as another object.

configureLink function can accept parameters in either of two formats :
  • As two separate parameters, the first parameter is an an Object containing all configurations (chart and overlayButton). The the second parameter accepts a number which denotes the level being configured. The first drill-down level is 0 (zero).
  • As a single dimensional indexed array each element of which is an object containing all chart and overlay button related configurations. Each drill down level is denoted by the index of the array where the first level is Zero. So, the Object in a particular array index actually applies those settings to the level number which is equal to array index number.

Overlay Button settings:

The following are the properties that we can pass as settings for overlay buttons:

  • show : (true/false) whether to show the overlay button
  • message: String contain the text for close button
  • bgColor: Hex coded background color of the overlay button
  • borderColor: Hex coded border color of the overlay button
  • font : Name of the font
  • fontColor : Hex coded color of the overlay button's text
  • fontSize :  Size of the font of overlay button text
  • bold : (true/false) Whether the overlay button's text will be bold
  • padding :padding around the overlay button in pixels 

myChart.configureLink(
 {
 swfUrl: 'Charts/Bar2D.swf',
 width: '30%',
 
 overlayButton:
 { 
 message: ' x ',
 bgColor:'999999',
 borderColor: 'cccccc'
 }
 },
0);
resizeTo ( width:String, height:String ) This function resizes an existing chart. You can pass the width and height values in percentage or as pixel values (without the px suffix) myChart.resizeTo( "500", "400" )

or

myChart.
resizeTo( "80%", "100%" )
exportChart( exportSettings: Object) Calls the export chart routine to save the chart as PDF/image. exportSettings object here contains over-riding parameters to over-ride the export parameters initially specified in XML.

In cases while saving a chart to a server location a callback function is invoked to convey status of export. 		myChart.
exportChart( { exportFormat : 'jpg'} )
print() Prints a chart.
 myChart.print()
clone ( [chartParams: Object] ) The function allows you to duplicate a FusionCharts JavaScript object and uses it's settings to create another chart.

The function can optionally take an object as parameter. The object can contain chart settings which would override the existing settings of the source chart before it gets cloned.

The function returns an instance of FusionCharts JavaScript object. 		var newChart = myChart.clone()

or

var newChart = myChart.clone( { swfUrl : 'Area2D.swf' } )
dispose() You can remove a chart instance from page and memory. using dispose() function.

Additionally, the function will raise BeforeDispose event prior to removing a chart and disposed after the chart has been removed.		 myChart.dispose()
chartType() This function returns the chart type or chart alias of the rendered by the FusionCharts JavaScript object.

Please note that the alias value is dependent on the chart swf file-name. The alias is built removing .swf extension and all extra path information from the src value of the chart loaded.		 var strCharType = myChart.chartType()
isActive() This function checks whether a FusionCharts swf is visible and active. Returns true or false. var strCharType = myChart.isActive()
hasRendered() This function returns Boolean value indicating whether the chart has finished rendering.

hasRendered() is deprecated.

 var strCharType = myChart.hasRendered()
signature() It returns a string representing the signature of chart. For FusionCharts v3 charts, it's "FusionCharts/3.2" var strCharType = myChart.signature()
 
FusionCharts.printManager class - static functions
configure ( configuration: Object ) This function configures print Manager. It takes an Object. In this object you can pass two properties:
enabled and message.

This function needs to be called before you call FusionCharts.printManager.enabled()

The enabled property sets the Print Manager on or off by setting the value to true or false, respectively.

The message property takes a string which gets displayed in place of the printable charts until the charts are prepared for printing. The default value is : 'Chart is being prepared for print.'


 FusionCharts.
printManager.
configure( { enabled: true, message : 'wait please...'} )
enabled( on:Boolean ) This function initializes the print manager if true is passed as the parameter. Once this function is called, the print manager starts preparing all the charts in a page for managed print. FusionCharts.printManager.enabled(true)
managedPrint() Print the chart once the print manager completes its process of making the chart ready for managed print. After the function being called, it  waits till the charts become ready. FusionCharts.printManager.managedPrint()
isReady() Returns true when the print manger has completed the process of making all charts in a page ready for print. var goPrint = FusionCharts.
printManager.isReady()
  More examples

chartJSInstance.isActive()

You can check whether a chart is visible and active after its been rendered using isActive() function. Note that this is applicable only using FusionCharts JavaScript Object. 

var whetherChartActive = FusionCharts("myChartId").isActive();

or

var whetherChartActive = FusionCharts.items["myChartId"].isActive();

This function returns a boolean value true when the chart is visible and is active. In other cases it returns false.

chartObject.hasRendered()

You can check whether a has completed rendering and is now ready to perform other interactive actions. hasRendered() function is available in both FusionCharts JavaScript Object and FusionCharts HTML Object. 

var whetherRendered = FusionCharts("myChartId").hasRendered();
or
var whetherRendered = FusionCharts.items["myChartId"].hasRendered();
or
var whetherRendered = getChartFromId("myChartId").hasRendered();
or
var whetherRendered = FusionCharts.getObjectReference("myChartId").hasRendered();

This function returns a boolean value true if called after the the chart has completed rendered. You can also checkout the drawcomplete, rendered, loaded events to track this status.

This function has been deprecated.

chartObject.signature()

This property returns a string representing the signature of the chart. For FusionCharts it's "FusionCharts/3.2".  This function is available in both FusionCharts JavaScript Object and FusionCharts HTML Object. 

var FCJOSignature = FusionCharts("myChartId").signature() ; 
// returns "FusionCharts/3.2"

var FCHOSignature = FusionCharts.getObjectReference("myChartId").signature() ; 
// returns "FusionCharts/3.2"

chartJSInstance.chartType()

This function returns the chart type or chart alias of the rendered by the FusionCharts JavaScript object. Please note that the alias value is dependent on the chart swf file-name. ยป the alias is built removing .swf extension and all extra path information from the src value of the chart loaded. This is only applicable in FusionCharts JavaScript object. 

var cType = FusionCharts("myChartId").chartType() ;
// returns "MSColumn3D" when MSColumn3D.swf is loaded
  Dispose a chart

You can remove a chart instance from page and memory. You need to use dispose() function of the chart's JavaScript Object. The function will take care of the rest. Additionally, the function will raise beforedispose event prior to removing a chart and disposed after the chart has been removed. The code is fairly simple and does not require to listen to the events in simple implementation.

FusionCharts("myChartId").dispose();
  Duplicate a chart

The function clone() allows you to duplicate a FusionCharts JavaScript object and uses it's settings to create another chart. The function returns an instance of FusionCharts JavaScript object. The function can optionally take an object as parameter. The object can contain more chart settings which would override the existing settings of the source chart before it gets cloned.

var newChart = FusionCharts("myChartId").clone();

or

var newChart2 = FusionCharts("myChartId").clone(
{ swfUrl : "FusionCharts/Pie3D.swf" }
);
 

Related Articles

No related articles were found.

Attachments

No attachments were found.

Visitor Comments

Article Details

Last Updated
22nd of October, 2010

Would you like to...

Print this page  Print this page

Email this page  Email this page

Post a comment  Post a comment

 Subscribe me

Subscribe me  Add to favorites

Remove Highlighting Remove Highlighting

Edit this Article

Quick Edit


User Opinions

100% thumbs up 0% thumbs down (15 votes)

How would you rate this answer?


Thank you for rating this answer.

Continue
Products
See It
Know More
Get It
Resources

info@fusioncharts.com

© , FusionCharts. All rights reserved.Privacy Policy