Folgen Sie GpsWandern.de auch per Atom-Feed:

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.

Kartenfenster mit TrackViewer-API erzeugt (Screenshot)

Kartenfenster mit TrackViewer-API erzeugt (Screenshot)

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.

Welche Versionen gibt es?

Aktuell ist die Version 5 der TrackViewer-API vom Dezember 2020. Dies ist die empfohlene Version.

Ältere Versionen werden bei www.GpsWandern.de nicht gelöscht und können weiterhin genutzt werden. Ein Upgradezwang besteht also nicht. Ältere Versionen werden aber nicht mehr unterstützt, nicht mehr weiterentwickelt und auch die Dokumentation bezieht sich nur auf die aktuelle Version.

Mehr zu den einzelnen TrackViewer-API Versionen gibts im ChangeLog.

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(s)://...) erreichbar ist. Die Adresse wird dann im interaktiven Trackviewer in das Feld "URL" eingegeben und nach Klick auf den Button "WEB-Datei abrufen" wird der Inhalt der GPX-Datei in Karte und Höhenprofil angezeigt. Es können über einen Button oberhalb des Kartenfensters zusätzliche Karten ausgewählt werden. Der TrackViewer generiert dazu den komplette HTML-Code zur Erstellung einer Webseite. (Das unterste der drei Codefenster ist das richtige für die TrackViewer-API).

Der vorgenerierte Code ist so gestaltet, dass externe APIs (Leaflet und jQuery) direkt aus dem Internet geladen werden. So kann der generierte Code 1:1 per Copy & Paste in eine HTMl-Seite auf dem eigenen Web-Space übernommen werden und ist sofort lauffähig. Für den produktiven Betrieb empfiehlt es sich aber (auch aus Datenschutzgründen) sowohl Leaflet, als auch jQuery auf den eingenen Server zu laden und die Programmpfade entsprechend anzupassen.

Der Programmcode kurz im Überblick

Der Programmcode für die TrackViewer-API V.5 im Detail

Codezeile Beschreibung
<!DOCTYPE html> Der Dokumenttyp, hier HTML5, 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 charset="utf-8"/> Als Zeichensatz wird utf-8 empfohlen, es funktioniert aber auch mit ISO 8859-1
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.7.1/dist/leaflet.css"
 integrity="sha512-xodZBNTC5n17Xt2atTPuE1HxjVMSvLVW9ocqUKLsCC5CXdbqCmblAshOMAS6/keqq/sMZMZ19scR4PsZChSR7A=="
 crossorigin=""/>		 Einbindung des Leaflet Stylesheets über das Leaflet eigene CDN (Content Delivery Network). Für einen produktiven Betrieb ist es besser, die Datei leaflet.css und das Verzeichnis images auf den eigenen Server zu übernehmen und die Verlinkung entsprechend anzupassen.
<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 src="https://unpkg.com/leaflet@1.7.1/dist/leaflet.js"
 integrity="sha512-XQoYMqMTK8LvdxXYG3nZ448hOEQiglfqkJs1NOQV44cWnUrBc8PkAOcXy20w0vlaXaVUearIOBhiXZ5V3ynxwA=="
 crossorigin=""></script>		 Einbindung der Leaflet JavaScript API.
Auch leaflet.js sollte besser auf den eigenen Server übernommen werden. (Leaflet 1.4 funktioniert auch)
<script type="text/javascript"
 src="https://code.jquery.com/jquery-3.5.1.min.js">
</script> 		Einbindung von jQuery.
Die jQuery-Datei kann aus Datenschutzgründen ebenfalls heruntergeladen und auf dem eigenen Server gehostet werden. Version 1.8.3 funktioniert auch.
<script type="text/javascript"
 src="https://tvapi.gpswandern.de/v/5/">
</script> 		Einbindung der TrackViewer-API.
Ab Version 3 immer per https.
<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://helmutkarger.de/download/tvapi/beispiel.gpx"; Hier kommt der Verweis auf die GPX-Datei. Der Link kann so wie hier absolut ("http://...", bzw. "https://...") 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.selectedMaps = ["OpenStreetMap.de","OpenStreetMap.fr OSM France","Kartogiraffe Hiking"]; Auswahl der Karten. Siehe Kartenanleitung.
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 spezielle 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 bevor 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: "5/0/0". Die Hauptversion ist also 5 und die beiden Unterversionen jeweils 0. Die TrackViewer-API wird sich weiterentwickeln, so dass die darauffolgende Version "5/0/1" heißen wird und eine spätere vielleicht "5/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="https://tvapi.gpswandern.de/v/5/0/0/">
</script>
Damit wird explizit die Version "5/0/0" angefordert. Möglich ist jedoch auch:
<script type="text/javascript"
 src="https://tvapi.gpswandern.de/v/5/0/">
</script>
Das fordert die aktuellste Version unter "5/0" an. Oder:
<script type="text/javascript"
 src="https://tvapi.gpswandern.de/v/5/">
</script>
würde über zwei Versionierungsebenen die aktuellste "5"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.

Umstellung von Version 4 auf V5

Wer bereits die Version 4 einsetzt, der benutzt bereits Leaflet und hat es mit der Umstellung leicht. Eigentlich geht es nur um das Kartenhandling. Die alten Kartenbezeichnungen wie zum Beispiel "osm" gibt es nicht mehr. Ich empfehle, den interaktiven Trackviewer zu verwenden, um die Karten auszuwählen, die künftig eingesetzt werden sollen. Dann ersetzt man die Zeile:

Tv.mapDiv = "osm";

einfach durch:

Tv.selectedMaps = ;

aber halt mit den Karten, die man selber haben will.

Dann die Version auf 5 umstellen:

<script type="text/javascript" src="https://tvapi.gpswandern.de/v/5/"></script>

und am besten die aktuellen Versionen von Leaflet und jQuery downloaden und einbinden (siehe oben), die alten Versionen funktionieren aber auch.

Der Umstieg von Version 3 auf Version 5 ist etwas aufwändiger, da Version 3 noch die Google-Maps-JavaScript-API anstelle Leaflet verwendet. Hier ist es am einfachsten, mit dem interaktiven Trackviewer einen neuen Beispielcode zu generieren und anhand dessen die eigene Seite anzupassen. Dazu gehört es jQuery und Leaflet downzuloaden und die Einbindung von Google-Maps zu entfernen.

Hilfe

Weitere Anleitungsseiten zum Themenkomplex TrackViewer-API finden Sie hier:

Stand: Dezember 2020