1. Progress Circle Elementine Genel Bakış

Progress Circle elementi, ilerleme durumlarını dairesel bir gösterimle sunmanızı sağlayan görsel bir bileşendir. Yüzdelik ilerlemeyi çember üzerinde tamamlanma payı şeklinde göstererek kullanıcıya net bir ilerleme algısı oluşturur. Görev tamamlama yüzdesi, proje ilerleyişi, performans hedefleri veya yükleme işlemleri gibi süreçlerin daha estetik ve kompakt bir şekilde sunulmasını mümkün kılar. Yuvarlak form faktörü sayesinde hem dashboardlarda hem de mobil ekranlarda minimal ve modern bir görünüm sağlar. 

Progress Circle elementi hem web hem de mobil uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Görev tamamlama yüzdesini göstermek (ör. bir görevin, formun veya sürecin tamamlanma oranı)
• Proje ilerleme durumunu görselleştirmek (ör. sprint ilerlemesi, toplam iş yükünün tamamlanma yüzdesi)
• Yükleme veya işlem süreçlerini dairesel biçimde takip etmek (ör. rapor oluşturma, dosya yükleme işlemleri)
• Performans hedeflerinin ne kadarının gerçekleştiğini göstermek. KPI tabanlı yüzdeler için ideal bir yapı sunar.
• Mobil uygulamalarda minimal yüzdelik göstergeler oluşturmak. Yuvarlak tasarım küçük ekranlarda daha ergonomik bir görünüm sağlar.
• Dashboardlarda kompakt ve modern ilerleme göstergeleri oluşturmak.

2. Temel Özellikler

• Dairesel ilerleme göstergesi: Yüzdelik ilerleme, çember üzerinde tamamlanan ve tamamlanmayan kısımlar ile net şekilde ifade edilir.
• Statik veya dinamik veri desteği: Yüzde değerleri manuel olarak verilebilir veya SQL, REST API, Managed DB gibi aksiyonlardan dinamik olarak alınabilir.
• Tamamen özelleştirilebilir renk yapısı: Çember rengi, ilerleme rengi, arka plan rengi ve gradient geçişleri düzenlenebilir.
• Çember kalınlığı ve boyutlandırma seçenekleri: UI tasarımına uygun olarak daha ince, daha kalın veya farklı çaplarda çemberler oluşturulabilir.
• İlerleme animasyonu desteği: Yüzde değerinin değişmesiyle çemberde yumuşak ve akıcı animasyon gösterilir.
• Yüzde bilgisini çember içinde gösterebilme: Kullanıcı, ilerleme oranını çemberin merkezinde yer alan metin ile doğrudan görebilir.

2.1 Element Ayarları (Properties)

Progress Circle elementini seçtiğinizde, sağ tarafta yer alan Properties paneli üzerinden ilerleme yüzdesi, yönlendirme ve görsel ayarları kolayca yapılandırabilirsiniz. Aşağıdaki tüm alanlar detaylı olarak açıklanmıştır:

İlerleme (Progress) Ayarları

• Percent: Progress Circle’ın ilerleme yüzdesini belirler.
  
  • Sabit bir değer kullanmak isterseniz Fixed Value seçeneği ile doğrudan bir sayı girebilirsiniz.
  • Dinamik bir değer kullanmak isterseniz Symbol Picker üzerinden SQL sorgusu, API yanıtı, kullanıcı girişi veya başka bir UI elementinden gelen değeri bağlayabilirsiniz.
  • Değer aralığı 0–100 arasında olmalıdır.

Yön Ayarı

• Percentage Direction: Yüzde dolumunun çember üzerinde hangi yönde ilerleyeceğini belirler. İki seçenek sunar:
  
  • Left: İlerleme çember üzerinde sol tarafa doğru genişleyerek ilerler.
  • Right: İlerleme çember üzerinde sağ tarafa doğru genişleyerek ilerler. Bu ayar animasyon yönünü ve çember üzerindeki ilerleme akışını kontrol eder.

2.2 Elemente Eklenebilen Aksiyonlar

Progress Circle elementi, görsel bir ilerleme göstergesi olduğu için kullanıcı etkileşimiyle aksiyon tetiklemeyi desteklemez. Bu nedenle element seçildiğinde ADD ACTION butonu görünmez ve Progress Circle’a özel bir tetikleyici eklenemez.

Aksiyonlara dair çalışma prensipleri:

• Progress Circle üzerinde tıklama, hover veya sürükleme ile aksiyon çalıştırılamaz.
• Percent alanının güncellenmesi, Progress Circle’ın bağlı olduğu veri kaynağını tetikleyen başka bir UI elementine aksiyon atanarak yapılır.
• Progress Circle yalnızca veriyi görselleştirir, hiçbir işlem başlatmaz.
• Dinamik ilerleme değerleri, bağlı aksiyonun dışarıdan tetiklenmesiyle yenilenir.

