1. Calendar Elementine Genel Bakış

Calendar elementi, kullanıcıların uygulama içinde bir tarih veya tarih aralığı seçmesini sağlayan temel bir tarih seçici elementtir. Kullanıcı, takvim görünümü üzerinden istediği günü işaretleyerek veri girişi, filtreleme, planlama veya zaman bazlı işlemler gerçekleştirebilir.

Calendar, tek tarih seçimi, çoklu tarih seçimi veya belirli bir dönem için aralık belirleme gibi farklı kullanım senaryoları sunar. Özellikle randevu yönetimi, etkinlik planlama, izin takibi veya zaman filtreleme gerektiren tüm uygulamalarda kritik bir rol oynar.

Calendar’ın sunduğu görsel takvim yapısı sayesinde kullanıcılar tarih bilgilerini hızlı ve hatasız şekilde seçebilir, süreçler daha akıcı hale gelir.

Calendar elementi yalnızca web uygulamalarında desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Tek tarih seçimi gereken durumlar. Örneğin: teslimat günü seçimi, ödeme tarihi, randevu günü.
• Tarih aralığı (date range) seçimi gereken senaryolar. Örneğin: izin başlangıç–bitiş tarihleri, raporlama dönemi seçimi, rezervasyon tarihleri.
• Çoklu tarih seçimi. Kullanıcının birden fazla günü işaretlemesi gereken durumlar (ör. çalışma günleri, etkinlik günleri).
• Liste veya tablo filtreleme için tarih bazlı seçim. Siparişler, log kayıtları, faaliyet listeleri gibi verileri belirli bir tarihe göre süzmek.
• Planlama ve takvimleme uygulamaları. Proje takvimleri, sprint planları, etkinlik planlama ekranları.
• Randevu yönetimi. Doktor randevuları, servis talep tarihleri, eğitim planlamaları.
• Dönem bazlı ayarlar veya zaman-periyot seçimleri. Örneğin kullanıcı bir faturanın geçerli olduğu ayı seçebilir.
• Takvim görünümünde belirli günlerin işaretlenmesi. Uyarılar, tatiller, özel günler gibi bilgilerin takvim üzerinde vurgulanması.

2. Temel Özellikler

• Tek tarih seçimi desteği. Kullanıcı takvimden yalnızca bir gün seçebilir. 
• Tarih aralığı (date range) seçimi. Kullanıcı başlangıç ve bitiş tarihi belirleyebilir. Raporlama, izin ve rezervasyon süreçlerinde yaygın kullanılır.
• Çoklu tarih seçimi. Birden fazla günün işaretlenmesini sağlar. Etkinlik günleri, çalışma takvimi veya özel tarihler için uygundur.
• Görsel takvim yapısı sayesinde kolay kullanım. Gün, hafta ve ay görünümüyle kullanıcı dostu bir tarih deneyimi sunar.
• Doğrudan veri bağlama desteği. Seçilen tarih veya tarih aralığı diğer aksiyonlara veya elementlere parametre olarak gönderilebilir.

2.1. Element Ayarları (Properties)

Calendar elementini seçtiğinizde sağ taraftaki Properties panelinde, takvimde görüntülenecek etkinliklerin yapılandırılması için gerekli tüm ayarları yapabilirsiniz. Aşağıda her bir özellik detaylı şekilde açıklanmıştır:

• Options: Takvimde görüntülenecek etkinliklerin hangi kolonlardan geleceğini belirleyen alandır. Event Title, Start Date, End Date gibi parametreler bu bölümde yer alan alanlardan beslenir. Options içeriği, seçilen aksiyon veya veri kaynağına göre otomatik şekillenir.‍
• Action: Calendar üzerinde görüntülenecek etkinlik listesini getiren aksiyondur. İlk yüklemede veya kullanıcı etkileşimlerinde çalışacak aksiyon burada tanımlanır. Örnek: Initial Action → Managed DB → GetCalendarEvents‍
• Event Id Field: Takvimde gösterilecek her etkinliği benzersiz şekilde tanımlar. Güncelleme, silme veya seçim işlemlerinin doğru çalışması için zorunludur.‍
• Event Title: Takvimde kullanıcıya gösterilecek etkinlik adıdır. Event kartında görünen başlık doğrudan bu alandan gelir.‍
• Start Date: Etkinliğin takvim üzerinde hangi gün ve saatte başlayacağını belirler. datetime formatında olmalıdır.‍
• End Date: Etkinliğin bitiş zamanını belirtir. Başlangıç tarihinden önce olamaz.‍
• Event Color Hex: Etkinliklerin takvim üzerinde hangi arka plan rengi ile gösterileceğini belirler. Hex renk formatı kullanılır (Örn. #28a745, #ffcc00).‍
• Calendar Start / Calendar End: Takvimde gösterilecek tarih aralığını tanımlar.‍
• Calendar Start: Görünümün ilk günü‍
• Calendar End: Görünümün son günü Örnek: 2025-01-01 → 2025-01-31‍
  

• Display Event Time: Etkinliklerin saat bilgilerinin gösterilip gösterilmeyeceğini belirler.
  
  • Açık ise: 09:00 – 11:00 gibi saat bilgileri görünür.
  • Kapalı ise yalnızca tarih bazlı görünür.
• Panel: Takvimin görünüm modunu belirler:
  
  • Day (Günlük)
  • Week (Haftalık)
  • Month (Aylık)

2.2. Calendar Elementine Veri Kaynağı Bağlama

Calendar’da etkinliklerin listelenmesi için veri kaynağının bağlanması gerekir. Aşağıdaki adımları izleyebilirsiniz:

1. Calendar elementini seçin.
2. Properties paneline gidin → +ADD ACTION → OnClick (veya Initial Action) → Managed DB → GetCalendarEvents
   
   • Bu aksiyon, takvimde gösterilecek verileri getirir.
3. Options bölümündeki alanları aksiyondan dönen kolonlar ile eşleştirin:
   
   • Event Id Field
   • Event Title
   • Start Date
   • End Date
   • Event Color Hex

Calendar Datasource ile de kullanılabilir; REST API veya Managed DB üzerinden veri çekilebilir.

2.3. Calendar Elementine Event Ekleme

Aşağıdaki adımlarla Calendar’a etkinlik ekleyebilirsiniz:

2.3.1. Veri tablosu oluşturma

• Datasources modülüne gidin.
• Yeni bir tablo oluşturun (Örn. CalendarEvents).
• Aşağıdaki alanları ekleyin:
  
  • id
  • title
  • startDate
  • endDate
  • colorHex

2.3.2. Sayfa yüklenirken veriyi çekme

Page Init üzerinde SELECT sorgusu çalıştırılır:

‍

 SELECT id, title, startDate, endDate, colorHex FROM CalendarEvents

2.3.3. Calendar Properties ayarlarını doldurma

Calendar elementini seçerek aşağıdaki alanları tablo kolonlarıyla eşleştirin:

• Event ID Field → id
• Event Title → title
• Start Date → startDate
• End Date → endDate
• Event Color Hex → colorHex
• Action → GetCalendarEvents

2.4 Elemente Eklenebilen Aksiyonlar

Calendar elementi, kullanıcı etkileşimlerine göre çalışacak aksiyonlar eklemenize olanak tanır. Calendar’ı seçtikten sonra sağ paneldeki ADD ACTION üzerinden aşağıdaki tetikleyiciler kullanılabilir:

onClickDay: Kullanıcı takvimde belirli bir güne tıkladığında tetiklenir. Bu tetikleyici özellikle tarih bazlı işlemlerde kullanılır.

Kullanım senaryoları:

• Yeni bir etkinlik oluşturmak
• Seçilen güne göre liste veya tabloyu filtrelemek
• Bir pop-up açarak o güne ait detay ekranını göstermek
• Formda tarih alanını otomatik doldurmak

onClickEvent: Kullanıcı takvim üzerinde bir etkinliğe tıkladığında çalışır. Etkinlik yönetimi için en yaygın kullanılan tetikleyicidir.

Kullanım senaryoları:

• Etkinlik detaylarını görüntülemek
• Etkinliği düzenlemek için modal açmak
• Etkinliği silmek
• Event ID üzerinden başka bir aksiyona yönlendirmek

onPanelChange

Kullanıcı takvim görünümünü değiştirdiğinde (Month → Week → Day), veya ileri–geri navigasyon yaptığında tetiklenir.

Kullanım senaryoları:

• Yeni seçilen tarih aralığına göre veri listesini güncellemek
• Ay değiştiğinde ilgili ayın etkinliklerini yeniden yüklemek
• Görünüm moduna göre farklı aksiyonlar çalıştırmak

Örnek:

• Kullanıcı Ocak ayından Şubat ayına geçtiğinde GET EVENTS aksiyonunu yeniden çalıştırma
• Haftalık görünüme geçildiğinde yalnızca ilgili haftanın etkinliklerini çağırma

3. Calendar Elementi Nasıl Kullanılır? 

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

Senaryo: Takvim Uygulaması Oluşturma

Bir görev, proje veya takım yönetimi uygulamasında, kullanıcıların belirli bir ay içerisindeki toplantılarını, etkinliklerini ve önemli iş akışlarını tek bir ekranda görebilmesi büyük kolaylık sağlar. Calendar elementi, aylık, haftalık ve günlük görünüm seçenekleriyle bu bilgileri düzenli ve anlaşılır şekilde sunar.

Bu senaryoda, kullanıcının kişisel veya takım takvimine ait etkinlikler; tarih, saat ve renk kodlarıyla birlikte bir aylık görünümde gösterilmektedir.

Senaryoda:

• Kullanıcı, Calendar elementi üzerinden araya Navigation tuşları ile aylar arasında geçiş yapabilir.
• Aylık görünümde, her güne ait etkinlikler renk kodları ile işaretlenir:
  
  • Mavi → Toplantı
  • Yeşil → Takım etkinlikleri
  • Sarı → Müşteri ziyaretleri
  • Kırmızı → Resmi tatil veya önemli uyarılar
    
    
• Etkinlikler, saat bilgisi ile birlikte gün kutularının içinde listelenir; kullanıcı ilgili etkinliğe tıklayarak detaylarına ulaşabilir.

• “Month / Week / Day” seçenekleri sayesinde kullanıcı, takvimi ihtiyacına göre geniş veya dar kapsamlı bir zaman görünümüne dönüştürebilir.

Örneğin:

• 15 Aralık → 12:00 Sprint Planning (Mavi)
• 16 Aralık → 17:00 Team Retrospective (Yeşil)
• 19 Aralık → 14:00 Client Meeting (Sarı)
• 22 Aralık → 19:00 Product Demo (Mavi)
• 29–30 Aralık → 09:00 Company Holiday (Kırmızı – tüm gün)

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

DataSources modülünde tablo oluşturma: 

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

• Önemli Alan adları:
  
  • EventTitle: Takvim üzerinde görüntülenecek etkinliğin adını belirtir (ör. “Sprint Planning”, “Client Meeting”).
  • EventDate: Etkinliğin gerçekleşeceği tarih bilgisini içerir.
  • EventTime: Etkinliğin saat bilgisini ifade eder (ör. 12:00, 17:00).
  • EventColor: Etkinlik tipine göre ayırt edici renk bilgisini tutar (mavi: toplantı, yeşil: takım etkinliği, sarı: müşteri görüşmesi, kırmızı: tatil).
  • EventType: Etkinliğin kategorisini belirtir (ör. “Meeting”, “Holiday”, “Demo”, “Retrospective”).

Adım 2 - Gerekli Aksiyonları Tanımlama

Arayüzde verileri göstermek ve veri eklemek için: 

1. İki aksiyon tanımlamanız gerekir.
2. UI Design modülünde Custom Action alanına gidin ve yeni SQL Action Oluştur'a tıklayın.

3. Açılan ekranda tüm etkinlikleri listelemek için CalendarEvents tablosu seçeneklerinden Add Select Query alanını seçin ve aksiyon adını GetCalendarEventsAll olarak tanımlayıp oluşturun.

4. Aynı işlemi tıklanan etkinlik içeriğini getirmek için GetCalendarEvent adında aksiyonu oluşturun.

Adım 3 - Sayfaları Oluşturma

1. UI Design modülünde yan panelden Screens’ı açın.
2. New Screen’e tıklayın ve ‘EtkinlikEkle’, ‘EtkinlikDetay’ adında iki yeni sayfa oluşturun. 

Adım 4 - Etkinlik Ekleme Sayfasının Geliştirilmesi

1. Sol yan paneldeki Pages > Screens alanından EtkinlikEkle sayfasını açın.
2. Sayfayı üst panelden mobil boyut olarak ayarlayın.

3. Sayfaya Add Screen Input butonundan StartDateInput adında DateTimeOffset türünde screen input ekleyin.

4. Sayfaya sol yan panelden Elements > Display > Label elementini sürükleyip bırakın.
5. Label elementine tıklayın Label > Styling > Text > Style > Heading 2 olarak ayarlayın.

6. Label elementinde Label > Properties > Value alanına ‘Etkinlik Oluştur’ yazısını ekleyin.
7. Label elementi altına Elements > Container > VerticalStack elementini sürükleyip bırakın.

8. Vertical Stack elementi içerisine Elements > Text Input > TextInput elementini ekleyin.
9. Text Input elementinde TextInput > Properties > Placeholder alanına ‘Etkinlik Adını Giriniz’ yazısını ekleyin.

10. Text Input elementi altına Elements > Date and Time Input > DateTimeRange elementini ekleyin.
11. DateTimeRange elementinde DateTimeRange > Properties > StartValue alanına ScreenInput > StartDateInput tanımlamasını yapın.

12. DateTimeRange elementi altına Elements > Select Input > SelectBox elementini ekleyin.
13. Select box elementinde SelectBox > Properties > Options > Fixed Option List > Fixed Data alanına aşağıdaki eklemeyi yapın.

İsterseniz Options alanına renkleri SQL aksiyonu ile sağlayabilirsiniz. İlgili senaryoda kolaylık olması için Fixed Data yöntemi kullanılmıştır.

14. Select Box elementi altına Elements > Navigation > Button elementini ekleyin.
15. Button elementinde Button > Properties > Label alanına ‘Oluştur’ yazısını ekleyin.
16. Button elementinden Button > Styling > Fill > Color alanında aşağıdaki rengi seçin.

17. Button elementinde Button > Properties > Icon alanında ‘event_available’ ikonunu seçin.
18. Button içerisine Button > Add Action > onClick > ManagedDb > Save Record hazır aksiyonunu ekleyin.

19. Save Record içerisinde aşağıdaki alanları seçin.

20. Aksiyon içerisindeki alanlara component kategorisi içerisindeki ilgili alanları bağlayın. İlk Alan örneği endDate > Components > DateTimeRange > endValue için aşağıdaki gibidir.

21. EndDate ve StartDate için DateTimeRange, EventTitle için TextInput, EventColorHex için SelectBox component alanlarını tanımlayın.

22. Son örnek Id alanını Id >Default > New Guid olarak tanımlayın.
23. Buttona ikinci bir Button > Add Action > onClick > Navigation > Go Back aksiyonunu ekleyin.

24. Button elementinin yanındaki boşluğa tıklayın.

25. Col alanını seçin Col > Styling > Layout > Align alanında dikeyde ve yatayda ortalamayı seçin.

Adım 5 - Etkinlik Detay Sayfasının Geliştirilmesi

1. Sol panelden Pages alanından EtkinlikEkle sayfasını yanındaki seçenekten klonlayın.
   

1. Klonladığınız sayfanın adını EtkinlikDetay olarak yeniden adlandırın.

3. StartDateInput Screen Input’u CalendarEventId adında aşağıdaki gibi güncelleyin.

4. Sayfaya PageInit aksiyonu ekleyin ve Add Action > Initial Action > Custom > Managed DB > GetCalendarEvent adımlarını izleyin. Ardından, Id alanına ScreenInputs > CalendarEventId değerini bağlayın.

5. Label elementinde Label > Properties > Value alanını ‘Etkinlik Detay’ olarak güncelleyin.
6. Buton elementinin yanındaki boşluğa tıklayın ve yatayda sağa hizlamayı seçin.
7. Buton elementinin yanına Elements > Container > HorizontalStack elementini ekleyin ve Button elementini Horizontal Stack içerisine sürükleyin.

8. Button elementine tıkayın ve ilk seçenek duplicate tuşuna basıp klonlayın.
9. Sol tarafta kalan butona tıklayın Button > Properties > Label alanındaki yazıyı ‘Düzenle’ olarak değiştirin.
10. Ardından Button > Properties > Icon içerisindeki ikonu ‘edit_calendar’ olarak ayarlayın.

11. Button içerisindeki Save Record aksiyonunda id alanını id > Screen Inputs > CalendarEventId olarak güncelleyin.  
12. Oluştur yazan button da Button > Properties > Label alanını ‘Sil’ olarak değiştirin.
13. Ardından Button > Properties > Icon içerisindeki ikonu ‘event_busy’ olarak ayarlayın.
14. Button rengini Button > Styling > Fill > Color alanını kırmızı tonunda ayarlayın.

15. Button içerisine Button > Add Action > onClick > ManagedDb > Delete Record hazır aksiyonunu ekleyin.

16. Delete Record aksiyonu içerisinde aşağıdaki tanımlamaları yapın.

17. Sil butonuna Button > Add Action > onClick > Navigation > Go Back aksiyonunu tanımla.
18. Text Input alınında TextInput > Properties > Value alanına aşağıdaki tanımlamayı yapın.

19. DateTimeRange alanında DateTimeRange > Properties > StartValue alanına aşağıdaki tanımlamayı yapın.

20. Benzer şekilde DateTimeRange > Properties > EndValue alanına Action Result > GetCalendarEvent > First > EndDate tanımlamasını yapın.

Adım 6 - Ana Sayfanın Geliştirilmesi

1. Yan paneldeki Pages tarafından HomePage sayfasına gidin.
2. Sayfa içerisine Add Action > Initial Action > Custom > Managed DB > GetCalendarEventsAll aksiyonunu ekleyin.

3. Boş sayfa içerisine Elements > Display > Label elementini ekleyin.
4. Label içerisinde Label > Styling > Text > Heading 2 olarak ayarlayın.

5. Label altına Elements > Data > Calendar elementini sürükleyip bırakın.
6. Calendar elementinde Calendar > Properties > Options alanını aşağıdaki gibi tanımlayın.
   

7. Calendar elementinde Calendar > Properties > DisplayEventTime seçeneğini açık olarak ayarlayın.

8. Calendar elementinde Calendar > Add Action > onClickDay > Navigation > Navigate aksiyonunu ekleyin.
9. Navigate içerisinde To Screen > EtkinlikEkle, Screen Inputs > Current > currentDate ve Open As > Drawer olacak şekilde tanımlayın. 

10. Son olarak Calendar elementinde Calendar > Add Action > onClickEvent > Navigation > Navigate aksiyonunu ekleyin.
11. Navigate içerisinde To Screen > EtkinlikDetay, Screen Inputs > Current > currentEvent > id  ve Open As > Drawer olacak şekilde tanımlayın. 

Preview:

Uygulama test edildiğinde, takvim bileşeni tüm etkinlikleri aylık, haftalık ve günlük görünümlerde listeleyerek kullanıcıya kapsamlı bir planlama deneyimi sunar.

Kullanıcı bir güne tıkladığında, sağ tarafta drawer olarak açılan panel üzerinden hızla yeni bir etkinlik oluşturabilir.

Mevcut bir etkinliğe tıklandığında ise etkinliğin detayları yine sağ tarafta drawer içinde görüntülenir; kullanıcı buradan etkinliği düzenleyebilir veya silebilir.

Bu yapı sayesinde etkinlik yönetimi kolay, hızlı ve sezgisel bir şekilde tamamlanabilir.

Aylık Takvim:
Tüm etkinliklerin ay bazında geniş bir görünümle listelendiği takvim yapısıdır. Kullanıcı tüm ayı tek ekranda görüp genel planlamayı kolayca değerlendirebilir.

Günlük Takvim:
Seçilen güne ait etkinlikler detaylı biçimde gösterilir. Gün bazlı planlama ve yoğunluk kontrolü için idealdir.

Haftalık Takvim:

Bir haftalık etkinlikler yatay düzende sunulur. Haftalık çalışma planlarını veya toplantı yoğunluklarını hızlıca analiz etmeyi sağlar.

Yeni etkinlik oluşturma:
Kullanıcı herhangi bir takvim gününe tıkladığında sağ tarafta açılan drawer paneli üzerinden etkinlik adı, tarih ve diğer bilgileri girerek kolayca yeni etkinlik ekleyebilir.

Mevcut Etkinliği Düzenleme veya Silme:

Takvimde yer alan bir etkinliğe tıklandığında drawer paneli açılır ve kullanıcı etkinliği düzenleyebilir veya tek tıkla silebilir.

4. Ortak Özellikler (Properties)

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

• Tarih alanlarını her zaman datetime formatında tutun. Yanlış veri tipleri (string, int vb.) etkinliklerin takvimde görüntülenmemesine neden olabilir.
• Etkinlik renklerini anlamlı şekilde kategorize edin. Farklı etkinlik türleri (toplantı, görev, izin, randevu) için kontrast renkler kullanmak kullanıcı deneyimini güçlendirir.
• Çok yoğun takvimlerde haftalık görünümü tercih edin. Weekly View, etkinliklerin daha okunabilir şekilde sunulmasını sağlar.
• PanelChange tetikleyicisini verimli kullanın. Ay, hafta veya gün değişiminde gereksiz aksiyon çağırmayın. Yalnızca ilgili tarih aralığı için veri çekmek performansı artırır.
• Start Date ve End Date sürelerini doğru sıralayın. End Date < Start Date olduğunda etkinlik görünmez veya hatalı yerleşebilir.

6. Kısıtlamalar

• Calendar elementi yalnızca web uygulamalarında desteklenir. Mobil uygulamalarda Calendar elementinin çalışma desteği bulunmamaktadır.
• Veri kaynağı tanımlanmadan etkinlikler görüntülenmez. Options bölümünde bir aksiyon veya datasource bağlı değilse takvim boş görünür.
• Tarih formatı hataları etkinliklerin görünmesini engelleyebilir. Özellikle REST API veya Managed DB üzerinden gelen tarihlerin yyyy-MM-dd veya datetime formatında olması gerekir.
• Event Color Hex yalnızca HEX formatını destekler. RGB veya renk adları desteklenmez.
• onClickEvent yalnızca etkinliğe tıklandığında tetiklenir; gün boş ise çalışmaz. Gün üzerinde boş alana tıklama için onClickDay kullanılmalıdır.
• onPanelChange tetikleyicisi, her yön değişiminde aksiyonu tekrar çalıştırır. Gereksiz veri yüklemelerini önlemek için ek kontrol eklenmelidir.