This article was previously published on GeoChalkboard, and has been reproduced here with permission. It is based on a sub-section of the Geospatial Training Services course Google Maps for your Apps.

The Google Maps API Utility Library contains a number of useful classes that you can add to your Google Maps application. Each class is contained in an open source JavaScript format and contains unique functionality. Some of the more useful functions provided include Marker Manager for efficiently adding a large number of markers to your application, Extended Large Map Control for displaying an alternate zoom and navigation control, Progress Bar Control for adding a progress bar to your application, and many others. Each class is located in an individual JavaScript file that you can access through the use of a tag.

What I’ll cover in this article is the use of MarkerManager for efficiently adding large numbers of markers to your application along with the ProgressbarControl which provides a visual progress indicator for long running operations such as adding large numbers of markers.

Here are a couple of Google Maps Utility examples that you can review. The first is a ProgressbarControl example, provided by Google, and the second is a MarkerManager example that we have created. To see the source code simply right click the page and select View Source. We’ll discuss some of the features of these utility classes below.

The Marker Manager

The Marker Manager is typically used when you need to display a large number of markers on your map.

Without the use of Marker Manager the performance of your Google Maps application can be very poor when attempting to display a large number of markers. In addition, Marker Manager can also be used to reduce the clutter of these markers by controlling the zoom level at which markers will show. When creating an instance of Marker Manager you have the ability to specify the zoom scale at which markers will appear. Doing so can reduce the clutter of displaying too many markers for a map scale. The manager monitors the map’s current viewport and zoom level, dynamically adding or removing markers from the map as they become active. In addition, by allowing markers to specify the zoom levels at which they display themselves, developers can implement marker clustering. Such management can greatly speed up map rendering and reduce visual clutter. To access Marker Manager you will need to point your application to the markermanager.js JavaScript library as seen below.

Creating MarkerManager

An instance of MarkerManager can be created in one of two ways. In its simplest form, an instance of MarkerManager can be created simply by passing an instance of GMap2 into the constructor for MarkerManager as seen below.

You can also pass an instance of MarkerManagerOptions into the constructor for MarkerManager to set optional arguments for the instance. MarkerManagerOptions can contain three properties including border padding, max zoom scale, and track markers. Border padding, specified in pixels, sets extra padding outside the map’s current viewport which will be monitored by the manager. Markers that fall within this padding are added to the map, even if they are not fully visible. This tends to improve the performance of small distance panning. The ‘maxZoom’ property is used to set the maximum zoom scale at which markers will be displayed and is used to control marker clutter. You will want to experiment with this property to determine the optimal scale at which markers should appear. This setting will vary depending upon the nature of your data. Finally, the ‘trackMarkers’ setting is used when your application has markers that change position during the application session. A value of ‘true’ specifies that MarkerManager should monitor the movements of the markers. By default, this setting is ‘false’. The MarkerManagerOptions class is an object literal which means that there is no need to create an instance through a constructor. You simply specify a variable name and then specify the settings as seen in the figure below.

Adding Markers to MarkerManager

Individual markers can be added to the MarkerManager in one of two ways. The addMarker() method is used to add a single marker while addMarkers() adds a collection of markers contained within an array. Markers added with the addMarker() method display on the map immediately. However, the more efficient way of using MarkerManager is to add them as a collection of markers. This collection or array is passed to the addMarkers() method along with a minZoom scale and an optional maxZoom scale. The markers will not display on the map until you call the refresh() method.

The ProgressBar Control

The ProgressBarControl class is used to show the progress of a function and is ideal for updating users on the status of long running operations. In this example we are plotting a large number of markers to the map. Users of our application could easily become frustrated if the loading of these markers is too slow. To give them some sense of the progress of the loading we could use a ProgressBarControl to update the status as each marker is loaded. This is a much more user friendly way of delivering our application and will result in less frustration on the part of our users.

Creating a ProgressBarControl

A pointer to the ProgressBarControl JavaScript library must be specified before creating an instance of this object. This is shown below.

As was the case with the creation of an instance of the MarkerManager class we have two options for creating an instance of ProgressBarControl. The first and simplest way to create this control is to simply pass in an instance of GMap2 to the constructor for ProgressbarControl as seen below.