Progress Circle’a aksiyon eklenemez; tüm ilerleme güncellemeleri, harici UI elementlerinin tetiklediği aksiyonlar üzerinden yönetilir.

3. Progress Circle Elementi Nasıl Kullanılır? 

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

Senaryo: Görev Tamamlama Oranının Gösterimi

Bir proje, sprint veya görev listesi içindeki ilerlemenin görsel olarak takip edilebilmesi için Progress Circle kullanılır.

Senaryoda:

• Toplam görev sayısı (TotalTasks)
• Tamamlanan görev sayısı (CompletedTasks)

Bu değerler kullanılarak görev tamamlama oranı hesaplanır ve Progress Circle üzerinde dairesel bir ilerleme göstergesi olarak sunulur. Kullanıcı, Select Box üzerinden bir proje, sprint ya da görev grubu (ContextName) seçtiğinde ilgili kayda ait tamamlama yüzdesi Progress Circle içinde otomatik olarak güncellenir.

Kullanıcı, Select Box üzerinden bir proje, sprint ya da görev grubu (ContextName) seçtiğinde, ilgili kayda ait görev tamamlama yüzdesi Progress Circle içinde güncellenir.

Örneğin (Sprint Bazlı Görev Tamamlama):

• Sprint Adı → “Sprint 1 – Ocak”
• Toplam Görev → 20
• Tamamlanan Görev → 15
• Tamamlama Oranı → %75

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

DataSources modülünde tablo oluşturma: 

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

• Önemli Alan adları:
  
  • ContextName: Tamamlama oranı hesaplanan görev grubunu ifade eder. Bu alan; proje adı, sprint adı veya belirli bir görev setinin başlığı olabilir. Progress Circle üzerinde hangi kapsamın görüntülendiğini kullanıcıya gösterir.
  • TotalTasks: İlgili görev grubunda yer alan toplam görev sayısını belirtir. Tamamlama yüzdesinin hesaplanmasında kullanılan temel referans değeridir.
  • CompletedTasks: Toplam görevler içinde tamamlanmış olanların sayısını ifade eder. Progress Circle'ın ne kadar dolacağını belirleyen ana metriktir.

Adım 2 - Gerekli Aksiyonları Tanımlama

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

• Üç aksiyon tanımlamanız gerekir.
• Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.

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

INSERT INTO TaskCompletionStats (Id, ContextName, TotalTasks, CompletedTasks)
VALUES
(NEWID(), 'Sprint 1 - Ocak',   20, 15),   -- %75
(NEWID(), 'Sprint 2 - Şubat',  25, 10),   -- %40
(NEWID(), 'Proje A - Modül 1', 30, 24);   -- %80

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

• Verileri Sağlayan ve Filtreleyen Aksiyon (GetTaskCompletionStats):
  

SELECT 
    ContextName,
    TotalTasks,
    CompletedTasks,
    CAST((CAST(CompletedTasks AS DECIMAL(10,2)) / TotalTasks) * 100 AS DECIMAL(5,2)) AS CompletionRate
FROM TaskCompletionStats
WHERE ContextName =
    ISNULL(
        NULLIF(@SelectedContext, ''),    -- Null veya boşsa NULL döner
        (SELECT TOP 1 ContextName         -- Eğer NULL ise ilk kaydı al
         FROM dbo.TaskCompletionStats
         ORDER BY ContextName ASC)
    );

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

• İçerik İsimlerini Sağlayan Aksiyon (GetTaskCompletionContextName):

SELECT Id, ContextName  FROM TaskCompletionStats;

‍

Uygularken TaskCompletionStats kısmını silip tekrar TaskCompletionStats 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

1. UI Design modülünü açın.
2. Sayfaya ADD ACTION butonundan Initial Actions > Custom > Managed Db > GetTaskCompletionContextName aksiyonunu ekleyin. 
3. İkinci aksiyon olarak ADD ACTION butonundan Initial Actions > Custom > Managed Db > GetTaskCompletionStats aksiyonunu ekleyin.  
4. GetTaskCompletionStats > SelectedContext parametre alanına Default > Empty tanımlamasını yapın. 

Adım 4 - Element Yerleşimi ve Stil Ayarları

• Sol Panelden Elements > Display > Label elementini ekleyin. 
• Label > Properties > Value değerini “Görev İlerleme Durumu” olarak tanımlayın.
• Label > Styling > Layout > Align alanında dikey ve yatay olarak ortalayın.

