GeoSmart OpenLayers Documentation
Overview
The GeoSmart OpenLayers library extends the OpenLayers library providing addtional classes for working with GeoSmart map data and a custom theme.
OpenLayers
OpenLayers is a free, Open Source, mapping library implemented in Javascript. As the GeoSmart OpenLayers library extends OpenLayers all documentation applicable to OpenLayers is equally applicable to working with the GeoSmart OpenLayers library. The main documentation for OpenLayers can be found here.
When using the GeoSmart OpenLayers library you also include the OpenLayers library in your web page. The current version of the GeoSmart OpenLayers library is compatible with OpenLayers 2.x releases. We recommend that you either use the latest stable release of OpenLayers or use the GeoSmart hosted version of the library.
Map Projection
GeoSmart, like other commercial API providers, uses the Spherical Mercator projection for its raster map tiles. When you create a new OpenLayers map using the GeoSmart.Map class the map will automatically be configured to use the Spherical Mercator projection.
When calling methods on a map instance that accept coordinate values as arguments those coordinates must be supplied as Spherical Mercator values. If you wish to use coordinates that are in a different projection, for example the standard longitude/latitude projection WGS84, you can transform these coordinates client-side with OpenLayers. This is known as reprojection.
var proj = new OpenLayers.Projection('EPSG:4326');
var point = new OpenLayers.LonLat(-71, 42);
point.transform(proj, map.getProjectionObject());
map.setCenter(point); Note that in the example above the transformations take place on the existing OpenLayers.LonLat object so there is no need to assign a new variable.
The OpenLayers web site has an in-depth article on the use of the Spherical Mercator projection with OpenLayers. If you have location data in a projection other than WGS84 or Spherical Mercator you may still to be able to reproject your data values to the map projection client-side using the Proj4js library. OpenLayers integrates with the Proj4js library if it is available, just include the library in your web page along with definitions for any projections you wish to use.
Using the GeoSmart OpenLayers Classes
The GeoSmart OpenLayers library provides 2 new classes for working with GeoSmart map data:
GeoSmart.Map
GeoSmart.Map is a subclass of OpenLayers.Map. It's preconfigured to use the Spherical Mercator projection and automatically creates a base layer configured for the GeoSmart Spherical Mercator tile set. In addition GeoSmart.Map is configured with a default set of controls and uses the custom GeoSmart theme for styling these. Both map control and theme defaults can be overridden using the standard OpenLayers.Map configuration options.
<!DOCTYPE html>
<html>
<head>
<title>GeoSmart Map</title>
<script type="text/javascript" src="http://api.geosmart.co.nz/openlayers/0.1/OpenLayers.js"></script>
<script type="text/javascript" src="http://api.geosmart.co.nz/openlayers/0.1/GeoSmart.js"></script>
<script type="text/javascript">
function init () {
var map = new GeoSmart.Map('map');
map.setCenter(new OpenLayers.LonLat(19195932, -5056360), 5);
}
window.onload = init;
</script>
</head>
<body>
<div style="width: 100%; height: 400px" id="map"></div>
</body>
</html>
GeoSmart.Layer.World
GeoSmart.Layer.World subclasses OpenLayers.Layer.XYZ. This class is pre-configured to fetch GeoSmart's street map tiles. Although this is a global tile set currently detailed street maps are only available for Australia and New Zealand. You will generally not need to provide any configuration options when instantiating this layer type other than the name to use for the layer instance.
var streetLayer = new GeoSmart.Layer.World('Streets');
map.addLayer(streetLayer); Note that you don't need to instantiate this layer directly if using GeoSmart.Map as that class automatically creates an instance of GeoSmart.Layer.World and sets it as its base layer.
Theming
OpenLayers allows the appearance of map controls to be changed to some extent through theming. When either GeoSmart.Map or OpenLayers.Map is instantiated, the path to a stylesheet from which to load theme styles can be specified using the theme option. The style of many of the controls in OpenLayers can be modified in this way. Some older controls however have their style declarations coded in Javascript and are therefore more limited in the extent to which they can be themed. For these controls you may swap out the default images with custom images of your own by setting the OpenLayers.ImgPath property.
GeoSmart Theme
The GeoSmart OpenLayers library ships with a custom theme. This theme is used by default when creating your map using the GeoSmart.Map class. The GeoSmart theme is a CSS3 based theme that degrades gracefully in older browsers without CSS3 support.
The following OpenLayers visual controls are supported by Version 0.1 of the GeoSmart theme:
- LayerSwitcher — the LayerSwitcher control displays a table of contents for the map.
- OverviewMap — the OverviewMap control creates a small overview map, useful to display the extent of a zoomed map and your main map and provide additional navigation options to the user.
- ScaleLine — the ScaleLine displays a small line indicator representing the current map scale on the map.
- PanPanel — the PanPanel is visible control for panning the map North, South, East or West in small steps.
- ZoomPanel — the ZoomPanel control is a compact collecton of 3 zoom controls: an OpenLayers.Control.ZoomIn, an OpenLayers.Control.ZoomToMaxExtent, and an OpenLayers.Control.ZoomOut.
Mobile Mapping
Support for mobile devices was added in OpenLayers 2.11. Map dragging is possible using both iOS and Android devices, pinch zooming is available on iOS and some Android devices. For further information about which map navigation features are supported by which mobile browsers see the Mobile Browsing page on the OpenLayers web site.
License
OpenLayers is released under the 2-clause BSD License. Use of the GeoSmart Spherical Mercator tile set is subject to the following terms:
The user agrees by using these services provided by GeoSmart that they have entered into and hold a current and valid license agreement for such services with GeoSmart. The user also accepts that if they have not entered into and signed a current license agreement with GeoSmart that there are significant penalties for a breach of our license. Please contact GeoSmart immediately for advice and guidance on our license agreement and terms and conditions if you are unsure at: