Folgen Sie GpsWandern.de auch auf:

Facebook RSS
Gpswandern.de Gastautorenprogramm

TrackViewer-API - Programmierung ~ Die Programmieranleitung zur API

TrackViewer-API - Programmierung

Die Programmieranleitung zur API

Diese Anleitung wendet sich an den Webmaster, der die TrackViewer-API auf seinen eigenen Seiten einsetzen will. Hier wird grundsätzlich beschrieben, wie man mit der API einen eigenen Trackviewer aufbaut.

Für Anwender des interaktiven Trackviewers oder einer einfachen Trackanzeige ist die hier aufgeführte Programmierung nicht nutzbar.

Was ist die TrackViewer-API?

Im Unterschied zu anderen Trackviewervarianten, die alle kurz auf dieser Vergleichsseite gegenübergestellt und beschrieben werden, handelt es sich bei der TrackViewer-API um keine eigene Webseite, sondern um eine Programmierschnittstelle (API = application programming interface). So wie es die Google-Maps API einem Webmaster ermöglicht, Google-Maps-Karten auf seiner Website anzuzeigen, so erlaubt es ihm die TrackViewer-API GPX-Dateien zu visualisieren. Die TrackViewer-API bringt also Tracks, Routen und Wegpunkte grafisch auf die eigene Webseite.

Was wird benötigt?

Um die TrackViewer-API benutzen zu können werden keine großartigen Programmierkenntnisse benötigt. Ein wenig Javascripterfahrung schadet aber nicht, vor allem, wenn die API durch eigene Programmierung erweitert werden soll. Ein lauffähiges Grundgerüst generiert bereits der interaktive Trackviewer automatisch.
Die Voraussetzungen im einzelnen sind:

Wie das alles eingebunden wird, wird nachfolgend beschrieben.

Wie fange ich an?

Am einfachsten gelingt der Schritt zum ersten eigenen Trackviewer über die interaktive Trackviewer-Seite auf GpsWandern.de. Dazu ist es wichtig, zuerst die GPX-Datei, deren Inhalt angezeigt werden soll im WEB abzulegen. Das muss nicht die gleiche Stelle sein, auf der die Trackviewer-Seite zu liegen kommt - kann aber. Wichtig ist nur, dass die GPX-Datei im Internet per URL (http://...) erreichbar ist. Die Adresse wird dann im interaktiven Trackviewer in das Feld "URL" eingegeben und nach Klick auf den Button "WEB-Datei abrufen" wird nicht nur der Inhalt der GPX-Datei in Karte und Höhenprofil angezeigt, es wird auch der komplette HTML-Code zur Erstellung einer Webseite mit Trackviewer generiert. (Das unterste der drei Codefenster ist das richtige für die TrackViewer-API).

Der vorgenerierte Code lässt sich 1:1 per Copy&Paste in eine eigene Webpage übernehmen und diese per FTP auf den eigenen Webspace hochladen. Fertig ist der eigene Trackviewer.

Der Programmcode kurz im Überblick

Der Programmcode im Detail

Codezeile Beschreibung
<!DOCTYPE html> Der Dokumenttyp, hier HTML5. Für Google-Maps wird HTML5 empfohlen, es funktioniert zum Beispiel aber auch mit XHTML 1.0 Transitional
<html>
<head>
<title>Mein eigener Trackviewer</title>
Wie in jeder HTML-Seite. Den Titel natürlich auf die eigenen Bedürfnisse anpassen!
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> Der Content-Type, ist "text/html", wie üblich. Als Zeichensatz wird UTF-8 empfohlen, es funktioniert aber auch mit ISO 8859-1
<style type="text/css">
 #karte {width:800px; height:400px}
 #linkback {margin-top:4px; font-size:9pt;}
 #hoehe {width:798px; border:solid black 1px; background-color:#dfdfdf;}
 #hoehenprofil {float:left;}
 #hoetabklein {font-size:11pt;}
 .clearleft {clear:left;}
</style>
Styleangaben hauptsächlich für das Layout der Höhendatentabelle. Wichtig ist es, hier die Größe des Kartenfensters zu bestimmen. Der Rest kann auch entfallen oder nach eigenen Vorstellungen gestaltet werden. Die Auslagerung in ein eigenes Stylesheet ist natürlich möglich.
</head>
<body>
 
<script type="text/javascript"
 src="//maps.googleapis.com/maps/api/js?key=MY-KEY">
</script>
Einbindung der Google-Maps API.
Es funktioniert zwar auch ohne Google-Key also &key=MY-KEY ruhig erst mal weg lassen. Google erwartet jedoch, dass man sich einen eigenen kostenlosen Key auf https://code.google.com/apis/console abholt und ihn anstelle von MY-KEY einbaut.
<script type="text/javascript"
 src="//code.jquery.com/jquery-1.8.3.min.js">
</script>
Einbindung von jQuery.
<script type="text/javascript"
 src="http://tvapi.gpswandern.de/v/2/">
</script>
Einbindung der TrackViewer-API.
Alternativ dazu per Https mit folgender URL:
https://ssl-account.com/tvapi.gpswandern.de/v/2/
<script type="text/javascript"> Nun folgt JavaScript Code zur Konfiguration des Trackviewers.
var Tv = new TrackViewer; Die Variable "Tv" (kann natürlich auch anders heißen) wird zum Trackviewer-Objekt, mit dem anschließend gearbeitet werden kann.
Tv.url = "http://muenchen-surf.de/karger/beispiel.gpx"; Hier kommt der Verweis auf die GPX-Datei. Der Link kann so wie hier absolut ("http://...") erfolgen oder relativ zur aufrufenden HTML-Datei (also schlicht "meintrack.gpx" wenn diese Datei im selben Verzeichnis liegt.
Tv.mapDiv = "karte"; Hier wird dem Trackviewer mitgeteilt, wohin die Karte gezeichnet werden soll. Das DIV-Element mit dieser Id muss dann später auch im HTML-Code vorkommen.
Tv.eleProfDiv = "hoehenprofil"; DIV-Id für das Höhenprofil (Grafik). Falls kein Höhenprofil gewünscht wird, dann diese Zeile einfach weglassen.
Tv.eleSmallTabDiv = "hoetabklein"; DIV-Id für die kleine Höhendatentabelle (es gibt auch eine große: Tv.eleLargeTabDiv). Falls keine Höhendatentabelle gewünscht wird, dann diese Zeile einfach weglassen.
Tv.eleProfWidth = 600; Die Breite der Höhenprofilgrafik in Pixel.
Tv.eleProfHeight = 170; Die Höhe der Höhenprofilgrafik in Pixel.
Tv.mapType = "hybrid"; Auswahl des Kartentyps. Möglich sind: roadmap, terrain, hybrid, satellite, osm, osmc, landscape, outdoors oder hikebike.
Tv.xxx = "yyy"; An dieser Stelle können noch weitere Optionen gesetzt werden - siehe: Programmier-Referenz.
Tv.request(); Die Anforderung wird abgeschickt.
Nun wird die GPX-Datei abgerufen und ihr Inhalt angezeigt.
</script> Ende des Scripts, was nun folgt ist der Aufbau der Seite in HTML.
<div id="karte"></div> Ein leeres DIV zur Aufnahme der Karte.
<p id="linkback">Der Trackviewer wird bereitgestellt von
 <a href="http://www.gpswandern.de">www.GpsWandern.de</a>.
</p>
GpsWandern.de erwartet im HTML-Code einer Seite, welche die TrackViewer-API verwendet, einen Link zurück. Das kann zum Beispiel in dieser Form erfolgen.
<p>Höhenprofil:</p>
<div id="hoehe">
 <div id="hoehenprofil"></div>
 <div id="hoetabklein"></div>
 <div class="clearleft"></div>
</div>
Der Rest ist wieder Gestaltung der Seite. Hier werden die DIVs für das Höhenprofil und die kleine Höhendatentabelle gesetzt.
Falls kein Höhenprofil und keine Höhendatentabelle gewünscht wird, dann können diese Zeilen entfallen.
</body>
</html>
 

Erweiterung durch Userexits

Userexits sind vordefinierte Funkionsaufrufe, die - sofern die Funktionen vom Webmaster angelegt wurden - an verschiedenen Stellen im Ablauf der API aufgerufen werden. So kann der Webmaster in die Verarbeitung der API selber programmtechnisch eingreifen. Für einfache Anwendungen wird das nicht erforderlich sein, die TrackViewer-API bietet die Möglichkeit aber an.

Wie die Userexits heißen müssen, wie sie angelegt werden und wann sie von der API aufgerufen werden, darüber gibt die Programmier-Referenz Auskunft.

Asynchrone Verarbeitung

Ein kurzes Wort zur internen Verarbeitung der API. In dem Moment, in dem Tv.request(); aufgerufen wird, wird eine Anforderung an einen serverseitigen Prozess gestartet, der auf der Website von GpsWandern.de läuft. Dieser Anforderung werden alle Optionen mitgegeben, die der Webmaster auf seiner Seite definiert hat, darunter vor allem die URL der GPX-Datei. Der Serverprozess ruft nun die GPX-Datei ab und bereitet die Daten auf. Dabei erzeugt er die Grafik des Höhenprofils und fertigt zwei verschiedene Höhendatentabellen vor. Die Daten werden dann an den Browser des Anwenders zurückgeschickt an eine speziell Antwortfunktion. Die veranlasst dann die Weiterverarbeitung, also die Darstellung in der Karte zum Beispiel.

Asynchron heißt diese Art der Verarbeitung deshalb, weil der Browser (also das JavaScript-Programm) nicht angehalten wird während die serverseitige Verarbeitung läuft, sondern weiterarbeitet. Irgendwann kommt dann die Serverantwort und triggert die Antwortfunktion, damit es weitergeht.

Warum erwähne ich das? Nun, ein Webmaster könne auf die Idee kommen, nach der Zeile
Tv.request();
einfach selber weiter zu programmieren. In folgendem Fall würde das sogar funktionieren:
Tv.request();
alert(Tv.version);

weil die Version zu diesem Zeitpunkt bereits bekannt ist. Folgende Abfrage würde allerdings schiefgehen:
Tv.request();
alert(Tv.host.status);

Warum das? Nun Tv.request(); wird nicht angehalten, solange die serverseitige Verarbeitung läuft, sondern sofort die nachfolgende Programmzeile mit dem alert(); ausgeführt. Zu diesem Zeitpunkt ist das Verarbeitungsergebnis aber noch nicht zurück und Tv.host nicht definiert.

Was also tun, wenn mit serverseitigen Daten weitergearbeitet werden soll? Hier kommen die Userexits ins Spiel. userExit2(obj); wird zum Beispiel getriggert, sobald die serverseitige Verarbeitung beendet ist aber noch vor geschaut wird, ob ein Fehler aufgetreten ist. Der richtige Zeitpunkt für:
Tv.request();
function userExit2(obj) {
 alert(obj.host.status);
}

Das wird funktionieren!

Versionierung

alert(Tv.version);
gibt die geladene Version der TrackViewer-API aus. Das sieht in etwa so aus: "2/0/0". Die Hauptversion ist also 2 und die beiden Unterversionen jeweils 0. Die TrackViewer-API wird sich weiterentwickeln, so dass die darauffolgende Version "2/0/1" heißen wird und eine spätere vielleicht "2/1/0". Dabei ist vorgesehen Änderungen, die das Datenmodell beeinflussen, nicht in den Unter-unter-Versionen (also auf Ebene der dritten Stelle) durchzuführen. Hier soll nur Fehlerkorrektur erfolgen.
Überholte Versionen der API sollen auch nicht gelöscht werden, sondern zumindest so lange bestehen bleiben, so lange sie genutzt werden.

Der Webmaster hat es nun in der Hand, welche Version er lädt.
<script type="text/javascript"
 src="http://tvapi.gpswandern.de/v/2/0/0/">
</script>

Damit wird explizit die Version "2/0/0" angefordert. Möglich ist jedoch auch:
<script type="text/javascript"
 src="http://tvapi.gpswandern.de/v/2/0/">
</script>

Das fordert die aktuellste Version unter "2/0" an. Oder:
<script type="text/javascript"
 src="http://tvapi.gpswandern.de/v/2/">
</script>

würde über zwei Versionierungsebenen die aktuellste "2"er Version laden. Für produktive Seiten bietet sich die mittlere Variante an. Damit sind kleinere Fehlerbehebungen in der API automatisch mit dabei, ein Versionssprung auf der zweiten Ebene erfolgt jedoch nicht ohne Eingriff des Webmasters.

Hilfe

Weitere Anleitungsseiten zum Themenkomplex TrackViewer-API finden Sie hier:

Markenzeichen: Google und Google-Maps sind Marken der Google Inc. USA.

Stand: Oktober 2014