API Quick Links

Articles and Tutorials

GSMap

GSMap encapsuates functionality for map creation, management of map feature layers, and map navigation.

Object
   |
   +--GSMap

Field Summary
<static>  <final> String	COMPACT_ZOOM_CONTROL           Constant for specifying a compact zoom control to be placed on the map
<static>  <final> String	MAP_CONTROL           Constant for specifying a pan control to be placed on the map
<static>  <final> String	SNAPBACK_CONTROL           Constant denoting the map snapback control
<static>  <final> String	TEXT_ZOOM_CONTROL           Constant for specifying a text zoom control
<static>  <final> String	ZOOM_CONTROL           Constant for specifying a regular zoom control to be placed on the map

 

Constructor Summary

GSMap (<Mixed> container, <Object> options)             Constructs a new GSMap that is initialized with the properties provided in the options object literal.

 

Method Summary
GSControl	addControl(<Object> control, <Object> position)            Adds a control to the map
void	addFeature(feature)            A convenience function for adding a feature to the map without explicitly creating a layer first.
void	centerAndZoom(<GSPoint> coordinate, <int> zoomLevel, <Function> onCenter)            Centers the map on the provided coordinate at the given zoom level
void	centerAtCoordinate(<GSPoint> coordinate, <Function> onCenter, <boolean> suppressMessaging)            Centers the map on the specified coordinate
void	centerOnLayer(<String> name, <Function> onCenter)            Re-centers the map on the named layer.
void	centerOnNewZealand(<Function> onCenter)            Centers the map on the center of New Zealand, Nelson, and at such a scale that the full extent of the country is visible
void	clearLayers()            Removes all user-defined layers from the map
void	closeInfoWindow()            Close the info window if it is open
GSLayer	createLayer(<String> name)            Creates a new layer with the specified name
GSBounds	getBounds()            Returns the bounds of the map viewport as NZMG coordinates
GSInfoWindow	getInfoWindow()            Returns this map's info window instance
GSLayer	getLayer(<String> name)            Returns the named map layer
Array	getLayers()            Returns the feature layers for this map instance
GSPoint	getMapCenter()            Returns the center point of the map as an NZMG coordinate
GSDimension	getSize()            Returns the size, in pixels, of this map
int	getZoomLevel()            Returns the current map zoom level
void	markForSnapback()            Marks the current map position and zoom level for snapping back to later by GSMap.snapback()
void	openInfoWindow(<GSPoint> coordinate, html, <Object> options)            Displays the info window at the given coordinate.
void	openMapBlowup(<GSPoint> coordinate, <Object> options)            Opens the info window with a blowup of the map specified by the coordinate and mpx parameters
Object	panTo(<GSPoint> coordinate, onPan)            Pans the map to the specified coordinate.
void	remove()            Removes all DOM nodes appended to the map container DOM element and releases any event handlers registered by the map.
Object	removeControl(<GSControl> control)            Removes a control from the map
void	removeFeature(feature)            A convenience function for removing a feature that was added directly to the map
void	removeLayer(<String> name)            Removes a feature layer from the map
void	setBounds(bounds, <Function> onBoundsChanged)            Sets the map extents to those specified by the bounds object
void	setMapOptions(<Object> options)            Updates the map's configuration properties.
void	setSize(<GSDimension> size)            Sets the size in pixels of the map to be created.
void	snapback()            Restores the map view saved by GSMap.markForSnapback()
void	updateSize()            Recalculates the dimensions of the map from its container.
void	zoom(<int> zoomLevel, <Function> onZoom)            Zooms to the specified zoom level

Field Detail

COMPACT_ZOOM_CONTROL

<static> <final> String COMPACT_ZOOM_CONTROL

Constant for specifying a compact zoom control to be placed on the map

 

See Also:

Constant Field Values

MAP_CONTROL

<static> <final> String MAP_CONTROL

Constant for specifying a pan control to be placed on the map

 

See Also:

Constant Field Values

SNAPBACK_CONTROL

<static> <final> String SNAPBACK_CONTROL

Constant denoting the map snapback control

 

See Also:

Constant Field Values

TEXT_ZOOM_CONTROL

<static> <final> String TEXT_ZOOM_CONTROL

Constant for specifying a text zoom control

 

See Also:

Constant Field Values

ZOOM_CONTROL

<static> <final> String ZOOM_CONTROL

Constant for specifying a regular zoom control to be placed on the map

 

See Also:

Constant Field Values

Constructor Detail

GSMap

GSMap(<Mixed> container, <Object> options)

 
 var options = {
   centerX: 2530000,
   centerY: 5990000,
   width: 600,
   height: 400,
   zoomLevel: 3};
 var map = new GSMap('map', options);

Constructs a new GSMap that is initialized with the properties provided in the options object literal.

