Mapping

Summary The discussion points and JavaScript code snippets in this topic will get you started working with the Web Application Developer Framework (ADF) JavaScript Library.

In this topic

About mapping with the Web ADF JavaScript Library

The Web ADF JavaScript Library provides access to Web ADF controls in a scriptable browser environment. In most cases, Web ADF applications are centered around a Map control. As a scriptable Web control, a Web ADF Map control is represented on both the client (browser) and server (IIS\ASP.NET process). As a result, the Map control can be accessed via JavaScript on the client or .NET on the server. Adding a Map control to a .aspx page includes the Web ADF JavaScript Library content necessary for using JavaScript to interact with the map. In many cases the same action (for example, method call or property change) can be initiated on the map via code on the client or server.
Both the JavaScript and .NET Map classes have events, methods, and properties you can use to interact with the map. In the page and code behind on the server you have access to the Web ADF Map control as a .NET class. Accessing the JavaScript Map class on the client via script in a browser must utilize (and is limited by) JavaScript capabilities. JavaScript can be added in a separate file or inlined on the .aspx page. In most cases, JavaScript content resides in the page header, body, or form and is triggered by an action on the page, such as pressing a key or clicking the mouse. The ASP.NET Asynchronous JavaScript and XML (AJAX) JavaScript Library provides a framework for event handling on JavaScript objects, so events can also trigger JavaScript code to execute.

Getting the JavaScript map instance

Assuming the server-side Web ADF Map control has been added to the page, use the ID of the Map control to find and get a client-side JavaScript reference to the Map class. If you need access to the Map class upon initial load of the page, find the Map control after the form containing it has loaded. Use the shortcut $find method included with the ASP.NET AJAX JavaScript Library as shown in the following code:
[JavaScript] 
var map = $find('Map1');

Navigating the map

Both the server and client side Map classes maintain a set of methods and properties to navigate the map. While both generate the same results, in many cases the client-side JavaScript code offers a simpler solution. For example, to set the JavaScript Map class to a specific extent, set the extent property to a Web ADF JavaScript Envelope as shown in the following code. As soon as the property is set, the action to update the Map is triggered.
[JavaScript] 
var map = $find('Map1');
map.set_extent(new ESRI.ADF.Geometries.Envelope( - 120, 35,  - 110, 45));
Properties on Web ADF JavaScript classes are prefixed with "set_" or "get_" depending on the accessibility of the property. No server-side code was required to set the map extent in this example. Instead after the state of the JavaScript Map class changed, the Web ADF JavaScript Library synchronized the state with the server-side .NET Map class. To perform the same action using a pure .NET server-side solution with a Map control requires that you manage a Web request for a callback or partial postback pattern or use a Web ADF Toolbar and implement a map server command action class. All require considerably more code than a couple lines of JavaScript running in the browser.
Another example is provided by the Zoom method. Both the server and client-side Map classes have methods to zoom to an extent defined by a scale factor. As with setting the extent property, as soon as the method is called, a Web request to update the map is generated. See the following code:
[JavaScript] 
var map = $find('Map1');
var scaleFactor = 2;
var centerPoint = new ESRI.ADF.Geometries.Point( - 110, 45);
var useAnimation = true;
map.zoom(scaleFactor, centerPoint, useAnimation);
Again, no server-side code is required. The order of Web requests when working with a map via a client-side versus server-side solution is different. The Web ADF includes a .NET Hypertext Transfer Protocol (HTTP) handler (MapHandler.ashx) to support dynamic map drawing on the server without iterating through the page lifecycle. This improves map draw performance but skips events and methods included on the page (for example, state maintenance and Web ADF control synchronization). As a result, a complimentary Web request to a page is required.
When working with the JavaScript Map class, Web requests to retrieve cached map tiles and dynamic maps via MapHandler.ashx are generated first, followed by a request to the page on which the map resides. Server-side solutions reverse the order since the action must occur on the .NET Map class before the client JavaScript can be updated.
The following diagram illustrates the client solution using the JavaScript Map class. The map is rendered in the browser before the final Web request is made.
To accomplish the same task using the server-side Map control, a Web request that calls the Map.Zoom() method must be initiated. This means the request is sent to the page first, then upon the response, the client-side Map class can do what it needs to update its content. See the following diagram:

Working with map events

