Currency elementi, uygulamanızda kullanıcıların para birimi formatında değer girmesini sağlayan bir giriş (input) elementidir. Currency elementi; fiyat, bütçe, ödeme, maaş, sipariş tutarı, kampanya indirimi gibi sayısal parasal verilerin doğru formatla girilmesi ve gösterilmesi gereken tüm senaryolarda kullanılır.
Currency elementi yalnızca web uygulamalarında kullanılabilir.
1.1. Sık Kullanım Senaryoları
Ürün / hizmet fiyatı girişi (ör. 12.500,00 ₺)
Sipariş toplamı, sepet tutarı, ödeme tutarı alanları
Bütçe, gider, gelir, teklif tutarı girişleri
İndirim, komisyon, vergi tutarı gibi parasal hesap alanları
Yönetim panellerinde raporlama amaçlı tutar filtreleri (min–max tutar gibi)
Kullanıcıdan “tutar” alınan formlar (bağış, depozito, iade bedeli vb.)
2. Temel Özellikler
Ondalık hassasiyet kontrolü (Decimal Scale): Girilecek ondalık basamak sayısı sınırlandırılabilir. Özellikle finansal işlemlerde standartlaştırılmış tutar girişleri sağlar.
Sayısal veri doğrulama: Harf, özel karakter veya geçersiz format girişlerini engelleyerek yalnızca geçerli parasal değerlerin girilmesini sağlar.
Form ve veri işlemleriyle uyumlu çalışma: Currency elementi; form submit işlemleri, state güncellemeleri, hesaplama aksiyonları ve backend entegrasyonları ile sorunsuz şekilde çalışır.
Diğer input elementleriyle tutarlı davranış: Visibility, Authorization, Editability gibi ortak özellikleri destekleyerek uygulama genelinde standart bir kullanım sunar.
2.1. Currency Elementi Özellikleri (Properties)
Properties panelinden aşağıdaki ayarları yapılandırabilirsiniz:
Decimal Separator: Ondalık kısmı ayırmak için kullanılan karakterdir (örn. 1,234.56 veya 1.234,56).
Value: Currency elementinde varsayılan olarak gösterilecek değerdir. Statik bir değer olabileceği gibi, dinamik olarak da belirlenebilir.
Placeholder: Değer girilmediğinde görüntülenen yer tutucu metindir.
Decimal Scale: Ondalık kısmında gösterilecek basamak sayısını belirler (örn. 2 ayarlandığında, 123.45 şeklinde görüntülenir).
Allow Negative: Kullanıcıların negatif değerler girmesine izin verilip verilmeyeceğini belirler.
Prefix: Değerin önünde gösterilecek metni tanımlar (örn. "$" veya "€").
Suffix: Değerin arkasında gösterilecek metni tanımlar (örn. " USD" veya " EUR").
Bu kılavuzu takip ederek Currency elementini uygulamanızda etkili bir şekilde kullanabilirsiniz.
2.2. Elemente Eklenebilen Aksiyonlar
Currency elementi, kullanıcıdan parasal değer girişi alınmasını sağlayan bir input elementi olduğundan belirli kullanıcı etkileşimleri üzerinden aksiyon tetiklemeyi destekler. Aksiyonlar, elementin kendisine değil; olay (event) bazlı olarak tanımlanır.
Currency elementi için aksiyonlar, sağ panelde Properties > Add Action alanı üzerinden aşağıdaki olaylara bağlanabilir.
Desteklenen Aksiyon Tetikleyicileri
onChange: Kullanıcı Currency alanındaki değeri her değiştirdiğinde tetiklenir.
Kullanım amaçları:
Girilen tutara göre anlık hesaplama yapmak (ör. KDV ekleme, indirim hesaplama)
State veya değişken güncellemek
Başka alanların değerlerini dinamik olarak değiştirmek
Canlı validasyon veya uyarı mesajı göstermek
Örnek senaryo: Kullanıcı tutar girdiğinde toplam fiyat otomatik hesaplanır ve başka bir alanda gösterilir.
onPressEnter: Kullanıcı Currency alanındayken Enter tuşuna bastığında tetiklenir.
Kullanım amaçları:
Form gönderme (submit)
Bir sonraki adıma geçiş
Navigasyon aksiyonu çalıştırma
Kaydetme veya onay işlemleri başlatma
Örnek senaryo: Kullanıcı tutarı girip Enter’a bastığında ödeme adımına yönlendirilir.
Aksiyonlara İlişkin Temel Kurallar
Currency elementi doğrudan aksiyon tetikleyemez; aksiyonlar yalnızca onChange ve onPressEnter olayları üzerinden çalışır.
Eklenen aksiyonlar, sadece ilgili event tetiklendiğinde çalışır.
Aynı event için birden fazla aksiyon tanımlanabilir.
Currency elementi, özellikle hesaplama, veri işleme ve form senaryolarında aksiyonlarla birlikte kullanıldığında güçlü ve esnek bir yapı sunar.
3. Currency Elementi Nasıl Kullanılır?
Bu bölümde Currency elementinin uçtan uca kullanımını, e-ticaret ürün fiyatlandırma senaryosu üzerinden ele alacağız.
Senaryo: Ürün Fiyatının Currency Elementi ile Girilmesi
Bir e-ticaret veya ürün yönetim uygulamasında, yöneticilerin ürün fiyatlarını doğru ve tutarlı bir formatta girmesi gerekir. Serbest metin alanları, yanlış formatlama ve hatalı girişlere neden olabilir.
Bu senaryoda, ürün fiyatı Currency elementi kullanılarak girilir. Girilen değer, seçilen para birimine göre otomatik olarak biçimlendirilir ve kaydedilmeye hazır hale getirilir.
Senaryoda:
Ürün fiyatı kullanıcıdan Currency elementi ile alınır.
Girilen değer otomatik olarak para birimi formatına dönüştürülür.
Negatif değer girişine izin verilmez.
Adım 1 - Veri Kaynağı Oluşturma
DataSources modülünde tablo oluşturma:
Datasources modülüne gidin.
Ardından Tables sekmesine gidin.
“PurchasedProducts” adında yeni tablo oluşturun.
Kurulması gereken tablo yapısı aşağıdaki gibidir:
Önemli Alan adları:
ProductName: Satın alınan ürünün ad bilgisini tutar. Form üzerinde kullanıcı tarafından girilen ana metin alanıdır.
Price: Ürünün satın alma fiyatını ifade eder. Sayısal veri türünde olup tutar bazlı hesaplamalarda kullanılır.
PurchaseDate: Ürünün satın alındığı tarih ve saat bilgisini saklar. Zaman bazlı filtreleme ve raporlama senaryolarında kullanılır.
Adım 2 – Ana Sayfa Element Ekleme
UI Design modülünü açın.
Sayfaya Elements > Display > Label elementini sürükleyip bırakın.
Fiyat birimlerinizi SelectBox veya Table üzerinden dinamik olarakta tanımlayabilirsiniz.
Sayfaya fiyat kaydetmek için Elements > Navigation > Button elementini sürükleyip bırakın.
Buton yazısını Button > Properties > Label > Fixed Value > “Kaydet” olarak ayarlayın.
Button elementine aksiyon ekleyin. Add Action > onClick > Managed DB > Save Record aksiyonunu ekleyin.
Aksiyonda tablo seçimini PurchaseProducts olarak ayarlayın ve açılan sütünlar alanında tüm sütunları seçin.
Price alanını Components > Currency > value olarak tanımlayın.
ProductName alanını Components > TextInput > value olarak tanımlayın.
PurchaseDate alanına Default > Now tanımlaması yapın.
Id alanına Default > New Guid tanımlamasını yapın.
Preview
Uygulama test edildiğinde, ürün ekleme ve düzenleme işlemleri için sade ve kullanıcı dostu bir form ekranı görüntülenir. Ekranda Ürün Adı ve Ürün Fiyatı alanları yer alır.
Form ilk açıldığında alanlar boş olarak gelir. Ürün Adı alanı metin girişi için hazır durumdadır, Ürün Fiyatı alanı ise sayısal değer girişi yapılabilecek şekilde varsayılan formatta görüntülenir. Kullanıcı, ürün bilgilerini bu alanlara girerek formu doldurur. Küsürat değerleri için “.” veya “,” basmanız durumunda kendisi tanımladığımız “,” ayracını kullanacaktır.
Kullanıcı gerekli bilgileri girdikten sonra Kaydet butonuna tıkladığında, form verileri sistem tarafından işlenir ve ürün bilgileri kaydedilir.
4. Ortak Özellikler (Properties)
Currency 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:
DecimalScale değerini senaryoya göre belirleyin. Fiyat ve ödeme alanlarında genellikle 2 ondalık basamak yeterlidir. Ondalık hassasiyet gerekmeyen durumlarda 0 kullanarak gereksiz girişleri engelleyebilirsiniz.
Doğru ondalık ayırıcıyı kullanın. Hedef kullanıcı kitlesinin alışık olduğu . veya , ayırıcısını seçmek, giriş hatalarını azaltır.
Placeholder ile kullanıcıyı yönlendirin. 0,00 veya Tutar giriniz gibi açıklayıcı placeholder’lar, beklenen formatın anlaşılmasını sağlar.
Negatif değer kullanımını bilinçli yönetin. Sadece borç, iade veya zarar gibi senaryolarda AllowNegative aktif edilmelidir. Fiyat ve satış tutarlarında kapalı tutulması önerilir.
6. Kısıtlamalar
Para birimi sembolü (₺, $, € vb.) için ayrı bir seçim alanı bulunmaz; element yalnızca sayısal parasal formatlama sağlar.
Aksiyonlar yalnızca onChange ve onPressEnter event’leri üzerinden tetiklenebilir.