Most of the available options may be set on the new map instance after it has been created using the GSMap.setMapOptions() method.

•  
  container - may be either a reference to the DOM element that will contain the map, or the value of the id property of that element.
  •  
    • centerOnDblClick <boolean> - when true enables map recentering when double-clicking on the map.
    • dragToPan <boolean> - when true enables map panning by moving the mouse while holding down the left mouse button.
    • useMouseWheelZooming <boolean> - if true mouse wheel zooming is enabled for the map
    • useInfoWindow <boolean> - if true the info window is enabled for the map
    • useScalebar <boolean> - if true a scalebar will be displayed on the map
    • resizeable <boolean> - if true the map will be sized to fit its container element
    • zoomLevel <int> - an integer value specifying the initial zoom level of the map, ranging from 0 (maximum zoom in) to 11 (maximum zoom out)
    • centerX <float> - the x coordinate the map should be initially centered on, currently the NZMG projection is supported only
    • centerY <float> - the y coordinate the map should be initially centered on, currently the NZMG projection is supported only
    • width <int> - the width of the map viewport in pixels. This option should be used exclusively of the resizeable option.
    • height <int> - the height of the map viewport in pixels. This option should be used exclusively of the resizeable option.
  options - an object literal specifying the map options to set. Supported options are:
Parameters:

Method Detail

addControl

GSControl addControl(<Object> control, <Object> position)

Adds a control to the map

•  
  control - the control object, or a String constant identifying the type of control to add to the map.
  position - an optional argument specifying the position of this control on the map. The control's position is specified as an object literal with 2 properties anchor and offset

    map.addControl(GSMap.MAP_CONTROL,    {anchor: GSControl.ANCHOR_TOP_LEFT, offset: new GSPoint(7, 7)});

Parameters:

•  
  the map control that was added
Returns:

•  
  - ZOOM_CONTROL
  - COMPACT_ZOOM_CONTROL
  - TEXT_ZOOM_CONTROL
  - MAP_CONTROL
See:

addFeature

void addFeature(feature)

A convenience function for adding a feature to the map without explicitly creating a layer first. Features added in this way are owned by the map's 'base' layer.

•  
  - removeFeature()
See:

centerAndZoom

void centerAndZoom(<GSPoint> coordinate, <int> zoomLevel, <Function> onCenter)

Centers the map on the provided coordinate at the given zoom level

•  
  coordinate - the real world coordinate (NZMG) to center the map on
  zoomLevel - an integer value from 0 (maximum zoom in) to 11 (maximum zoom out)
  onCenter - an optional function that will be invoked when the map has been centered on the specified coordinate
Parameters:

centerAtCoordinate

void centerAtCoordinate(<GSPoint> coordinate, <Function> onCenter, <boolean> suppressMessaging)

Centers the map on the specified coordinate

•  
  coordinate - the real world coordinate (NZMG) to center the map on
  onCenter - an optional function that will be invoked when the map
  suppressMessaging - set to true to prevent this function from notifying listeners upon completion has been centered on the specified coordinate
Parameters:

centerOnLayer

void centerOnLayer(<String> name, <Function> onCenter)

Re-centers the map on the named layer. Specifically the minimum bounding box required to display all features in the layer is calculated and the map is resized to match the extents of this bounding box.

In many cases the features belonging to the layer that the map is being centered on should not be visible until after the map has been re-centered. To do this call GSLayer.setVisible() with an argument of false before adding the feature data to it. centerOnLayer() will automatically set the layer features to be visible after the map has been recentered.

•  
  name - the name of the layer to center the map on
  onCenter - an optional function that will be invoked when the map has been re-centered
Parameters:

centerOnNewZealand

void centerOnNewZealand(<Function> onCenter)

Centers the map on the center of New Zealand, Nelson, and at such a scale that the full extent of the country is visible

•  
  onCenter - an optional function that will be invoked when the map has been centered
Parameters:

clearLayers

void clearLayers()

Removes all user-defined layers from the map

closeInfoWindow

void closeInfoWindow()

Close the info window if it is open

•  
  coordinate - the point which the info window refers to
  html - the HTML content of the info window
Parameters:

createLayer

GSLayer createLayer(<String> name)

Creates a new layer with the specified name

•  
  name - the layer name
Parameters:

•  
  the layer that was created
Returns:

getBounds

GSBounds getBounds()

Returns the bounds of the map viewport as NZMG coordinates

•  
  a GSBounds object representing the bounds of the map viewport in NZMG
Returns:

•  
  - setBounds()
See:

getInfoWindow

GSInfoWindow getInfoWindow()

Returns this map's info window instance

•  
  the map's info window or undefined if the info window is not enabled for this map instance
Returns:

getLayer

GSLayer getLayer(<String> name)

Returns the named map layer

•  
  name - of the layer to return
Parameters:

•  
  the named layer
Returns:

getLayers

Array getLayers()

Returns the feature layers for this map instance

•  
  an array of GSLayer objects
Returns:

getMapCenter

GSPoint getMapCenter()

Returns the center point of the map as an NZMG coordinate

•  
  the map center point as an NZMG coordinate
Returns:

getSize

GSDimension getSize()

Returns the size, in pixels, of this map

•  
  the size of the map
Returns:

•  
  - setSize()
See:

getZoomLevel

int getZoomLevel()

Returns the current map zoom level

•  
  the current map zoom level
Returns:

markForSnapback

void markForSnapback()

Marks the current map position and zoom level for snapping back to later by GSMap.snapback()

openInfoWindow

void openInfoWindow(<GSPoint> coordinate, html, <Object> options)

Displays the info window at the given coordinate. If the window is already open at some other location it will be closed and thereafter reopened at the new location. The info window content may be provided either as an HTML string, or a DOM node.

•  
  coordinate - the point which the info window refers to
  html - the HTML content of the info window
  •  
    • offset <GSPoint> - pixel offset from the specified coordinate to position the info window at
    • onopen <boolean> - a function to be called when the info window is opened
    • onclose <boolean> - a function to be called when the info window is closed
  options - an object literal specifying content and display options for the info window. The following parameters may be specified:
Parameters:

openMapBlowup

void openMapBlowup(<GSPoint> coordinate, <Object> options)

Opens the info window with a blowup of the map specified by the coordinate and mpx parameters

•  
  coordinate - the coordinate at which to position the info window
  •  
    • zoomLevel <int> - an integer value from 0 (maximum zoom in) to 11 (maximum zoom out)
    • size <GSPoint> - size the size of the blowup map
    • offset <GSPoint> - pixel offset from the specified coordinate to position the info window at
    • onopen <boolean> - a function to be called when the info window is opened
    • onclose <boolean> - a function to be called when the info window is closed
  options - an object literal specifying content and display options for the info window. The following parameters may be specified:
Parameters:

panTo

Object panTo(<GSPoint> coordinate, onPan)

Pans the map to the specified coordinate. If the coordinate is within the visible part of the map panning is animated, otherwise the map is directly centered on the coordinate.

•  
  coordinate - the real world coordinate (NZMG) to pan the map to
  onCenter - an optional function that will be invoked when the map has been panned to the specified coordinate
Parameters:

remove

void remove()

Removes all DOM nodes appended to the map container DOM element and releases any event handlers registered by the map.

removeControl

Object removeControl(<GSControl> control)

Removes a control from the map

•  
  control - the control object
Parameters:

removeFeature

void removeFeature(feature)

A convenience function for removing a feature that was added directly to the map

•  
  - addFeature()
See:

removeLayer

void removeLayer(<String> name)

Removes a feature layer from the map

•  
  name - the layer name
Parameters:

setBounds

void setBounds(bounds, <Function> onBoundsChanged)

Sets the map extents to those specified by the bounds object

•  
  onBoundsChanged - [optional] an optional function that will be invoked when the map bounds have been set
  the - new map bounds
Parameters:

•  
  - getBounds()
See:

setMapOptions

void setMapOptions(<Object> options)

Updates the map's configuration properties.

•  
  •  
    • centerOnDblClick <boolean> - when true enables map recentering when double-clicking on the map.
    • dragToPan <boolean> - when true enables map panning by moving the mouse while holding down the left mouse button.
    • useMouseWheelZooming <boolean> - if true mouse wheel zooming is enabled for the map
    • useInfoWindow <boolean> - if true the info window is enabled for the map
    • useScalebar <boolean> - if true a scalebar will be displayed on the map
    • resizeable <boolean> - if true the map will be sized to fit its container element
  options - an object literal specifying the map options to set. Supported options are:
Parameters:

•  
  - Exception if a non-supported option is provided
Throws:

setSize

void setSize(<GSDimension> size)

Sets the size in pixels of the map to be created. Note this method doesn't update the map to match the new size, call one of the map positioning methods to do this.

•  
  size - the size of the map to be created in pixels
Parameters:

•  
  - Exception if the map is not configured as resizeable
  - getSize()
Throws:See:

snapback

void snapback()

Restores the map view saved by GSMap.markForSnapback()

updateSize

void updateSize()

Recalculates the dimensions of the map from its container. This method is called automatically in reponse to window resize events when the resizeable map option is set to true. If the container DOM element is resized independently of a window resize event this method should be called explicitly to allow the map to resize to the dimensions.

zoom

void zoom(<int> zoomLevel, <Function> onZoom)

Zooms to the specified zoom level

•  
  zoomLevel - an integer value from 0 (maximum zoom in) to 11 (maximum zoom out)
  onZoom - [optional] an optional function that will be invoked when the map has been zoomed to the new zoom level
Parameters: