NXDOM

Nxdom Framework

Nusantara eXtreme Development Object Model — dokumentasi resmi

NexaGeolocation — GPS & lokasi perangkat

NexaGeolocation membungkus Geolocation API browser: posisi sekali jalan, pemantauan berkelanjutan, objek data yang rapi, penanganan error yang ramah pengguna, dan helper jarak (Haversine). Tersedia lewat bundel Nexa sebagai NexaGeolocation atau NX.Geolocation / Geolocation.

Fitur utama

  • getCurrentPosition() mengembalikan Promise dengan data terformat
  • watchPosition() / stopWatching() untuk pelacakan real-time
  • Callback berantai: onPositionSuccess, onPositionError, onPositionUpdate
  • Opsi default: akurasi tinggi, timeout 10s, cache posisi (maximumAge)
  • Properti bantuan: coordinates, googleMapsUrl, distanceTo(lat, lng)
  • Error terstruktur: type, userMessage, suggestion

Prasyarat browser

  • navigator.geolocation harus ada (cek isSupported setelah instansiasi)
  • Konteks aman (HTTPS) — banyak browser menolak geolocation di HTTP biasa
  • Izin lokasi dari pengguna; tanpa izin Anda mendapat PERMISSION_DENIED

Instalasi & akses

Gunakan modul yang sudah diimpor NXDOM, atau impor langsung dari berkas modul.

// Setelah Nexa / NX termuat: const geo = new NX.Geolocation(); // atau import { NexaGeolocation } from "/assets/modules/Geolocation/NexaGeolocation.js"; const geo2 = new NexaGeolocation({ timeout: 15000 });

getCurrentPosition

Mengambil satu pembacaan lokasi. Opsi per-panggilan dapat digabung dengan opsi instance.

const geo = new NexaGeolocation(); geo.getCurrentPosition({ maximumAge: 0 }) .then((data) => console.log(data.latitude, data.longitude, data.googleMapsUrl)) .catch((err) => console.warn(err.userMessage, err.suggestion));

watchPosition / stopWatching

watchPosition memanggil callback (dan onSuccess / onUpdate) setiap ada pembaruan. Panggil stopWatching() saat selesai untuk memanggil clearWatch internal.

const tracker = new NexaGeolocation(); tracker.onPositionUpdate((data) => console.log("update:", data.coordinates)); tracker.watchPosition(); // … tracker.stopWatching();

Callback berantai

Metode onPositionSuccess, onPositionError, dan onPositionUpdate mengembalikan this sehingga bisa dirantai.

new NexaGeolocation() .onPositionSuccess((d) => console.log(d.coordinates)) .onPositionError((e) => console.error(e.userMessage)) .getCurrentPosition();

Objek posisi

Nilai yang dikembalikan formatPosition (inti yang dipakai aplikasi):

Field Keterangan
latitude, longitude, accuracy Koordinat WGS-84 dan akurasi (meter)
altitude, altitudeAccuracy, heading, speed Bisa null jika perangkat tidak menyediakan
timestamp, datetime Waktu pembacaan (epoch dan Date)
coordinates, googleMapsUrl String siap tampil / dibuka di peta
distanceTo(lat, lng) Fungsi jarak ke titik lain (meter)
raw Objek GeolocationPosition asli browser

Tipe error

Tipe / sumber Arti singkat
PERMISSION_DENIED Pengguna menolak atau browser memblokir izin lokasi
POSITION_UNAVAILABLE Lokasi tidak bisa ditentukan (GPS mati, sinyal buruk, dll.)
TIMEOUT Tidak ada respons dalam batas timeout
NOT_SUPPORTED API tidak ada — dari reject internal
UNKNOWN_ERROR Kode error tidak dikenali

Ringkasan metode

Method Keterangan
checkSupport() Boolean dukungan navigator.geolocation
getCurrentPosition(opts?) Promise → data posisi terformat
watchPosition(opts?) Mulai pantau; kembalikan watch id
stopWatching() Hentikan watchPosition
getStatus() isSupported, isWatching, lastPosition, options
setOptions / resetOptions Ubah opsi Geolocation API
onPositionSuccess/Error/Update(cb) Set callback; chainable

Demo SPA

Contoh modul siap coba ada di assets/modules/Geolocation/index.html (snippet memakai NX.Geolocation, watchPosition, dan interval status). Salin pola tersebut ke route NXDOM Anda setelah Nexa dimuat.

Tips

  • Gunakan enableHighAccuracy: true bila perlu GPS; bisa lebih lambat dan boros baterai
  • Atur timeout realistis (mis. 5–15 detik) dan tangani TIMEOUT dengan retry terkontrol
  • maximumAge > 0 mengurangi beban jika posisi cache masih boleh dipakai
  • Selalu hentikan watch saat keluar halaman / unmount komponen

Referensi MDN