One of the nice User Interface features to implement when using a Map to insert/edit location data within an application is the ability to allow the user to reposition a pushpin or shape by dragging it with the mouse. Neither Web.Maps.VE or Virtual Earth directly implement this functionality. However, the Virtual Earth Toolkit (VEToolkit) contains a DragShapeExtender component that allows for this functionality to easily be implemented using the Web.Maps.VE server control. This tutorial will cover the basics of hooking up the VEToolkit DragShapeExtender to the Web.Maps.VE Map to allow your users reposition shapes by dragging them with the mouse.
Prerequisites
This tutorial assumes that you already have a basic understanding of how to place a Map on a Page using Web.Maps.VE within an ASP.NET Website or Web Application Project. If you need an overview of how to place a Map on a page, then I recommend you go check out the Getting Started Tutorial.
It is also assumed that you have a basic understanding of JavaScript programming, but don’t worry only a tiny bit is needed for this tutorial.
Before you continue, you’ll want to go download the latest JavaScript release of the Virtual Earth Toolkit (VEToolkit) open source project.
Download VEToolkit Here: http://vetoolkit.codeplex.com/
Allow User to Create/Delete Shapes using the Mouse
First, you’ll need to create an empty ASP.NET Website or Web Application Project and add a Map to it’s Default.aspx page.
Before we hook up the VEToolkit DragShapeExtender to our Map to allow “draggable” shapes, we need to plot some shape on the Map. To do this we’ll use the following code within the Maps OnClick event handler to Plot New Shapes using the Left Mouse Button and Delete Existing Shapes using the Right Mouse Button.
protected void Map1_Click(object sender, AsyncMapEventArgs e)
{
if (e.leftMouseButton && e.Shape == null)
{
// If the user clicked on the Map using the Left Mouse Button and
// they didn't click on an existing Shape, then Add a New Pushpin
// Shape to the Map.
Map1.AddShape(new Shape(e.latlong));
}
else if (e.rightMouseButton && e.Shape != null)
{
// If the user clicked on an existing Shape using thr Right Mouse
// Button, then Delete that Shape from the Map.
Map1.DeleteShape(e.Shape);
}
}
Attach the above method to the Map.Click event using the following:
<Simplovation:Map runat="server" ID="Map1"
OnClick="Map1_Click">
</Simplovation:Map>
If you need an overview of handling the Map.Click (“OnClick”) event, please read the “Basics of the Click Event” Tutorial.
Now that we have a mechanism that allows the user to dynamically add/remove pushpin shapes from the Map, we can go ahead and hook up the VEToolkit DragShapeExtender component.
Enable “Draggable” Shapes
To enable “draggable” Shapes, we need to incorporate the VEToolkit DragShapeExtender component into our example.
- Copy the following two JavaScript files from the VEToolkit into your project.
VEToolkit.Core.js
VEToolkit.DragShapeExtender.js
The VEToolkit.Core.js file contains the “core” functionality provided by the VEToolkit. I’m not going to go into what it all contains here, but it is required by the VEToolkit.DragShapeExtender.js; which contains the DragShapeExtender component.
- Add <script> references to the Page Header to include the above two scripts:
<head runat="server">
<title></title>
<script src="scripts/VEToolkit.Core.js"></script>
<script src="scripts/VEToolkit.DragShapeExtender.js"></script>
</head>
- Declare a JavaScript method to be called once the Map has finished loading in the Page.
<script type="text/javascript">
function Map1_ClientMapLoaded(map) {
// The "map" variable will contain a reference to the client-side
// Web.Maps.VE object instance.
}
</script>
- Set the above JavaScript Methods Name to the Map.OnClientMapLoaded property so it gets fired appropriately.
<Simplovation:Map runat="server" ID="Map1"
OnClientMapLoaded="Map1_ClientMapLoaded">
</Simplovation:Map>
- Now we need to create an instance of the VEToolkit.DragShapeExtender component within our OnClientMapLoaded JavaScript Event Handler, and hook it up to the Map to allow for Shapes to be “draggable.” To do this, copy the below <script> block into the page replacing the one we just created to add the Map1_ClientMapLoaded method.
<script type="text/javascript">
// Global variable to hold a reference to the VEToolkit.DragShapeExtender.
var dragShapeExtender = null;
// This Method is called once the Web.Maps.VE Map Control has finished
// loading on the Page.
function Map1_ClientMapLoaded(map) {
// The "map" variable will contain a reference to the client-side
// Web.Maps.VE object instance.
// Obtain a reference to the VEMap instance within the Web.Maps.VE
// Map Control.
var vemap = map.get_Map();
// Create a new instance of the VEToolkit.DragShapeExtender and
// attach it to the VEMap instance.
dragShapeExtender = new VEToolkit.DragShapeExtender(vemap);
// Set the DragShapeExtender to only allow Shapes to be dragged
// using the Left Mouse Button
dragShapeExtender.DragLeftMouseButton = true;
dragShapeExtender.DragRightMouseButton = false;
}
</script>
Conclusion
Event though this functionality isn’t built directly into Web.Maps.VE (or the MS Virtual Earth API) it’s extremely easy to implement with only a few lines of code. Now you have a nice example of how to allow users of your application to dynamically plot and reposition location data using a Map and their Mouse.