Autocomplete

Die Autovervollständigung (Autocomplete) stellt auf Basis der Eingabe einer Adresse oder eines Adressbestandteils eine Liste von Ortsangaben zur Auswahl bereit. Diese Liste wird in Abhängigkeit von der Eingabe dynamisch verändert.

Kontextsensitives Autocomplete

Durch die Verwendung des kontextsensitiven Autocompletes erhöhen Sie die Relevanz der gefundenen Suchtreffer im jeweiligen Kartenausschnitt. Die Funktion gewichtet die im Kartenausschnitt befindlichen Ortstreffer, sodass diese zuerst in der Trefferliste erscheinen. Hierdurch erhalten Ihre Benutzer noch schneller das gewünschte Ergebnis. Natürlich werden auch weiterhin Treffer außerhalb des Kartenausschnitts gefunden.

Für die Verwendung müssen Sie einfach ein eigenes Koordinatenrechteck definieren. Alternativ können Sie auch Ihre SmartMaps-Karte als Suchausschnitt verwenden.

Anleitung

Um die Autovervollständigung verwenden zu können, muss das Modul geladen werden, dies geschieht, indem man bei der eingebunden JS-Datei beim Parameter libraries zusätzlich autocomplete-5 ergänzt.

    <script
        src="https://www.yellowmap.de/api_rst/api/loader?libraries=free-3,autocomplete-5&apiKey={{API_KEY}}"></script>
    <script>

Für die Implementierung einer Autocomplete-Suche, welche gefundene Ergebnisse nach Wunsch des Nutzers auf die SmartMaps-Karte geokodiert, wird vorerst im body-Tag des HTML-Skriptes ein div-Element mit der ID map-wrapper hinzugefügt.

  <div id="map-wrapper">
     ...
  </div>

Der map-wrapper beinhaltet in sich ein Formular, in dem sich ein input-Element des Typs search befindet. Dieses input-Element stellt die Autocomplete-Suche anhand einer Suchleiste in der Benutzeroberfläche bereit und besitzt die ID Autocomplete.

    <form class="float">
      <input id="Autocomplete" class="ym-search" type="search" placeholder="Suche">
    </form>

Für die Anzeige der SmartMaps-Karte, beinhaltet der map-wrapper ein leeres div-Element mit der ID map.  In diesem wird zur Laufzeit die Karte geladen. Für das div-Element kann man durch das style-Attribut eine feste Höhe und Breite für die Karte festlegen.

    <div id="map" style="height: 400px; width: 500px;"></div>

Für die Umsetzung der Funktionalität der Autocomplete-Suche und die dazugehörige Geokodierung der Ergebnisse, ist die Einbindung von JavaScript-Code notwendig. Dieser kann, wie in diesem Beispiel, anhand eines script-Tags im HTML-Skript oder in einer separaten .js-Datei eingebunden werden. Alle Variablen und Funktionen werden in der ym.ready-Methode implementiert, da diese Abhängigkeiten auflöst, um die eigentliche Kartenanwendung zu starten. In den Options übergibt man { autocomplete: 5 } damit die neue Version 5 des Autocomplete verwendet wird.

    ym.ready({ autocomplete: 5 }, function(modules) {
...
});

Für das Anzeigen der SmartMaps-Karte zur Geokodierung der Autocomplete-Ergebnisse wird ein Objekt der Klasse ym.map angelegt. Als Parameter wird dabei die ID des div-Elementes übergeben, in dem die Karte eingezeichnet werden soll, und die gewünschten Karten-Optionen (Startposition, Startzoom-Level, usw.). Um die Karte weiterhin im Code zu verwalten, wird das Objekt in einer Variable map gelagert.

      var map = ym.map("map", {
        center: ym.latLng(49.021273, 8.439316),
        zoom: 14
      });

Für die Geokodierung der Ergebnisse der Autocomplete-Suche werden die Methoden der Klasse ym.services.GeoCoder() benötigt. Um diese zu nutzen wird ein Objekt der Klasse in die Variable geocoder gelagert.

      var geocoder = new ym.services.GeoCoder();

Um die Geokodierung zu verfolgen, nutzt man für die geoCoder-Klasse, welche die Geokodierung auf der SmartMaps-Karte ermöglicht, einen EventEmitter. Dieser ermöglicht durch seine on-Methode, dass ein Listener hinzugefügt wird. Der Listener führt Funktionen bei bestimmten Events durch und kann somit genutzt werden um zwischen einer erfolgreichen und nicht erfolgreichen Geokodierung zu unterscheiden. In dem Falle ist die GeoCoder-Klasse mit einen EventEmitter schon ausgestattet und kann direkt auf die on-Methode zugreifen.
Im Falle einer erfolgreichen Geokodierung ('success') wird auf der SmartMaps-Karte der Bereich der geokodierten Adresse angezeigt.

      geocoder.on('success', function(req, res) {
        if (res.body && res.body.features && res.body.features.length) {
          map.fitBounds(ym.geoJson(res.body.features[0]).getBounds());
        }
      });

Die Funktionalität der Autocomplete-Suche wird durch ein Objekt der Klasse ym.modules.AutoComplete realisiert. Dieses wird in die Variable autoComplete gelagert. Für die Initialisierung des Objektes werden zwei Parameter benötigt: Ein Selector, für den ein jQuery-Objekt oder ein CSS3-Selektor übergeben werden kann, der auf das Eingabefeld für das Autocomplete verweist (Hier: input-Element mit der ID Autocomplete), und Settings, in denen verschiedene Bedingungen und Einstellungen für die Autocomplete-Suche vorgenommen werden können.
Im folgenden Beispiel wird im Settings-Parameter definiert, dass die Autocomplete-Suche sich auf die Adressen in Deutschland beschränkt und diese im Rückgabetyp JSONP zurückgibt. Des Weiteren wird eine Funktion definiert, welche sobald ein Eintrag aus der Liste vom Nutzer gewählt wird, die dementsprechende Geokodierung startet.

      var autoComplete = modules.autoComplete("#Autocomplete", {
        dataType: "jsonp",
        isoCountries: ['de'],
        // Funktion wird aufgerufen, sobald ein Eintrag aus der Liste ausgewählt wurde.
        onSelected: function(geoJson) {
          geocoder.geocode(geoJson.properties);
        }
      });

Die Autocomplete-Suche ist nun erfolgreich eingebunden.

Falls Sie die alte Autocomplete Version 3 benutzen, klicken Sie hier. Wenn Sie auf die aktuelle Version wechseln wollen, finden Sie hier eine Migrationsanleitung.

HTML-Dokument

Codebeispiel: Karte einzeichnen

<!DOCTYPE html>
<html>

<head lang="en">
    <meta charset="UTF-8">
    <title>Autovervollständigung</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={{API_KEY}}"></script>
    <script>
        ym.ready({ autocomplete: 5 }, function (modules) {

            // Karte definieren.
            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[0]).getBounds());
                }
            });

            var autoComplete = modules.autoComplete("#Autocomplete", {
                isoCountries: ['de'],
                // Funktion wird aufgerufen, sobald ein Eintrag aus der Liste ausgewählt wurde.
                onSelected: function (geoJson) {
                    geocoder.geocode(geoJson.properties);
                }
            });
        });
    </script>
</body>

</html>