Customizing the map progress bar in the 9.3 Web ADF (.NET)

The Web ADF includes a progress bar that displays when the map is loading map images or tiles. It makes the user aware that the site is processing the user's request. You may wish to customize the progress bar, either to modify it or to replace it with your own progress indicator. An earlier blog post described how to do this at the 9.2 version. Things have changed for the 9.3 version, and this post gives some tips on customizing the progress bar for 9.3.

We will cover two options for customizing the progress indicator. First, you can set some of the properties of the existing progress bar. Second, you can completely replace the progress bar with your own custom progress indicator. The second option involves working with custom progress events, which we will discuss before we get to the actual replacement of the default progress indicator.

Setting progress bar properties

At the 9.3 release, two public properties are exposed that you can set for the standard progress bar. These properties are the alignment, or location, of the progress bar on the map; and whether to enable or disable the progress bar. More properties may be exposed at future service packs or versions. We will use the enable/disable property later in this article, when we replace the progress bar. Let us look now at setting the alignment property, which will introduce a client-side approach we will use throughout this article.

The alignment property may be set using the Web ADF JavaScript Library. The Web ADF contains both code that runs on the server and code that runs on the client. The server-side code uses an ASP.NET language (C# or VB). The client-side code uses JavaScript, so we use that language to customize how the client code works. You can find documentation on the Web ADF JavaScript Library in the ArcGIS Server Developer Help, available either installed on your development computer, or online at the ESRI Resource Center. See the topic Web ADF JavaScript Library under the heading Developing Web applications using the Web ADF.

The progress bar properties are on the Map, since the bar is tied to the Map. Most of the properties and methods for the Map class are actually on the MapBase class, which the Map class extends. If you look on the class properties for MapBase, you will find the progressBarAlignment property. You will notice that, like most other properties, the documentation actually shows two methods associated with this property: get_progressBarAlignment() and set_progressBarAlignment(). As you will see in the code, we use these methods rather than the property per se when setting the propery.

The set_progressBarAlignment() method takes one argument when you call it: a ContentAlignment setting. For information on this enumeration, you can click on the ContentAlignment link on the progressBarAlignment page in the help, or find it under the ESRI.ADF.System namespace in the Web ADF JavaScript Library documentation. The ContentAlignment enumeration has nine values, corresponding to nine positions on the map. They include TopLeft, MiddleCenter, and BottomRight (the default).

Now we have the information we need to set the progress bar's alignment. To demonstrate, we will set the progress bar alignment to the MiddleCenter of the map. To do this, we add some JavaScript code into the .aspx page for our application, typically the Default.aspx page. Near the bottom of the page, just before the closing </body> tag, add a JavaScript function that will be called when the page starts up. We can do this using the ASP.NET AJAX add_init function, which guarantees our function will run after the page completely loads. We pass to add_init the name of the function (setupProgressIndicator) that will be called on startup.

In the setupProgressIndicator function, we get a reference to the JavaScript component for the map, using the ASP.NET AJAX $find function. Then we set the progress bar alignment using the ContentAlignment value we want. The resulting code would go into your .aspx page, just before the closing </body> tag.

<script language="javascript" type="text/javascript">
    
    // Have our custom function called when the user starts the application
    Sys.Application.add_init(setupProgressIndicator);

    function setupProgressIndicator() {
    
        // Get the JavaScript map component
        var map = $find('Map1');

        // Set the location of the progress bar
        map.set_progressBarAlignment(ESRI.ADF.System.ContentAlignment.MiddleCenter);
    }
    
</script>

Custom progress events

If you want to do more than set the alignment of the built-in progress bar, you can have custom code that runs when the map is loading images or tiles. You can use this approach to supplement the standard progress bar, or completely replace it with your own indicator. The map's onProgress event enables us to run custom code. This and other map events are discussed in the Web ADF JavaScript Library section of the Developer Help. In this section, we will use this event to display the number of pending tiles on the progress bar. Later we will replace the progress bar with a custom indicator.

To show custom content when the map is loading images or tiles, we can use the onProgress event on the map client. This event is new at 9.3, and replaces multiple events that were used at 9.2 (onRequestsPending, etc.). When a function is attached to the onProgress event, it gets called each time the number of pending tiles changes. The custom function takes two arguments: the sender of the event, which is the map component; and the number of pending tiles. You can check the second argument to determine what to display to the user.

In the code sample below, we attach to the onProgress event by calling the map's add_onProgress method. We pass it the function to be called when the number of pending tiles changes. In this function, showProgress, we examine the number of tiles as given in the args value. If the number is greater than zero, then we display the number of tiles in the browser's status bar. If the number of tiles is zero (i.e., the map is finished loading tiles), then we hide the status bar message.

<script language="javascript" type="text/javascript">
    
    Sys.Application.add_init(setupProgressIndicator);

    function setupProgressIndicator() {
    
        // Get the JavaScript map component
        var map = $find('Map1');

        // Set the location of the progress bar
        map.set_progressBarAlignment(ESRI.ADF.System.ContentAlignment.TopLeft);
        
        // Add the custom progress function
        map.add_onProgress(showProgress);
    }
    
    // Custom progress function
    //  sender = map component, args = number of pending tiles
    function showProgress(sender, args) {
    
        // If tiles pending, display number in status bar
        if (args > 0) {
            window.status = "Pending map tiles: " + args.toString();
        } else {
            // All tiles loaded - hide status bar message
            window.status = "";
        }
    }
    
</script>

Custom progress indicator

Finally, we look at how to completely replace the existing progress bar with a custom indicator. The steps are: (1) turn the standard progress bar off; (2) create our custom progress indicator; and (3) turn on and off our custom indicator using the onProgress event described earlier.

The best way to turn off the standard progress bar is to use the EnableProgressBar property on the ASP.NET Web control. You can set this in Visual Studio by switching the page to Design view, selecting the Map control, and setting EnableProgressBar to False in the Properties window. Or, you can scroll up in the Source view to the Map control and add the EnableProgressBar property there, like this:

<esri:Map ID="Map1" runat="server" Height="423px"  
    MapResourceManager="MapResourceManager1" Width="554px"
    EnableProgressBar="False" >
</esri:Map>

Second, we'll create our custom progress indicator. This indicator can be as simple or complex as you wish. An animated GIF image is common, but you could write a custom indicator similar to the built-in progress bar, which uses multiple divs and styles to create an animation. For our example, we will use the ajax-loader-circle.gif image, which is included with several samples in the Web ADF developer samples, such as ArcGIS_Spatial_Query_SOE. We copied this gif into our Web application folder and added it into the .aspx page within a div. We set the style position of the div so that it is approximately centered on the map control. Of course you could add code to dynamically position the progress indicator over the map, such as by getting the map's offsetLeft/offsetTop and setting the progress indicator's style position (see the zip file for the sample for an example of this).

<div id="progressImageDiv" style="position:absolute;left:250px;top:320px;">
    <img id="progressImg" src="ajax-loader-circle.gif" alt="Loading..." />
</div>

Third, to show and hide our custom progress indicator, we use the same approach with the onProgress event as above. If tiles are pending (args > 0), then we show the progress indicator; otherwise we hide the indicator. To show/hide the indicator, we could add code to get the indicator div and set its style.display property. But the Web ADF has built-in functions to show or hide a div section, which we will use instead: showLayer and hideLayer. The complete code, with both the custom progress indicator and status bar text, is shown below.

<div id="progressImageDiv" style="position:absolute;left:250px;top:320px;">
    <img id="progressImg" src="ajax-loader-circle.gif" alt="Loading..." />
</div>

<script language="javascript" type="text/javascript">
    
    Sys.Application.add_init(setupProgressIndicator);

    function setupProgressIndicator() {
    
        // Get the JavaScript map component
        var map = $find('Map1');

        // Add the custom progress function
        map.add_onProgress(showProgress);
    }
    
    // Custom progress function
    //  sender = map component, args = number of pending tiles
    function showProgress(sender, args) {
    
        var progressImageDiv = $get("progressImageDiv");

        // If tiles pending, display progress indicator and tile number in status bar
        if (args > 0) {
            window.status = "Pending map tiles: " + args.toString();
            progressImageDiv.style.display = "block";
        } else {
            // All tiles loaded - hide progress indicator and status bar message
            window.status = "";
            progressImageDiv.style.display = "none";
        }
    }
    
</script>

The code produces something like this when the progress indicator is displaying:

The complete code for this sample is available in this zip file. The code includes a few enhancements to the code above, such as an option to recenter the custom progress indicator if the map is resized, which may occur with the Web Mapping Application template. You can also try out this sample with the link provided.

Conclusion

We have seen how to customize the progress indicator for the map, both by setting properties of the standard progress bar and by adding our own custom event handling to display information or even a custom progress image. The map has other events and properties that you could use for performing custom handling on the client. See the Web ADF JavaScript Library reference in the Developer Help for further information.

Try the example application

Get the code

Contributed by Bryan Baker of the ArcGIS Server .NET software development team.