FusionMaps and JavaScript > How it Works?

FusionMaps offers tremendous integration capabilities with JavaScript. It seamlessly binds with JavaScript/AJAX to let you do the following:

  1. You can register your map with JavaScript and then listen to various events like - map loaded, map loaded, map rendered, error in map etc. For a full list of events exposed by map, please click here.
  2. You can update the map at client side, without incurring any page refreshes, by providing it ready-made XML data from JavaScript functions. Using this method, you can integrate FusionMaps with your AJAX applications. Your AJAX wrappers can get the data from server, process it, convert it into XML and then update the maps already present on the page.
  3. Update the map at client side by providing it direct URL to the XML data provider page. The map would itself download the new data, parse it and then render - all without involving any page refreshes.
  4. Get the map's XML data
  5. Get any attribute from map XML
  6. Get the map's data as CSV
  7. Invoke the exporting routine for map (as image/PDF)
  8. Invoke further JavaScript methods like signature() and hasRendered() to get information about the map

Using a combination of FusionMaps and JavaScript, you can offer a seamless experience to your end users. Here, we'll discuss how to integrate both these technologies to yield the best results.

This section assumes that you already know how FusionMaps works and the XML data structure it accepts. If you do not already know this, please read the relevant sections of documentation, as examples in this section are based on concepts explained in those sections.

 
The first step

Before we start with any of our examples, you first need to make sure that you've the following things ready with you:

  1. Map SWF Files - Present in Download Package > Maps
  2. FusionMaps JavaScript Class File (FusionMaps.js) - Present in Download Package > JSClass

Let's now create a basic example, where we see how to register the map with JavaScript and track the rendered event of map.

Code examples discussed in this section are present inDownload Package > Code > JavaScript folder.

 
Registering with JavaScript and tracking the rendered event
For this example, create a simple HTML page BasicExample.html with the following code:
<HTML>
<HEAD>
    <TITLE>FusionMaps & JavaScript - Basic Example</TITLE>
    <SCRIPT LANGUAGE="Javascript" SRC="../JSClass/FusionMaps.js"></SCRIPT>
    <SCRIPT LANGUAGE="JavaScript">
        //FC_Rendered method is called whenever a FusionMaps map on the page
        //has finished initial rendering. To this function, the map passes its
        //own DOM Id.
        function FC_Rendered(DOMId){
            //If it's our required map
            if (DOMId=="map1Id"){
                //Simply alert
                window.alert("Look Ma! I am World Map and I've finished loading and rendering.");
                return;
            }
        }
    </SCRIPT>
</HEAD>
<BODY>
    <div id="map1div">
        FusionMaps
    </div>
    <script language="JavaScript">
        var map1 = new FusionMaps("../Maps/FCMap_World.swf", "map1Id", "750", "400", "0", "1");
        map1.setDataXML("<map borderColor='005879' fillColor='D7F4FF' numberSuffix=' Mill.' includeValueInLabels='1' labelSepChar=': ' baseFontSize='9'><data> <entity id='NA' value='515' /><entity id='SA' value='373' /><entity id='AS' value='3875' /><entity id='EU' value='727' /><entity id='AF' value='885' /><entity id='AU' value='32' /></data></map>");
map1.render("map1div");
    </script>
</BODY>
</HTML>

In the above code, we are first creating a World Map using FusionMaps JavaScript class. We set the DOM Id of the map as map1Id. It is this ID using which the map will now be recognized in the HTML page. You need to make sure that each map on the page gets a different Id, else the browser would start behaving weirdly.

To register the map with JavaScript, we set the registerWithJS parameter to 1. It's the last parameter in FusionMaps constructor function.

var map1 = new FusionMaps("../Maps/FCMap_World.swf", "map1Id", "750", "400", "0", "1");

Now, we've provided a basic XML data document to map using its setDataXML method. Finally, we render the map.

If you now switch to <SCRIPTS> section of HTML <HEAD>, you'll find the following function:

<SCRIPT LANGUAGE="JavaScript">
   //FC_Rendered method is called whenever a FusionMaps map on the page
   //has finished initial rendering. To this function, the map passes its
   //own DOM Id.
   function FC_Rendered(DOMId){
      //If it's our required map
      if (DOMId=="map1Id"){
         //Simply alert
         window.alert("Look Ma! I am World Map and I've finished loading and rendering.");
         return;
      }
   }
</SCRIPT>

The above function FC_Rendered() gets invoked whenever a FusionMaps map (on the page) has finished rendering for the first time. To this function, the map passes its own DOM Id, so that we can cross refer to it.

In our example, when the World Map (with DOM Id map1ID) has finished rendering, it calls this function too. In this function, we check if it was invoked by our required World Map. To do so, we match the DOM Id passed to this id with the DOM Id of our World Map. This is useful when you've multiple maps on page and you want to track loading of each of those maps.

Finally, in this function, we output a message to the user that the map has been loaded. In your applications, you can put in application logic here (or AJAX code) to get data or build data and then update the map, which we'll soon see.

Now that you're famililar with the basic concepts of FusionMaps and JavaScript, we'll next see how to change the data of a map at client side using setDataXML method.