Finding features on the ArcGIS Server map

This walk-through shows how to query an ArcGIS Server map layer to search for features. Features in ArcGIS Server map layers have attributes associated with them. For example, a map layer of cities might have attribute fields such as population, area, and number of housing units. The code in this walk-through searches these attributes using a string. In this case, the search string is hard-coded in the page, but you could extend this to allow the user to input the string to search for.

This walk-through closely parallels the "Finding things on a map" example in the ArcGIS Virtual Earth Interactive SDK. The complete code for the walk-through is at the bottom of this page if you have any questions about where code goes during the steps below.

Finding map features

This walk-though queries an ArcGIS Server map service to find features with text matching an input string. Matching features are returned by the server, and these are then added to the Virtual Earth map as native VE shapes.

Create a web page with a basic Virtual Earth map. You may use the walk-through in this Help, Creating a base map with Virtual Earth. Save the file, for example to ArcGISVEFind1.htm.
Add a reference to the ArcGIS JavaScript client script. This is required for every page to use the ArcGIS JavaScript Extension for Virtual Earth. Add this in the header section, just below the reference to the Virtual Earth script.
CopyArcGIS JavaScript Extension for Virtual Earth script reference
```
<script src="http://serverapi.arcgisonline.com/jsapi/ve/?v=1.4" type="text/javascript"></script>
```
Now add a button and an empty div tag to the page, just after the <div> with id of "mymap". The user will click the button to query the ArcGIS Server map service. We'll code the onclick event of this button next. The empty div will display a progress message when the query executes.
CopyButton to run query
```
<input type="button" id="addMapButton" value="Find map features" 
   style="width: 200px;" onclick="ExecuteTask()" />
<div id="job"></div>
```
Just after the OnPageLoad function inside the existing <script> block, add the following code. The ExecuteTask function will be called when the user clicks the button. This function deletes all existing shapes that may have previously been added to the VE map, then sets up the query. A FindParameters object is created and its search properties set. In this case, the SearchText is hard-coded to find the text "facility". The layers to be searched are set in the Layers property, as an array of layer IDs. In this case, layers with IDs 14 and 17 will be queried. Layer IDs may be determined by examining the map properties, either in the original ArcGIS map or in the Services Directory available at the ArcGIS Server that provides the map service.

A FindTask is then created that will actually perform the search. The find task must have its Url set to a valid ArcGIS Server map service. Again, the Services Directory might be used to find the URL. The FindTask is executed by passing in the FindParameters object, along with the name of a function that will receive the results of the query. We'll create this function (addShapes) next. To help inform the user of progress, a status message is displayed in the empty div created earlier.
CopyExecuting the query
```
var findTask = null;
var findFilter = null;

function ExecuteTask() {
    map.DeleteAllShapes();
    findFilter = new ESRI.ArcGIS.VE.FindParameters();
    findFilter.SearchText = "Delaware";
    findFilter.Layers = [3, 5]; 
    findTask = new ESRI.ArcGIS.VE.FindTask();
    findTask.Url = "http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer";
    findTask.Execute(findFilter, addShapes);        
    var div = $get("job");
    div.innerHTML = 'Finding features. . . ';
    div.style.cursor = "wait";   
}
```
Note this code assumes the VE map has been created with the name of "map", as in the suggested code used in starting up this walk-through.

Finally, add the addShapes function that was specified in the ExecuteTask function. The ArcGIS Server will pass to this function a FindResults object with the results of the query. After ensuring that no error occurs, the function adds each feature in the results to the VE map. Each result is a FindResult object. The Feature property of the FindResult contains a GraphicFeature object, which has a set of VEShapes in its Shapes property. These VEShapes are added directly to the VE map once symbol properties are set, such as line and fill color. Note that we are adding native Virtual Earth shapes, not an ArcGIS Server map layer (which we did in the walk-through Adding an ArcGIS Server service to the Virtual Earth map).

CopyAdding the results to the VE map

