User Manual Falk Map API
Allgemeines zur Benutzung der API
Einleitung
Die Falk Map API ist eine Programmierschnittstelle, mit der auf einfache Art und Weise interaktive Kartenanwendungen erstellt und per JavaScript in eine beliebige Webseite eingebunden werden können. Die Schnittstelle bietet dabei eine Vielzahl von Möglichkeiten, die Karten zu verändern, eigene Inhalte zu integrieren, Adressen zu geolokalisieren und eine Routenplanung durchzuführen.
Die API liefert dabei lediglich die Schnittstellen, die zum Bau eines User Interfaces nötig sind. Das User Interface selber ist nicht Bestandteil der API. Das einzige User Interface, welches die API bereitstellt ist ein Kartenwidget.
Das Verhalten und die Implementierung der Falk Map API soll nachfolgend dokumentiert und durch einzelne Anwendungsbeispiele visualisiert werden.
Versionen
Die Schnittstelle der Falk Mapi API liegt in 2 Versionen vor. Die Interfaces unterscheiden sich in den Koordinaten-Formaten und der Definition der Zoomlevel. Die restliche Funktionalität der Methoden ist in beiden Versionen identisch.
Version 1
Das default Koordinaten-Format ist eine Mercator_Projektion mit einem Erdradius von 6.371.000 Meter. Mit Hilfe der FalkMapConfiguration kann man das Koordinaten-Format explizit auf WGS-84 umstellen.
Die Zoomlevel sind definiert für den Werte-bereich von -2 bis 17. Der Wert -2 entspricht dem größten Maßstab, d.h. die höchste Detailansicht. der Wert 17 entspricht der Weltansicht.
Version 2
Das default Koordinaten-Format ist WGS-84. Mit Hilfe der FalkMapConfiguration kann man das Koordinaten-Format explizit auf eine Mercator-Projektion umgestellt werden, wobei zu berücksichtigen ist, dass der verwendete Erdradius 6.378.137 Meter entspricht.
Die Zoomlevel sind definiert für den Werte-bereich von 1 bis 19. Der Wert 1 entspricht dem kleinsten Maßstab und zeigt die gesamte Welt. Der Wert 19 entspricht zeigt eine Karte mit dem größten Maßstab, d.h. die höchste Detailansicht.
Beim Laden der API gibt man mit Hilfe eines request-Parameters an, welches Interface man haben möchte. Hängt man den request-Parameter v=2 an, wird das neue Format geladen. Fehlt dieser Parameter wird das alte Format der Api geladen. Es wird empfohlen, die Version 2 der Falk Map API zu verwenden.
Beispiel altes Format:
<script type="text/javascript"
src="http://maps.falk.de/do/loadFalkMapApi?id=YourLicenceKey">
</script>
Beispiel neues Format:
<script type="text/javascript"
src="http://maps.falk.de/do/loadFalkMapApi?id=YourLicenceKey&v=2">
</script>
Browser Kompatibilität
Die API ist auf folgenden Browser getested
| Browser | Version |
|---|---|
| MS Internet Explorer | ab Version 6.0 (ab Version 5.5) |
| Mozilla Firefox | ab Version 2.0 |
| Opera | 9+ |
| Apple Safari | 2+ |
| Konqueror | 3.5+ |
Hostingumgebung
Die Falk Map API wird unter der Domain http://maps.falk.de/ gehostet und von der Falk Content & Internet Solutions GmbH & Co. KG zur Verfügung gestellt. Sie kann nach einer Registrierung und Freischaltung einer Domain auf eigenen Seiten eingebunden werden. Die Falk Content & Internet Solutions GmbH & Co. KG ist Eigentümer aller Rechte.
Zugangsbeschränkung
Die Nutzung der Falk Map API ist an eine Freischaltung für einen anzugebenen Domainnamen oder eine IP-Adresse gebunden. Für jede Freigabe wird ein Lizenzkey erstellt, der für das Einbinden der Falk Map API Voraussetzung ist.
Der Lizenzschlüssel ist beim Laden des JavaScripts anzugeben:
<script type="text/javascript" src="http://maps.falk.de/do/loadFalkMapApi?id=$YOUR_LICENCE_KEY$"></script>
Genauere Angaben zu diesem Thema entnehmen Sie bitte der E-Mail, die Ihnen bei Freischaltung ihrer Domain zugestellt wird.
Das Yahoo User Interface (YUI 2)
Die Falk Map API und der Falk Kartendienst beinhaltet die YUI 2 Library Version 2.9.0.
Folgende Komponenten sind defaultmäßig eingebunden:
- yahoo
- YUI Dokumentation für Module: yahoo
- YUI Beispiele für YUI 2: YAHOO Global Object
- dom
- YUI Dokumentation für Module: dom
- YUI Beispiele für YUI 2: Dom Collection
- event
- YUI Dokumentation für Module: event
- YUI Beispiele für YUI 2: Event Utility
- dragdrop
- YUI Dokumentation für Module: dragdrop
- YUI Beispiele für YUI 2: Drag & Drop
- animation
- YUI Dokumentation für Module: animation
- YUI Beispiele für YUI 2: Animation
- container
- YUI Dokumentation für Module: container
- YUI Beispiele für YUI 2: Container
- slider
- YUI Dokumentation für Module: slider
- YUI Beispiele für YUI 2: Slider
Nutzen Sie die den Falk Kartendienst mit Falk Map API können bei Bedarf weitere Komponenten der YUI in der Datei eingebunden werden.
Getting Startet mit Falk Maps
Die folgende Webseite zeigt eine 300*300 px große Karte, die auf Kemnat, Ostfildern zentriert ist.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>Falk Map: getting started</title> <script type="text/javascript" src="http://maps.falk.de/do/loadFalkMapApi?id=123456789&v=2&language=en"> </script> <script type="text/javascript"> registerNodeListener(window, "load", main); // html loaded function main(){ // create a new map map = new FalkMap("mymap"); // create a GeoPoint geocode = new FalkPoint(9.223379437790086, 48.72223860481109); // show map at this point in zoomlevel 13 map.centerMapToGeocode(geocode, 13); } </script> <style type="text/css"> #mymap { width: 300px; height: 300px;} </style> </head> <body> <div id="mymap"> </div> </body> </html>
Über die URL http://maps.falk.de/do/loadFalkMapApi?id=123456789 im obigen Beispiel wird die Falk Map API geladen.
Der Aufruf der Methode registerNodeListener(window, "load", main); dient dazu, die Karte nach dem Laden des Dokumentes zu initialisieren.
Im HTML-Teil wird zum Anzeigen der Karte nur ein DIV mit einer eindeutigen ID benötigt. Diese ID muss der ID beim Erzeugen der Karte entsprechen.
map = new FalkMap("mymap");
Geocoding
Formate von Geokoordinaten
Es können Geokoordinaten in den Formaten WGS84 und Mercator genutzt werden. Bem Mercator-Format ist zu berücksichtigen, dass abhängig vom Versions-Parameter der Erdradius entweder 6.371.000 Meter oder 6.378.137 Meter ist.
Desweiteren ist zu berücksichtigen, dass in der Version 2 das voreingestellte Default-Format WGS84 ist.
Beispiel:
Geokoordinaten der Pinakothek der Moderne im WGS84-Format: (11.57202, 48.14899)
Geokoordinaten der Pinakothek der Moderne im Mercator-Format: (1286750, 6124816)
Zur Konfiguration siehe Konfigurierbarkeit der Geokoordinatenformate.
Geocodierung von Adressen
Um eine Adresse in der Karte anzeigen zu können, müssen vorhandene Adresse zunächst mit einem Geocode versehen werden. Diese kann dann genutzt werden, um über ein FalkMapObject (FMO) eine Fähnchen in der Karte zu platzieren.
Es gibt zwei Möglichkeiten, Addressen zu geokodieren:
1. Geokodieren mit FalkAddress
Das stellt eine strukturierte Form der Adresseingabe dar. Bei einem FalkAddress Objekt können Sie die Eigenschaften einer Adresse gezielt befüllen.
Folgende Schritte sind dabei notwendig:
- Erzeugen eines FalkAddress-Objektes mit den relevanten Daten der Adresse
- Erzeugen eines FalkGeocoder-Objektes
- Aufruf der Methode
FalkGeocoder#geocodeAddress(falkAddress)des FalkGeocoders mit der Adresse als Parameter
Einfaches Beispiel
Parallele Geocodierung mehrerer Addressen
2. Geokodieren mit einer unstruktierten Adressangabe
Dabei wird versucht, für eine als Text vorliegende Adresse einen Geocode zu ermitteln. Der FalkGeocoder stelle dazu die Methode FalkGeocoder#geocodeLocation(/* String */ location) zur Verfügung.
Je nach Eingabe der Adressdaten variiert dabei die Treffergenauigkeit. Am besten ist es daher, wenn Sie die Adresseingabe mit dem FalkAutoSuggestControl verknüpfen. Das angegeben Beispiel zeigt die notwendigen Schritte.
Reverse Geocoding
Unter Reverse Geocoding, also einer umgekehrten Geokodierung, wird das ermitteln einer Adresse zu einem gegebenen Geocode verstanden. Der FalkGeocoder stellt dafür die Methode FalkGeocoder#findLocation(/*FalkPoint*/ geocode) zur Verfügung.
Das unten angegebene Beispiel zeigt, wie man einen Geocode durch einen Klick in die Karte ermitteln kann. Mit dem dadurch ermittelten Geocode wird die Methode FalkGeocoder#findLocation(/*FalkPoint*/ geocode) aufgerufen. Das Resultat wird in der Karte mit einem Fähnchen markiert und im sich öffnenden InfoFenster werden die Adressdaten angezeigt.
Konfigurierbarkeit der Geokoordinatenformate
Der Nutzer kann festlegen, welches Geokoordinatenformat er nutzen möchte.
Dazu muss die Eigenschaft FalkMapConfiguration.mapCoordinateFormat entsprechend eingestellt werden.
Mögliche Werte sind
FalkMapConfiguration.mapCoordinateFormat = FalkMapConfiguration.MAP_COORDINATE_FORMAT_MERCATOR
oder
FalkMapConfiguration.mapCoordinateFormat = FalkMapConfiguration.MAP_COORDINATE_FORMAT_WGS_84
In Version 1 ist das Format FalkMapConfiguration.MAP_COORDINATE_FORMAT_MERCATOR voreingestellt.
In Version 2 ist das Format FalkMapConfiguration.MAP_COORDINATE_FORMAT_WGS_84 voreingestellt.
In Abhängigkeit von diesem Wert wird intern die jeweilige Projektion genutzt.
Routenberechnung in WGS84 oder Mercator:
Die Falk Map und ihre Funktionalitäten
Initialisierung
Um die Kartenanzeige zu starten, muss die Karte initialisiert werden. Dazu gibt man entweder einen Geocode und einen Zoomlevel oder eine gültige BoundingBox an. Im zweiten Fall wird der Zoomlevel automatisch so berechnet, dass die komplette BoundingBox in den Viewport passt.
Angabe von Geocode und Zoomlevel
Um eine Karte mit einem Geocode und Zoomlevel zu initialisieren, sind folgende Schritte notwendig:
- Erzeugen eines Map-Objektes
- Aufruf der Methode
centerMapToGeocodeauf dem Map Objekt
Angabe einer BoundingBox
Um eine Karte mit einer BoundingBox zu initalisieren, sind folgende Schritte notwendig:
- Erzeugen eines Map-Objektes
- Aufruf der Methode
centerMapToBoundingBoxauf dem Map Objekt
MapLayer (Karte / Sat / Birdview)
Die FalkMapApi unterstützt die Anzeige unterschiedlicher Karten-Ansichten (MapLayer). Zur Zeit sind folgende MapLayer verfügbar:
- MAP - Straßen-Karten von Mairdumont
- MSMAP - Straßen-Karte von Bing
- MSAIR - Sat-Karte von Bing
- MSHYBRID - Hybrid-Karte von Bing
- BIRDVIEW_NORTH - Vogelperspektive in Richtung Norden
- BIRDVIEW_WEST - Vogelperspektive in Richtung Westen
- BIRDVIEW_SOUTH - Vogelperspektive in Richtung Süden
- BIRDVIEW_EAST - Vogelperspektive in Richtung Osten
Um den MapLayer umzuschalten verwendet man die Funktion:
FalkMap.prototype.changeMapLayer = function (mapLayerName)
ACHTUNG: Für alle Kartenansichten unterstützt die Karte die Methode:
FalkMap.prototype.getPixelPositionOfGeocode
Wichtig ist zu wissen das die Koordinatensysteme für die Birdview-Ansicht nicht linear sind und das sie je nach Scene unterschiedlich gedreht und verzerrt sind.
Die Birdview-Kartenansichten unterstützen die Varianten mit und ohne Label. Defaultmäßig ist die Variante mit Label aktiv. Soll auf die andere Variante umgeschaltet werden, sind folgende Schritte notwendig. Man wollt sich den oder die entsprechenden MapLayer über die FalkMapConfiguration und setzt das Flag useLabels um. Das folgende Beispiel zeigt wie man alle Birdview MapLayer umschaltet.
var layers = FalkMapConfiguration.getMapLayerByGroupName(layer.group);
for (var i = 0; i < layers.length; i++) {
layers[i].useLabels = false;
}
FalkMapConfiguration
Da nicht alle Karten_layer alle Zoomstufen zur Verfügung stellen, liefert die Klasse FalkMapConfiguration Methoden zur verfügung, um zu prüfen ob Zoomlevel verfügbar sind, welcher der nächste Zoomlevel ist, und welcher Zoomelvel am besten passen würde, wenn der gewünschte Zoomlevel nicht verfügbar ist.
Verfügbarkeit von Birdview
Birdview ist in nicht allen Teilen der Welt verfügbar. Bei jeder Kartenoperation, in der nicht Birdview-Ansicht prüft die Karte, ob Birdview Verfügbar ist.
Für die Verfügbarkeit von Birdview zu prüfen sind folgende Events verfügbar:
/** * The event is fired when for the current geocode birdview is available */ FalkMap.MSG_BIRDVIEW_AVAILABLE /** * The event is fired when for the current geocode birdview is not available */ FalkMap.MSG_BIRDVIEW_NOT_AVAILABLE
ACHTUNG:: Das Birdview Event MSG_BIRDVIEW_AVAILABLE wird nur erzeugt wenn man sich in einer Zoomstufe größer gleich 12 befindet. Für alle anderen Zoomstufen wird Birdview nicht geprüft und das Event MSG_BIRDVIEW_NOT_AVAILABLE geworfen.
Fragt man in der Birdview-Ansicht einen neuen Geocode an, für den keine Szene verfügbar ist, wird folgendes Event geworfen.
/** * The event is fired when a scene was requested, but cannot be loaded */ FalkMap.MSG_BIRDVIEW_SCENE_NOT_AVAILABLE
Angabe Bühne via FalkMapStage
Die FalkMapStage dient dazu, einen bestimmten Bereich der Karte als den Bereich zu bestimmen, der für die Anzeige einer BoundingBox oder zum Zentrieren der Karte genutzt werden soll. Das ist sinnvoll, wenn Teile der Karte durch Controls verdeckt sind und diese Bereiche nicht Fokus des Interesses liegen.
Zum definieren einer FalkMapStage muss Höhe und Breite der Stage definiert werden. Außerdem kann über ein Offset eine Verscheibung der Stage auf der Karte erreicht werden.
- Erzeugen eines FalkMap-Objektes
- Erzeugen eines FalkMapStage-Objektes
- Aufruf der Methode
FalkMap#setFalkMapStage(FalkMapStage)
var mapStage = new FalkMapStage ({Number} width, {Number} height, {Number} offsetX, {Number} offsetY);
map.setFalkMapStage (mapStage);
Insbesondere bei der Routenplanung kommt die FalkMapStage zum tragen. Hat man eine FalkMapStage definiert, malt der Router die Route in diesen Bereich. Der Zoomlevel wird automatisch so bestimmt, dass die gesamte Route innerhalb der Stage sichtbar ist. Ohne Definition der Bühne würde der Zoomlevel der Karte so gewählt, dass die Route im Viewport der gesamten Karte gezeichnet wird. Das ist von Nachteil, wenn bestimmte Bereiche der Karte von einem Control verdeckt sind.
Öffnet man für einzelne Wege-Punkte das Info-Fenster, wird dieses auch innerhalb des FalkMapStage dargestellt.
Lebenszyklusinformationen (Event-Handling)
Es besteht die Möglichkeit, sich über Events informieren zu lassen, wenn sich die Karte geändert hat. Hierzu kann man sich mit der subscribe Methode auf ein bestimmtes Event registrieren. Der zweite Parameter der Methode ist ein Funktionspointer auf die Funktion, die aufgerufen wird, wenn das Ereignis eintritt:
map.subscribe(FalkMap.MAP_CHANGED, newCenterGeocode);
Analog kann man auch ein unsubscribe durchführen, wenn man nicht mehr benachrichtigt werden will.
Beispiel: Karte mit Übersichtsichtskarte
Die durchgeführten Kartenaktionen auf der einen Karte werden analog auf der zweiten Karte durchgeführt:
Beispiel: Neupositionierung der Karte bei Klick auf GeoPunkt
Beim dem Event FalkMap.MSG_MAP_CLICKED wird man informiert, wenn der Benutzer in die Karte geklickt hat. Das nachfolgende Beispiel nutzt dieses Event, um einen GeoPunkt in der Karte neu zu positionieren.
Geo-Lokalisierung der IP-Adresse
Die Api bietet die Möglichkeit, zu der IP-Adresse des Client eine Geo-Lokalisierung durchführen zu lassen. Hierfür muss die Api mit dem Parameter locate geladen werden. Ist dieser Parameter nicht gesetzt findet keine Geo-Lokalisierung statt.
Die Geo-Lokalisierung besteht aus zwei Teilen:
- Bestimmung des Geocodes der IP-Adresse
- Bestimmung der Adresse des bestimmten Geocodes
Abfragen kann man diese Informationen an der FalkMap über die Schnittstelle:
FalkMap.prototype.getClientLocation = function()
Das Rückgabe-Objekt ist vom Typ FalkClientLocation. Die Variablen address und geocode sind gesetzt, wenn die jeweiligen Schritte erfolgreich durchgeführt werden konnten. Konnte ein Schritt nicht durchgeführt werden ist die jeweilige Variable null. Wurde die Geo-Lokalisierung nicht aktiviert liefert die Methode null zurück.
Änderbarkeit der Karten-Größe / Karten-Position
Wenn man in einer HTML-Seite die Kartengröße oder -position mit Hilfe von Java-Script ändern will, muss man dies der Karte mitteilen.
Man beauftragt dazu die Karte, ihren Karten-Container zu überprüfen mittels Aufruf der Methode checkMapContainer.
Mit Hilfe des Karten-Features FEATURE_RECENTER_AFTER_CHECK_MAP_CONTAINER kann man einstellen, ob die ursprüngliche Mitte als neue Mitte verwendet werden soll. Ist dies nicht gewünscht, bleibt die linke obere Ecke der Karte fest.
Behandlung der Weltgrenzen
Intern arbeitet die FalkMapiApi mit der Mercator-Projektion auf Basis des Erdradius 6.378.137 Meter. Da die Mercator-Projektion nicht periodisch ist, ist die Welt eine projizierte Fläche. In der X-Richtung wird die Welt periodisch erweitert, so dass ein Verschieben über die Weltgrenze hinaus möglich ist. In der Y-Richtung hört die Welt im Norden bei dem Mercator-Wert -20037508,343 (entspricht -85.06849330187032 Grad in WGS84) und im Süden bei dem Mercator-Wert -20037508,343 (entspricht 85.06849330187032 Grad in WGS84) auf. Kommt man mit der Kartendarstellung an den Rand dieser Fläche werden weiße Kacheln dargestellt.
Verschiebt man die Welt in X-Richtung soweit, dass man die Welt-Grenze ein- oder mehrmals überschreitet, so liefert einem die Api Geocodes und Bounding-Boxen normiert auf die Weltgrenzen zurück. Das heißt der Wertbereich in WGS84 in X-Richtung entspricht -180. ... +180.0 Grad.
Mit der fitToWorld-Option wird die Karte immer so angezeigt, dass sie in Y-Richtung an den Weltgrenzen aufhört. Ein Verschieben der Karte ist dennoch möglich.
Die "fitToWorld"-Option kann man einfach beim Aufruf der Methoden centerMapToBoundingBox und centerMapToGeocode mit angeben werden.
var options = {fitToWorld:true};
map.centerMapToBoundingBox(bb, options);
map.centerMapToGeocode(geocode, zoomlevel, options);
Toolbox für die Karte (Controls)
Die Falk Map API stellt zwei vordefinierte Toolboxen für die Karte zur Verfügung. Es besteht zusätzlich die Möglichkeit eigene Controls zu entwickeln und mit der Karte zu verknüpfen.
Um ein Control einer Karte hinzuzufügen, sind folgende Schritte notwendig:
- Erzeugen eines Map Objektes
- Erzeugen des Controls
- Control dem Map Objekt bekannt machen
BigMapToolbox
Die BigMapToolbox ist innerhalb der Karte verschiebbar und enthält folgende Funktionalitäten:
- Umschalten Panning, Rechteckzoom
- Verschieben der Karte nach Norden, Westen, Süden und Osten
- Zoomslider, inklusive Anzeige der aktuellen Zoomstufe
Die Zoomstufenanzeige im Slider zeigt beim Verschieben des Reglers auch die Zoomstufe an, auf die der Slider gezogen wurde. Beim MouseUp Event wird die Karte dann umgeschaltet.
<script type="text/javascript">
registerNodeListener(window, "load", main);
var bigMapControl = null;
function main() {
FalkMapConfiguration.mapCoordinateFormat = "WGS84";
// create a new map
var map = new FalkMap("mymap");
bigMapControl = new FalkBigMapControl("mycontrol");
map.addMapControl(bigMapControl);
// address
var geocode1 = new FalkPoint(9.014729, 47.854040);
...
}
</script>
SmallMapToolbox
Als kleine Variante gibt es die SmallMapToolbox, die sich innerhalbe der Karte nicht verschieben lässt. Die SmallMaptoolbox enthält die Buttons zum Verschieben der Karte nach Norden, Westen, Süden und Osten, sowie Buttons zum hinein- und herauszoomen.
Durch den Aufruf von
smallMapControl.setPosition (500, 5);
lässt sich die Toolbox fest positionieren. Ist keine Positionierung angegeben wird die Toolbox auf 5px, 5px positioniert.
Eine Kombination mehrerer Toolboxen ist möglich.
<script type="text/javascript">
registerNodeListener(window, "load", main);
var smallMapControl = null;
function main() {
// create a new map
var map = new FalkMap("mymap");
smallMapControl = new FalkSmallMapControl("mysmallcontrol");
smallMapControl.setPosition (5, 5, 'right');
map.addMapControl(smallMapControl);
// address
var geocode1 = new FalkPoint(9.014729, 47.854040);
...
}
</script>
Karte ist in konfigurierten Zoomstufen zoombar
Die Karte ist in konfigurierten Zoomstufen zoombar. Hiiebei ist zu berücksichtigen, dass die Definition der Zoomlevel zwischen den zwei Versionen unterschiedlich ist.
In Version 1 sind die Zoomlevel von -2 bis 17 definiert, wobei -2 die Detailansicht und 17 die Weltansicht abdeckt.
In version 2 sind die Zoomlevel von 1 bis 19 definiert, wobei 19 die Detailansicht und 1 die Weltansicht abdeckt.
Um die Zoomstufen zu konfigurieren muss das Attribut availableZoomlevel der FalkMapConfiguration angepasst werden:
FalkMapConfiguration.availableZoomlevel = [2,6,14];
Karten-Optionen (Features)
Die FalkMapApi besitzt die Möglichkeit, folgende Optionen in der Karte zu nutzen.
- Klick in die Karte zentriert auf den geklickten Punkt
- Doppelklick in die Karte zentriert auf den geklickten Punkt und zoomt um einen Level in die Karte hinein
- Mousewheel zoomt die Karte (in beide Richtungen)
Beim Zoom mit Hilfe des Mousewheels, bleibt die Karte unterhalb des Mauszeigers stehen.
- Bei einer Vergößerung / Verkleinerung der Karte (z.b. Änderung des Brwoserfensters, bei einer Kartemit prozentualer Breite), kann man den bisherigen Mittelpunkt automatisch neu zentrieren lassen.
Eigene Controls
Mit der FalkMapApi können auch eigene Controls zum Ein- und Auszoomen des Kartenausschnitts erstellt werden.
Hierzu können die Methoden map.zoomIn() bzw. map.zoomOut() verwendet werden.
Externe Controls
Bsp.:
<div id="mymap"> </div>
<button type="button" onclick="map.zoomIn();">Einzoomen</button>
<button type="button" onclick="map.zoomOut();">Auszoomen</button>
POI
GeoPunkt (POI) in Karte anzeigen
Um eine GeoPunkt (POI) in einer Karte anzuzeigen, sind folgende Schritte nötig:
- Anlegen eines Map Objektes
- Anlegen eines PoiOverlays Objektes
- Hinzufügen des PoiOverlays zum Map Objekt
- Anlegen eines POI Objektes
- Auf dem POI Objekt einen gültigen Geocode setzen
- Ggf. auf dem POI Objekt das zu verwendende Icon setzen
- Hinzufügen des POIs zum PoiOverlay
- Anzeige der Karte mit diesem Geocode
GeoPunkt (POI) mit Default-Icon
Das folgende zweite Beispiel zeigt, dass das Default-Icon aus der FalkMapConfiguration genommen wird, da kein Icon gesetzt wird.
/**
* the default icon that should will used in case no other icon is assigned
*/
defaultIconUrl : "/img/defaultPoiIcon.gif"
Ein Icon besitzt folgende Attribute, die angepasst werden können:
- alignment: Gibt an wo das Icon ausgerichtet werden Soll (N; E, S, W, SW, NW, SE, NE, Center)
- url: Die URL für das Icon
- offsetX: Verschiebung des Icons (Pixel) in X-Richtung
- offsetX: Verschiebung des Icons (Pixel) in Y-Richtung
Ändert man ein Icon-Attribut, wenn des FalkMapObjekt auf dem Overlay schon bekannt ist, muss das Overlay mit Hilfe der update-Methode aktualisieren.
Zusätzlich zeigt das Beipiel, das man die Karte auch schon starten kann, bevor man den GeoPunkt hinzufügt.
GeoPunkte (POIs) in Layern organisieren
Das FalkPoiOverlay besitzt die Möglichkeit, GeoPunkte in Layern zu organisieren. Dazu kann man im FalkPoiOverlay einen neuen Layer anlegen:
var poiLayerSonnig = new FalkPoiLayer(); poiOverlay.addLayer(poiLayerSonnig);
Man kann einem Layer ein Icon zuweisen:
poiLayerSonnig.name = "sonnig"; poiLayerSonnig.icon = new FalkIcon(); poiLayerSonnig.icon.url = "/img/icons/sonnig.gif";
Dieses Icon wird dann für alle POIs innerhalb dieses Layers verwendet, die kein eigenes Icon assoziiert haben.
Layer kann man dann POIs hinzufügen.
poiOverlay.addPoiToLayer (poi, "sonnig");
Layer können dann sichtbar bzw. unsichtbar geschaltet werden:
poiOverlay.showLayer("sonnig");
poiOverlay.hideLayer("sonnig");
Info-Fenster
Das FalkPoiOverlay bietet die Funktionalität, sich in der Karte ein Info-Fenster anzeigen zu lassen. Zu diesem Zweck steht die Klasse FalkPoiInfoWindow zur Verfügung. Es besteht die Möglichkeit, ein allgemeines oder ein speziell mit den Informationen eines POIs gefülltes Infofenster zu verwenden.
Allgemeines Info-Fenster
Um sich ein allgemeines statisches Infofenster anzuzeigen zu lassen, sind folgende Schritte nötig:
- Erzeugen eines Map Objektes
- Erzeugen eines FalkPoiOverlays Objektes
- Dem Map Objekt das FalkPoiOverlay Objekt hinzufügen
- Aufruf der Methode openInfoWindow (<html>) auf dem FalkPoiOverlay
Poi Info-Fenster
Klickt man auf einen POI, öffnet sich dessen Infofenster. Hat ein POI einen gesetzten Content, so wird dieser angezeigt, andernfalls ruft das FalkPoiInfoWindow die Methode createInfoContent auf, um den Content basierend auf den Addressdaten zu bestimmen.
Das Info-Fenster biete zusätzlich die Möglichkeit einen Titel und Fotter-Zeile zu füllen.
fmo.setInfoTitle ("titel text");
fmo.setInfoFooter("footer text");
Man kann auch Info-Fenster nummerieren. Hierzu setzt man auf dem Icon das text-Attribute.
fmo.icon.text = "1";
Custom Layer (Overlay)
Möchte man ein Custom Overlay programmieren muss dieses das Interface IFalkMapOverlay und damit die Methoden init, hide, show und getName implementieren.
In diesem Beispiel wurde ein Overlay erzeugt, das die definierten Länder der FalkMapAPI in der Karte sichtbar macht. Dabei werden 4 DIV-Elemente so in der Karte positioniert, dass alle Teile der Karte, die nicht zu diesem Landesrechteck gehören, abgedunkelt sind.
Routenplanung
einfache Routen-Darstellung
Möchte man eine Route in der Karte darstellen benötigt man eine Instanz von FalkRouter:
var router = new FalkRouter(map);
Die Stationen der Route gibt man als Instanzen von FalkAddress an. Um eine Geocodierung zu vermeiden (Route kann schneller angezeigt werden), einfach die Adresse mit einem gültigen Geocode verbinden:
var startAddress = new FalkAddress(); startAddress.setGeocode (new FalkPoint(9.265566614323733, 48.57309003880415));
Und anschließend die Routen-Berechnung starten:
router.calcRoute([startAddress, viaAddress, endAddress ]);
Der Router malt automatisch die Route so in die Karte, so dass sie vollständig angezeigt werden kann.
mehrere Routen in Karte / Routenfarbe
Möchte man mehrere Routen in die Karte zeichen instanziert man einfach mehrere FalkRouter. Man muss allerdings beachten, dass wenn eine Routenberechnung fertig ist die Karte auf die BoundingBox der neu berechnetetn Route positioniert wird. Möchte man einen anderen Ausschnitt anzeigen muss man am Ende Die Karte neu positionieren.
Um die Routenfarbe zu ändern setzt man einfach auf dem Router die gewünschte Farbe. Zur Zeit stehen drei Farben als Konstanten in der FalkRouter-Klasse zur Verfügung.
router.setRouteColor (FalkRouter.ROUTE_COLOR_RED);
Routedarstellung mit Beschreibung
Um zusätzlich zum Routenbild eine Wegbeschreibung zu erhalten, definiert amn auf seiner Seite einfach ein DIV in welches die Routenbeschreibung zu rendern sind.
Die Id des DIVs gibt man bei der Erstellung des Routers mit an:
var router = new FalkRouter(map, "routeDescrpiton");
Styling der Wegbeschreibung
Es werden von der API Vorgaben über das Aussehen der Wegbeschreibung getroffen. Will man diese Vorgaben ändern, kann man die voreingestellten CSS-Anweisungen überschreiben, in dem man in einer dem Laden der Falk Map API nachgelagerten JavaScript-Datei diese Angaben überschreibt.
Die Falk Map API besitzt dazu das Konfigurationsobjekt ROUTE_HTML_STYLE.
Dieses Objekt ist ein Array, welches zu jeder definierten CSS-Klasse CSS-Style Angaben aufnimmt.
Das folgende Beispiel zeigt die Defaulteinstellungen für Elemente mit der CSS-Klasse even0. Diese wird benutzt, um Tabellenzeilen mit gerade Zeilennummer zu formatieren:
...
{classname : 'even0',
styles:[
{ key: 'background-color', value: '#FFFFFF'},
{ key: 'cursor', value : 'pointer'}
]
}
...
Die Notation folgt der JSON-Syntax. Das Objekt hat zwei Eigenschaften:
-
classname @type String CSS-Klassenname -
styles @type Array of @type Object
Die Objekte im Array styles haben die Eigenschaften key und value. Beide sind vom Typ String. Der key bezeichnet dabei die CSS-Eigenschaft und value den Wert dieser CSS-Angabe.
Möchte man also die Hintergrundfarbe von weiß (#FFFFFF) auf eine andere Farbe ändern, z.B. hellgrau (#EEE), fügt man der Variablen ROUTE_HTML_STYLE ein neues ConfigurationObject hinzu:
ROUTE_HTML_STYLE.push(
{classname : 'even0',
styles:[
{ key: 'background-color', value: '#EEE'}
]
}
);
Natürlich kann man auf diese Art und Weise nicht nur Werte überschreiben, sondern auch zusätzliche CSS-Anweisungen angeben.
Alternativ kann die Variable ROUTE_HTML_STYLE als leeres Array neu definiert werden:
ROUTE_HTML_STYLE = [];
Jetzt kann die Formatierung über CSS komplett in einem eigenen CSS-File definiert werden.
einfacher Routenplaner
Um einen einfachen Routenplaner zu programmieren, braucht man nur die entsprechenden Eingabefelder. Aus den Eingabefelder werden dann FalkAddress-Objekte erzeugt und dem Router übergeben. Die Adressen werden automatisch geocodiert.
Anfahrtsrouting
Um ein Anfahrts-Routing zu programmieren, verwendet man als Zieladresse eine feste Adresse. Die Startadresse liest man aus Eingabefelder aus. Um an der ZielAddresse z.B. ein Firmenlogo zu bekommen, ist die einfachste Möglichkeit ein FalkMapObjekt genau an dieser Stelle zu definieren. Da sich diese Adresse nicht ändert, sollte man die Geocodes direkt auf dem FalkMapObjekt setzten.
Routen Mal-Modus
Standard mäßig werden die Routenbilder innerhalb des Clients erzeugt. Für den IE wird hierfür VML verwendet und für Firefox und Opera SVG.
Alternativ dazu können die Routen-Bilder auch auf dem Server gemalt werden. Dies lässt sich mit dem Feature FalkRouter.FEATURE_DRAW_ROUTE einstellen.
var routerNoDrawing = new FalkRouter(mapNoDrawing); routerNoDrawing.disableFeature (FalkRouter.FEATURE_DRAW_ROUTE);
ACHTUNG: Für den Safari-Browser wurde immer der Server-Modus gewählt, da sich der Safari (Version 3) noch nicht korrekt an den SVG Standard hält. In der Safari Version 2 ist SVG nicht verfügbar.
Routenplan für Fußweg
Als eine Alternative kann man den Routenplan für Auto oder für Fußweg frei auswählen. Dies lässt sich mit der Erweiterung des Routenprofils um Fußweg RouteProfile.ROUTE_MODE_WALKING einstellen.
var routeProfileWalking = new RouteProfile(); routeProfileWalking.setRouteMode (RouteProfile.ROUTE_MODE_WALKING); routerWalking.setRouteProfile (routeProfileWalking);
Um eine Routenplan für Auto auszuliefern, wird dies mit dem Feature RouteProfile.ROUTE_MODE_DRIVING eingestellt.
var routeProfileDriving = new RouteProfile(); routeProfileDriving.setRouteMode (RouteProfile.ROUTE_MODE_DRIVING); routerDriving.setRouteProfile (routeProfileDriving);
IVW-Handling
Die FalkMapApi besitzt eine API-Komponente zum Zählen von User-Aktionen bei der IVW. Mit Hilfe des statischen Objekts FalkIVWReporter lässt sich die IVW-Integration realisieren.
Eine IVW-Zählung darf immer nur auf Basis einer User-Aktion ausgeführt werden und der Inhalt (Content) der Seite muss sich relevant geändert haben. Auf eine User-Aktion darf immer nur genau eine IVW-Zählung durchgeführt werden.
Die FalkMapApi stellt dies für den Bereich der Karte sicher. Für die Sicherstellung dieses Requirements bei programmtechnischen Erweiterungen ist der Entwickler verantwortlich.
Technischer Hintergrund und Umsetzung
Die IVW API-Komponente besteht aus den Klassen FalkIVWReporter, FalkIVWNotificationData, FalkIVWAcknowledgmentData, FalkIVWMapAcknowledgmentData und FalkIVWConfiguration.
Für eine IVW-Zählung werden grundsätzlich zwei Aktionen benötigt:
- User-Aktion (Notification)
Ein User startet eine Aktion, z.B. Klick auf Zoomlevelwechsel im FalkBigMapControl. Für das Melden einer User-Aktion wird die Methode notifyUserAction mit dem Daten-Objekt FalkIVWNotificationData verwendet. Der Parameter "serviceName" beschreibt den Bereich (z.B. Karte) auf dem die UserAktion durchgeführt wird. Der Parameter "actionName" gibt einen Namen für die User-Aktion an. Dieser Parameter ist optional und wird im Zusammenhang mit der Konfiguration benötigt.
- Bestätigung (Acknowledgment)
Die Seite, in diesem Fall die Karte, bestätigt, dass eine relevante Änderung vorliegt. Für das Melden einer Bestätigungs-Aktion wird die Methode acknowledgeUserAction mit dem Daten-Objekt FalkIVWNotificationData verwendet. Der Parameter "serviceName" beschreibt den Bereich (z.B. Karte), der sich relevant geändert hat. Der Parameter "resultName" ist optional und beschreibt das erreichte Ergebnis bzw. was sich geändert hat. Dieser Parameter wird im Zusammenhang mit der Konfiguration benötigt.
=> Es wird immer dann IVW gezählt, wenn auf eine User-Aktion eine passende Bestätigung folgt. Dabei wird im Normalfall (ohne spezielle Konfiguration) geprüft, ob der "Service-Name" der Notification mit dem "Service-Namen" der Bestätigung übereinstimmt. Ist dies nicht der Fall wird die Bestätigung verworfen. Bleibt die Bestätigung aus oder folgt eine zweite "Notification" einer User-Aktion, wird keine IVW-Zählung durchgeführt. Im Falle einer IVW-Zählung wird der code-Block der IVW-URL mit dem "Service-Namen" ersetzt.
Beim Ausliefern der FalkMapApi wird automatisch eine statische Instanz FalkIVWReporter erzeugt. Auf diesem Objekt werden die User-Aktionen und die Bestätigung mit Hilfe der Methoden notifyUserAction und acknowledgeUserAction gemeldet. Die Karte macht diese Aufrufe automatisch. Als "Service-Namen" verwendet die Karte entweder die HTML-ID des Karten-DIVs oder den Namen der Karte, falls dieser gesetzt wurde.
Konfiguration:
Für die Umsetzung komplexerer IVW-Zählungen (der IVW-Code oder Code-Teile sind abhängig vom jeweiligen Zustand der Applikation) kann die IVW-Zählung konfiguriert werden. Eine Konfiguration besteht aus einer Liste von FalkIVWConfiguration-Objekten. Ein Konfigurationsobjekt beschreibt eine gültige Kombination einer User-Aktion und einer Bestätigung. Bei einer User-Aktion werden die Parameter notificationServiceName und notificationActionName mitgeliefert. Bei einer Bestätigung kommen die Parameter acknowledgmentServiceName und acknowledgmentResultName mit. Bei jeder Bestätigung wird in allen Konfigurations-Einträgen geprüft, ob ein passender Eintrag mit der letzten User-Aktion gefunden wird. Ist dies der Fall, wird eine IVW-Zählung ausgeführt. Die Parameter notificationActionName und acknowledgmentResultName sind bei der Konfiguration optional. Treffer ohne diese Parameter werden weniger stark gewichtet. Abhängig vom Status einer Applikation kann es sein, das eine UserAktion zu unterschiedlichen Ergebnissen führt. Ebenso können zwei unterschiedliche User-Aktionen zu einem gleichen Ergebniss führen. Mit Hilfe der Konfigurationsparameter notificationActionName und acknowledgmentResultName können diese beiden Szenarios flexibel behandelt werden.
Die Karte liefert als "serviceName" entweder die HTML-ID des Karten DIVs oder den Namen der Karte. Als "actionName" werden Konstanten des jeweiligen Controls verwendet. Im Acknowledgment verwendet die Karte als "resultName" entweder "MAP_CHANGED", wenn sich die Karte geändert hat, oder "MAP_LAYER_CHANGED", wenn sich der angezeigte MapLayer geändert hat.
Der code-Parameter der gefundenen Konfiguration ersetzt den Block [code], den man beim Setzen der URL angegeben hat.
FalkIVWReporter.setIVWURL("http://test/cgi-bin/ivw/CP/[code]")
Mit dem Parameter useCodeParts lässt sich angeben, welche dynamischen Code-Anteile verwendet werden sollen.
Dynamische Code-Anteile:
Dynamische Code-Anteile lassen sich in der URL einfach innerhalb [] definieren.
FalkIVWReporter.setIVWURL("http://test/cgi-bin/ivw/CP/[code][dynamicCode]")
Zum Füllen der dynamischen Blöcke muss man sich auf das Event FalkIVWReporterClass.MSG_IVW_BEFORE_REPORT registrieren.
FalkIVWReporter.subscribe (FalkIVWReporterClass.MSG_IVW_BEFORE_REPORT, addLayerName);
Wird dann eine IVW-Zählung durchgeführt, wird zuvor die registrierte Methode aufgerufen. Durch Verändern der useCodeParts Variablen des mitgelieferten acknowledgment- Parameters lassen sich die dynamische Code-Teile setzen.
function addLayerName (acknowledgment) {
acknowledgment.useCodeParts['name'] = 'value';
}
ACHTUNG: Registriert man mehrere Methoden, um an unterschiedlichen Stellen die dynamischen-Blöcke zu erweitern, werden diese in der Reihenfolge der Registrierung abgearbeitet.
Nachrichten:
Der FalkIVWReporter feuert bei bestimmten Aktionen bestimmte Nachrichten, auf die man sich registrieren kann:
- FalkIVWReporterClass.MSG_IVW_NOTIFICATION
Die Nachricht wird erzeugt, wenn die "notifyUserAction"-Methode aufgerufen wird. Als Methoden-Parameter bekommt man die Referenz auf das FalkIVWNotificationData-Objekt mitgeliefert.
- FalkIVWReporterClass.MSG_IVW_ACKNOWLEDGMENT
Die Nachricht wird erzeugt, wenn die "acknowledgeUserAction"-Methode aufgerufen wird. Als Methoden-Parameter bekommt man die Referenz auf das FalkIVWAcknowledgmentData-Objekt mitgeliefert. Achtung die Bestätigung muss nicht zu einer IVW Zaählung führen.
- FalkIVWReporterClass.MSG_IVW_BEFORE_REPORT
Die Nachricht wird erzeugt, kurz bevor eine IVW-Zählung ausgelöst wird. Als Methoden-Parameter bekommt man die Referenz auf das FalkIVWAcknowledgmentData-Objekt mitgeliefert. Änderungen an diesem Objekt führen zu Änderungen der dynamischen Code-Anteile bei der IVW-Zählung.
- FalkIVWReporterClass.MSG_IVW_REPORT
Die Nachricht wird erzeugt, nachdem eine IVW-Zählung durchgeführt wurde. Als Methoden-Parameter bekommt man die komplette IVW-URL mitgeliefert.
Integration
Zur Integration der IVW-Zählung sind folgende Schritte nötig:
- Setzen einer URL:
FalkIVWReporter.setIVWURL("http://test/cgi-bin/ivw/CP/[code]")
Beim Setzen der URL kann man statische Teile mit dynamischen Teilen kombinieren. Dynamische Teile stehen in [] und werden vor der IVW-Zählung ersetzt. Bei den dynamischen Teilen gibt es standardmäßig den code-Block, der entweder durch den Service-Namen oder durch den IVW-Code einer Konfiguration ersetzt wird. Dynamische Blöcke, die nicht ersetzt werden können, werden entfernt.
- Aktivieren des Reports:
FalkIVWReporter.activate();
Damit eine IVW-Zählung durchgeführt wird muss diese aktiviert werden, da defaultmäßig keine IVW-Zählung stattfindet.
- Optional lässt sich für komplexere und variablere Zählungen noch eine Konfiguration angeben.
FalkIVWReporter.addConfiguration (new FalkIVWConfiguration ("servieNameBeispiel", "actionNameBeispiel",
"servieNameBeispiel", "resultNameBeispiel",null, "ivwCodeBeispiel"));
Um eine IVW-Zählung manuell auszuführen, werden folgende Schritte benötigt:
- Notification der User-Aktion:
FalkIVWReporter.notifyUserAction ( new FalkIVWNotificationData(<notificationServiceName>, <notificationActionName>));
- Bestätigung des Ergebnisses:
FalkIVWReporter.acknowledgeUserAction ( new FalkIVWAcknowledgmentData(<acknowledgmentServiceName>, <acknowledgmentResultName>));
IVW Use-Cases und Beispiele
Für die folgenden Use-Cases sind in den nachfolgenden Beispielen Lösungsvarianten verfügbar:
- einfache Zählung:
Es wird eine Karte in eine HTML-Seite eingebunden, die automatisch eine IVW-Zählung ausführen soll. Bei der IVW-Zählung soll nicht zwischen dem aktuellen Zustand der Karte oder der Applikation unterschieden werden. Es finden keine zusätzlichen programmierten Kartenaktionen statt.
- Integration eines eigenen Controls - programmiertechnische Kartenänderung
Die Karte wird programmiertechnisch um ein eigenes Control erweitert, oder die Karte wird durch Verwendung der Methoden der FalkMap verändert. Z.B. soll programmiertechnisch eine BoundingBox gesetzt werden.
- zusätzliche manuelle IVW-Zählung
Mit Hilfe der Komponente FalkIVWReporter sollen zusätzliche IVW-Zählungen durchgeführt werden. Z.B. sollen User-Aktionen gezählt werden, die auf einem anderen Teil der HTML-Seite basieren.
- Konfiguration von mehreren Services (Konfiguration)
Um die IVW-Zählung in einer komplexen Javascript-Anwendung integrieren zu können, besteht die Möglichkeit den IVWReporter zu konfigurieren. Dadurch lässt sich die IVW-Zählung in unterschiedliche "Services" einteilen und individuell festlegen bei welcher Notification- / Acknowledgment-Kombination was für ein IVW-Code gezählt werden soll.
- Dynamische Code-Teile
Um in einer komplexeren Javascript-Anwendung, abhängig vom aktuellen Zustand der Applikation unterschiedliche IVW-Zählungen durchführen zu können, gibt es zusätzlich zur Konfiguration das Konzept der "dynamischen Code-Anteile". Z.B. möchte man für die unterschiedlichen Kartenansichten (Karte, Luftbilder, Hybrid-Ansicht) unterschiedliche IVW-Zählungen durchführen.
Einfache Zählung
Es sind nur folgende Schritte nötig:
- Setzen einer URL:
FalkIVWReporter.setIVWURL("http://test/cgi-bin/ivw/CP/[code]")
- Aktivieren des Reports:
FalkIVWReporter.activate();
Dabei wird der [code]-Block der URL mit dem Service-Namen (ID der Karte) ersetzt. Der [code]-Block kann auch entfallen, wenn der Service-Name nicht benötigt wird.
Die Karte zählt auf User-Aktionen, die über ein Control der FalkMapApi getriggert werden, automatisch IVW.
Integration eines eigenen Controls
Karten-Aktionen die programmiertechnisch, z.B. über ein eigenes MapControl angestoßen werden, brauchen einen separaten Aufruf der notifyUserAction-Methode.
Als ServiceName verwendet man für diese Aufrufe die HTML-ID des DIVs, in das die Karte gerendert worden ist oder den Namen der Karte, der mit der Methode setName auf der FalkMap gesetzt wurde.
FalkIVWReporter.notifyUserAction ( new FalkIVWNotificationData("mymap", "centerToBoundingBox"));
var geocode1 = new FalkPoint(1025593, 6320893);
var geocode2 = new FalkPoint(1125593, 6220893);
var boundingBox = new FalkArea(geocode1, geocode2);
map.centerMapToBoundingBox(boundingBox);
Der "notificationActionName"-Parameter kann in diesem Beispiel auch leer bleiben.
zusätzliche (manuelle) IVW-Zählung
Um eine manuelle Zählung durchzuführen, muss man sowohl die Notification-Methode, als auch die Acknowledge-Methode manuell aufrufen.
FalkIVWReporter.notifyUserAction ( new FalkIVWNotificationData("serviceNameBeispiel", "userActionNameBeispiel"));
....
FalkIVWReporter.acknowledgeUserAction (new FalkIVWMapAcknowledgmentData("serviceNameBeispiel", "resultNameBeispiel");
Wie oben beschrieben, wird eine Zählung nur durchgeführt, wenn der serviceName ("serviceNameBeispiel") übereinstimmt. Ist eine Konfiguration angegeben, wird zusätzlich der "notificationActionName" und der "acknowledgmentResultName"-Parameter gegen die Konfiguration geprüft.
Konfiguration
Wem das einfache Handling nicht ausreicht, der kann das Verhalten des Reports konfigurieren.
FalkIVWReporter.addConfiguration (new FalkIVWConfiguration (
<serviceNameNotification>,<notificationActionName>, <serviceNameAcknowledgment>,
<resultNameAcknowledgment>, <useCodePartObject>, <ivwCode>));
Ist eine Konfiguration angegeben, wird bei jeder Bestätigung geprüft, ob ein gültiger Konfigurationseintrag gefunden wird. Ein Eintrag ist gültig, wenn serviceName der Notification, actionName der Notification, serviceName des Acknowledgments und resultName des Acknowledgments mit dem Konfigurationseintrag übereinstimmen. Der actionName und der resultName Parameter können auch leer sein; dann hat die Regel eine niedrigere Priorität.
Will man die üblichen Karten-Aktionen zählen, so muss auch dafür eine Konfiguration angegeben werden.
Um Karten-Aktionen abhängig von der User-Aktion zu zählen, können folgende Konstanten für die Konfiguration verwendet werden, wobei der "acknowledgmentResultName" entweder der Leerstring "" oder der hier aufgelistete String sein kann:
| notificationActionName | acknowledgmentResultName |
|---|---|
| FalkSmallMapControl.USER_ACTION_ZOOM_IN = "MAP_ZOOM_IN" | "MAP_CHANGED" |
| FalkSmallMapControl.USER_ACTION_ZOOM_OUT = "MAP_ZOOM_OUT"; | "MAP_CHANGED" |
| FalkSmallMapControl.USER_ACTION_MOVE_NORTH = "MAP_MOVE_NORTH"; | "MAP_CHANGED" |
| FalkSmallMapControl.USER_ACTION_MOVE_SOUTH = "MAP_MOVE_SOUTH"; | "MAP_CHANGED" |
| FalkSmallMapControl.USER_ACTION_MOVE_EAST = "MAP_MOVE_EAST"; | "MAP_CHANGED" |
| FalkSmallMapControl.USER_ACTION_MOVE_WEST = "MAP_MOVE_WEST"; | "MAP_CHANGED" |
| FalkBigMapControl.USER_ACTION_CHANGE_ZOOMLEVEL = "MAP_CHANGE_ZOOMLEVEL"; | "MAP_CHANGED" |
| FalkMapSwitchControl.USER_ACTION_CHANGE_MAP_LAYER = "MAP_CHANGE_MAP_LAYER"; | "MAP_LAYER_CHANGED" |
| Map.USER_ACTION_RECTANGLE_ZOOM = "MAP_RECTANGLE_ZOOM"; | "MAP_CHANGED" |
| Map.USER_ACTION_RECTANGLE_PAN = "MAP_RECTANGLE_PAN"; | "MAP_CHANGED" |
| Map.USER_ACTION_RECTANGLE_PAN = "MAP_RECTANGLE_PAN"; | "MAP_CHANGED" |
Da das FalkBigMapControl das FalkSmallMapControl erweitert (Vererbung), sind die Einträge des FalkSmallMapControl auch im FalkBigMapControl verfügbar.
Dynamische Code-Anteile
Braucht man für die IVW Zählung dynamische Code-Anteile, können diese in der URL [<codeteil>] z.B. [language] angegeben werden.
Kurz bevor der FalkIVWReporter eine IVW-Zählung durchführt, wird das Event MSG_IVW_BEFORE_REPORT geworfen. Registriert man sich auf dieses Event,
FalkIVWReporter.subscribe (FalkIVWReporterClass.MSG_IVW_BEFORE_REPORT, <function>);
hat man die Möglichkeit dynamische Code-Anteile hinzuzufügen.
function addLanguage (acknowledgment) { acknowledgment.useCodeParts['language'] = "de";}
Die entsprechenden Code-Anteile werden dann ersetzt. Alle Code-Blöcke, für die kein dynamischer Teil im acknowledgment.useCodeParts gefunden werden kann, werden entfernt.
Verwendung der dynamischen Code-Anteile in Verbindung mit Konfiguration
Wenn man die Konfiguration verwendet, kann man pro Regel angeben, welche Code-Blöcke verwendet werden sollen:
var useCodePartObject = {};
useCodePartObject['language'] = true;
FalkIVWReporter.addConfiguration (new FalkIVWConfiguration (<serviceNameNotification>,
<notificationActionName>, <serviceNameAcknowledgment>, <resultNameAcknowledgment>,
useCodePartObject, <ivwCode>));
Fehler-Diagnose
Die Falk-Map-API bietet über die Klasse FalkMessageManager die Möglichkeit zur Fehler-Diagnose. Werden beim Aufruf von Falk-Map-API Funktionen Fehler festgestellt werden diese im FalkMessageManager gepseichert. Die letzten 10 Meldungen können über den FalkMessageManager abgerufen werden.
FalkMessageManager.getAllMessages();
Mit Hilfe der methode getNumberOfMessages kann überprüft werden wieviele neue Meldungen im Stack bereit liegen. Dieser Wert wird beim Abholen der Meldungen auf 0 zurückgesetzt. Mit Hilfe der methode getTotalNumberOfMessages kann man abrufen wieviele Meldungen schon aufgelaufen sind.
XML HTTP Requests (XHR)
Die FalkMapApi bietet die Möglichkeit Requests über XHR abzusetzen.
Get-Request
Ein asynchroner Get-Request benötigt immer eine Callback-Methode.
Beispiel für asynchronen Get-Request
try {
var ajax = new AjaxElement();
ajax.SetCallback(function(result, cbAddress){/* handle geocoding result */});
ajax.SetCallbackParameter(address);
ajax.GetRequest( url );
}
catch(e) {
// Fehlerfall Code
}
Folgende Schritte sind nötig:
- Erzeugen eines AjaxElement Objektes
- Setzen einer Callback-Methode auf diesem Objekt (Optional für XHR, für XDomainXHR Pflicht)
- Setzen eines Callback-Parameters, dieser ist dann in der Callback-Methode als zweiter Paramter verfügbar, so dass eine eindeutige Zuordnung von Request zum Aufruf der Callback-Methode möglich ist (Optional).
- Aufruf des Get-Requests mit der erforderlichen Url.
Die Angabe einer Callback-Methode für asynchrone Requests ist notwendig. Benötigt man keine Verarbeitung des Ergebnisses, kann auch eine Dummy-Funktion angegeben werden:
ajax.SetCallback(function() {});
Die Callback-Methode muss den JSON-String auswerten, der als erster Paramter verfügbar ist, es kann zusätzlich auf den optional gesetzten Callback-Parameter zugegriffen werden. Beispiel:
FalkGeocoder.prototype._handleGeocodeAddressResult = function (jsonStr, address) {
var retObj = null;
if( is_string(jsonStr) ) {
try {
retObj = eval( '('+jsonStr+')' );
}
catch(e) {
// Fehlerbehandlung
}
}
else {
retObj = jsonStr;
}
// Verwendung des Callback-Parameters address
var result = new FalkGeocodeResult(address);
...
}
Beispiel für synchronen Get-Request (nur XHR)
try {
var url = ...;
var ajax = new AjaxElement();
ajax.GetRequest( url );
}
catch(e) {
// Fehlerfall Code
}
Folgende Schritte sind nötig:
- Erzeugen eines AjaxElement Objektes
- Aufruf des Get-Requests mit der erforderlichen Url.
Post-Request
Hinweis: Post-Requests können nur für XHR-Anfragen durchgeführt werden. Für XDomainXHR-Anfragen wird mit den Parametern des Post-Requests ein Get-Request durchfgeführt. Es ist hier daher insbesondere auf die Länge der Url zu achten, da diese für einige Browser (z.B. auf 255 Zeichen) beschränkt ist. Post-Requests können als XHR synchron oder asynchron ausgeführt werden. Für asynchrone Post-Requests muss eine Callback-Methode gesetzt werden.
Beispiel für asynchronen Post-Request (nur XHR)
var ajax = new AjaxElement();
ajax.SetCallback( function(result, cbAddress){/* handle result */} );
ajax.SetCallbackParameter(address);
ajax.ResetRequestParam();
// Setzen der Request-Parameter
ajax.AddRequestParam('geoX', address.geoX);
ajax.AddRequestParam('geoY', address.geoY);
...
var url = ...;
ajax.PostRequest( url );
Folgende Schritte sind nötig:
- Erzeugen eines AjaxElement Objektes
- Zurücksetzen der RequestParameter
- Setzen einer Callback-Methode auf diesem Objekt
- Setzen eines Callback-Parameters
- Setzen der Request-Parameter über die Methode AddRequestParamter
- Aufruf von PostRequest mit der erforderlichen Url.
Die Auswertung des JSON-Strings erfolg analog zur Handhabung beim Get-Request.
Beispiel für synchronen Post-Request (nur XHR)
var ajax = new AjaxElement();
ajax.ResetRequestParam();
// Setzen der Request-Parameter
ajax.AddRequestParam('geoX', address.geoX);
ajax.AddRequestParam('geoY', address.geoY);
...
var url = ...;
ajax.PostRequest( url );
Folgende Schritte sind nötig:
- Erzeugen eines AjaxElement Objektes
- Zurücksetzen der RequestParameter
- Setzen der Request-Parameter über die Methode AddRequestParamter
- Aufruf von PostRequest mit der erforderlichen Url.