Drop-in-Tools

🧩 Place-Widget (JavaScript)

Verwandelt jedes <input>-Feld mit dem Attribut data-geoapi-place in ein Autosuggest-Feld mit Tastatur-Navigation, Hidden-Field-Pflege und Auto-Fill.

Schnellstart

<form method="post" action="speichern.php">
  <input type="text" name="ort" data-geoapi-place placeholder="Ort eingeben">
  <button type="submit">Speichern</button>
</form>

<script src="https://geoapi.world/dist/geoapi-widget.js"></script>

Im Server-PHP stehen anschließend zur Verfügung:

• $_POST["ort"] — der angezeigte Text
• $_POST["ort_geonameid"] — die GeoNames-ID
• $_POST["ort_timezone"] — die IANA-Zeitzone

data-Attribute

Format-Templates: verfügbare Keys

Jeder Key kann sowohl in data-geoapi-format-list/-input als auch in data-geoapi-fill verwendet werden. Verschachtelte Blöcke (admin, country) werden mit Punkt-Notation adressiert.

Beispiel: Bundesland in der Vorschlagsliste

Default-Rendering enthält das Bundesland bereits (aus admin1.name bzw. admin1_code). Eigene Variante mit Untertitel:

<input data-geoapi-place
       data-geoapi-lang="de"
       data-geoapi-format-list="<strong>{name}</strong>, {admin1.name} ({country_code})<small>{population} Einw. · {timezone}</small>">

Auto-Fill in beliebige Elemente

Mit data-geoapi-fill="key" auf einem beliebigen Element wird dieses nach jeder Auswahl automatisch gefüllt:

<input type="text" name="ort" data-geoapi-place>

<p>Land:        <span data-geoapi-fill="country_code"></span></p>
<p>Zeitzone:    <span data-geoapi-fill="timezone"></span></p>
<p>Einwohner:   <span data-geoapi-fill="population"></span></p>
<p>Koordinaten: <span data-geoapi-fill="lat"></span>, <span data-geoapi-fill="lon"></span></p>

Timeshift — Zeitzonen-Verschiebung pro Datum

Spezielle Fill-Keys, die nicht direkt aus dem Suche-Treffer kommen, sondern den Offset für ein konkretes Datum + Zeit über /api/offset.php nachladen — DST-aware, mit historischen Regeln.

Trigger-Bedingungen:

• Es muss ein Ort ausgewählt sein (das Hidden-Field {name}_timezone ist gefüllt) und
• Datum/Zeit-Felder enthalten gültige Werte.

Datums-/Zeit-Änderungen ohne Ortsauswahl lösen keine API-Anfrage aus. Nach dem ersten Auswählen werden die Datum/Zeit-Felder mit Listenern versehen (debounced 250 ms, vorheriger In-Flight-Request wird gegen Race Conditions abgebrochen).

<input type="text" name="ort" data-geoapi-place>
<input type="date" name="geburtstag">
<input type="time" name="geburtszeit">

<input type="text" data-geoapi-fill="timeshift"
       data-geoapi-timeshift-date="geburtstag"
       data-geoapi-timeshift-time="geburtszeit"
       name="zeitverschiebung">

Verfügbare Fill-Keys:

Datum-Bindung — Attribute auf dem Fill-Element:

Slash-Datumsformate (11/01/1988) werden bewusst nicht unterstützt — sie sind zwischen DD/MM/YYYY und MM/DD/YYYY mehrdeutig.

URL-Pre-Fill / Auto-Resolve

Typischer Fall: das Formular wird mit URL-Parametern befüllt (z. B. ?ort=Berlin) und du brauchst trotzdem die Hidden-Felder (geonameid, lat, lon, timezone, …) ohne Klick des Nutzers.

<input type="text" name="ort" data-geoapi-place
       data-geoapi-autoresolve
       value="<?= htmlspecialchars($_GET['ort'] ?? '') ?>">

Beim Laden prüft das Widget: ist der Input gefüllt, das Hidden-_geonameid aber leer? Falls ja, läuft eine Suche. Verhalten je nach Wert des Attributs:

• ohne Wert oder ="strict" — wenn die Suche genau einen Treffer hat, wird er still ausgewählt (Hidden-Felder + Timeshift werden ohne Sichtkontakt befüllt). Bei mehreren Treffern öffnet sich die Vorschlagsliste — der Nutzer entscheidet.
• ="top" — der erste Treffer wird immer ausgewählt, ohne Liste. Riskant bei gängigen Namen wie „Springfield".

Beide Modi feuern geoapi:auto-resolved (siehe Events) — du kannst die Auto-Auswahl mitlesen oder weiter verarbeiten.

JavaScript-Events

Fünf Events bubbeln bis document:

document.querySelector("[data-geoapi-place]")
  .addEventListener("geoapi:select", (e) => {
    const ort = e.detail;
    console.log("Gewählt:", ort.name);
    // map.setView([ort.lat, ort.lon], 13);
  });

→ Alle Widget-Anpassungen live ausprobieren