Articles and Tutorials

Getting Started with the Maps API Version 1

This document is a guide to using the Maps Javascript API to add rich, interactive maps to your web applications. The API exposes a set of Javascript objects for the creation of maps and map features, and supporting classes for data loading and event management. Familiarity with the Javascript language, especially its object-oriented features will be helpful in working with the API.

This document refers to version 1 of the SmartFIND Maps API. Upgrading to the current version will allow you to take advantage of new features. For version 2 please click here.

The Maps API provides many other functions not documented in this guide so be sure to take a look at the API Class Reference.

Introduction

Getting an API Key

The Maps API is a commerical service. For information on using the API on your website contact sales@geosmart.co.nz

Including the API in your Project

To begin using the Maps API in your project you need to include a <script> tag referencing the API.

When you registered for your API key you will have received a snippet of HTML code that includes the required script tag:

 
<script type="text/javascript" 
   src="http://api.geosmart.co.nz/api?service=sfapi&v=1&user=<your-user-name>"></script>

The script tag shown above imports all of the Javascript objects documented in the API reference as well as introducing two additional symbols into the global namespace:

_globals - global variables used by the various SmartFIND objects
_browser - encapsulates information about the current browser, its version, and host operating system

Browser Compatibility

The Maps API supports recent versions of Gecko-based browsers (Mozilla/Firefox), Opera 9, Internet Explorer 6+, and Safari 1.2+.

To provide alternative content for browsers that are currently unsupported by the API you can call a function which does a compatibility check, see GSBrowser.isSmartfindCompatible()

Using the API

An instance of GSMap is created for each map to be displayed on a page. A map is embedded in a container such as a div element and a reference to this element is passed to the map as a constructor parameter. If the map's size is not specified the map will be sized to fit its container, if the containers size changes due to the user resizing their browser window the map will be resized also.

Through the GSMap class the area displayed in the map's viewport can be manipulated, map navigational controls configured, and features layered over the map background.

Features are added to a map instance, either individually or collectively using the GSLayer class. The map window can be centered on points, features, and feature layers.

Each map instance has a single info window that can be used to display information about a point on the map. The info window can display arbitrary HTML markup which may either be stored as a property of a map feature or passed to the map's showInfoWindow() method.

Creating a Map

A map instance is created by instantiating the GSMap class. To display a map the map needs to be centered on a point or a group of features belonging to a map layer.

 
var params = {"id" : "myMap",
              "centerX" : 2530000,
              "centerY" : 5990000,
              "zoomLevel" : 11};
var map = new GSMap(params);

The example above uses name-value pairs to specifiy the arguments used to initialize a new map instance. An alternative way of creating a map centered upon the same point would be to create the map object first and then call its centerAndZoom() method.

 
var map = new GSMap({"id", "myMap"});      
var coordinate = new GSPoint(2530000, 5990000);
map.centerAndZoom(coordinate, 11);

View Example

In this example the map is centered on a coordinate within the New Zealand Map Grid (NZMG) at a given zoom level.

Map Properties

GSMap exposes properties for configuring some of its basic capabilities, these are described in Table 1.

Table 1. GSMap Properties
Property	Type	Default Value	Description
centerOnDblClick	boolean	true	When true enables map recentering by double-clicking on the map.
dragToPan	boolean	true	When true enables map panning by moving the mouse while holding down the left button.
infoWindowEnabled	boolean	true	When true enables an info window to be opened to display information relating to a point on the map.
scalebarEnabled	boolean	true	When true a scalebar will be displayed in the lower left-hand corner of the map.
mouseWheelZoomingEnabled	boolean	true	When true the map can be zoomed in and out using the mouse wheel.

Map Controls

The Maps API provides several graphical map controls that can be used to pan and zoom the map in various ways. Custom controls can also be developed if none of the in-built controls meet the needs of your application.

Map controls are added to a map instance using the GSMap.addControl() method. The easiest way to use an in-built map control is to pass the constant value identifying the control type as an argument to the addControl() method.

 
var map = new GSMap({"id" : "myMap"});
map.addControl(GSMap.MAP_CONTROL);

View Example

The code above adds a map control that lets users pan and zoom the map.

Using Labels with the Zoom Slider

