1. Auto Complete Elementine Genel Bakış

Auto Complete elementi, kullanıcıların metin girişi sırasında önceden tanımlanmış veri kümeleri üzerinden hızlı ve doğru seçim yapmasını sağlayan etkileşimli bir input elementidir. Kullanıcı yazmaya başladığında, girilen metinle eşleşen öneriler otomatik olarak listelenir ve kullanıcı bu listeden seçim yapabilir.

Auto Complete elementi; uzun liste içeren seçim alanlarında manuel yazım ihtiyacını azaltır, veri giriş hızını artırır ve yazım hatalarının önüne geçer. Özellikle arama, filtreleme ve seçim senaryolarında kullanıcı deneyimini önemli ölçüde iyileştirir.

Auto Complete elementi hem web hem de mobil uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Şehir, ülke veya adres seçimi
• Kullanıcı, ürün veya etiket arama alanları
• Kategori veya alt kategori seçimi
• Büyük veri setleri içinden hızlı seçim yapılması
• Filtreleme ve arama ekranlarında metin destekli seçim alanları

2. Temel Özellikler

• Dinamik öneri listesi: Kullanıcı metin yazdıkça, girilen ifadeyle eşleşen öneriler otomatik olarak listelenir.
• Hızlı ve hatasız seçim deneyimi: Kullanıcılar yazmak yerine listeden seçim yaparak veri giriş süresini kısaltır.
• Metin tabanlı arama ve filtreleme: Girilen karakterlere göre öneriler daraltılır ve yalnızca ilgili sonuçlar gösterilir.

2.1. Auto Complete Elementi Özellikleri (Properties)

Properties panelinden aşağıdaki ayarları yapılandırabilirsiniz:

• Options: Liste içinde gösterilecek verinin bağlantısını yapabilirsiniz. Statik bir liste de oluşturabilirsiniz.
• Fixed Options List: Veri tabanına bağlı olmadan manuel olarak tanımlanan sabit verileri listeler.
• Fixed Data: Listeyi oluşturan her bir verinin görünen ismini (Text) ve uygulama içinde kullanılacak değerini (Key) belirler.
• Placeholder: Kullanıcının veri girmediğinde görüntülenen yer tutucu metindir.
• Allow Clear: Sağ kenarda bir Sil (X) simgesi ekleyerek girilen verinin tek tıklamayla silinmesini sağlar.
• Value: Statik bir değer ekleyebilir veya Symbol Picker aracılığıyla başka bir elementin içeriğini ya da aksiyon sonucunu dinamik olarak gösterebilirsiniz.

2.2. Auto Complete Elementine Fixed Options Özelliği ile Veri Bağlama

1. Sağ kenardaki Properties panelini açın.
2. Options açılır menüsünden Actions altında yer alan Please Select butonuna tıklayın.
3. Açılan menüden Fixed Options List seçeneğini belirleyin.‍
4. Fixed Options List altında bulunan Fixed Data butonuna tıklayın.
5. Açılan ekranda manuel olarak Key ve Text alanlarını doldurun.‍
6. UPDATE butonuna tıklayarak verileri bağlayın.

2.3. Elemente Eklenebilen Aksiyonlar

Auto Complete elementi, kullanıcı etkileşimlerine bağlı olarak olay (event) bazlı aksiyonlar tanımlanmasını destekler. Aksiyonlar, elementin kendisine değil; kullanıcı girişleri ve seçimleri sonucunda tetiklenen event’lere bağlanır.

Auto Complete elementi için aksiyonlar, Properties > Add Action alanı üzerinden aşağıdaki event’ler aracılığıyla eklenebilir.

Desteklenen Aksiyon Tetikleyicileri

onSearch: Kullanıcı arama yaptığında tetiklenir. Arama metni temizlendiğinde (clear) de çalışır.

Kullanım amaçları:

• Girilen metne göre öneri listesini dinamik olarak oluşturmak
• API çağrısı yaparak sonuçları filtrelemek
• Büyük veri setlerinde arama performansını artırmak

Örnek senaryo: Kullanıcı şehir ismi yazdıkça, API üzerinden eşleşen şehirler liste halinde getirilir.

onSelect: Kullanıcı her seçim yaptığında tetiklenir.

Kullanım amaçları:

• Seçilen değeri state veya değişkene atamak
• Bağlı alanları otomatik doldurmak
• Form verisini güncellemek

Örnek senaryo: Kullanıcı bir ürünü seçtiğinde, ürün detayları otomatik olarak ilgili alanlara yazılır.

onChange: Yalnızca seçilen item değiştiğinde tetiklenir.

Kullanım amaçları:

• Kullanıcı girişini izlemek
• Yardımcı metin veya uyarı göstermek
• Bağımlı alanların durumunu güncellemek

onBlur: Kullanıcı Auto Complete alanından odak çıktığında tetiklenir.

Kullanım amaçları:

• Alan boş bırakıldıysa validasyon çalıştırmak
• Girilen değerin geçerli olup olmadığını kontrol etmek

getTextFromValue: Seçilen değerden gösterilecek metni elde etmek için kullanılır.

Kullanım amaçları:

• Value–Label ayrımı olan veri yapılarında doğru metni göstermek
• API’den gelen karmaşık veri yapılarında kullanıcıya anlamlı etiket sunmak

Örnek senaryo: Value olarak user_id, metin olarak Ad Soyad bilgisinin gösterilmesi.

Aksiyonlara İlişkin Temel Kurallar

• Auto Complete elementi birden fazla event üzerinden aksiyon tetikleyebilir.
• Aynı event için birden fazla aksiyon tanımlanabilir.
• onSearch event’i yoğun kullanıldığında performans açısından API çağrıları dikkatli planlanmalıdır.
• Karmaşık veri eşleştirme senaryolarında onSelect ve getTextFromValue birlikte kullanılması önerilir.

Auto Complete elementi, özellikle arama, filtreleme ve büyük veri setleriyle seçim yapılan senaryolarda aksiyonlarla birlikte kullanıldığında güçlü ve esnek bir kullanıcı deneyimi sunar.

3. Auto Complete Elementi Nasıl Kullanılır?

Bu bölümde Auto Complete elementinin uçtan uca kullanımını örnek senaryo üzerinden ele alacağız.

Senaryo: Ürün Kategori Tercihi

Kullanıcı, uygulama içerisinde ürünleri filtrelemek veya belirli bir kategoriye ait kayıtları hızlı bir şekilde görüntülemek için Auto Complete elementini kullanır. Kullanıcı arama alanına yazmaya başladığında sistem, veri kaynağındaki kategori kayıtlarını filtreleyerek eşleşen sonuçları liste halinde gösterir. Kullanıcı listeden uygun seçeneği seçtiğinde değer ilgili alana otomatik olarak aktarılır.

Senaryoda:

• Uygulamada ürün listeleme veya ürün yönetimi ekranında iki adet Auto Complete alanı bulunur: Birinci Kategori ve İkinci Kategori.
• Kullanıcı birinci kategori alanına yazmaya başladığında sistem veri kaynağındaki kategori kayıtlarını filtreleyerek eşleşen kategori önerilerini listeler. Kullanıcı listeden uygun kategoriyi seçtiğinde seçilen değer ilgili alana aktarılır ve filtreleme için ilk parametre olarak kullanılır.
• Benzer şekilde kullanıcı ikinci kategori alanına yazdığında sistem veri kaynağındaki ikinci kategori alanındaki kayıtları filtreleyerek öneri listesi oluşturur. Kullanıcı listeden bir kategori seçtiğinde seçilen değer ikinci filtre parametresi olarak belirlenir.
• Kullanıcı her iki kategori alanında seçim yaptıktan sonra sistem, seçilen Birinci kategori ve ikinci kategori değerlerine göre ilgili ürün veya kayıtları filtreleyerek listeler.
• Bu yapı sayesinde kullanıcılar uzun listeler içerisinde manuel seçim yapmak yerine yazdıkça filtrelenen sonuçlar üzerinden hızlı ve hatasız seçim yapabilir. Ayrıca kategori bazlı filtreleme işlemi daha pratik hale gelir ve kullanıcı deneyimi önemli ölçüde iyileştirilir.

Adım 1 - Veri Kaynağı Oluşturma

DataSources modülünde tablo oluşturma: 

• Datasources modülüne gidin. 
• Ardından Tables sekmesine gidin.
• “CategoryItems” adında yeni tablo oluşturun.
• Kurulması gereken tablo yapısı aşağıdaki gibidir:
  

• Önemli Alan adları:
  
  • CategoryOne: Ürünün veya kaydın birinci kategori bilgisini ifade eder. İlk Auto Complete alanında kullanıcıya sunulan kategori seçeneklerini oluşturur ve filtreleme sürecinde ilk seçim parametresi olarak kullanılır.
  • CategoryTwo: Ürünün veya kaydın ikinci kategori bilgisini ifade eder. İkinci Auto Complete alanında kullanıcıya sunulan kategori seçeneklerini oluşturur ve filtreleme sürecinde ikinci seçim parametresi olarak kullanılır.
  • ItemName: İlgili ürün veya kayıt adını ifade eder. Kullanıcı filtreleme işlemini tamamladıktan sonra listelenen sonuçlarda gösterilen temel bilgi alanıdır.
  • BrandName: İlgili ürünün marka bilgisini ifade eder. Filtreleme sonrası getirilen kayıtların marka bazında anlaşılmasını sağlar ve ürün bilgisini daha detaylı sunmak için kullanılır.
  • Price: İlgili ürün veya kayda ait fiyat bilgisini belirtir. Filtreleme sonucunda listelenen kayıtların fiyat bilgisini göstermek için kullanılır.

