Next, you create an instance of the GMap2 class, which is the basic GM object that defines a map, and you bind it to the

   var map = new GMap2(document.getElementById("myMap"));

Working with Markers
The most-used feature of GM is its ability to show markers on a map. For example, you might show a marker to indicate a point of sale, a company address, or a location related to your business or application. You can refer to Parts 1 and 2 of this article to see other scenarios.

You create a marker using the GMarker object. The constructor requires a coordinate (a GLatLng instance); you can add the new GMarker object to your map object as an overlay. In fact, every object you add to a map is an overlay. To extend the previous example:

   map.addOverlay(new GMarker(new GLatLng(myLatitude, myLongitude)));   

The preceding code does several things. Reading from the inside parentheses outward, it first creates a GLatLng coordinate object using two decimal variables (myLatitude and myLongitude—the input parameter values were declared earlier), then it creates a new GMarker positioned at this coordinate, and finally adds the marker as an overlay to the previously created map.

You can repeat this operation as many times as you wish to create additional markers on your map.

By default, markers are relatively plain, but you can define your own marker icon if you don’t want to use the standard GM one. To do that, you create a GIcon object, and then create a marker using that object:

   var myIcon = new GIcon();   myIcon.shadow =       "http://www.google.com/mapfiles/shadow50.png";   myIcon.iconSize = new GSize(20, 34);   myIcon.shadowSize = new GSize(37, 34);   myIcon.iconAnchor = new GPoint(9, 34);   myIcon.infoWindowAnchor = new GPoint(9, 2);   myIcon.infoShadowAnchor = new GPoint(18, 25);   myIcon.image =       "http://www.mycompany.com/mapfiles/marker.png";      markerOptions = { icon:myIcon };   map.addOverlay(new GMarker(      point, markerOptions));

In the preceding code, iconAnchor, shadowSize, and so on, are attributes that control how GM shows visual effects related to your icon. This can get quite complex, so I suggest you start from this simple example and make changes as needed, or refer to the complete GM API documentation.

Working with Lines
To show a line, you simply use an array of points defined with GLatLng objects. The points define a connected set of line segments. GM will connect every pair of points with a direct line segment, so anything except a straight line will always require a sequence of linear segments. GM has no concept of curves—in other words, GM (like Google Earth) doesn’t provide a way to draw a “real” curved line, but you can approximate curved lines with close-set points. The more points you provide, the better the approximation to a true curve.

Here’s an example showing the JS code required to draw a line (termed a “PolyLine” in GM parlance):

var map = new GMap2(      document.getElementById("myMap"));   map.enableDragging;   map.enableScrollWheelZoom() ;   map.setCenter(new GLatLng(      45.629865, 9.576918333333341), 13);

Figure 1. Drawing Polylines: Using an array of GLatLng objects, you can draw lines to outline or overlay an area.

      var polyline = new GPolyline([   new GLatLng(45.629865, 9.576918333333341),   new GLatLng(45.6320033333333,       9.581189999999999)], "#ff0000", 10);      map.addOverlay(polyline);

In the preceding code, the PolyLine constructor takes an array of GLatLng objects, and draws a set of line segments connecting those coordinates. The PolyLine constructor also requires a line color and width (in pixels).

The code example above creates the map shown in Figure 1.

The PolyLine object exposes its own set of properties and methods. The most important are getLength(), which returns the length (in meters) of the line along the Earth’s surface, and the hide() and show() methods that hide or show the line.

Working with Polygons
Defining a polygon is similar to defining a line, except that you use the GPolygon object. In GM polygons in fact are filled GPolyLines. For example, here’s the JS code required to create a simple polygon around a center point as shown in Figure 2:

Figure 2. Drawing Polygons: A polygon consists of a set of GLatLng objects that define its vertices relative to a center point, drawn with a specified stroke width, fill color, and opacity.

   var map = new GMap2(      document.getElementById("myMap"));   map.enableDragging;   map.enableScrollWheelZoom() ;      center = new GLatLng(      45.6320033333333, 9.581189999999999);      map.setCenter(center, 13);      var latOffset = 0.01;   var lonOffset = 0.01;      var polygon = new GPolygon([     new GLatLng(center.lat(),          center.lng() - lonOffset),     new GLatLng(center.lat() +          latOffset, center.lng()),     new GLatLng(center.lat(),          center.lng() + lonOffset),     new GLatLng(center.lat() -          latOffset, center.lng()),     new GLatLng(center.lat(),          center.lng() - lonOffset)   ], "#f33f00", 5, 1, "#ff0000", 0.2);      map.addOverlay(polygon);

The parameters to the GPolygon constructor method shown in the preceding code are points, strokeColor, strokeWeight, strokeOpacity, fillColor, fillOpacity, opts, and—except for the points themselves—all are optional.

Creating GM Files Programmatically
Although the simplest way to create a JS application that works with your server application and data is to render JS or parameters from a server-side technology, such as ASP.NET, I suggest you create your GM application by placing all your JS code in separate and static JS files, as functions. By doing that you can emit only the required values in your main HTML code, such as positioning data and so on. You’ll find that—while it’s harder to begin with—you’ll end up with cleaner and more reusable code. You can also create your own server-side framework to use GM in your application without having to write a lot of JS in every page. Again, this requires a serious commitment up front, but you’ll have a powerful resource when you want to create other GM applications.

Geocoding
One of GM’s most interesting features is Geocoding. Geocoding a point involves using a description of that point (which could be anything from a full address to just a city name) to retrieve that point’s coordinates on Earth. You can use this powerful feature whenever you need the latitude and longitude for a known location.

You can geocode a point either by calling the GM API from JS or by calling a Google web service. The web service takes the address as an input parameter, and returns an XML document containing all available geocoded information of that address. This means that you can work from a server-side application and use the returned data however you like, from any language. The web page environment is not involved. Here’s an example that creates a map and then shows a specific point on the map, using data it retrieves from the web service:

You need to define form fields to display the data and interact with JS:

Figure 3. Geocoding in Action: This simple form lets you search for and display a map given a city or specific address.

The preceding code creates a web page with a form and a map, as in Figure 3. You can enter a location into the text box, then click the Go button, and the map will find and display that place.

The most interesting part of that code is the GClientGeocoder class. This class exposes a GetLatLng (address) method that retrieves coordinates from a Google web service. The web service requires a string value—in this case the address (full or partial)—that you want to geocode. It also requires a second parameter—a callback function pointer. The callback function is necessary because geocoding requires a round trip to a Google web service, which can take a long time. Making the request synchronously would block the browser interface until the operation completes, thus freezing the application for the user. With the asynchronous implementation, you start the request, which the browser executes on a secondary thread, and the main thread remains free to handle the UI. When the Google web service has responded, the browser calls the callback function. You place the code that manages the retrieved coordinates and reports them to the user in the callback function body. For example, the preceding code defines a function that checks whether the geocoding request returned a value, and if so, creates a marker to pinpoint the returned location on the map.

Google Maps is a powerful and customizable interactive, 2D, online framework for rendering maps. Using its JavaScript API, you can create exciting web applications that show maps, locations, and other geographical views. Your users can interact with these maps and get useful information from your application in a powerful and intuitive way.