1. Select Box Elementine Genel Bakış

Select Box elementi, kullanıcıların açılır menü (dropdown) aracılığıyla önceden tanımlanmış seçenekler arasından tek bir seçim yapmasını sağlayan temel bir seçim elementidir. Kompakt yapısı sayesinde çok sayıda seçeneğin düzenli bir şekilde sunulmasına olanak tanır.

Select Box elementi; form alanları, filtreleme seçenekleri ve ayar ekranlarında sıkça kullanılır. Açılır menü yapısı, arayüzde yer tasarrufu sağlarken kullanıcıların hızlı ve kontrollü seçim yapmasını destekler.

Select Box elementi hem web hem de mobil uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Tekli seçim gerektiren form alanları
• Kategori, durum veya tip seçimi
• Filtreleme ve sıralama seçenekleri
• Ayar ve tercih ekranları
• Çok sayıda seçenek içeren ancak tek seçim yapılması gereken senaryolar

2. Temel Özellikler

• Tekli seçim (single select) desteği: Kullanıcı aynı anda yalnızca bir seçeneği seçebilir.
• Açılır menü (dropdown) tabanlı yapı: Seçenekler ihtiyaç halinde açılarak gösterilir, böylece arayüzde yer tasarrufu sağlanır.
• Statik ve dinamik seçenek desteği: Seçenekler manuel olarak tanımlanabilir veya veri kaynakları üzerinden dinamik şekilde bağlanabilir.
• Seçili değerin net gösterimi: Kullanıcının yaptığı seçim, Select Box üzerinde açıkça görüntülenir.

2.1. Select Box Elementi Özellikleri

• Value: Statik bir değer ekleyebilir veya Symbol Picker kullanarak başka bir elementin içeriğini ya da aksiyon sonucunu dinamik olarak gösterebilirsiniz.
• Options: Açılır liste içinde gösterilecek veri tablosunun bağlantısını sağlar.
• Fixed Options List: Manuel olarak tanımlanan sabit verilerin listelenmesini sağlar.
• Placeholder: Kullanıcının veri girmediğinde görünen yer tutucu metindir.
• Allow Clear: Seçilen değerin tek tıklamayla silinmesini sağlar.
• Searchable: Açılır liste içinde arama yapılabilmesine olanak tanır.
• Contains Null Item: Listenin ilk değerini boş olarak ayarlayabilirsiniz.
• Sort By: Liste öğelerini alfabetik olarak A-Z veya Z-A sıralar.
• Dropdown Scroll Item Limit: Açılır listede aynı anda görüntülenecek maksimum öğe sayısını belirler. Belirtilen limit aşıldığında, kullanıcı aşağı kaydırarak kalan seçenekleri görebilir.

2.2. Datasources Modülünde Veri Aktarımı

1. Datasources modülünü açın.
2. Verilerinizi içeren bir tablo oluşturun. Örnek: Department tablosu.
3. Tabloya gerekli sütunları ekleyin (örn. DepartmentName).‍
4. Actions bölümünden yeni bir SQL Action oluşturun. Örnek: SelectDepartment.
5. SQL Editöründe şu sorguyu yazın:

SELECT * FROM Department

6. Aksiyonu kaydedin.

2.3. UI Design Modülünde Veri Aktarımı

1. UI Design modülüne gidin.
2. Select Box’ı eklediğiniz ekranda sağ kenardaki Properties panelinden ADD ACTION butonuna tıklayın.
3. Initial Actions → Custom → Datasource adımlarını izleyerek SelectDepartment aksiyonunu seçin.
4. Select Box elementine tıklayın ve Options menüsünden şu ayarları yapın:
   
   • Action: SelectDepartment
   • Field to display: DepartmentName
   • Field to Use as Key: Id

2.2. Elemente Eklenebilen Aksiyonlar

Select Box elementi, kullanıcıların açılır menü üzerinden yaptığı seçime bağlı olarak olay (event) bazlı aksiyonlar tanımlanmasını destekler. Aksiyonlar, elementin kendisine değil; kullanıcı etkileşimleri sonucunda tetiklenen event’lere bağlanır.

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

Desteklenen Aksiyon Tetikleyicileri

onSelect: Kullanıcı açılır listeden bir seçenek seçtiğinde tetiklenir.

Kullanım amaçları:

• Seçilen değeri state veya değişkene kaydetmek
• Seçime bağlı alanları otomatik doldurmak
• Filtreleme veya liste güncelleme işlemlerini başlatmak

Örnek senaryo: Kullanıcı “Durum” alanında bir seçenek seçtiğinde, liste yalnızca seçilen duruma göre filtrelenir.

onChange: Select Box içindeki değer her değiştiğinde tetiklenir.

Kullanım amaçları:

• Seçim değişikliğini izlemek
• Bağımlı alanların durumunu güncellemek
• Form akışını veya adımlarını kontrol etmek

onBlur: Kullanıcı Select Box alanından odak çıktığında tetiklenir.

Kullanım amaçları:

• Seçim yapılıp yapılmadığını kontrol etmek
• Validasyon çalıştırmak veya uyarı göstermek

getTextFromValue: Seçilen value’ya karşılık 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

Aksiyonlara İlişkin Temel Kurallar

• Select Box elementi birden fazla event üzerinden aksiyon tetikleyebilir.
• Aynı event için birden fazla aksiyon tanımlanabilir.
• Tekli seçim yapısı sayesinde aksiyon akışları öngörülebilir ve kontrollüdür.
• Dinamik veri kaynaklarıyla çalışırken getTextFromValue kullanımı önerilir.

Select Box elementi, özellikle form alanları, filtreleme ve ayar ekranlarında aksiyonlarla birlikte kullanıldığında sade ve etkili bir kullanıcı deneyimi sunar.

3. Select Box Elementi Nasıl Kullanılır? 

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

Senaryo: Kategori Seçimi ve Ürün Listeleme

Kullanıcı, belirli bir kategoriye ait ürünleri görüntülemek için Select Box elementini kullanır. Select Box sayesinde kullanıcı listelenen kategoriler arasından tek bir seçim yapabilir ve seçilen kategoriye bağlı ürünler ekranda görüntülenir.

Senaryoda:

• Ekranda bir Select Box alanı bulunur. Bu alanda sistemde tanımlı olan kategoriler listelenir. Kullanıcı listeden bir kategori seçtiğinde, seçilen kategori bilgisi ilgili filtreleme parametresi olarak kullanılır.
• Kategori seçimi yapıldıktan sonra sistem, seçilen kategoriye ait ürünleri getirir ve kullanıcıya liste halinde gösterir. Böylece kullanıcı sadece ilgili kategoriye bağlı ürünleri görüntüleyebilir.
• Bu yapı sayesinde kullanıcılar kategoriler arasında kolayca seçim yapabilir ve seçilen kategoriye göre ürünleri hızlı bir şekilde filtreleyebilir.

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

DataSources modülünde tablo oluşturma: 

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

• Önemli Alan adları:
  
  • CategoryName: Kullanıcıya Select Box içerisinde gösterilen kategori adını ifade eder. Kullanıcı bu alan üzerinden seçim yapar.
• “StoreProducts” adında yeni tablo oluşturun.
• Kurulması gereken tablo yapısı aşağıdaki gibidir:
  

• Önemli Alan adları:
  
  • CategoryId: Ürünün hangi kategoriye ait olduğunu belirtir. Seçilen kategoriye göre ürünlerin filtrelenmesini sağlar.
  • ProductName: Seçilen kategoriye bağlı olarak kullanıcıya listelenecek ürün adını ifade eder.

Adım 2 - Gerekli Aksiyonun Tanımlanması

Arayüzde verileri göstermek için: 

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

• Kategorileri ve Ürünleri Ekleyen Aksiyon  (InsertCategoriesStoreProducts):

Uygulamayı örnek verilerle test etmek için aşağıdaki SQL aksiyonunu ekleyin ve TEST butonuna basın.

DECLARE @ElektronikId UNIQUEIDENTIFIER = NEWID()
DECLARE @BilgisayarId UNIQUEIDENTIFIER = NEWID()
DECLARE @TelefonId UNIQUEIDENTIFIER = NEWID()
DECLARE @EvAletleriId UNIQUEIDENTIFIER = NEWID()
DECLARE @MobilyaId UNIQUEIDENTIFIER = NEWID()

-- Categories
INSERT INTO Categories (Id, CategoryName)
VALUES
(@ElektronikId, 'Elektronik'),
(@BilgisayarId, 'Bilgisayar'),
(@TelefonId, 'Telefon'),
(@EvAletleriId, 'Ev Aletleri'),
(@MobilyaId, 'Mobilya')

-- Products
INSERT INTO StoreProducts (Id, CategoryId, ProductName)
VALUES
(NEWID(), @ElektronikId, 'Televizyon'),
(NEWID(), @ElektronikId, 'Kulaklık'),

(NEWID(), @BilgisayarId, 'Laptop'),
(NEWID(), @BilgisayarId, 'Masaüstü Bilgisayar'),

(NEWID(), @TelefonId, 'iPhone'),
(NEWID(), @TelefonId, 'Android Telefon'),

(NEWID(), @EvAletleriId, 'Buzdolabı'),
(NEWID(), @EvAletleriId, 'Çamaşır Makinesi'),

(NEWID(), @MobilyaId, 'Ofis Sandalyesi'),
(NEWID(), @MobilyaId, 'Çalışma Masası')

Uygularken Categories ve StoreProducts kısımlarını silip tekrar Categories ve StoreProducts yazıp Enter'a basınız. Böylelikle tablo adlarının önünde doğru şema adları eklenecektir.

• Kategorileri Listeleyen Aksiyon  (GetProductCategories):

SELECT * FROM Categories

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

• Seçilen Kategori Ürünlerini Listeleyen Aksiyon  (GetStoreProducts):

SELECT * FROM StoreProducts WHERE CategoryId = @CategoryId OR @CategoryId IS NULL

