Maps elementi, uygulama içerisinde coğrafi verilerin harita üzerinde görsel olarak sunulmasını sağlayan bir UI elementidi. Kullanıcılar harita üzerinde konumları görüntüleyebilir, yakınlaştırma–uzaklaştırma işlemleri yapabilir ve belirli bölgeleri detaylı şekilde inceleyebilir.
Maps elementi, birbirine çok yakın olan pinleri otomatik olarak gruplandırarak (cluster) daha düzenli bir harita görünümü sunar. Bu özellik, yoğun konum bulunan bölgelerde haritanın okunabilirliğini artırır ve kullanıcı deneyimini iyileştirir.
1.1. Sık Kullanım Senaryoları
Mağaza, ofis veya şube konumlarını göstermek
Konum tabanlı servis ve bilgilendirme ekranları
Harita üzerinden nokta inceleme ve gezinme
Yoğun konum verilerinin görsel olarak sunulması
2. Temel Özellikler
Harita tabanlı görsel sunum: Konumlar, harita üzerinde pinler aracılığıyla görsel olarak gösterilir.
Yakınlaştırma ve uzaklaştırma (Zoom) desteği: Kullanıcılar harita üzerinde detaylı inceleme yapabilir veya genel görünümü görüntüleyebilir.
Pin (Marker) gösterimi: Tekli veya çoklu konumlar harita üzerinde işaretlenebilir.
Otomatik pin gruplama (Clustering): Birbirine yakın konumlar otomatik olarak gruplanarak daha sade ve okunabilir bir harita görünümü sunulur.
Dinamik veri ile çalışma: Konum verileri statik olarak tanımlanabilir veya datasource / aksiyon çıktıları üzerinden dinamik olarak bağlanabilir.
Etkileşimli harita deneyimi: Kullanıcılar harita üzerinde gezinerek farklı bölgeleri inceleyebilir.
2.1. Maps Elementi Özellikleri
Datasource: Haritada gösterilecek konumların veri kaynağını belirler. REST API ve SQL Actions gibi kaynaklar desteklenir.
Latitude: Haritanın ilk açılışta odaklanacağı enlem değeridir. Statik veya dinamik olarak atanabilir.
Longitude: Haritanın ilk açılışta odaklanacağı boylam değeridir.
Circle Radius In Km: Harita üzerinde belirli bir alanı dairesel bir sınır içinde vurgular.
Auto Center: Haritanın açılışta nasıl konumlanacağını belirler.
True: Harita, veri kaynağında bulunan tüm konumları kapsayacak şekilde otomatik olarak merkezlenir ve uygun zoom seviyesini harita kendisi belirler. Tüm marker’ları içine alacak biçimde konumlanır.
False: Harita herhangi bir otomatik merkezleme yapmaz. Açılış konumu Latitude ve Longitude alanlarında belirtilen değerlere göre ayarlanır. Bu alanlar boşsa harita varsayılan başlangıç konumunda açılır.
Auto Center = True olduğunda Latitude ve Longitude değerleri kullanılmaz.
Group Picker Icon: Yakın konumların zoom-out sırasında tek bir simge altında gruplandırılmasını sağlar.
Current Location Icon: Kullanıcının mevcut konumunu gösterir.
Keep Center On Zoom: Zoom işlemi sırasında harita merkezi sabit kalır.
Map Type: Haritanın görünüm tarzını belirler. Desteklenen harita türleri şunlardır:
Roadmap: Standart yol haritasıdır. Karayolları, sokaklar ve şehir detayları net bir şekilde gösterilir.
Terrain: Yükselti farklarını ve doğal arazi özelliklerini gösteren bir harita türüdür. Dağlar, tepeler ve vadiler belirgin hale gelir.
Satellite: Uydu görüntülerini kullanarak haritayı gerçek dünya görselleriyle gösterir. Binalar, doğa alanları ve su kaynakları net bir şekilde görülür.
Hybrid: Uydu görüntüleri ile yol ve yerleşim bilgilerini birleştiren bir harita modudur. Uydu görüntülerinin üzerine yol ve şehir isimleri eklenerek daha kapsamlı bir görünüm sunar.
HideTrafficLayer: Harita üzerindeki trafik yoğunluğu katmanının (yolların doluluk durumu) gösterilip gösterilmeyeceğini kontrol eder. Varsayılan değeri false’tur.
HideTransitLayer: Harita üzerindeki toplu taşıma rotalarının (tren, metro, tramvay vb.) gösterilip gösterilmeyeceğini kontrol eder. Varsayılan değeri false’tur.
Waypoints: Girilen lokasyonlara, kullanıcının mevcut konumundan otomatik rota çizilmesini sağlar.
FullScreenControl: Haritanın tam ekran moduna alınıp alınamayacağını kontrol eder.
StreetViewControl (Web): Sokak görünümüne geçiş yapılabilmesini sağlar.
ScaleControl (Web): Harita üzerinde mesafe ölçeğinin gösterilip gösterilmeyeceğini belirler.
Zoom: Haritanın ilk yüklendiğinde hangi yakınlık seviyesinde açılacağını belirler.
Harita, ekran ilk açıldığında bu değer üzerinden render edilir.
Kullanıcı sonradan zoom yapabilir; bu ayar yalnızca başlangıç görünümünü etkiler.
Geçerli değer aralığı:
0: En uzak görünüm
22: En yakın görünüm
Çok düşük veya çok yüksek bir zoom değeri seçilmesi, kullanıcının haritayı ilk açılışta anlamasını zorlaştırabilir.
ZoomControl (Web): Harita yakınlaştırma ve uzaklaştırma butonlarının gösterilip gösterilmeyeceğini belirler.
CameraControl (Web): Harita perspektifini ve kamera açısını kontrol etmeyi sağlar.
EnableLocationTracking: Kullanıcının anlık konumunun harita üzerinde gerçek zamanlı izlenmesini sağlar.
Latitude ve Longitude değerleri “Decimal” formatında olmalıdır.
Maps elementi, latitude ve longitude değerleri Null (boş) olduğunda bile harita ekranını açar ve diğer konumları görüntüler.
Konum Alma
Google Maps üzerinden bir konumun enlem ve boylam değerlerini almak için haritada sağ tıklayıp çıkan menüden koordinatları kopyalayabilirsiniz. Bu değerleri Maps elementinin Latitude ve Longitude alanlarına ekleyin.
Events
On Location Click: Kullanıcı haritada bir konuma tıkladığında tetiklenir.
On Map Load: Harita yüklendiğinde çalışır.
On Zoom Change: Kullanıcı yakınlaştırma veya uzaklaştırma yaptığında etkinleşir.
Maps elementi, farklı veri kaynaklarından gelen bilgileri harita üzerinde dinamik olarak gösterir. Böylece uygulamanız, konum tabanlı hizmetleri daha kullanıcı dostu ve etkileşimli bir şekilde sunabilir.
2.2. Elemente Eklenebilen Aksiyonlar
Maps elementi, harita üzerindeki konum veya görünüm değişikliklerine bağlı olarak aksiyon tetiklenmesini destekler. Aksiyonlar, elementin kendisine değil; harita etkileşimi sonucu tetiklenen event’e bağlanır.
Maps elementi için aksiyonlar, Properties > Add Action alanı üzerinden aşağıdaki event aracılığıyla tanımlanabilir.
onChange: Harita üzerinde seçilen konum, pin veya görünüm durumu değiştiğinde tetiklenir.
Kullanım amaçları:
Seçilen konum bilgisini state veya değişkene kaydetmek
Harita etkileşimine bağlı liste veya detay alanlarını güncellemek
Konum değiştiğinde filtreleme veya veri yenileme işlemi yapmak
Örnek senaryo: Kullanıcı harita üzerinde farklı bir konuma geçtiğinde, o bölgeye ait mağazalar otomatik olarak listelenir.
3. Maps Elementi Nasıl Kullanılır?
Bu bölümde Maps elementinin uçtan uca kullanımını örnek senaryo üzerinden ele alacağız.
Senaryo: Şube ve Konum Noktalarının Harita Üzerinde Gösterimi
Bu örnekte Maps elementi kullanılarak belirli konum noktalarının harita üzerinde görüntülenebildiği basit bir harita ekranı oluşturulmuştur. Kullanıcı, harita üzerinde tanımlanan noktaları marker olarak görebilir ve ilgili konumları harita üzerinden inceleyebilir.
Senaryoda:
Konum noktalarının harita üzerindeki gösterimi, Latitude ve Longitude alanları ile sağlanır.
LocationName alanı marker başlığı olarak, Tooltip alanı ise konuma ait kısa açıklama bilgisi olarak kullanılır.
Marker seçildiğinde ilgili konuma ait bilgi görüntülenir.
Adım 1 - Gerekli Aksiyonun Tanımlanması
Arayüzde verileri göstermek için:
Örnek bir aksiyon tanımlamanız gerekir.
Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.
Lokasyonları Getiren Aksiyon (MapDataSource):
SELECT
1 AS Sequence,
N'Karşıyaka' AS LocationName,
38.457500 AS Latitude,
27.116700 AS Longitude,
N'Başlangıç noktası' AS Tooltip
UNION ALL
SELECT
2,
N'Alsancak',
38.432000,
27.140000,
N'Şehir merkezi'UNION ALL
SELECT
3,
N'Konak',
38.419200,
27.128700,
N'Merkez meydan'UNION ALL
SELECT
4,
N'Balçova',
38.390000,
27.050000,
N'Yerleşim bölgesi'UNION ALL
SELECT
5,
N'Narlıdere',
38.390800,
26.980000,
N'Bitiş noktası'
Konum verileri senaryo için tablo kullanılmadan, SELECT sorgusu ile Latitude, Longitude, LocationName ve Tooltip alanları dönecek şekilde hazırlanmıştır.
Adım 2 - Initial Action Ekleme
Başlangıçta anasayfada:
Maps üzerinde lokasyonların gösterimi için Add Action > Initial Action > Custom > Managed DB > MapDataSource aksiyonunu ekleyin.
Ekran açılışında kullanıcının mevcut konum bilgileri üzerinden harita alanının başlatılması için Add Action > Initial Action > Geolocation > Location Get Current Coordianates aksiyonunu ekleyin.
Adım 3 - Maps Elementini Ekleme ve Aksiyon Tanımlama
Başlangıçta anasayfada:
Sol yan panelden Elements > Special > Maps elementini sayfaya sürükleyip bırakın.
Başlangıç koordinatı için Maps > Properties > Latitude > Action Results > Location Get Current Coordinates > latitude tanımlamasını yapın.
Longitude koordinatı için Maps > Properties > Longitude > Action Results > Location Get Current Coordinates > longitude tanımlamasını yapın.
Veri kaynağını bağlamak için Maps > Properties > DataSource > Action > MapDataSource tanımlamasını yapın ve açılan alanlara aşağıdaki tanımlamayı yapın.
Harita türünü kullanıcının seçebilmesi için Maps > Properties > MapType > User Select tanımlamasını yapın.
Mevcut konumunuz izlemek için Maps > Properties > EnableLocationTracking > Açık tanımlamasını yapın.
Icon elementi üzerine gelindiğinde ilgili lokasyonun sıra numarasını göstermek için Icon > Properties > Tooltip > Current > Sequence > To String olarak tanımlayın.
Icon yanına Horizontal Stack elementi içerisine Elements > Display > Label elementini sürükleyip bırakın.
Label elementinin yazısını Label > Properties > Value > Field to display > Tooltip olarak tanımlayın.
Label, Horizontal Stack içerisine eklendiği için 100 pxön tanımlı genişlikte gelecektir. Bu genişliği kaldırmak için Label > Styling > Layout > Width alanını temizleyiniz.
Preview:
Maps elementi açıldığında, harita üzerinde tanımlı lokasyonlar marker olarak görüntülenir. Street View, zoom ve full screen gibi kontrol araçları element properties alanı içerisinde varsayılan olarak aktif gelir ve isteğe bağlı olarak yapılandırılabilir. Harita, sistem aksiyonu ile kullanıcının mevcut konumunu merkez alacak şekilde başlatılır ve kullanıcı bulunduğu bölge üzerinden lokasyonları inceleyebilir.
Harita üzerindeki markerlara tıklandığında, ilgili lokasyona ait detay bilgiler popup alanında gösterilir. Marker ikonunun üzerine gelindiğinde ise tooltip olarak lokasyonun listedeki sıralama bilgisi görüntülenir. Bu sayede kullanıcı, hem konum bilgisine hem de sıralama detayına hızlı şekilde erişebilir.
Zoom seviyesine bağlı olarak, birbirine yakın konumdaki markerlar gruplanarak tek bir gösterim halinde sunulur (örneğin, üzerinde “2” yazan grup marker). Gruplanmış marker üzerine tıklandığında, ilgili lokasyonlara ait açıklamalar liste şeklinde bir drawer alanında görüntülenir. Bu yapı sayesinde yoğun lokasyon verileri daha düzenli ve kullanıcı dostu bir şekilde sunulur.
4. Ortak Özellikler (Properties)
Maps elementi üzerinde yer alan bazı alanlar tüm UI elementlerinde ortak olarak kullanılır. Bu nedenle, aşağıdaki özelliklerin detaylı açıklamaları ilgili genel kılavuz sayfalarında yer almaktadır:
