Topin Map API

Die Topin Map API benutzt die Google Maps Javascript API v3 als Grundlage. Sie kann in eine bestehende Google Maps Karte eingebunden werden oder sie erzeugt selber eine Google Maps Karte.

Einführung

Diese Einführung richtet sich an Entwickler, die mit Javascript, objektorientierter Programmierung, DOM und HTML vertraut sind.

Die Einbindung der Topin Map auf Ihre Seite ist grundsätzlich mit wenigen Zeilen Javascript erledigt. Das beinhaltet das Laden der Javascript-Codes der API und das Erzeugen einer Instanz des TopinMap-Objects. Diese Instanz kann entweder an einen Container (meistens ein DIV-Element) oder an eine schon bestehende Instanz einer Google Map gebunden werden. Bei der Bindung an einen Container wird von der Topin Map API eine Instanz der Google Map erzeugt.

Bindung an einen Container

Das nachfolgende Beispiel zeigt die Implementation der Topin Map mit einer Bindung an einen Container.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="de">
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
	<script type="text/javascript" src="http://map.topin.travel/api/map.php?key=[GoogleMapsKey]"></script>
	<script type="text/javascript">
	//<![CDATA[
		var map = null;

		function loadMap() {
			map = new TopinMap('map', {
				center: new google.maps.LatLng(47.379987, 8.538780),
				zoom: 11,
				type: 'street',
				controls: ['zoom', 'crosshair']
			});

			map.selectPlatform('webcams', function(res, params) {
				map.showCategories();
			}, null);
		}
	//]]>
	</script>
</head>
<body onload="loadMap()">
	<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
Dieses Beispiel anzeigen (container.php)

Erklärung

Zuerst wird der Javascript-Code für die Topin Map API geladen.
<script type="text/javascript" src="http://map.topin.travel/api/map.php?key=[GoogleMapsKey]"></script>
Hier muss an stelle von [GoogleMapsKey] der Google Maps API Key für Ihre Domain eingesetzt werden.
<script type="text/javascript">
//<![CDATA[
	var map = null;

	function loadMap() {
		map = new TopinMap('map', {
			center: new google.maps.LatLng(47.379987, 8.538780),
			zoom: 11,
			type: 'street',
			controls: ['zoom', 'crosshair']
		});

		map.selectPlatform('webcams', function(res, params) {
			map.showCategories();
		}, null);
	}
//]]>
</script>
In diesem Javascript-Abschnitt wir die Instanz der Topin Map erzeugt. Dies darf erst geschehen, wenn die Seite komplett geladen wurde. Die Karte wird im DIV-Element mit der ID map angezeigt. Mit den Optionen wird die Karte über Zürich zentriert und auf Level 11 gezoomt. Der Kartentyp wird auf die Strassenkarte festgelegt und er werden ein Fadenkreuz und Kontrollen zur Kartensteuerung eingeblendet. Die genaue Beschreibung der Optionen finden Sie in der Topin Map API Klassenreferenz.

Bindung an eine Google Map v3 Instanz

Das nachfolgende Beispiel zeigt die Implementation der Topin Map mit einer Bindung an eine bestehende Google Map v3 Instanz.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="de">
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
	<script src="http://maps.googleapis.com/maps/api/js?key=[GoogleMapsKey]&sensor=false" type="text/javascript"></script>
	<script type="text/javascript" src="http://map.topin.travel/api/map.php"></script>
	<script type="text/javascript">
	//<![CDATA[
		var gmap = null;
		var map = null;

		function loadMap() {
			gmap = new google.maps.Map(document.getElementById('map'), {
				center: new google.maps.LatLng(47.379987, 8.538780),
				zoom: 11,
				mapTypeId: google.maps.MapTypeId.ROADMAP
			});

			map = new TopinMap(gmap);
			map.enableControls(['zoom', 'crosshair']);

			map.selectPlatform('webcams', function(res, params) {
				map.showCategories();
			}, null);
		}
	//]]>
	</script>
