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

   
Concept:Bing Maps v7 Modules - Drag Handles


One of the features of Bing Maps v7 is support for a Modular framework. The Modular Framework allows developers to isolate application logic into separate modules (or files) and use them only when needed. One key advantage to this approach it that it can help reduce the load time of your page by deferring the loading of application logic until it is needed, but there are other advantages as well.

Organizing map application logic into modules promotes code reusability and reduces the cost of maintenance. By implementing modules, a given module can be redeployed for multiple applications by simply referencing the script file. By taking this approach, development time can be reduced. Additionally, since the code is implemented in a modular fashion, updates and enhancements can be easily rolled out, which will reduce the overall cost of maintenance

One of the examples on this site that seems to get a fair amount of attention are those that show how drag handles can be implemented to edit/modify a given shape. This seemed to be a good candidate for a Bing Map Module, so I took the existing code and developed a module that will allow a shape (polyline or polygon) to be edited.

In the included example, two shapes have been added to the map. The Drag Handle Module has also been implemented and the two shapes have been set up to utilize the Drag Handle Module. When either shape is clicked on, the shape becomes editable and the drag handles appear. The drag handles can then be used to edit the shape accordingly. Once finished, the button at the bottom of the map can be clicked to exit the edit mode for the shape.

Walk Through:

The focus of this walk through is the implementation of the drag handle module. The actual code for the drag handle module will not be covered. The Drag Handle Module code and logic will be a topic for a future article.

In this example the map is implemented in the typical fashion, so we won't touch on that. Two shapes are then added to the map. The implementation of adding the shapes is not that important. These shapes are just examples and your shape implementation will be different. What is important is ensuring that the shapes can work with the drag handle module.

In this example, theses shapes will work with the drag handle module by adding a handler to each of the shapes that will execute a function that interacts with the drag handle module. This implementation is as follows:

    ...
    Microsoft.Maps.Events.addHandler(myPolyline, 'click', editShape);
    ...
    Microsoft.Maps.Events.addHandler(myPolygon, 'click', editShape);
    ...
    

For each shape, the 'click' event is wired to the 'editShape' function, which will be executed each time the shape is clicked. The 'editShape' function will contain the logic to interact with the drag handler. Before we touch on that function, there are a couple of other items that are part of the map initialization process.

While Bing Map Modules can be loaded at the point at which they are needed, in this example, the drag handle module is loaded as part of the map initialization process. That implementation is as follows:

    // Register and load a new module
    Microsoft.Maps.registerModule("DragHandles", "Modules/DragHandleModule/DragHandleModule.js");
    Microsoft.Maps.loadModule("DragHandles", { callback: myModuleLoaded });
    

First the drag handle module is registered. This is done via the 'registerModule' method in the Bing Maps API (Microsoft.Maps.registerModule). Two values are passed to this method which are the module key and the script/module URL. The module key is the name or identifier for the module ('DragHandles') and the script URL is the location of the module code (JS file).

Once the module has been registered, it can then be loaded. This is done via the 'loadModule' method in the Bing Maps API (Microsoft.Maps.loadModule). Two values are passed to this method which are the module key and the callback name. The module key is the identifier for the module ('DragHandles') and the callback name is function that will be executed when the module has finished loading.

With those two steps, the drag handle module is registered, loaded and ready for use. Part of the initialization process for the module was to specify a call back function. The call back function can be used to execute and additional logic needed to use the module once it has been loaded. The drag handle module does have such a requirement. The implementation of the callback function 'myModuleLoaded' is as follows:

    function myModuleLoaded() {
        myDragHandleModule = new dragHandleModule(map);
        document.getElementById('loadedMessage').innerHTML = 'Drag Handle Module Loaded (version ' + myDragHandleModule.version() + ')';
    }
    

The callback is executed to initialize the drag handle module. An instance of the drag handle module is created and assigned to the globally scoped object 'myDragHandleModule'. The drag handle module class accepts two parameters, one of which is optional. The first parameter is the instance of the map that contains the shapes to be edited. The second optional parameter is the style options for the edit mode. The available options are as follows:

Property Default Description
DragHandleImage www.garzilla.net/.../DragHandleWhite.gif Image for default drag handle
DragHandleImageActive www.garzilla.net/.../DragHandleGreen.gif Image for active drag handle
DragHandleImageHeight 10 Height for default and active drag handle image
DragHandleImageWidth 10 Width for default and active drag handle image
DragHandleImageAnchor Microsoft.Maps.Point(5, 5) Anchor Point for drag handle image
shapeMaskStrokeColor Microsoft.Maps.Color(200, 100, 100, 100) Line color of shape mask
shapeMaskFillColor Microsoft.Maps.Color(000, 000, 000, 000) fill color of shape mask (polygon only)
shapeMaskStrokeThickness 2 line width of shape mask
shapeMaskStrokeDashArray 2 2 dash pattern of shape mask

Now the drag handle module has been initialized and is ready to use. Earlier in the article we touched on how the 'click' event for each shape was wired to the 'editShape' function. The implementation of that function is as follows:

    function editShape(e) {
        try {
            myDragHandleModule.edit(e.target);
            document.getElementById('cmdEdit').style.visibility = 'visible';
        }
        catch (err) {
            alert(err.message);
        }
    }
    

Upon clicking one of the shapes, this function is executed and the MouseEventArgs object is passed to this function and assigned to object e. The interaction with the drag handle module is wrapped in a try/catch block to ensure that any errors raised from the drag handle module are handled, accordingly. The 'target' property of the MouseEventArgs object, e, represents the object that raised the event. This object is passed to the 'edit' method of the Drag Handle Module object, myDragHandleModule, and the target shape is put into edit mode. The shape can now be manipulated as needed.

Upon entering edit mode, a button is displayed to exit edit mode. Upon clicking the button, the following function is executed.

    function toggleEdit() {
        myDragHandleModule.dispose();
        document.getElementById('cmdEdit').style.visibility = 'hidden';
    }
    

The 'dispose' method of the Drag Handle Module object, myDragHandleModule, is executed to exit edit mode for the current shape and take care of any necessary housekeeping items within the drag handle module itself. Lastly the exit button is hidden.

Wrap-up:

And that’s about all there is to it! With only a few lines of code, you implement the Drag Handle Module to make all any polyline or polygon editable. The Bing Maps Module framework gives you a platform to implement reusable, centralized, easy to maintain code modules that will reduce development time and maintenance costs.

This is just one approach that can be taken to implement this type of functionality and is intended to illustrate the mechanics behind this concept. Your implementation will vary depending on your specific needs. As always, feedback, comments or questions are welcome. I look forward to hearing from you.

Return to Home Page

©2007-2014, Mike Garza, All Rights Reserved