function addShapes(findResults) {
    var div = $get("job");
    div.style.cursor = "default";
    var err = findResults.Error;
    if (err!=null) 
        div.innerHTML = err.message;
    else {
        var color = new VEColor(255,0,0,.5);
        var lineColor = new VEColor(0,0,0,.5); 
        var results = findResults.Results;            
        for(var i = 0; i < results.length; i++) {
            var result = results[i];
            var content = "";
            var feature = result.Feature; 
            var shapes = feature.Shapes;
            for (var ss=0;ss<shapes.length;ss++) {
                var shape = shapes[ss];
                shape.SetLineColor(lineColor);
                shape.SetFillColor(color);
                shape.Show();
                map.AddShape(shape);
            }
        }
        div.innerHTML = "Completed.";
    }
}

Save the page. Then open it in a browser, either by double-clicking the file in your file browser, or loading it from your Web server. It should display the standard Virtual Earth map. When you click the button, the ArcGIS Server map service is queried and the shapes of the features found are added to the VE map.

Discussion

Remember that each page that uses the ArcGIS JavaScript Extension for Virtual Earth requires references both to the VE script library and to the ArcGIS Virtual Earth script library (step 2 above). The URL of each script library is an online resource. This means that the browser must be connected to the Internet.

To query an ArcGIS Server map service, you must include the URL of the map service into the page (step 4). For more information about finding map services, see The Services Directory and the REST API. For tips on creating map services in ArcGIS Server, see Creating services for the ArcGIS JavaScript Extension for Virtual Earth.

The function that receives the results (addShapes) displays the features found on the VE map. The results contain VEShapes that may be added directly to the map. The only work you must do is to set up symbology for these shapes. Consult Microsoft's Virtual Earth references for more information about symbolizing with VEShapes.

This walk-through uses the FindTask, which queries multiple layers with a simple string. More sophisticated queries may be performed with the QueryTask, which queries a single layer. With the QueryTask you can specify a more complex where clause, and query based on spatial location. Spatial queries are illustrated in the Querying features by distance or spatial relationship walk-through.

Complete code for this walkthrough

CopyExample: Finding features on an ArcGIS Server map

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>Finding features on an ArcGIS Server map</title>
    <script src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2" type="text/javascript"></script>
    <script src="http://serverapi.arcgisonline.com/jsapi/ve/?v=1.4" type="text/javascript"></script>
    <script language="javascript" type="text/javascript" >
        var map = null;

        function OnPageLoad() {
            var centerat = new VELatLong(43.0, -95.0);
            map = new VEMap('mymap');
            map.LoadMap(centerat, 4, VEMapStyle.Aerial ,false);
        }

        var findTask = null;
        var findFilter = null;

        function ExecuteTask() {
            map.DeleteAllShapes();
            findFilter = new ESRI.ArcGIS.VE.FindParameters();
            findFilter.SearchText = "Delaware";
            findFilter.Layers = [3, 5]; 
            findTask = new ESRI.ArcGIS.VE.FindTask();
            findTask.Url = "http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer";
            findTask.Execute(findFilter, addShapes);        
            var div = $get("job");
            div.innerHTML = 'Finding features. . . ';
            div.style.cursor = "wait";   
        }

        function addShapes(findResults) {
            var div = $get("job");
            div.style.cursor = "default";
            var err = findResults.Error;
            if (err!=null) 
                div.innerHTML = err.message;
            else {
                var color = new VEColor(255,0,0,.5);
                var lineColor = new VEColor(0,0,0,.5); 
                var results = findResults.Results;            
                for(var i = 0; i < results.length; i++) {
                    var result = results[i];
                    var content = "";
                    var feature = result.Feature; 
                    var shapes = feature.Shapes;
                    for (var ss=0;ss<shapes.length;ss++) {
                        var shape = shapes[ss];
                        shape.SetLineColor(lineColor);
                        shape.SetFillColor(color);
                        shape.Show();
                        map.AddShape(shape);
                    }
                }
                div.innerHTML = "Completed.";
            }
        }

    </script>
</head>
<body onload="OnPageLoad()" >
    <form action="" >
    <div id='mymap' style="position:relative; width: 750px; height: 500px;"></div>
    <input type="button" id="findFeatures" value="Find map features" 
       style="width: 200px;" onclick="ExecuteTask()" />
    <div id="job"></div>
    </form>
</body>
</html>