Autocomplete
Autocomplete liefert eine Liste von Orten zur Auswahl, basierend auf der Eingabe einer Adresse oder eines Adressteils. Diese Liste wird dynamisch an die Eingabe angepasst.
Kontextsensitives Autocomplete
Durch die Verwendung des kontextsensitiven Autocomplete erhöhen Sie die Relevanz der gefundenen Suchtreffer im jeweiligen Kartenausschnitt. Die Funktion gewichtet die lokalen Treffer im Kartenausschnitt so, dass sie zuerst in der Trefferliste erscheinen. Dadurch erhalten Ihre Nutzer das gewünschte Ergebnis noch schneller. Treffer außerhalb des Kartenausschnitts werden natürlich weiterhin gefunden.
Um diese Funktion zu nutzen, müssen Sie lediglich ein eigenes Koordinatenrechteck definieren. Alternativ können Sie auch Ihre SmartMaps-Karte als Suchbereich verwenden.
Anleitung
Um die Autocomplete-Funktion nutzen zu können, muss das Modul geladen werden. Dies geschieht, indem autocomplete-5 dem Parameter libraries in der eingebundenen JS-Datei des HTML-Dokuments hinzugefügt wird.
<script
src="https://www.yellowmap.de/api_rst/api/loader?libraries=free-3,autocomplete-5&apiKey={[INSERT API-KEY]}"></script>
<script>
Für die Implementierung einer Autocomplete-Suche, die gefundene Ergebnisse gemäß den Wünschen des Nutzers auf der SmartMaps-Karte geocodiert, wird zunächst ein div-Element mit der ID map-wrapper zum body-Tag des HTML-Skripts hinzugefügt.
Der map-wrapper enthält ein Formular mit einem Input-Element vom Typ search. Dieses Input-Element stellt die Autocomplete-Suche über eine Suchleiste in der Benutzeroberfläche bereit und hat die ID Autocomplete.
<form class="float">
<input id="Autocomplete" class="ym-search" type="search" placeholder="Suche">
</form>
Um die SmartMaps-Karte anzuzeigen, enthält der map-wrapper ein leeres div-Element mit der ID map. In diesem div-Element wird die Karte zur Laufzeit geladen. Für das div-Element können Sie mit dem Attribut style eine feste Höhe und Breite für die Karte festlegen.
Um die Funktionalität der Autocomplete-Suche und das entsprechende Geocoding der Ergebnisse zu implementieren, ist die Einbindung von JavaScript-Code erforderlich. Wie in diesem Beispiel kann dieser Code im HTML-Skript oder in einer separaten .js-Datei über ein Script-Tag eingebunden werden. Alle Variablen und Funktionen werden in der Methode ym.ready implementiert, da diese Methode Abhängigkeiten auflöst, um die eigentliche Kartenanwendung zu starten. Übergeben Sie in den Optionen { autocomplete: 5 }, um die neue Version 5 von Autocomplete zu verwenden.
Um die SmartMaps-Karte zum Geocoding der Autocomplete-Ergebnisse anzuzeigen, wird ein Objekt der Klasse ym.map erstellt. Als Parameter werden die ID des div-Elements, in dem die Karte gezeichnet werden soll, sowie die gewünschten Kartenoptionen (Startposition, Start-Zoomstufe usw.) übergeben. Um die Karte im Code weiter zu verwalten, wird das Objekt in einer Variable map gespeichert.
Zum Geocoding der Ergebnisse der Autocomplete-Suche werden die Methoden der Klasse ym.services.GeoCoder() benötigt. Um diese Methoden zu nutzen, wird ein Objekt der Klasse in der Variable geocoder gespeichert.
Um das Geocoding zu verfolgen, wird für die Klasse geoCoder, die das Geocoding auf der SmartMaps-Karte ermöglicht, ein EventEmitter verwendet. Dies ermöglicht über die on-Methode das Hinzufügen eines Listeners. Der Listener führt Funktionen bei bestimmten Ereignissen aus und kann verwendet werden, um zwischen erfolgreichem und nicht erfolgreichem Geocoding zu unterscheiden. In diesem Fall ist die Klasse geoCoder bereits mit einem EventEmitter ausgestattet und kann direkt auf die on-Methode zugreifen.
Im Falle eines erfolgreichen Geocodings ('success') zeigt die SmartMaps-Karte den Bereich der geocodierten Adresse an.
geocoder.on('success', function(req, res) {
if (res.body && res.body.features && res.body.features.length) {
map.fitBounds(ym.geoJson(res.body.features).getBounds());
}
});
Die Funktionalität der Autocomplete-Suche wird durch ein Objekt der Klasse ym.modules.AutoComplete realisiert. Dieses Objekt wird in der Variable autoComplete gespeichert. Zur Initialisierung des Objekts werden zwei Parameter benötigt: ein Selector, für den ein jQuery-Objekt oder ein CSS3-Selector übergeben werden kann, der auf das Eingabefeld für das Autocomplete verweist (hier: Input-Element mit der ID Autocomplete), sowie settings, in denen verschiedene Bedingungen und Einstellungen für die Autocomplete-Suche vorgenommen werden können.
Im folgenden Beispiel legt der Parameter Settings fest, dass die Autocomplete-Suche auf Adressen in Deutschland beschränkt ist und JSONP als Rückgabetyp liefert. Außerdem wird eine Funktion definiert, die das entsprechende Geocoding startet, sobald der Nutzer einen Eintrag aus der Liste auswählt.
var autoComplete = modules.autoComplete("#Autocomplete", {
locales: ['DE'],
// Function is called as soon as an entry is selected from the list.
onSelected: function(geoJson) {
geocoder.geocode(geoJson.properties);
}
});
Die Autocomplete-Suche ist nun erfolgreich integriert.
Wenn Sie die alte Autocomplete-Version 3 verwenden, klicken Sie hier. Wenn Sie zur neuen Autocomplete-Version 5 wechseln möchten, finden Sie hier die Migrationsanleitung.
HTML-Dokument
Codebeispiel: Autocomplete
<!DOCTYPE html>
<html>
<head lang="en">
<meta charset="UTF-8">
<title>Autocomplete</title>
</head>
<body>
<div id="map-wrapper">
<form class="float">
<input id="Autocomplete" class="ym-search" type="search" placeholder="Suche">
</form>
<div id="map" style="z-index:0; width:100%; height: 600px"></div>
</div>
<!-- SmartMaps-API -->
<script
src="https://www.yellowmap.de/api_rst/api/loader?libraries=free-3,autocomplete-5&apiKey={[INSERT API-KEY]}"></script>
<script>
ym.ready({ autocomplete: 5 }, function (modules) {
// Define Map
var map = ym.map("map", {
center: ym.latLng(49.021273, 8.439316),
zoom: 14
});
var geocoder = new ym.services.GeoCoder();
geocoder.on('success', function (req, res) {
if (res.body && res.body.features && res.body.features.length) {
map.fitBounds(ym.geoJson(res.body.features).getBounds());
}
});
var autoComplete = modules.autoComplete("#Autocomplete", {
isoCountries: ['de'],
// Called when a item is selected
onSelected: function (geoJson) {
geocoder.geocode(geoJson.properties);
}
});
});
</script>
</body>
</html>