</head>
<body onload="loadMap()">
	<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
Dieses Beispiel anzeigen (gmap.php)

Dieses Beispiel führt wie das obere zum selben Ergebnis, mit dem Unterschied, dass eine schon bestehende Instanz der Google Map verwendet wird. Der Google Maps API Key muss in diesem Fall bei der Google Maps API angegeben werden. Bei Topin Map API darf dieser nicht mehr verwendet werden.

Google Maps API Key

Um die Topin Map API nutzen zu können, benötigen Sie zwingend einen gütigen Google Maps API Key für Ihre Domain. Einen Google Maps API Key erstellen.

Unterstützte Browser

Es werden alle Browser unterstützt, die auch von Google Maps unterstützt werden.

Beispiele

Die Möglichkeiten der Topin Map API lassen sich am besten anhand von Beispielen erklären.

Controls

Die sogenannten Controls sind vor allem Elemente zur Steuerung der Karte (Zoom, Kartentyp, ...). Einige Controls dienen lediglich rein informativen Zwecken (Massstab, Position, ...). Die Controls können mittels den Methoden enableControls und disableControls der Topin Map Instanz ein- und ausgeblendet werden.
var map = new TopinMap('map', {controls: ['zoom', 'crosshair']});

// Alle Controls anzeigen
map.enableControls(['all']);

// Positionsanzeige ausblenden
map.disableControls(['coords']);
Dieses Beispiel anzeigen (controls.php)

Beim Erzeugen der Instanz werden das Fadenkreuz und das Zoomsteuerelemt geladen. Der Aufruf von enableControls(['all']) blendet noch alle restlichen Controls ein. Der Aufruf von disableControls(['coords']) blendet nur die Positionsanzeige aus.

Kartenposition

Es gibt zwei verschiedene Möglichkeiten, den aktuellen Ausschnitt der Karte anzupassen. Es kann zum einen das Zentrum und der Zoomlevel festgelegt werden oder zum anderen ein Bereich (Bounds).
var map = new TopinMap('map');

// Das Zentrum festlegen
map.setCenter(new google.maps.LatLng(47.379987, 8.538780), 11);

// Einen Bereich festlegen
map.setBounds(new google.maps.LatLngBounds(new GLatLng(45.7828, 5.8441), new google.maps.LatLng(47.8868, 10.5908)));
Dieses Beispiel anzeigen (position.php) Bei der Methode setBounds wird die Karte in der Mitte des Bereichs zentriert und der Zoomlevel wird so gewählt, dass der komplette Bereich so gross wie möglich im Container angezeigt wird.

Points of Interest (POIs)

Auf der Karte können sogenannte POIs angezeigt werden. Dies sind entweder die Webcams von Swisswebcams, oder die Angebote auf Topin-Ausflugstipps und Topin-Urlaubsideen.
var map = new TopinMap('map');

// Alle Webcams auf der Karte anzeigen
map.selectPlatform('webcams', function(res, params) {
	map.showCategories();
}, null);

// Die Webcams ausblenden
map.unselectPlatform();
Dieses Beispiel anzeigen (pois.php) Mit der Methode selectPlatform wird ausgewählt, welche POIs angezeigt werden soll. Es können jeweils immer nur die POIs einer einzigen Plattform angezeigt werden. Als ersten Parameter verlangt die Methode den Namen der Plattform. Der zweite Parameter ist ein Callback, der aufgerufen wird, sobald alle notwendigen Daten zur Verügung stehen. Im Callback werden die POIs mittels showCategories aller Kategorien eingeblendet.

Eine Liste aller verfügbaren Plattformen und Kategorien finden Sie in Topin Map API Klassenreferenz.

Weitere Informationen

In der Topin Map API Klassenreferenz finden Sie die Beschreibung zum kompletten Funktionsumfang der Topin Map API.