Adım 2 - Gerekli Aksiyonun Tanımlanması

Arayüzde verileri göstermek için: 

1. Örnek üç aksiyon tanımlamanız gerekir.
2. Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.

• Örnek Verileri Ekleyen Aksiyon (InsertCategoryItems): Uygulamayı örnek verilerle test etmek için aşağıdaki SQL aksiyonunu ekleyin ve TEST butonuna basın.

INSERT INTO dbo.CategoryItems (Id, CategoryName, ItemName, BrandName, Price)
VALUES
(NEWID(), 'Elektronik', 'iPhone 15', 'Apple', 69999.00),
(NEWID(), 'Elektronik', 'Galaxy S24', 'Samsung', 52999.00),

(NEWID(), 'Mobilya', 'Ofis Sandalyesi', 'XYZ', 8999.00),
(NEWID(), 'Mobilya', 'Çalışma Masası', 'ABC', 12999.00),

(NEWID(), 'Ev Aletleri', 'Air Fryer', 'Philips', 7999.00),
(NEWID(), 'Ev Aletleri', 'Robot Süpürge', 'Xiaomi', 15999.00),

(NEWID(), 'Bilgisayar', 'MacBook Air', 'Apple', 45999.00),
(NEWID(), 'Bilgisayar', 'ThinkPad X1', 'Lenovo', 38999.00),

(NEWID(), 'Telefon', 'iPhone 14', 'Apple', 57999.00),
(NEWID(), 'Telefon', 'Redmi Note 13', 'Xiaomi', 18999.00),

(NEWID(), 'Tablet', 'iPad Air', 'Apple', 24999.00),
(NEWID(), 'Tablet', 'Galaxy Tab S9', 'Samsung', 21999.00),

(NEWID(), 'Kulaklık', 'WH-1000XM5', 'Sony', 12999.00),
(NEWID(), 'Kulaklık', 'AirPods Pro', 'Apple', 10999.00),

(NEWID(), 'Akıllı Saat', 'Apple Watch Series 9', 'Apple', 19999.00),
(NEWID(), 'Akıllı Saat', 'Galaxy Watch 6', 'Samsung', 15999.00),

(NEWID(), 'Oyun Konsolu', 'PlayStation 5', 'Sony', 29999.00),
(NEWID(), 'Oyun Konsolu', 'Xbox Series X', 'Microsoft', 28999.00),

(NEWID(), 'Fotoğraf', 'Canon EOS R10', 'Canon', 34999.00),
(NEWID(), 'Fotoğraf', 'Sony A6400', 'Sony', 32999.00),

(NEWID(), 'Spor', 'Koşu Bandı', 'Voit', 18999.00),
(NEWID(), 'Spor', 'Dambıl Seti', 'Delta', 2999.00),

(NEWID(), 'Bahçe', 'Çim Biçme Makinesi', 'Bosch', 9999.00),
(NEWID(), 'Bahçe', 'Bahçe Hortumu', 'Gardena', 899.00),

(NEWID(), 'Aydınlatma', 'LED Masa Lambası', 'Philips', 799.00),
(NEWID(), 'Aydınlatma', 'Akıllı Ampul', 'Xiaomi', 499.00),

(NEWID(), 'Ofis', 'Laptop Standı', 'Baseus', 699.00),
(NEWID(), 'Ofis', 'Kablosuz Mouse', 'Logitech', 899.00),

(NEWID(), 'Mutfak', 'Blender', 'Arzum', 1499.00),
(NEWID(), 'Mutfak', 'Tost Makinesi', 'Tefal', 1999.00),

(NEWID(), 'Temizlik', 'Elektrikli Süpürge', 'Dyson', 18999.00),
(NEWID(), 'Temizlik', 'Buharlı Temizleyici', 'Karcher', 6999.00),

(NEWID(), 'Otomotiv', 'Araç Kamerası', '70Mai', 2499.00),
(NEWID(), 'Otomotiv', 'Akü Şarj Cihazı', 'Bosch', 1799.00);

Uygularken CategoryItems kısmını silip tekrar CategoryItems yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

• Kategorileri Filtreleyen Aksiyon  (GetItemsCategory):

SELECT
    MIN(Id) AS Id,
    CategoryName