• Sol Panelden Elements > Container > Panel elementini ekleyin. 
• Panel elementinin boyutunu  Panel > Styling > Layout > Width ve Height (275,400) px olarak tanımlayın.

• Panel elementinin arka planını Panel > Styling > Fill > White Background olarak ayarlayın.
• Panelin kenarlarını Panel > Styling > Style > Border > Radius > 40 px olarak ayarlayın.
• Yeni Elements > Container > Row  elementini panel elementi içerisine sürükleyip bırakın.

• Row içerisindeki Col alanına Elements > Container > VerticalStack elementini ekleyin.
• Vertical Stack içerisine Elements > Charts > ProgressCircle elementini ekleyin.

•  Vertical Stack içerisine Progress Circle ‘ın bir altına Elements > Select Input > SelectBox elementini ekleyin. 

• Yazılar için Elements > Container > Row elementini Panel içerisine ekleyin ve Row > Properties > Desktop > 2 olarak seçiniz.

•  Her iki Col içerisini Col >Styling > Layout > Align yatayda ve dikeyde ortalayın.
•  Her iki Col içerisine Elements > Display > Label elementini sürükleyip bırakın.
• Oluşturulan Row elemenetini ilk seçenek Duplicate ile kopyalayın.

• Tüm aşamalar sonucunda beklenen sonuç aşağıdaki gibidir.

Adım 5 - Element Ayarlamalarının Yapılandırılması

1. Yüzdelik bilgisini ProgressCircle > Properties > Percent > Action Result > GetTaskCompletionStats > First > CompletionRate değerini ekleyin. 

2. Başlangıç değeri için SelectBox > Properties > Value alanında aşağıdaki tanımlamayı yapın.
   
   
3. Benzer şekilde ön değeri gösterebilmek için SelectBox > Properties > Placeholder alanına önceki adımdaki gibi ContextName aksiyon sonucunu tanımlayın.

4. Seçenekleri listelemek için SelectBox > Properties > Options alanına aşağıdaki tanımlamayı yapın.

5. Select Box seçim bilgilerinin getirilmesi için SelectBox > Add Actions > onChange > Custom > Managed DB > GetTaskCompletionStats tanımlamasını yapın.

6. Select Box seçim bilgilerinin getirilmesi için SelectBox > onChange > GetTaskCompletionStats > Components > SelectBox > value > ContextName tanımlamasını yapın.

7. İlk sütundaki ilk Label içerisinde  Label > Properties > Value  ‘Toplam Görev’ olarak tanımlayın.
8. İkinci Sütun ilk Label içerisine Label > Properties > Value alanına aşağıdaki aksiyon sonucunu bağlayın.

9. İkinci sütundaki ilk Label içerisinde  Label > Properties > Value  ‘Tamamlanan Görev’ olarak tanımlayın.
10. İkinci Sütun ilk Label içerisine Label > Properties > Value alanına aşağıdaki aksiyon sonucunu bağlayın.

Preview:

Uygulama test edildiğinde, seçilen görev grubuna ait toplam görev ve tamamlanan görev bilgilerinin Progress Circle üzerinde doğru tamamlama oranı ile görüntülendiği görülür. Select Box aracılığıyla hangi proje, sprint veya görev grubunun durumunun gösterileceğini seçebilirsiniz.

‍

4. Ortak Özellikler (Properties)

Progress Circle 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)

Progress Circle elementini daha etkili ve okunabilir hale getirmek için aşağıdaki öneriler dikkate alınmalıdır:

• Çember kalınlığını tasarıma göre ayarlayın. Çok ince çemberler mobilde zor görünürken çok kalın çemberler okunabilirliği düşürebilir.
• Yavaş işleyen süreçlerde mutlaka açıklayıcı metin ekleyin.  Örn. “Hazırlanıyor…”, “Yükleniyor…” gibi bilgilendirmeler kullanıcıyı rahatlatır.
• Percentage Direction (Left/Right) seçimini tasarımla uyumlu yapın. Soldan sağa yönlenen çemberler genellikle daha doğal bir algı yaratır.
• Birden fazla Progress Circle kullanılıyorsa boyutları birbiriyle tutarlı olmalıdır.

6. Kısıtlamalar

Progress Circle elementini kullanırken aşağıdaki sınırlamalar göz önünde bulundurulmalıdır:

• Kullanıcı etkileşimi ile aksiyon tetiklenemez. İlerleme çemberi yalnızca bir gösterimdir.
• Datasource tanımlanmadan dinamik ilerleme mümkün değildir. Percent alanı manuel veya aksiyonla sağlanmalıdır.
• Progress Circle tek bir ilerleme değerini gösterir; çoklu veri serileri için uygun değildir.