A combination pan and zoom map control can be created by passing the GSMap.MAP_CONTROL constant to the GSMap.addControl() method. This control can also be directly instantiated, and when created in this way can be configured to display labels on the zoom slider for jumping to specific zoom levels.

 
var labels = [{level: 9, value: 'Region'}, {level: 3, value: 'Suburb'}, {level: 0, value: 'Street'}];
var mapControl = new GSMapControl(labels);
map.addControl(mapControl);

In the code sample above the map control instance is parameterised with an array of objects specifying the labels to be shown on the slider. Each object has 2 properties:

level - the zoom level the map should be zoomed to when the user clicks on the label
value - the text to be displayed on the label

View Example

Map Navigation

An instance of GSMap can be panned and zoomed programatically using methods for centering and zooming the map. This allows a map view to be changed in response to events occurring outside of the API classes.

The example below shows a map that can be zoomed using a custom radio button control.

 
<script type="text/javascript">
var map;
 
function initMap() {
   map = new GSMap({"id" : "myMap"});
   map.centerOnNewZealand();
}
 
function zoomMap(level) {
   map.zoom(level);
}
</script>
 
<input type="radio" onclick="zoomMap(11); return true" value="11" checked="true"/><label>Region</label>
<input type="radio" onclick="zoomMap(3); return true" value="3"/><label>Suburb</label>
<input type="radio" onclick="zoomMap(1); return true" value="1"/><label>Street</label>

View Example

Panning Programatically

The map can be panned programatically using GSMap's panTo() method. The panTo() method smoothly scrolls the map to the specified coordinate if the coordinate is within the map's viewport, otherwise the map is directly centered on the coordinate.

 
      function init() {
          var map = new GSMap({"id" : "myMap"});
 
          var coordinate = new GSPoint(2662445, 6493132);
          map.centerAndZoom(coordinate, 1);
 
          var params = {"name" : "GeoSmart Auckland Office",
          "coordinate" : coordinate};
          var feature = new GSPointFeature(params);      
          feature.addEventHandler('click', panToFeature);
          
          map.addFeature(feature);
      }
 
      function panToFeature(e) {
          this.map.panTo(this.coordinate);
          GSUtil.cancelEvent(e);
      }

View Example

Features

Map features represent geographic information that is overlaid on the map background. Map features are used to geographically position your data on the map.

Point Features

The GSPointFeature class is used to display a discrete location on the map. The minimum information required to create a point feature is an NZMG coordinate, though in practice you will probably want to supply a name for the feature as well (this will be displayed in a tool tip when the user mouses over the icon for the feature).

 
var map = new GSMap({"id" : "myMap"});
 
var coordinate = new GSPoint(2662445, 6493132);
 
map.centerAndZoom(coordinate, 0);
 
var params = {"name" : "GeoSmart Auckland Office",
              "coordinate" : coordinate};
var feature = new GSPointFeature(params);
 
map.addFeature(feature);

View Example

The appearance of a point feature on the map is determined by an associated icon object. If no icon is specified for a point feature, as in the example above, the feature will be created with the map's default icon. Many users of the API will want to create their own images for feature icons, see the Icons section for how to do this.

Event handlers can be defined for point features so that they can respond to user events such as mouse clicks. The example below shows how to open the info window for a point feature when it receives a mouse click.

The infoHtml property of GSPointFeature is used to define the default information that should be shown in the info window when it is opened for the feature. This property can be set to an arbitrary HTML string. See Using the Info Window for more detail on how to use this property.

 
var map = new GSMap({"id" : "myMap"});
 
var coordinate = new GSPoint(2662445, 6493132);
 
map.centerAndZoom(coordinate, 0);
 
var params = {"name" : "GeoSmart Auckland Office",
              "coordinate" : coordinate,
              "infoHtml" : "<b>GeoSmart Auckland Office</b>"};
 
var feature = new GSPointFeature(params);
 
feature.addEventHandler("click", function(e) {
  this.showInfoWindow();
 
  // prevents click event propagating to map
  GSUtil.cancelEvent(e);
});
 
map.addFeature(feature);

View Example

Blowup Maps

A blowup map showing the point feature at an increased zoom level can be displayed in the info window by calling the feature's openMapBlowup() method.

View Example

Draggable Point Features

