Building datadriven map applications using the Flex DataMap control

http://www.adobe.com/devnet/flex/articles/flex_datamap.html

The excellent Yahoo! Maps ActionScript 3.0 component lets you easily build a Flash or Flex-based map application. But if you are a Flex developer, you might find the usage model significantly different from that of a Flex data-driven control such as the DataGrid or the List.

The Flex DataMap control is a free, open source component built on top of the Yahoo! map component that takes input from the same data providers you use for your DataGrid or TileList control and plots that data on a map based on a Location or customizable field. When you click a marker on the map, an item renderer pops up to show the data associated with that location.

Additionaly, changes to your data provider are automatically tracked; you can hold down the Control key to box-select multiple items (see Figure 1); you can freely draw on the map (your drawing will scale up and down with the zoom level); and you can also save and restore the drawing.

Note: The DataMap control is licensed under the MPL 1.1 open source license.

The primary use case for this control is any situation in which you have data that has location information in it and you want to plot it in a map while showing the data associated with a location on click. (Initially, I used to refer to it as the control for "mapifying a DataGrid".)

Figure 1: The Flex DataMap Control

In this article, I'll describe the capabilities of the DataMap control and walk you through the process of building a simple yet powerful application in a few lines of code that:

Shows the same data on a DataGrid and on the map.
Reflects changes made in the DataGrid on the map.
Lets you box-select multiple items on the map.
Lets you make free form drawings on the map, which can be saved and restored.

Requirements

In order to make the most of this article, you need the following software and files:

Flex Builder 3

Sample files:

flex_datamap.zip (ZIP, 450K)

Prerequisite knowledge

General familiarity with Flex.
Basic understanding of data-driven controls such as the DataGrid or List.

Features of the DataMap control

The Flex DataMap control takes input from a data provider similar to the way a List or DataGrid control does, checks each object for a mapField property (by default Location), and plots a marker on the map at that location. Any change to the data provider ArrayCollection is reflected in the map. As with DataGrid and List controls, you can add, edit, remove, or filter objects and have the map update automatically. Though this may sound trivial, there are some subtle points to note. First, the bounds of the map and the zoom level are automatically adjusted to show all the markers. The DataMap control can also draw an overlay (which the Yahoo! Maps component has APIs for) to help visualize the area covered by the locations plotted on the map. To improve the visualization, this overlay encloses more area than would normally be included if you used the API directly.

Item and marker renderers

Clicking a marker pops up an item renderer (you can set your own item renderer), which pans along with the map (though there is some lag) and correctly clips at the map boundaries. You can also specify a marker renderer to specify how each marker is drawn. This feature is built-in with the Yahoo! Maps component.

Marker selection

After you select a marker by clicking it, selectedObject will point to the data associated with that marker. Control-click lets you select multiple markers, which are then accessible via selectedObjects. You can also select markers by holding down the Control key and dragging the mouse to create a selection box. Any markers within the selection box will be selected. This is a toggle, so if a selected marker was within the box, it will be unselected.

Free form drawing on the map

To draw on the map, hold down the Shift key while moving the mouse. The drawing is recorded based on the latitude and longitude, so it scales and pans correctly with the map. You can also save this data as a Base64 encoded string and restore it by getting or setting the freeformLinesBase64 property of the DataMap control.

Building a simple yet powerful application using DataMap

Building a map application with DataMap is quite easy. Your first aim is to plot your data on the map. Then you can add an editable DataGrid bound to the same data, customize the way data is shown, and add some interactivity to the application.

Plotting data on the map

Create a new Flex project.
Download the Yahoo! Maps SWC file and copy it to your libs directory.
Copy the DataMap SWC file from this article’s sample files to your libs directory.

Note: The sample files also include a Flex Builder project with the application’s final completed MXML file.

In your main MXML file, Declare the data you want to show:

private var mapData:Array = [
     {Name: "Joe", Location:"Agra"},
     {Name: "Sam", Location:"Delhi"},
     {Name: "Ram", Location:"Mumbai"},
     {Name: "Shyam", Location:"Chennai"},
     ];
     [Bindable]
     private var mapColl:ArrayCollection = new ArrayCollection(mapData);

Note: The array here can also be populated with live data by making a server side request using an HTTPService, WebService or Remoting call.

Instantiate the DataMap control by typing <DataMap and pressing Control+Space in Flex Builder to activate Content Assist. Bind the data you declared above to it:
```
<controls:DataMap
     id="mapGrid"
     yahooAppID="yourappidhere" 
     dataProvider="{mapColl}" 
     enableDrawMode="true"
     geocoderFailure="Alert.show('failed to geocode' + event)"    
     width="75%" height="100%" />
```
Note: Control+Space will only work if DatamapLib.swc is present in the libs folder.
Obtain a Yahoo! API key and assign it to the component via the yahooAppID attribute.

If you compile and run the application now, it should show you the map with markers plotted on Agra, Delhi, Mumbai, and Chennai. Try clicking on a marker to see the name associated with it. Remember that you can hold down the Control key to box-select multiple markers or hold down the Shift key to draw free form lines on the map (see Figure 2).

Figure 2: Sample application built using the DataMap control

Taking it a step further

Assign the same data to an editable DataGrid so that you can change the values for the Location field and instantly see the marker update on the map.
```
<mx:DataGrid id="dg" dataProvider="{mapColl}" editable="true" width="25%" /> 
```
Set the layout attribute of <mx:Application> to horizontal so that you can see the DataGrid and the map side by side.

To customize the way data is shown when you click on a marker, simply set an item renderer like so:

<controls:DataMap id="mapGrid"
      <!-- other attributes omitted for brevity -->
      >
        <controls:itemRenderer>
          <mx:Component>
            <mx:Canvas>
           <mx:TextArea editable="false" text="This guy's name is {data.Name}" />
            </mx:Canvas>
          </mx:Component>
        </controls:itemRenderer>
      </controls:DataMap>

To perform an action when a marker on the map is clicked or box selected, you’ll need to listen for the itemClick or boxSelect event. In the event handler, the event Object will have a selectedObject or selectedObjects property that you can use to determine which items were selected.
```
<controls:DataMap id="mapGrid" itemClick="dg.selectedItem = event.selectedObject"
      
> 
```
Now when an item on the map is clicked, the corresponding object will be selected in the DataGrid.

Where to go from here

I hope that the DataMap control significantly accelerates development of your map-based Flex applications. The DataMap control has other configurable properties that have not been discussed in this article. To see them, try out the DataMap component demo.

If you are interested in using the Yahoo! Maps Flash API without DataMap, refer to the Adobe Developer Connection article Using the Yahoo! Maps Flash API.

This work is licensed under a Creative Commons Attribution-Noncommercial 3.0 Unported License.