Bing Maps Concepts
(formerly Virtual Earth)
Mike Garza   
VEMaps@garzilla.net   

   
Click and drag pin to get started


Latitude: 0.0000 - Longitude: 0.0000
Concept: Draggable Push Pins - Bing Maps v7

In Bing Maps v6.3, one of the features added was the ability to drag push pins . In v7, this feature was not part of the core framework, or so it seemed.

As it turns out, the drag functionality is part of the v7 control, but at this point is not part of the documentation. Why is that? I am not 100% sure. Personally speaking it seems that the documentation for v7 is a little light right now, at least compared to the previous versions of the control. But that’s not the important thing to focus on. What is important is that the dragging functionality is part of the v7 control. The implementation is similar to v6.3, however the event names have changed.

In the included example, a push pin has been placed at the center of the map and dragging has been enabled. To drag the pin, simple click on the pin and move it to the desired location. A label has been added to below the map to indicate when the drag events have been fired. Additionally, there are labels below the map to display the latitude and longitude of the push pin as it’s dragged.

NOTE: As mentioned previous, the drag functionality is currently undocumented (as of the time of this article). Until that functionality becomes part of the documentation, use with caution. The implementation, event name or the base functionality could be subject to change until it is “officially” part of the documented control.

Walk Through:

Now that we are working with v7 of the Bing Maps AJAX control we need to make sure that we have a reference to the v7 library. The reference is as follows:

    <script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0"></script>
    

Next we need to build out the map, add the push pin and wire up all of the needed events. The implementation is as follows:

    // Initialize the map
    var map = new Microsoft.Maps.Map(document.getElementById("mapDiv"),
                    {
                        credentials: 'Your Key Here',
                        center: new Microsoft.Maps.Location(41.8756, -87.9956),
                        mapTypeId: Microsoft.Maps.MapTypeId.road,
                        zoom: 7
                    });
     
    // Retrieve the location of the map center 
    var center = map.getCenter();
     
    // Add a pin to the center of the map
    var pin = new Microsoft.Maps.Pushpin(center, { text: '1', draggable: true });
    map.entities.push(pin);
     
    //Wire events for dragging
    Microsoft.Maps.Events.addHandler(pin, 'dragstart', StartDragHandler);
    Microsoft.Maps.Events.addHandler(pin, 'drag', DragHandler);
    Microsoft.Maps.Events.addHandler(pin, 'dragend', EndDragHandler);
    

Lines 1-8 build out the initial map, set the location, map type and zoom level (don’t forget your map key). Next the push pin is added to the map. On line 11, the getCenter() method on the map object is executed to retrieve a “Location” object, which represents the location of the center of the map. This location object is assigned to the variable “center”. This location object will be used to position the push pin in this example.

Line 14 is the implementation for the creation of the push pin. A new pushpin object is created and assigned to the variable “pin”. The constructor of the pushpin class accepts a Location object and a series of PushPinOptions as parameters. The variable “center” is passed as the Location object and two PushPinOptions are provided. The first property is “text”, which is the display text for the push pin and the second is the undocumented “draggable” property which is set to “true”. As you would expect, setting the draggable property to enables dragging for this push pin. Once the pin has been created is it added to the map via the “push” method of the “entities” object in the map object, as listed on line 15.

While there is mode code to walk through, it should be noted that at this point there is nothing else needed to enable dragging for the push pin. At this point in the code, the dragging functionality for this push pin is fully functional. That said, there are events associated with the dragging features that can be captured so that additional logic can be added to the dragging process. The events associated with dragging are “dragstart”, “drag” and “dragend”. These should be pretty self explanatory.

Beginning on line 17, these three events are wired to specific JavaScript functions. As the dragstart, drag or dragend events are fired, the StartDragHandler, DragHandler or EndDragHandler JavaScript functions will be executed, respectively. The implementation for these functions is as follows:

     function StartDragHandler(e) {
        document.getElementById("mode").innerHTML = "Dragging started (dragstart event)."
    }
     
    function DragHandler(e) {
        document.getElementById("mode").innerHTML = "Dragging in process (drag event).."
     
        var loc = e.entity.getLocation();
        document.getElementById("MouseLat").innerHTML = loc.latitude.toFixed(4);
        document.getElementById("MouseLng").innerHTML = loc.longitude.toFixed(4);
    }
     
    function EndDragHandler(e) {
        document.getElementById("mode").innerHTML = "Dragging stopped (dragend event)."
    }
    

There is not much logic behind these three functions. They have been implemented just to illustrate how to capture these events in the event that you have logic that needs to be executed for a given event. All three of these functions essentially do the same thing in updating a label (below the map) to indicate what event is being fired. The one exception is the DragHandler function. This function also updates additional labels that indicate the current latitude and longitude of pushpin while being dragged.

Again, there is no documentation for these events, but here is what seems to be occurring. An event object, “e”, is passed to these function. An “entity” object is contained within the in “e” event object. This entity object appears to be an instance of a push pin class, specifically the push pin being dragged. In the DragHandle function, the “getLocation” method in the entity object is called to return a Location object, which is the current location of the push pin. This Location object is assigned to the variable “loc”. The “loc” variable is then used (line 9 & 10) to display the current latitude and longitude of the push pin.

Wrap-up:

As with the implementation in v6.3, the approach is pretty straight forward and easy to implements. Activating the dragging functionality is simple and you have the corresponding events to implement any necessary business logic for your application. Again, since this functionality is undocumented (at the time of the article), please use with caution. The implementation, naming convention and/or base functionality is probably subject to change until it’s officially part of the documented control.

As always, feedback, comments or questions are welcome. I look forward to hearing from you.

Return to Home Page

©2007-2017, Mike Garza, All Rights Reserved