The JavaScript Map class maintains a group of event methods that leverage the ASP.NET AJAX JavaScript Library to capture events on JavaScript objects in a browser at run time. The event handler methods are prefixed with "add_" to add a handler or "remove_" to remove a handler. The handler consists of a JavaScript function that is usually passed two parameters: the sender (Map class) and the event arguments associated with the event.
Event handler functions can be defined upon initial load of the application by using the init event method of the ASP.NET AJAX Sys.Application object. To ensure the server-side content of the page has loaded (for example, Map control representation in the browser), call the init method in a script block after the form containing the Web controls.
In the following code, a mouseMove event method on the Map class is configured upon application initialization. As the mouse cursor moves over the map, the current coordinates are updated in the browser status bar.
[JavaScript] 
. . . <  / form >  < script type = "text/javascript" > Sys.Application.add_init
    (initialize);

function initialize(){
    var map = $find('Map1');
    map.add_mouseMove(mouseMove);
}

function mouseMove(sender, eventArgs){
    window.status = sender.get_id() + ': ' + eventArgs.coordinate.get_x().toFixed(3)
        + ', ' + eventArgs.coordinate.get_y().toFixed(3);
}

 <  / script >
The event argument passed to the mouseMove function is a type of Sys.UI.DomEvent with an additional coordinate property in map units.
See the Map and MapBase classes in the library reference for more information on the event handlers available for use.

Tracking pending tiles during map draw

As a Web ADF developer working in an asynchronous communication environment, it is often beneficial to provide an end user with some indication that a user action is being processed. Since most Web ADF applications are centered on working with a map, the ability of an end user to effectively interact with map content is essential.
The ADF can asynchronously retrieve map images (dynamic or cached tiles) from multiple sources and consolidate them in a map control. In general, data sources often differ in the time it takes to respond to a request. Since the Web ADF Map control is capable of rendering map data as it is returned to the browser, it is possible that some portion of data in the map is visible and accessible before another portion. In this case, let the end user know when the map control has finished loading map data from all sources.
The JavaScript Map class maintains an onProgress event method to handle situations where the map is in process of retrieving and displaying map tiles. The Map control contains an integrated progress bar to indicate that a map is working to retrieve map images. This progress bar utilizes the map's onProgress event to determine how it renders. The progress bar can be disabled on the control (via the EnableProgressBar property) and replaced with a custom activity indicator.
The following JavaScript code shows how to handle the onProgress event on the map and show and hide a custom activity indicator. The arguments to the onProgress handler are the map object (sender) and an integer indicating the number of map images pending retrieval (pendingTiles).
[JavaScript] 
 < script type = "text/javascript" > 

var mapID = 'Map1';
Sys.Application.add_init(initialize);
function initialize(){
    var map1 = $find(mapID);
    map1.add_onProgress(customProgress);
}

function customProgress(sender, pendingTiles){
    if (sender != null){
        window.status = "Pending tiles: " + pendingTiles;
        if (pendingTiles > 0){
            // showLayer and hideLayer are part of the Web ADF JavaScript library
            // in the display_common.js.             
            showLayer("BusyIndicator");
        }
        else{
            hideLayer("BusyIndicator");
        }
    }
}

 <  / script >

Modifying arguments in Web requests generated by a map

Use the onServerRequest method to add custom content to a Web request generated by a JavaScript Map object. This method passes a reference to the Map object and the input argument as an array. The array has an argument property that can be used to access the current argument-value pairs in the Web request and to modify or add your custom argument-value pairs. This capability is important for making the most efficient use of Web requests generated by interaction with a Map.
In the following code, a Hypertext Markup Language (HTML) select element with a set of options is present on the page. The select element functions as a drop-down list from which an end user can select an item. If a specific tool is selected, the selected option is added to the Web request generated by the Map and is available on the server side. The selected option represents any client-side element, property, or value you want to send to the server. In this case, it can represent a selected layer, a query parameter, buffer units, and so on, used by the selected tool's implementation code on the server.
[JavaScript] 
 < script type = "text/javascript" > 

var selectedTool;
Sys.Application.add_init(initialize);

function initialize(){
    var map1 = $find('Map1');

    map1.add_onServerRequest(mapServerRequest);

    var toolbar1 = $find('Toolbar1');
    toolbar1.add_onToolSelected(toolbarToolSelected);
}

function toolbarToolSelected(toolbarObject, activeToolInfo){
    selectedTool = activeToolInfo.tool;
}

function mapServerRequest(mapObject, inputArgument){
    if (selectedTool && selectedTool.name == "MyTool"){
        inputArgument.argument = addCustomArguments(inputArgument.argument);
    }
}

function addCustomArguments(args){
    // Get the value of pure client element (no server-side representation).
    var optionElement = $get("Select1");
    var optionValue = optionElement.item(optionElement.selectedIndex).innerHTML;
    args += "&inlineArgument=" + optionValue + "&";

    return args;
}

 <  / script >


See Also:

Web ADF JavaScript Library
Dynamic resources
Graphics and MapTips