FusionMaps XT uses the FusionCharts jQuery plugin that takes care of all the products of the FusionCharts Suite XT including FusionMaps XT.
FusionCharts jQuery plugin provides a number of jQuery methods. The list below shows details on each function:
| Map Rendering functions |
| insertFusionCharts( chartConfigurations : Object) |
Renders maps inside HTML elements. The HTML elements need to be selected using jQuery selector. In case, multiple HTML elements are selected using the jQuery selector, a map will be rendered inside each selected HTML element. All existing elements inside the selected elements will be replaced by the rendered maps.
The method returns the original jQuery selection to allow chaining of other jQuery methods.
An object (set of key or value pairs) passed as parameter contains map configurations. The possible configurations are:
| swfUrl: Path (as string) to the map SWF file. You can get the list of map SWF file names from List of maps page. |
| type:Alias of the map. You can get the list of map alias from List of maps page. This property is used as an alternative of swfUrl. By default, a JavaScript map is rendered when type property is specified (unless renderer is explicitly with 'flash') |
| id: Sets the DOM Id of the map. The value is provided as string. (optional) |
| width: Width of the map (optional - default is 400). The value is provided as number if the width is in pixels or as string if the width is to be set in percentage (for example, "50%") |
| height: Height of the map (optional - default is 300). The value is provided as number if the height is set in pixels or as string if the height is to be set in percentage (for example, "50%") |
| dataSource: XML or JSON map 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 map renderer engine. Acceptable values are 'flash' and 'javascript'. The default value is automatically selected depending on the availability and support of Flash player. When set to javascript FusionCharts JavaScript Class renders pure JavaScript maps. (optional) |
wmode: Allows the map's base background to become transparent or opaque. The acceptable values and their usage are as follows:
- transparent - Renders the map's base with a transparent background. Additionally, one needs to set bgAlpha attribute in map's XML/JSON to '0,0' to make the map transparent.
- opaque - Renders the map's base to have an opaque background. One can set color this opaque background using bgColor property.
- window - Only for Flash maps, this mode renders Flash maps in a separate layout on top of a Web page.
Note:Map's base background is the first background layer on which map messages are shown and all map objects are rendered. While rendering, another background layer is drawn on top of this base background whose cosmetic properties can be customized through XML/JSON.
This property is optional and the default value is opaque.
|
| bgColor: This sets the color of the map's base background on which a map is drawn. The color is passed as a string containing hex coded color value.
This property is optional and the default value is "#FFFFFF", that is, white.
Note:Map's base background color is not same as the background color of a map (set through XML/JSON). The base background color is visible while showing map messages or when wmode is set to opaque and map's bgAlpha is set to less than 100.
|
| scaleMode: Flash player's mode of scaling a map. NoScale is the default value. There are other settings namely, showAll, ExactFit, noBorder. But these are not supported and might result in distorted maps. (optional) |
| lang: Sets the language for map 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 redirect to Flash Player installation page of Adobe's website. (optional - default is "0") |
| debugMode: Sets the debug window on. Can take "0" or "1". When set to "1", the map shows a debug window over itself. (optional - default value is "0") |
|
$("#mapContainer").insertFusionCharts({
swfUrl: "Maps/FCMap_World.swf",
dataSource: "Data.xml", dataFormat: "xmlurl",
width: "400", height: "300" })
|
| appendFusionCharts( chartConfigurations : Object) |
Renders and inserts maps at the end of HTML elements. The HTML elements need to be selected using jQuery selector. In case, multiple HTML elements are selected using the jQuery selector, a map will be rendered inside each selected HTML element. All existing elements inside the selected elements will be preserved.
The method returns the original jQuery selection to allow chaining of other jQuery methods.
An object (set of key or value pairs) passed as parameter contains map configurations. The possible configurations are listed in the Map configurations table. |
$("#mapContainer").insertFusionCharts({
swfUrl: "Maps/FCMap_World.swf",
dataSource: "Data.xml", dataFormat: "xmlurl",
width: "400", height: "300", id: "myMapId" })
|
| prependFusionCharts( chartConfigurations : Object) |
Renders and inserts map at the beginning of HTML elements. The HTML elements need to be selected using jQuery selector. In case, multiple HTML elements are selected using the jQuery selector, a map will be rendered inside each selected HTML element. All existing elements inside the selected elements will be preserved.
The method returns the original jQuery selection to allow chaining of other jQuery methods.
An object (set of key or value pairs) passed as parameter contains map configurations. The possible configurations are listed in the Map configurations table. |
$("#mapContainer").appendFusionCharts({
swfUrl: "Maps/FCMap_World.swf",
dataSource: "Data.xml", dataFormat: "xmlurl",
width: "400", height: "300", id: "myMapId" })
|
| cloneFusionCharts( callback:function, [cloneConfigurations : Object] ) |
This method makes copy of existing maps and passes the list of cloned map objects to a function for further processing. The method looks for all the maps in jQuery selected elements and clones them.
An array of cloned map objects is passed to a callback function whose name or reference needs to be passed as a mandatory parameter to cloneFusionCharts method. One can also use an anonymous function as the callback function.
Before cloning of existing maps, one can optionally overwrite some of the configurations of the existing maps. To do this, one needs to pass an object (set of key or value pairs) containing map configurations as cloneConfigurations parameter. The possible cloneConfigurations are listed in the Map configurations table.
|
$(“#mapContainer”).cloneFusionCharts(callbackFn, {width:300, height: 400})
or
$("#leftPanel").cloneFusionCharts( function() { $("#rightPanel").insertFusionCharts(this[0]); }, { renderer: "javascript" } );
|
| updateFusionCharts( updateConfigurations : Object) |
This method helps in updating map configurations of an existing map at run-time. Barring id, you can re-configure swfUrl, dataSource, dataFormat, width, height, renderer, bgColor, debugMode, scaleMode etc. of existing maps.
The possible updateConfigurations are listed in the Map configurations table. Please note that id configuration cannot be passed to updateConfigurations parameter.
updateFusionCharts method is applied on HTML elements selected using jQuery selector. It finds all the maps rendered in the selected elements. It updates all these maps with the values passed through the updateConfigurations parameter.
Please note that the maps thus updated are actually re-drawn with the new configurations. |
$("#mapContainer").updateFusionCharts( {"dataSource": NewMSXMLAsString, "dataFormat": "xml", "swfUrl" : "FCMap_World.swf"}) |
| attrFusionCharts( chartAttribute : string)
or
attrFusionCharts( chartAttribute:string, newValue:string)
or
attrFusionCharts( chartAttributes : Object) |
Using this method one can dynamically read or update map's root properties (also known as "map attributes" which are passed through <map> element in map XML data or through map property in map's JSON data) on-the-fly. This feature will come handy when one wishes to change the map titles, theme colors, number formatting or scaling setup, divisional line and grid configurations and other functional and cosmetic features of existing maps.
The method is applied on HTML elements which are selected using jQuery selector. It finds all the maps rendered in the selected elements and retrieves the value of a map parameter from those maps or updates those maps with new parameter values.
This method returns the value of a map attribute (of an existing map) if the name of the map attribute is passed to the method as a single string parameter - chartAttribute.
If a value is passed as a second parameter (newValue) to the method along with the name of the map attribute through chartAttribute (as first parameter), the map gets updated with the new parameter value.
The attrFusionCharts method also helps in passing a set of key(attribute-name)/value pairs (JavaScript Object) to apply multiple map attributes to existing maps at run-time. The method here will accept a single Object parameter which will contain the new settings.
Please note that when the maps are updated with selective configurations and properties, internally, FusionCharts re-draws the entire map. |
var oldCaption = $("#mapContainer" ).attrFusionCharts( "fillColor")
or
$("#mapContainer" ).attrFusionCharts( "fillColor", "FF00FF" )
or
$("#mapContainer" ).attrFusionCharts( {"bgAlpha": "50", "bgColor": "D977B7"})
|
| disposeFusionCharts() |
You can remove a chart instance from page and memory using disposeFusionCharts()function.
Additionally, the function will raise BeforeDispose event prior to removing a chart and disposed after the chart has been removed. |
$("#chartContainer").disposeFusionCharts(); |
| |
| Selector |
| :FusionCharts |
A custom jQuery selector :FusionCharts which helps in selecting all the maps rendered using FusionCharts jQuery plugin or using FusionCharts JavaScript Class. You can use this custom selector as a conventional jQuery selector. |
$("div :FusionCharts").attrFusionCharts( { fillColor: "FF00FF" } )
or
$("div :FusionCharts").attrFusionCharts( { fillColor: "FF00FF" } );
or
$("#topRow :FusionCharts").attrFusionCharts( "bgColor", "ecdecd")
or
$(".myFusionCharts :FusionCharts").attrFusionCharts( { showCanvasBorder:1 )
or
$("#bottomRow").find(":FusionCharts").attrFusionCharts( { canvasborderColor : "008800" } )
or
$("span.myFusionCharts").find(":FusionCharts").attrFusionCharts( {bgColor : "ecdecd", showCanvasBorder:1, canvasborderColor:"880000"} )
or
$("div#dashboard #upper:visible").find(":FusionCharts").attrFusionCharts( {bgColor : "ecdecd", showCanvasBorder:1, canvasborderColor:"880000"} )
|
| Event handling |
| bind( eventType : String, eventHandler : function ) |
Adds an event handler function to all FusionCharts related events. The event handler needs to be attached to the container HTML elements of the FusionCharts objects.
As the first parameter, the method takes the name of the event (through eventType parameter) .The list of FusionCharts event names or event types can be derived from FusionMaps XT and JavaScript > API > Events page. The event names used here are similar to those listed in the "Name (Advanced model)" column of the list of events in the Events page. One will just need to prefix the listed event names with "fusionmaps". This is done to avoid conflict with the pre-existing jQuery event types having same names, for example, the event name Loaded (as listed in the Events page) needs to be passed as "fusionmapsloaded".
The second parameter eventHandler accepts the name or reference to the event handling function. You can also directly create anonymous function instead. The parameters passed to the event handler function for each event are also same as stated in the Events page. |
$("#mapContainer").bind( "fusionchartsdrawcomplete",
function ( eventObject, argumentsObject) {
alert("Map named " + eventObject.sender.id + " has completed map drawing." );
}
) |