This tutorial will walk you through the steps necessary to get a ComponentArt DataVisualization for Silverlight Map control up and running.

1. Create a new Project

In Visual Studio, create a new "Silverlight Application" project. Call it "MyFirstMap". Use the default Web site settings. Visual Studio will generate the Silverlight and .Web projects, and should open up the MainPage.xaml.

2. Adding the required Assembly Reference

A quick way to add the required reference is to simply drag it from the File Explorer into the Toolbox. By default, the Data Visualization assemblies are installed to \Program Files\ComponentArt\Data Visualization for Silverlight\assembly\. Drag the "ComponentArt.Silverlight.DataVisualization.Mapping.dll" file into the Toolbox -- Visual Studio will then add the reference to the "MyFirstMap" project and populate the Toolbox with the Map control.

3. Adding the Map control

Drag the Map from the Toolbox to the MainPage.xaml design surface creating a new Map control with the Name map1 inside the "LayoutRoot" Grid. At this point, if you start debugging or otherwise run the Solution, you'll only see a blank page -- we will need to add a ShapeFile to properly see the Map.

4. Adding a ShapeFile to the Project

ShapeFiles are used by the Map control to draw the map. Maps are included with DataVisualization for Silverlight and by default are installed to \Program Files\ComponentArt\Data Visualization for Silverlight\support\designers\maps. They are categorized by country, region and world maps. For the purposes of this demo lets select the region map: "\maps\regions\nafta.shp" and "\maps\regions\nafta.dbf". (dbf files contain metadata which can be used when attaching a datasource to the map, this is important for this tutorial) We need to add these files to the Silverlight Project.

5. Setting the ShapeFile Perperty to the MapLayer

To set the ShapeFile to the Map, we will need to add a Layer to the Map first. We will also add some properties to the MapLayer to help with showing the associated data. PopupIndexField, DataBindingMetaDataKey, DataBindingItemPerpertyName. There are two sections of the popup. The top section is the IndexTemplate, the bottom section is the DataTemplate. We need to set PopupIndexField="NAME" so that the map can send the correct field to populate the Popup, for our scenario we want this to display the country name. We will deal with the DataTemplate later. We also need to set some DataBinding properties DataBindingMetaDataKey="NAME" this tells the Map that we are going to bind against values for NAME and DataBindingItemPropertyName="X" this tells the Map that this propertyname will match the MetaDataKey, so it can create it's own relationship. Finally we set ShapeFile="/MapData;component/nafta.shp" to the file we have imported.

<my:Map.Layers>
    <my:MapLayer ShapeFile="/MapData;component/nafta.shp" PopupIndexField="NAME" DataBindingMetaDataKey="NAME" DataBindingItemPropertyName="X">
    </my:MapLayer>
</my:Map.Layers>

6. Adding Some Data to the MapLayer

Now lets add some data to the map layer. Here we are using the the DemoDataValues collection from DataVisualization.Utils, make sure you have this namespace referenced in your page.

xmlns:my1="clr-namespace:ComponentArt.Silverlight.DataVisualization.Utils;assembly=ComponentArt.Silverlight.DataVisualization.Common"

Now we add the values to the collection and place it inside the ItemSource for the layer.

<my:MapLayer.ItemsSource>
    <my1:DemoDataValues>
        <my1:DemoDataValue X="United States" Y="60" />
        <my1:DemoDataValue X="Canada" Y="25" />
        <my1:DemoDataValue X="Mexico" Y="15" />
    </my1:DemoDataValues>
</my:MapLayer.ItemsSource>

7. Adding a FillRule to the MapLayer

Now that we have our Map in a state where it has some Data, we will need to add a FillRule.  Fill rules enable the map to be colored, here we will create a new fill rule where we set Binding="{Binding Y}" where the Y value of the DataItem will be used to satisfy the rule. Setting ColorFromPalette="True" enables the map to pull fill colors from its list in the assigned palette, this is most useful in a dashboard scenario where we have global Themes and Palettes assigned. Each GradientStop Offset determines how the section is coloured.

<my:MapLayer.FillRule>
    <my:MapLayerFillRule Binding="{Binding Y}" ColorFromPalette="True">
        <my:MapLayerFillRule.Colors>
            <LinearGradientBrush>
                <GradientStop Offset="0" />
                <GradientStop Offset="25" />
                <GradientStop Offset="50" />                                    
            </LinearGradientBrush>
        </my:MapLayerFillRule.Colors>
    </my:MapLayerFillRule>
</my:MapLayer.FillRule>

8. Adding a PopupValueTemplate

Now that we've added our Data and FillRule, let's add a PopupValueTemplate to complete the popup.   As described above the PopupValueTemplate contains the bottom section of content.  Here we are just going to put a TextBlock where we bind the Y data.

<my:MapLayer.PopupValueTemplate>
    <DataTemplate>
        <TextBlock Margin="3" Grid.Row="1" Grid.Column="1" FontSize="11" Text="{Binding Y}" />
    </DataTemplate>
</my:MapLayer.PopupValueTemplate>

At this point, if you start debugging or otherwise run the Solution, you'll see the finished product.

For reference, the XAML should look something like:

         
<my:Map HorizontalAlignment="Left" Name="map1" VerticalAlignment="Top" Height="480" Width="640" >
    <my:Map.Layers>
        <my:MapLayer ShapeFile="/MapData;component/nafta.shp" PopupIndexField="NAME" DataBindingMetaDataKey="NAME" DataBindingItemPropertyName="X">
            <my:MapLayer.ItemsSource>
                <my1:DemoDataValues>
                    <my1:DemoDataValue X="United States" Y="60" />
                    <my1:DemoDataValue X="Canada" Y="25" />
                    <my1:DemoDataValue X="Mexico" Y="15" />
                </my1:DemoDataValues>
            </my:MapLayer.ItemsSource>            
            <my:MapLayer.FillRule>
                <my:MapLayerFillRule Binding="{Binding Y}" ColorFromPalette="True">
                    <my:MapLayerFillRule.Colors>
                        <LinearGradientBrush>
                            <GradientStop Offset="0" />
                            <GradientStop Offset="25" />
                            <GradientStop Offset="50" />                            
                        </LinearGradientBrush>
                    </my:MapLayerFillRule.Colors>
                </my:MapLayerFillRule>
            </my:MapLayer.FillRule>
            <my:MapLayer.PopupValueTemplate>
                <DataTemplate>
                    <TextBlock Margin="3" Grid.Row="1" Grid.Column="1" FontSize="11" Text="{Binding Y}" />
                </DataTemplate>
            </my:MapLayer.PopupValueTemplate>
        </my:MapLayer>
    </my:Map.Layers>         
</my:Map>

Congratulations! You've successfully colored a map from data.