Kuika'nın Date elementi, kullanıcıların bir tarih seçmesini veya manuel olarak tarih girmesini sağlayan temel bir giriş elementidir. Form yapılarında, filtreleme ekranlarında, rezervasyon ve planlama süreçlerinde en sık kullanılan elementlerden biridir. Kullanıcı, açılır tarih seçici (date picker) sayesinde hızlı ve hatasız şekilde tarih belirleyebilir.
Date elementi hem basit tarih seçimlerini hem de doğrulama kurallarıyla desteklenen kontrollü girişleri mümkün kılar. Böylece yanlış format, geçersiz tarih veya belirli aralık dışındaki seçimler kullanıcıya engellenebilir veya yönlendirilebilir.
Date elementi, web ve mobil uygulamalarda desteklenmektedir.
1.1. Sık Kullanım Senaryoları
Formlarda tarih girişi: Doğum tarihi, son kullanım tarihi, fatura tarihi, randevu tarihi gibi alanlarda kontrollü ve hatasız giriş sağlar.
Filtreleme ekranları: Kullanıcıların veri listelerini belirli bir tarihe göre filtrelemesi gereken senaryolarda kullanılır. Örn: Sipariş tarihi, işlem tarihi, ödeme tarihi filtreleri.
Rezervasyon ve planlama işlemleri: Otel, spor salonu, restoran, taşıma veya randevu rezervasyonlarında tarih seçimi için kullanılabilir.
Tarih doğrulaması gerektiren süreçler: Minimum/maximum tarih aralığı belirlemek, geçmiş tarih seçimini engellemek gibi kurallarla hata oranını azaltır.
Etkinlik, görev ve proje yönetimi: Görev başlangıç/bitiş tarihi, proje sprint tarihi, etkinlik günleri gibi alanlarda kullanılır.
2. Temel Özellikler
Kolay tarih seçimi (Date Picker) desteği: Kullanıcılar manuel tarih girebilir veya açılır tarih seçici aracılığıyla hızlı seçim yapabilir.
Tarih doğrulama (Validation) desteği: Minimum ve maksimum tarih sınırı belirlenerek geçersiz tarihlerin seçilmesi engellenebilir. Örn: “Bugünden önce tarih seçilemez.”
Dinamik değer bağlama: Seçilen tarih diğer aksiyonlara parametre olarak gönderilebilir veya sayfadaki diğer elementleri tetiklemek için kullanılabilir.
Format uyumluluğu: Tarih değerleri uygulama içinde YYYY-MM-DD formatında işlenir. Kullanıcıya gösterim formatı özelleştirilebilir.
Zaman bağımsız kullanım (sadece tarih): Element sadece günü temsil eder. Saat bilgisi içermez. (Saat seçimi için Time veya DateTime elementi tercih edilmelidir.)
Boş değer (null) desteği: Formlarda isteğe bağlı tarih alanı gerektiğinde boş bırakılabilir ve doğrulama kuralları buna göre yapılandırılabilir.
2.1. Date Elementi Özellikleri (Properties)
Date elementinin tüm ayarları, sağ tarafta bulunan Properties paneli üzerinden yapılandırılır. Aşağıda her bir özellik detaylı biçimde açıklanmıştır:
Value: Date elementi, statik bir tarih değeri alabilir veya Symbol Picker kullanılarak dinamik değerler atanabilir.
Placeholder: Kullanıcıya rehberlik etmek için yardımcı bir yer tutucu metin ekleyebilirsiniz. Örneğin, "Tarih Seçin".
Allow Clear: Kullanıcıların girdikleri tarih değerini tek bir tıklama ile silebilmesi için sağ köşede Delete (X) ikonu görünür.
Format: Tarih biçimlendirmesini Properties panelindeki açılır menüden seçebilirsiniz:
DD/MM/YYYY: Gün/Ay/Yıl (Örneğin, 20/10/2023)
MM/DD/YYYY: Ay/Gün/Yıl (Örneğin, 10/20/2023)
YYYY/MM/DD: Yıl/Ay/Gün (Örneğin, 2023/10/20)
DMY: Günü, ayı ve yılı kısaltmalar veya tam tarihle birlikte sırasıyla gösterir. (Örneğin, "20 Ekim 2023")
Formatlar arasında GG/AA/YYYY veya AA/GG/YYYY gibi ihtiyacınıza uygun seçenekler kullanılabilir.
Disable Before Date: Belirli bir tarihten önceki tarihlerin seçilmesini önler. Statik bir tarih girebilir veya dinamik değerler kullanabilirsiniz. Örneğin, bir ürün teslimi için yalnızca ileri tarihler seçilebilir.
Disabled Days: Belirli günlerin seçim için devre dışı bırakılmasını sağlar. Örneğin, geçmiş tarihleri veya tatil günlerini seçilemez hale getirebilirsiniz. (Bu özellik yalnızca web uygulamalarda kullanılabilir.)
Return Display Value (Web only): Kullanıcının seçtiği tarih değerinin, formatlı şekilde (ekranda göründüğü haliyle) mi yoksa ham değer olarak mı döndürüleceğini belirler. Mobilde kullanılamaz.
2.2. Elemente Eklenebilen Aksiyonlar
Date elementi kullanıcı etkileşimleriyle çalışan bir input alanıdır ve yalnızca onChange tetikleyicisini destekler. Kullanıcı tarih seçtiğinde, değiştirdiğinde veya alanı temizlediğinde bu event çalışır. Aksiyon eklemek için Date elementini seçtikten sonra sağ paneldeki ADD ACTION → onChange tetikleyicisi kullanılır.
Aşağıda Date elementi için desteklenen event ve kullanım senaryoları yer almaktadır:
onChange
Kullanıcı tarih alanında bir değişiklik yaptığında tetiklenen aksiyondur. Aşağıdaki tüm durumlarda çalışır:
Yeni bir tarih seçildiğinde
Seçilen tarih değiştirildiğinde
AllowClear aktifleştirildiyse tarih temizlendiğinde
Kullanım Senaryoları:
Formdaki diğer alanları seçilen tarihe göre doldurmak. Ör: Seçilen başlangıç tarihine göre bitiş tarihini otomatik ayarlamak
Tarihe bağlı filtreleme yapmak. Ör: Bir listeyi seçilen tarihe göre yeniden yüklemek
API çağrısı yapmak. Ör: Seçilen tarihteki müsait randevuları getirmek
Validasyon tetiklemek. Ör: Kullanıcının geçmiş tarih seçmesini engellemek
Hesaplama işlemleri başlatmak. Ör: “Başlangıç Tarihi – Bitiş Tarihi” gün farkını hesaplamak
3. Date Elementi Nasıl Kullanılır?
Bu bölümde Date elementinin uçtan uca kullanımını örnek senaryolar üzerinden ele alacağız.
Senaryo: Hatırlatıcı Oluşturma
Bir hatırlatma veya günlük not uygulamasında kullanıcılar, belirli bir tarihe ait kısa bir açıklama kaydetmek ister. Date elementi, bu senaryoda notun hangi güne ait olduğunu seçmek için kullanılır.
Senaryoda:
Kullanıcı, tarih bazlı kayıtlarını tek ekranda kolayca takip eder.
Date elementi sayesinde zaman bilgisi net ve hatasız şekilde alınır.
Basit form + liste yapısıyla, tek sayfa üzerinde giriş ve görüntüleme işlemleri tamamlanır.
Adım 1 - Veri Kaynağı Oluşturma
DataSources modülünde tablo oluşturma:
Datasources modülüne gidin.
Ardından Tables sekmesine gidin.
“
Önemli Alan adları:
NoteText: Kullanıcının girdiği not veya kısa açıklama bilgisini tutar. Liste veya tablo yapısında, kaydın içeriğini kullanıcıya okunabilir şekilde gösterir.
NoteDate: Nota ait tarih bilgisini ifade eder. Date elementi üzerinden seçilen bu alan, kaydın hangi güne ait olduğunu belirtir ve tarih bazlı takip yapılmasını sağlar.
” adında yeni tablo oluşturun.
Kurulması gereken tablo yapısı aşağıdaki gibidir:
Önemli Alan adları:
NoteText: Kullanıcının girdiği not veya kısa açıklama bilgisini tutar. Liste veya tablo yapısında, kaydın içeriğini kullanıcıya okunabilir şekilde gösterir.
NoteDate: Nota ait tarih bilgisini ifade eder. Date elementi üzerinden seçilen bu alan, kaydın hangi güne ait olduğunu belirtir ve tarih bazlı takip yapılmasını sağlar.
Önemli Alan adları:
NoteText: Kullanıcının girdiği not veya kısa açıklama bilgisini tutar. Liste veya tablo yapısında, kaydın içeriğini kullanıcıya okunabilir şekilde gösterir.
NoteDate: Nota ait tarih bilgisini ifade eder. Date elementi üzerinden seçilen bu alan, kaydın hangi güne ait olduğunu belirtir ve tarih bazlı takip yapılmasını sağlar.
Adım 2 - Gerekli Aksiyonları Tanımlama
Arayüzde verileri göstermek ve kaydetmek için:
Bu senaryoda üç aksiyon kullanılacaktır. Kayıt işlemleri için Kuika tarafından sunulan Save Record hazır sistem aksiyonu kullanılır.
Veri listeleme işlemi, ön tanımlı SQL sorguları ile oluşturulan özel bir aksiyon üzerinden gerçekleştirilir.
Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.
Örnek Verileri Listeleyen Aksiyon (GetNotes): Select aksiyonu, SQL Action bölümünde sol panelde yer alan NoteDateRecords tablosu altında hazır olarak sunulur. Add Select Query seçeneğine tıklandığında sorgu otomatik oluşturulur. Oluşturulan aksiyonu GetNotes olarak adlandırın ve kaydedin.
Table Column içerisine Elements > Date and Time Input > Date elementini sürükleyip bırakın.
Adım 5 - Element Ayarlarının Yapılandırılması
Sayfaya eklenen initial aksiyonun elementlere bağlantısı ve kayıt aksiyonun eklenmesi:
Button elementine tıklayın. Button > Add Action > onClick > ManagedDb > Save Record aksiyonuna tıklayın.
Save Record NoteDate parametresini Components > Date1 > value olarak tanımlayın.
NoteText parametresini Components > TextInput1 > value olarak ayarlayın.
Id alanına Default > New Guid tanımlamasını yapın.
Kayıttan sonra listenin güncellenmesi için Button > onClick > Custom > Managed DB > GetNotes aksiyonunu ekleyin.
Table elementi içerisindeki Label elementine tıklayın. Label > Properties > Value > Field to display> NoteText olarak tanımlayın.
Date elementine tıklayın. Date > Properties > Value > Field to display > NoteDate olarak tanımlayın.
Tablodaki hatırlatma zamanının sadece okunabilir olması için DateTime > Properties > Editability > Disabled olarak ayarlayın.
Preview:
Uygulama test edildiğinde, kullanıcı Text Input alanına hatırlatma açıklamasını ve Date alanına hatırlatma tarihini girerek kaydı oluşturur.
Kaydedilen hatırlatma, tek sayfa üzerinde yer alan tabloda listelenir. Daha önce eklenmiş hatırlatmalar da aynı tablo içerisinde görüntülenerek geçmiş kayıtların kolayca takip edilmesi sağlanır.
4. Ortak Özellikler (Properties)
Date 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:
Tarih formatını tutarlı kullanın. Backend, veritabanı ve diğer UI elementleriyle uyumlu bir format seçin (örn. YYYY-MM-DD). Farklı formatlar validasyon hatalarına yol açabilir.
Disable Before Date ile hatalı seçimleri önceden engelleyin. Formda geçmiş tarihler geçerli değilse, kullanıcıyı uyarı vermek yerine seçimi en baştan kısıtlamak en iyi pratiktir.
Placeholder metinleri anlamlı seçin. Kullanıcıya hangi formatta tarih beklendiğini hissettiren kısa bir metin seçim hatalarını azaltır (Örn. “Teslimat Tarihini Seçin”).
Validasyonları onChange ile tetikleyin. Tarih değiştiği anda formun diğer alanlarını güncellemek veya kullanıcıyı yönlendirmek daha akıcı bir deneyim sağlar.
Dinamik tarih kısıtları kullanın.
6. Kısıtlamalar
Disabled Days özelliği yalnızca web tarafında desteklenir. Mobil uygulamalarda belirli günleri devre dışı bırakma özelliği çalışmaz.
Zaman verisi içermez. Date elementi yalnızca günü seçer; saat bilgisi gerekiyorsa DateTime veya DateTimeRange kullanılmalıdır.