FROM CategoryItems
WHERE @SearchText IS NULL
   OR @SearchText = ''
   OR CategoryName LIKE '%' + @SearchText + '%'
GROUP BY CategoryName

Uygularken CategoryItems kısmını silip tekrar CategoryItems yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

• Ürünleri Filtreleyen Aksiyon (GetItems):

SELECT
    Id,
    CategoryName,
    ItemName,
    BrandName,
    Price
FROM dbo.CategoryItems
WHERE CategoryName = @CategoryName

Uygularken CategoryItems kısmını silip tekrar CategoryItems yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

Adım 3 - Initial Action Ekleme

Başlangıçta anasayfada: 

• Element içerisinde örnek verilerin gösterimi için Add Action > Initial Action > Custom > Managed DB > GetItemsCategory aksiyonunu ekleyin.
  

• Başlangıçta tüm kategorilerin görüntülenmesi için SearchText alanını Default > null olarak tanımlayın.
  

Adım 4 - Auto Complete Elementini Ekleme ve Aksiyon Tanımlama

Başlangıçta anasayfada: 

• Sol yan panelden Elements > Display > Label elementini sayfaya sürükleyip bırakın. 
• Yazıyı Label > Properties > Value > “Kategori:” şeklinde tanımlayın.
  

• Altına sol yan panelden Elements > Select Input > AutoComplete elementini sayfaya sürükleyip bırakın. 
• Auto Complete elementinde arama işlemi sonrasında filtreleme için AutoComplete > Properties > Add Action > onSearch > GetItemsCategory aksiyonunu bağlayın.
  

• SearchText alanını Components > AutoComplete > Search Value olarak tanımlayın.
  

• Sonuçların aşağıda listelenmesi için AutoComplete > Properties > Add Action > onBlur > GetItems aksiyonunu bağlayın. (İsteğe bağlı onSearch tanımıda kullanılabilir)
  

• CategoryName alanını Components > AutoComplete > Value > CategoryName olarak tanımlayın.
  

• Son olarak tablo üzerinde ilgili kategoriye ait verileri görmek için sol yan paneldeki Action Tree alanında GetItems aksiyonu yanındaki mavi ikonu basılı tutup sayfaya sürükleyin ve ilgili alanları seçin.
  

Preview:

Bu örnekte Auto Complete elementi kullanılarak kullanıcıların ürünleri kategori bazında hızlı bir şekilde filtrelemesi sağlanır. Kullanıcı, ekranın üst kısmında yer alan Kategori alanına yazmaya başladığında sistem veri kaynağındaki kategori kayıtlarını filtreleyerek eşleşen sonuçları liste halinde gösterir. Kullanıcı listeden bir kategori seçtiğinde seçilen değer ilgili alana otomatik olarak aktarılır.

Kategori seçimi yapıldıktan sonra sistem, seçilen kategoriye ait ürünleri alt bölümde yer alan Table üzerinde listeler. Tablo içerisinde her ürün için Kategori Adı, Ürün Adı, Marka Adı ve Fiyat bilgileri görüntülenir. Böylece kullanıcılar belirli bir kategoriye ait ürünleri tek bir seçim ile hızlıca görüntüleyebilir.

4. Ortak Özellikler (Properties)

Auto Complete 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:

• Authorization (Yetkilendirme) Ayarları
• Visibility (Görünürlük)
• Editability (Düzenlenebilirlik)
• Style Panel (Stil Ayarları)

5. Kullanım Tavsiyeleri (Best Practices)

• onSearch event’ini performans açısından dikkatli yönetin. Her karakter girişinde tetiklendiği için, API çağrıları debounce veya minimum karakter sayısı ile sınırlandırılmalıdır.
• getTextFromValue kullanımını netleştirin. Value–Label ayrımı olan veri yapılarında, kullanıcıya gösterilecek metnin açık ve anlaşılır olmasına dikkat edin.
• onSelect ile bağlı alanları otomatik doldurun. Seçim sonrası form deneyimini hızlandırmak için ilişkili alanları güncelleyin.
• Placeholder ile kullanıcıyı yönlendirin. Arama yapın, Seçim yapınız gibi ifadeler, beklenen etkileşimi netleştirir.
• Validations ekleyerek yanlış girişleri engelleyin. Zorunlu alanlar veya geçersiz değerler için doğrulama kuralları tanımlayın.

6. Kısıtlamalar

• Çok büyük veri setlerinde, önlem alınmadan kullanılan onSearch event’i performans sorunlarına yol açabilir.
• Aksiyonlar yalnızca desteklenen event’ler (onSearch, onSelect, onChange, onBlur) üzerinden tetiklenebilir.