Uygularken StoreProducts kısmını silip tekrar StoreProducts yazıp Enter'a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir. CategoryId parametre türünü Guid tanımlayın.

Adım 3 - Initial Action Ekleme

Başlangıçta anasayfada: 

• Radio Group içerisinde gösterilecek etiketler için Add Action > Initial Action > Custom > Managed DB > GetProductCategories  aksiyonunu ekleyin.
  

• Seçim ekranında Radio Group tercihlerinin kayıt ve güncelleme işlemlerini gözlemlemek için Add Action > Initial Action > Custom > Managed DB > GetStoreProducts  aksiyonunu ekleyin.
  

• GetStoreProducts aksiyonu içerisinde CategoryId > Default > null tanımlamasını yapın.

Adım 4 - Select Box Elementini Ekleme ve Aksiyon Tanımlama

Başlangıçta anasayfada: 

• Sol yan panelden alan adını belirtmek için Elements > Display > Label elementini sayfaya sürükleyip bırakın. 
• Yazıyı Label > Properties > Value > “Ürün Kategorisini Seçiniz:” olarak tanımlayın.

• Altına Elements > Select Input > SelectBox elementini sürükleyip bırakın.
• Kategorileri dinamik olarak listelemek için  SelectBox > Properties > Options > GetCategories tanımlamasını yapın. Açılan alanları Field to display > PaymentTypeName ve Id ve Field to User as Key > Id olacak şekilde tanımlayın.
  ‍

Select Box elementinin özelliği olarak Id dahil birden fazla gösterim alanı belirleyebilirsiniz.

• Ön yazı metnini SelectBox > Properties > Placeholder > “Kategori Seçiniz” olarak tanımlayın.
  

• Tercihlerin temizlenebilmesi için SelectBox > Properties > AllowClear > Açık olarak ayarlayın.
  

• Select Box elementi içerisinde metin üzerinden arama yapabilmek için SelectBox > Properties > Searchable > Açık olarak ayarlayın.
  

• Kategori seçim sonrası ürünleri filtrelemek için SelectBox > Properties > Add Action > onChange > Custom > ManagedDB > GetStoreProducts aksiyonunu ekleyin.

• GetStoreProducts aksiyonu içerisinde CategoryId > Components > SelectBox > value > Id tanımlamasını yapın.
  

• Ürünleri göstermek için sol yan paneldeki Action Tree alanından GetStoreProducts aksiyonunu yanındaki ikondan basılı tutarak sayfaya sürükleyin.
  
  

• Açılan ekranda aşağıdaki tanımlamaları yapın.
  

•  Son durumda beklenen sayfa yapısı aşağıdaki gibidir.
  

Preview:

Bu örnekte Select Box elementi, ürün kategorileri arasından seçim yaparak ürün listesini filtrelemek için kullanılır. Sayfa ilk açıldığında herhangi bir kategori seçili değildir ve bu durumda tabloda tüm ürünler listelenir. Kullanıcı açılır listeden bir kategori seçtiğinde ise alttaki tablo otomatik olarak güncellenir ve yalnızca seçilen kategoriye ait ürünler gösterilir.

Select Box içerisinde bulunan arama alanı sayesinde kullanıcı kategori adını yazarak listede hızlı bir şekilde arama yapabilir ve istediği kategoriye kolayca ulaşabilir. Ayrıca alanın sağ tarafında yer alan temizleme (clear) ikonu kullanılarak yapılan seçim kaldırılabilir. Seçim temizlendiğinde filtre kaldırılır ve tablo tekrar tüm ürünleri gösterecek şekilde güncellenir.

4. Ortak Özellikler (Properties)

Footer 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)

• Tekli seçim gereken senaryolarda kullanın. Kullanıcının yalnızca bir seçenek seçmesi gerekiyorsa Select Box tercih edilmelidir.
• Seçenek listesini anlamlı ve sade tutun. Çok fazla seçenek içeren listelerde, arama (Searchable) özelliğini kullanarak kullanıcı deneyimini iyileştirin.
• Placeholder ile kullanıcıyı yönlendirin. Seçiniz, Bir seçenek seçin gibi ifadeler, beklenen etkileşimi netleştirir.
• onSelect ve onChange event’lerini bilinçli kullanın. Seçim sonrası çalışması gereken işlemleri bu event’lere bağlayarak kontrollü bir akış oluşturun.
• Allow Clear özelliğini gerektiğinde aktif edin. Kullanıcının seçimini kolayca temizleyebilmesi, özellikle filtreleme senaryolarında faydalıdır.
• Dinamik veri kaynaklarında getTextFromValue kullanımını ihmal etmeyin. Value–Label ayrımı olan yapılarda kullanıcıya doğru metnin gösterilmesini sağlar.

6. Kısıtlamalar

• Select Box elementi tekli seçim senaryoları için uygundur; çoklu seçim için Multi Select kullanılmalıdır.
• Aksiyonlar yalnızca desteklenen event’ler (onSelect, onChange, onBlur) üzerinden tetiklenebilir.