You are viewing documentation for an older version. For current documentation - click here.

FusionWidgets XT uses FusionCharts jQuery plugin that takes care of all the products of FusionCharts XT Suite including FusionWidgets XT.

FusionCharts jQuery plugin also allows you to configure an existing chart. At run-time, you can update chart data, chart size, chart type, rendering engine (flash/javascript) of an existing chart. You can also dynamically update chart's root properties (also known as "chart attributes" which are passed through the <chart> element in chart XML data or through chart property in chart's JSON data) on-the-fly. This feature will come handy when you wish to change the chart titles, theme colors, number formatting or scaling setup, divisional line and grid configurations and other functional and cosmetic features of an existing chart. While the API allows you to update selective configurations and properties, internally, FusionWidgets XT re-draws the entire chart.

To aid your understanding of this section, we recommend you to go through the Overview page of FusionCharts jQuery plugin

The following two methods of FusionCharts jQuery plugin needs to be used to achieve these:

In the following sections of this page we go through some use-cases to showcase how to use these methods.

Code examples and data files discussed in this section are present in Download Package > Code > jQuery folder

Changing type of an existing chart

Using the updateFusionCharts method you can change chart type of an existing chart. This method accepts new configuration values for chart as a set of key/value pairs (JavaScript Object). To change the chart type, you need to change the value of the swfUrl configuration of an existing chart.

A code snippet is shown below:

$("#chartContainer").updateFusionCharts({"swfUrl": "Charts/Cylinder.swf"});

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using the jQuery selector. The updateFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. A new SWF file-name is set through swfUrl property of the parameter passed to the method. The charts rendered in the selections are re-rendered using the newly set SWF file-name.

The detailed list of acceptable chart-configurations which can be passed to the updateFusionCharts method are provided in the table below:

Chart configuration or property Description and acceptable value
swfUrl Path (as string) to the chart SWF file. You can get the list of chart SWF file names from Chart List page.
width Width of the chart  (optional - default is 400). The value is provided as number if the width is set in pixels or as string and if the width is to be set in percentage (e.g., "50%")
height Height of the chart (optional - default is 300). The value is provided as number if the height is set in pixels or as string and if the height is to be set in percentage (e.g., "50%")
dataSource XML or JSON chart data. It can be a URL for XML or JSON. It can also be a string containing XML or JSON object
dataFormat Defines the format of the dataSource.
  • Set it to xmlurl when data source is a URL to XML data
  • Set it to xml when the data source is an XML String
  • Set it to jsonurl when data source is a URL to JSON data
  • Set it to json when the data source is a JSON String or JSON object
renderer Sets the chart renderer engine. Acceptable values are 'flash' and 'javascript'. The default value is automatically selected depending on the availability and support of the Flash player. When set to javascript, FusionCharts JavaScript Class renders pure JavaScript charts. (optional)
bgColor This sets the color of the flash player's background on which a chart gets drawn. It is passed as a string containing hex coded color value. 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 is the default value. There are other settings namely, showAll, ExactFit, noBorder. But these are not supported and might result in distorted charts.  (optional)
lang Sets the language for chart messages. It presently supports only English. 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')
debugMode Sets the chart debug window on. Can take "0" or "1". When set to "1", the chart shows a debug window over itself. (optional - default value is "0")

While changing chart type, please make sure that the chart type which you are setting can accept the data of the existing chart or you are also changing the data of existing chart along with the chart type.

Changing data of an existing chart

The updateFusionCharts method can accept and apply multiple configurations passed to it. We will like to change the chart type as well as the data of an existing chart. To change data you need to provide fresh configurations through dataSource and/or dataFormat properties.

$("#chartContainer").updateFusionCharts({"dataSource": NewMSXMLAsString, "dataFormat": "xml", "swfUrl" : "Thermometer.swf"});

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. updateFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. A new SWF file-name is set through swfUrl property of the parameter passed to the method. The charts rendered in the selections are re-rendered using the newly set SWF file-name. Fresh data is also passed to the method and all the charts found in the selection are updated with the fresh data.

Updating real-time data

