PrintThough you won't be expected to create maps with lines or polygons at this stage in the course, we're going to cover how to do so now. You can copy and paste the example code into test documents of your own if you like, but it is also OK if you just read through the examples.
Adding Lines
Adding a line to a map actually involves creating an object of the Polyline class. The name Polyline comes from the fact that a number of shorter straight lines are drawn in sequence to build the complete geometry. A straight line is drawn between the first vertex and the second vertex. Then another straight line is drawn between the second vertex and the third vertex. This continues until the last vertex in the sequence is encountered and the polyline is complete.
As you might guess, a Polyline is created by passing a PolylineOptions object to the Polyline class constructor. As with the MarkerOptions class, a PolylineOptions object must have its map property set to specify which Map the Polyline should be added to. However, unlike MarkerOptions which has a position property that is set using a LatLng, PolylineOptions has a path property that is set using an array of LatLng objects.
To customize the look of the Polyline, the PolylineOptions class has three simple properties:
- strokeColor - set using a hexadecimal color value, just like those we encountered in the Lesson 2 content on CSS,
- strokeOpacity - set using a value from 0 to 1 depending on the extent to which you want the user to be able to see the base map behind the line; 0 produces a fully transparent line and 1 a fully opaque line, and
- strokeWeight - set to the desired width in pixels; values in the range 1-4 are typical.
Here is a simple example of a three-vertex line drawn in red with 100% opacity and four pixels in width:
var lineCoords = [
new google.maps.LatLng(40.73033, -77.87844),
new google.maps.LatLng(40.812, -77.8565),
new google.maps.LatLng(40.812419, -77.922449)
];
var lineOpts = {
path: lineCoords,
map: map,
strokeColor: "#FF0000",
strokeOpacity: 1.0,
strokeWeight: 4
};
var line = new google.maps.Polyline(lineOpts);
The first statement creates the array of LatLng objects representing the desired line. Recall from earlier in the lesson that a simple way to construct an array is to put together a list of items separated by commas and enclosed within square brackets. In the next lesson, we'll dig deeper into other ways arrays can be constructed.
After the array is built and stored in the lineCoords variable, the next statement creates a PolylineOptions object as an object literal. The lineCoords array is used to set the path property, a variable called map is used to set the map property, the hexadecimal value of "#FF00000" is used to set the strokeColor to red and the strokeOpacity and strokeWeight properties are set to the values of 1 and 4 respectively. A variable called lineOpts is used to store a reference to the PolylineOptions object literal.
With the PolylineOptions object defined, the last statement passes that object to the Polyline class constructor to create a new Polyline object.
You can see this code in a complete working example (polyline).
Adding great-circle lines
By default, the lines connecting the vertices in a Polyline are drawn such that they are straight in the two-dimensional Mercator projection used by the base map. But the Earth is not flat and the default two-dimensional lines are not really the shortest paths between the points. Great-circle lines (also called geodesics) represent the true shortest paths because they take the Earth's curvature into account. For large-scale maps like the one above, the difference between three-dimensional paths and two-dimensional paths is negligible, and you as the map author need not worry about the issue. However, if your map is of a regional or continental scale, the difference may be quite significant.
Fortunately, switching from a two-dimensional polyline to a geodesic is as simple as setting the PolylineOptions object's geodesic property to true. Have a look at this geodesic example showing both types of lines connecting Miami to San Francisco.
In addition to illustrating the geodesic concept, this example also shows how properties of an object literal can be re-set to new values after they've been initialized. Because I wanted to draw the same Polyline with different values for just the geodesic and strokeColor properties, I didn't need to create a new PolylineOptions object. I could simply refer to the existing object through the lineOpts variable name and use the 'object.property = value'' syntax to assign new values to the properties I wanted to change.
Adding Polygons
Adding simple polygons to a map follows a pattern similar to what you just saw for lines. The end goal is to create a Polygon object from a PolygonOptions object. As with Polylines, you need to create an array of LatLng objects that delineate your Polygon's boundary. (I recommend making the last LatLng in the array the same as the first, though the documentation says that Polygons will close themselves if not closed explicitly.) Like PolylineOptions, PolygonOptions objects have a strokeColor, strokeOpacity, and strokeWeight property. These properties control the appearance of the polygon outline. To control the appearance of the polygon's interior, you will need to set the fillColor and fillOpacity properties.
Have a look at this PolygonsOptions example showing the boundaries of the District of Columbia. Note in the source code that the fillColor and fillOpacity are not set. This demonstrates that the default values for these properties appear to be gray and ~50% opaque.
You should also note from the example that PolygonOptions doesn't have a path property, but instead a paths property. This difference arises from the fact that the API also allows for the display of more complex polygons, such as those with holes in their interior (donut polygons) and those made up of multiple parts (like the islands of Hawaii). In both cases, the idea is to create an array of coordinate arrays. In other words, for a donut polygon, you would create one coordinate array depicting the exterior of the polygon and a separate array depicting the hole. For a multi-part polygon, you would create a separate array for each part. Once all the coordinate arrays have been stored in variables, those coordinate array variables should be put into an array and used to set the paths property. This example demonstrates the depiction of a famous donut polygon, the Pentagon.