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 <script> tag.
What I’ll cover in this post 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.
More Information
See our “Introduction to the Google Maps API” e-learning course for more information on the Google Maps API.