The streamFusionCharts method can accept and apply multiple configurations passed to it. We will like to enter a new values to multiple datasets.

$("#chartContainer").streamFusionCharts('&value=66|44');

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. streamFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. Two new values are set through value property of the parameter passed to the method. The values are separated using the '|' character. Multiple values are set for multiple datasets. There are various ways by which you can update real-time data. To know more please go through the Real-time jQuery API page.

Changing width and height of an existing chart

To change width and height of an existing chart, all you need to do is to pass width and height configuration to the updateFusionCharts method as shown below:

$("#chartContainer").updateFusionCharts({ width : 280, height : 200  });

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. updateFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements and set new width and height to these charts after re-rendering them.

Please note that you can pass the width and height values in either of the two formats:
  • If you wish to set chart size in pixels, you can pass the pixel value (without px suffix) as number to width or height properties, e.g., {width : 280, height : 200 }
  • If you wish to set chart size in percentage values (relative to the size of the chart's container HTML element), you need to pass the value as string with % as suffix, e.g., {width : "80%", height : "100%" }

Convert to JavaScript charts

Using the updateFusionCharts method, you can convert any Flash chart into JavaScript chart passing just a single configuration property - renderer: 'javascript'. The code snippet below will showcase with live example:

$("#chartContainer").updateFusionCharts({ renderer :'javascript'  });

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. The updateFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. The renderer setting is configured to the method having 'javascript' as the preferred renderer. The updateFusionCharts method re-renders the found charts using 'javascript' as the rendering engine.

Note : JavaScript charts use AJAX to load data from Data URL sources (XML/JSON files/streams). Many browser block AJAX data-loading when running from local file system (using file:/// protocol). Hence, a JavaScript chart will fail to render if it is run from local file system and if it uses Data URL method (i.e. loading data from XML/JSON files). It is recommended to use Data String method (XML data passed as string or JSON data passed as string or JSON object) while running the chart from local file system.
 
Using the attrFusionCharts to get the current title of a chart

The attrFusionCharts method helps in retrieving value of a "chart attribute".To achieve this, you need to pass the name of the attribute as string to the attrFusionCharts method. The code snippet below gets the value of the caption attribute of a chart:

 // Get the latest caption of the chart and show it as alert message
var oldCaption = $("#chartContainer").attrFusionCharts("caption");
alert("The existing title of the chart is "  + oldCaption);

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. The attrFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. The method is passed with a string parameter "caption". The method returns the value of the caption attribute of all the found charts.

All the chart attributes are listed under "<chart> element attributes" section of the XML Sheet of each chart.

Using attrFusionCharts to set a new title to a chart

The attrFusionCharts method also helps in applying or setting value of a "chart attribute".For this, you need to pass the name of the attribute and the new value to be set to attrFusionCharts method. The code snippet below sets a new title to an existing chart:

// Set a new caption of the chart [ updating a single attribute of the chart ]
$("#chartContainer").attrFusionCharts("caption": "Updated chart title");

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. The attrFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. The method is passed with two parameters, the name of the attribute (namely, "caption") and the new value to set. The method sets the "caption" attribute of all the found charts with the new value passed as the second parameter.

All the chart attributes are listed under "<chart> element attributes" section of the XML Sheet of each chart.

Setting a new color theme (using multiple chart attributes) through attrFusionCharts

The attrFusionCharts method also helps in passing a set of key(attribute-name)/value pairs (JavaScript Object) to apply multiple chart attributes to existing charts at run-time. The code snippet below shows how to set a different color theme to existing charts updating two chart attributes - palette and is2D:

// Set palette and paletteColors attributes [ updating multiple attributes of the chart ]
$("#chartContainer").attrFusionCharts({"palette": "5", "is2D": "1" });

See it live!

In the above code, the HTML elements with id - chartContainer, which contain charts, are selected using jQuery selector. The attrFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements.The method is passed with an Object containing two properties (chart attribute names - palette and is2D) and the respective values which will get reflected in the charts found by the method.

All the chart attributes are listed under "<chart> element attributes" section of the XML Sheet of each chart.