You can also use an instance of ProgressbarOptions to define ProgressbarControl. ProgressbarOptions include the ability to define a ‘loadstring’ which specifies the string that is displayed to the user when the control is first displayed and before any updates occur along with a ‘width’ property that defines the width (in pixels) of the bar.

Updating the ProgressbarControl

Once the progress bar has been created you can start it with an initial maximum value using the ProgressbarControl.start(number) method which is used to display the progress bar. The value you pass into the ‘start’ method serves as the maximum value that can be reached while the bar is displayed. In our case this equals the total number of fires found in the WitchFireResidenceDestroyed.xml file. You can update the current value of the bar using the ProgressbarControl.updateLoader(step:Number) method which increments the progress bar by the value passed into the ‘updateLoader’ method. In our case, we simply update the value by ‘1’ each time a marker has been added to the array of markers that will be displayed on the map. The value displayed in the progress bar will be in relation to the initial number supplied to the ProgressbarControl.start(number) method.

Adding a ProgressBar to Google Maps

Next we’ll examine the ProgressbarControl in more detail by reviewing a sample application.

Click here to see the demonstration and click the ‘Add Destroyed Homes’ button to add the markers to the map and watch the ProgressbarControl update as the markers are added. We’ll discuss the code used to create the ProgressbarControl below the image. You can view the code used to generate this simple demonstration by right clicking the web page and selecting View Page Source.

We will be loading the contents of an xml file containing approximately 200 residences destroyed in the San Diego Witch Fire. Each address in the file is loaded as a marker on the map. Because this is a large number of markers to add to a map it makes sense to use a ProgressbarControl that updates your user with the current status of the operation.

The initialize( ) function, as seen below, creates the basic structure of the map including map types and controls and at the end of this function makes a call to the loadFiresIntoMemory() function. This function opens the WitchFireResidenceDestroyed.xml file, loops through each record creating a marker for each address, and finally placing the marker into an array variable called ‘batch’. We will use the ‘batch’ variable later in our code to access each marker and add it to the map. All of this takes place as the map initially loads.

We can get away with loading the markers into memory because there are only 230 rows in the file, but this would not be a good idea if you have a really large dataset due to the performance hit of loading a large number of records.

Before we can access the ProgressbarControl we need to reference the progressbarcontrol.js file as seen below. This is done near the top of the file.

Now that we have a reference to progressbarcontrol.js we can create a new instance of ProgressbarControl. We add the following line of code to the initialize() function just below the call to loadFiresIntoMemory().

The initialize function should appear as follows:

Toward the bottom of the file you will see a button called ‘Add Destroyed Homes’. The ‘onclick’ event for this button will call a JavaScript function called ‘loadProgressBar()’. We are going to create this function next.

Next, we create the loadProgressBar() function that will be called when the ‘Add Destroyed Homes’ button is clicked.

Inside the loadProgressBar() function we initialize the ProgressbarControl using the start() method as seen above. The ProgressbarControl.start() method is used to display the progress bar on the map. In addition, we pass in a numeric value that defines the maximum value for the bar. In this case we are getting the size of our array using the length property. Remember that the ‘batch’ variable is an array containing GMarkers for each address in the xml file.

Next, we use the array.length method again to set a variable called ‘maxNum’ which will be used as a counter in a function we will create later.

Finally, we call the setTimeout() JavaScript function. This function is used to set a timer. Since the browser will not update the screen unless it has time to do so, we use setTimeout with a 1 millisecond delay in between each update. The setTimeout() function also accepts a function reference which will be called after the delay. In this case, the addMarkers() function will be called after the delay. We’ll discuss this function next.

Near the top of addMarkers() we called the ProgressbarControl.updateLoader() method which will update the progress of the control by a value of 1. Next, we pull the next GMarker out of the ‘batch’ array and add it to the map with GMap2.addOverlay. Finally, we check the value of ‘num’ to see if it is less than ‘maxNum’. Remember that ‘maxNum’ is set to the total number of GMarker objects loaded in the ‘batch’ array. This number should be 230. The ‘num’ value gets updated each time the ‘addMarkers()’ function is called until it is less than or equal to ‘maxNum’.

About Eric Pimpler

This article was written by Eric Pimpler at GeoSpatial Training Services. Geospatial Training Services provide a range of geoweb courses. The original article was based on an excerpt of the Google Maps for your Apps course.