When a point feature should be able to be re-positioned by a user it can be instantiated as a draggable feature. Draggable point features can be moved to a new position on the map and communicate information about their state change during dragging through drag events. Your code can respond to these events by implementing drag event handlers and registering as a listener for a point feature instance. The events generated by draggable point features are shown in Table 2.

Table 2. GSPointFeature Events
Method	Arguments	Description
featureDragStart	feature	Triggered when the user begins to drag the point feature. This function takes a single argument which is a reference to the feature that generated the drag event.
featureDrag	feature	This event is fired continuously as the feature is moved. This function takes a single argument which is a reference to the feature that generated the drag event.
featureDragEnd	feature	Triggered when the user has released the feature. This function takes a single argument which is a reference to the feature that generated the drag event.

View Example

Icons

The GSIcon class is used to specify the images that are used to represent a feature on the map. The GSIcon class is necessarily quite complex to ensure consistent rendering of the icon across different browsers.

An icon can reference up to 3 different images. The icon's foreground image is set using the imageSrc property. The referenced image may be in either GIF or PNG format. Transparency is supported for both image formats, browser differences in the rendering of alpha transparency are automatically handled in how GSIcon internally creates the image object.

A shadow image can be added to the icon, this is rendered behind the foreground image and is set using the shadowSrc property. The shadow image may also be in either GIF or PNG format.

If the foreground image specified for an icon is in PNG format, and the map should be able to be printed, an additional GIF version of the foreground image can be specified for use during printing. The print image is set using the icon's printSrc property.

Note that some browsers have problems printing images with alpha-channel transparency. Specifying a GIF image with a solid background colour to be used when the icon is printed avoids unpredictable rendering behaviour.

The icon's alt property can be used to set the text that should be displayed in a tool tip when a user mouses over the icon.

If the shape of the icon image is not rectangular a 'hit' area can be defined that is the part of the image that will respond to mouse events. When using PNG images with alpha transparency on Internet Explorer no additional work needs to be done as mouse events will automatically 'pass through' the transparent regions of the image. To achieve a similar effect for Mozilla browsers an image map can be created to define the 'hit' area. The image map coordinates are set on the icon using the icon's imageMap property. When the icon is rendered an HTML image map is created and associated with the icon's foreground image.

 
var icon = new GSIcon();
icon.imageSrc = "http://www.example.com/images/office.png";
icon.imageSize = new GSDimension(22, 16);
icon.shadowSrc = "http://www.example.com/images/shadow.png";
icon.shadowSize = new GSDimension(12, 16);
icon.printSrc = "http://www.example.com/images/office.gif";
icon.printSize = new GSDimension(12, 16);
icon.imageMap = [0,0,0,14,16,14,18,15,21,15,21,12,19,10,19,0];
icon.imageMapShape = "poly";
icon.alt = "GeoSmart Auckland Office";

An icon may be copied by passing an existing icon instance as an argument to the GSIcon constructor.

 
var icon = new GSIcon();
icon.imageSrc = "http://www.example.com/images/office.png";
var copy = new GSIcon(icon);

Layers

Layers are a way of managing a collection of map features as a group. Some of the uses of the the GSLayer class are:

Addition or removal of a group of features without affecting features present in other map layers
Toggling visibility of a group of map features
Getting the geographical extents of a group of map features

For simple applications where all map features can belong in a single layer, features can be added directly to the map instance's base layer. All map objects have a base layer that is automatically created when the map is instantiated. To add a feature to the map's base layer use the GSMap.addFeature() method.

Using the Info Window

Each map instance has a single info window which can be used to display information about a point on the map. The info window can be shown for a map feature in response to a mouse event occuring on that feature or invoked programatically.

To show the info window programmatically the GSPointFeature class provides a showInfoWindow() method that will open the info window above the feature on the map displaying the provided HTML markup.

Any HTML markup can be displayed in the info window. The info window will expand in size vertically and horizontally if a large fragment of HTML is added (though consideration should be given to the size of the map that the info window will be displayed on).

If using the showInfoWindow method of GSPointFeature the info window's offet from the feature marker is automatically calculated.

Concepts

Event Handlers

GSMap produces events to communicate changes in its internal state to code written by the API user. Notification of an event is via either a user-defined callback method or through the invocation of a listener method defined on an object that has been registered with a map instance as a map listener.

