Retrieving and updating properties of maps using FusionCharts jQuery plugin | ||||||||||||||||||||||||||||
FusionMaps XT uses FusionCharts jQuery plugin that takes care of all the products of FusionCharts Suite XT including FusionMaps XT. FusionCharts jQuery plugin also allows you to configure an existing map. At run-time, you can update map data, map size, map type, rendering engine (flash/javascript) of an existing map. You can also dynamically 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 you wish to change the map titles, theme colors, number formatting or scaling setup, divisional line and grid configurations and other functional and cosmetic features of an existing map. While the API allows you to update selective configurations and properties, internally, FusionMaps XT re-draws the entire map. To aid your understanding of this section, we will 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. |
||||||||||||||||||||||||||||
Changing type of an existing map | ||||||||||||||||||||||||||||
Using the updateFusionCharts method you can change map type of an existing map. This method accepts new configuration values for map as a set of key or value pairs (JavaScript Object). To change map type, you will need to change the value of the swfUrl configuration of an existing map. A code snippet is shown below: $("#mapContainer").updateFusionCharts({"swfUrl": "Maps/FCMap_World.swf"}); In the above code, the HTML elements with ID - mapContainer, which contain maps, 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 maps rendered in the selections are re-rendered using the newly set SWF file-name. The detailed list of acceptable map-configurations which can be passed to updateFusionCharts method are provided in the table below:
While changing map type, please make sure that the map type which you are setting can accept the data of the existing map or you are also changing the data of existing map along with the map type. |
||||||||||||||||||||||||||||
Changing data of an existing map | ||||||||||||||||||||||||||||
The updateFusionCharts method can accept and apply multiple configurations passed to it. We will like to change map type as well as the data of an existing map. To change data you will need to provide fresh configurations through dataSource and/or dataFormat properties. $("#mapContainer").updateFusionCharts({"dataSource": NewMSXMLAsString, "dataFormat": "xml", "swfUrl" : "FCMap_World.swf"}); In the above code, the HTML elements with ID - mapContainer, which contain maps, 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 maps 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 maps found in the selection are updated with the fresh data. |
||||||||||||||||||||||||||||
Changing width and height of an existing map | ||||||||||||||||||||||||||||
To change width and height of an existing map all you will need to do is to pass width and height configuration to updateFusionCharts method as shown below: $("#mapContainer").updateFusionCharts({ width : 280, height : 200 }); In the above code, the HTML elements with ID - mapContainer, which contain map, 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 maps after re-rendering them. Please note that you can pass the width and height values in either of the two formats:
|
||||||||||||||||||||||||||||
Convert to JavaScript maps | ||||||||||||||||||||||||||||
Using the updateFusionCharts method, you can convert any map using Flash into JavaScript maps passing just a single configuration property - renderer: 'javascript'. The code snippet below will showcase with live example: $("#mapContainer").updateFusionCharts({ renderer :'javascript' }); In the above code, the HTML elements with ID - mapContainer, which contain maps, are selected using jQuery selector. updateFusionCharts method is applied on these elements to find all the FusionCharts objects rendered in the selected elements. The renderer setting is to the method having 'javascript' as the preferred renderer. The updateFusionCharts method re-renders the found maps using 'javascript' as the rendering engine. Note : JavaScript maps use AJAX to load data from data URL sources (XML/JSON files/streams). Many browsers block AJAX data-loading when running from local file system (using file:/// protocol). Hence, a JavaScript map will fail to render if it is run from local file system and if it uses Data URL method (that is, 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 map from local file system.
|
||||||||||||||||||||||||||||
Using attrFusionCharts to get the current title of a map | ||||||||||||||||||||||||||||
The attrFusionCharts method helps in retrieving value of a "map attribute". To achieve this, you will need to pass the name of the attribute as string to attrFusionCharts method. The code snippet below gets the value of the fillColor attribute of a map: // Get the latest hex code of the fill color of the map and show it as alert message var oldfillColor = $("#mapContainer").attrFusionCharts("fillColor"); alert("The existing fill color of the map is " + oldfillColor); In the above code, the HTML elements with ID - mapContainer, which contain maps, 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 "fillColor". The method returns the value of the fillColor attribute of all the found maps. All the map attributes are listed under "<map> element attributes" section of each map page in Map XML API section. |
||||||||||||||||||||||||||||
Using attrFusionCharts to set a new title to a map | ||||||||||||||||||||||||||||
The attrFusionCharts method also helps in applying or setting value of a "map attribute". For this, you will 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 map: // Set a new fill color of the map [ updating a single attribute of the map ] $("#mapContainer").attrFusionCharts("fillColor": "Updated map fill color"); In the above code, the HTML elements with ID - mapContainer, which contain maps, 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, "fillColor") and the new value to set. The method sets the "fillColor" attribute of all the found maps with the new value passed as the second parameter. All the map attributes are listed under "<map> element attributes" section of each map page in Map XML API section. |
||||||||||||||||||||||||||||
Setting a new color theme (using multiple map attributes) through attrFusionCharts | ||||||||||||||||||||||||||||
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 code snippet below shows how to set a different color theme to existing maps updating two map attributes - palette and paletteColors: // Set palette and paletteColors attributes [ updating multiple attributes of the map ] $("#mapContainer").attrFusionCharts({"palette": "5", "paletteColors": "D977B7"}); In the above code, the HTML elements with ID - mapContainer, which contain maps, are selected using jQuery selector. 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 (map attribute names - palette and paletteColors) and the respective values which will get reflected in the maps found by the method. All the map attributes are listed under "<map> element attributes" section of each map page in Map XML Sheet section. |