Callbacks

All of the navigational methods supplied by GSMap take a user-defined callback function as an optional argument. The callback function is executed after the map background has been updated and any map listeners have been notified of the map's state change.

 
var map = new GSMap({"id" : "myMap"});
var coordinate = new GSPoint(2530000, 5990000);
 
var callback = function() {
   alert("Map centered at: " + map.getMapCenter());
};
 
map.centerAndZoom(coordinate, 11, callback);

Listeners

Objects that support the map listener interface can be registered with a GSMap instance to be notified of events of interest to the object. A map listener can be any Javascript object that provides an implementation of one or more of the handler methods that define the map listener interface. Table 3 lists the handler methods and any arguments that are passed to them when invoked.

Table 3. GSMap Events
Method	Arguments	Description
mapClicked	map, object	Triggered when the user clicks on the map or a map feature. The first argument is a reference to the map itself, the 2nd argument is an instance of GSPoint if the click was on the map or a an instance of GSPointFeature if the click was on a feature.
mapDblClicked	map, object	Triggered when the user double clicks on the map or a map feature. The first argument is a reference to the map itself, the 2nd argument is an instance of GSPoint if the double click was on the map or a an instance of GSPointFeature if the double click was on a feature.
mapResized	map, oldSize, newSize	Triggered when the map is resized. The first argument is a reference to the map itself, the 2nd and 3rd arguments are GSDimension objects containing the original and the new size of the map.
mapZoomed	map, oldZoomLevel, newZoomLevel	Triggered when the map is zoomed in or out. The first argument is a reference to the map itself, the 2nd and 3rd arguments are integer values specifying the old zoom level and new zoom level
mapBoundsChanged	map, oldBounds, newBounds	Triggered when the point the map is centered on is changed. The first argument is a reference to the map itself, the 2nd and 3rd arguments are GSBounds objects specifying the old map extents and the new map extents.
infoWindowOpened	none	Triggered when the map's info window is opened.
infoWindowClosed	none	Triggered when the map's info window is closed.

The example below shows how a listener can be used to update a status panel that displays the map's current bounds.

 
var map = new GSMap({"id" : "myMap"});
  
var status = document.getElementById("status");
 
// implement the mapBoundsChanged method on the status
// element
status.mapBoundsChanged = function(map, oldBounds, newBounds) {
   status.innerHTML = "minimum X: " + newBounds.minX + "<br/>" +
                      "minimum Y: " + newBounds.minY + "<br/>" +
                      "maximum X: " + newBounds.maxX + "<br/>" +
                      "maximum Y: " + newBounds.maxY;
};
 
// register the status element as a map listener
map.addListener(status);
 
// change the map's bounds
map.centerOnNewZealand();

Using Remote Data

The Maps API is focused upon client-side functions for programming the map viewer, for an example of using remote data with the API see Using JSON with the Maps API

Printing

The map controls and info window will not be visible when the map is printed. Lack of browser support for printing images with alhpa-channel transparency means that irregularly shaped elements like the info window cannot be printed.

Many applications will require printable maps. The API supports printing through media-specific CSS rules.

The images for map controls overlaid over the background map are classified with a CSS rule that hides them during printing. Likewise the map info window will not be printed if open when printing.

Point features will only be displayed if a print image has been specified for the feature's icon, see Icons.

When the API is initialized in your application the following CSS rules are written into the DOM, for API objects to print correctly care should be taken to avoid clobbering these rules in your application's stylesheet.

 
      <STYLE type="text/css">
      @media screen {
        .noscreen {
          display: none;
        }
        .noprint {
          display: block;
        }
      }
      
      @media print {
        .noscreen {
          display: block;
        }
        .noprint {
          display: none;
        }
      }
      </STYLE>

API Quick Links

Getting Started with the Maps API Version 1

Introduction

Getting an API Key

Including the API in your Project

Browser Compatibility

Using the API

Creating a Map

Map Properties

Map Controls

Using Labels with the Zoom Slider

Map Navigation

Panning Programatically

Features

Point Features

Blowup Maps

Draggable Point Features

Icons

Layers

Using the Info Window

Concepts

Event Handlers

Callbacks

Listeners

Using Remote Data

Printing