1. Progress Bar Elementine Genel Bakış

Progress Bar elementi, bir işlemin, görevin veya sürecin ne kadarının tamamlandığını kullanıcıya görsel olarak aktarmak için kullanılan temel arayüz elementidir. Yükleme adımları, form tamamlama süreçleri, işlem ilerlemeleri veya adım bazlı görevlerde kullanıcıya anlık geri bildirim verir. Hem doğrusal hem de yüzdesel ilerleme göstergeleriyle süreçlerin anlaşılır şekilde takip edilmesini sağlar.

Progress Bar elementi hem web hem de mobil uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Görev tamamlama durumlarını göstermek (ör. bir formun yüzde kaçının doldurulduğu, bir görevin tamamlanma oranı)
• Yükleme veya işlem sürecini görselleştirmek (ör. dosya yükleme, veri işleme, senkronizasyon işlemleri)
• Adım bazlı süreçlerin ilerlemesini izlemek (ör. kayıt akışı, çok aşamalı formlar, onboarding süreçleri)
• Performans ve süreç takibi yapmak (ör. günlük hedef tamamlama oranı, çalışma ilerleme seviyesi)
• Dashboardlarda özet KPI göstergeleri oluşturmak (ör. hedefe ulaşma yüzdesi)
• Zaman alan işlemler sırasında kullanıcıyı bilgilendirmek (ör. rapor oluşturulması, batch işlemleri)

2. Temel Özellikler

• İlerleme durumunu yüzde bazlı gösterebilme. Progress Bar, bir sürecin ne kadarının tamamlandığını net ve anlaşılır bir yüzde değeriyle temsil eder.
• Statik veya dinamik veri ile çalışabilme. Yüzde değeri manuel olarak verilebildiği gibi SQL, REST API veya Managed DB aksiyonlarından dinamik olarak da alınabilir.
• Renk ve stil özelleştirmeleri. Arka plan rengi, dolgu rengi, yükseklik, köşe yuvarlama gibi görsel ayarlar kolayca yapılabilir.
• Animasyonlu ilerleme desteği. Yüzde değeri değiştiğinde çubuğun yumuşak geçişlerle ilerlemesi kullanıcı deneyimini artırır.
• Birden fazla Progress Bar elementini aynı sayfada kullanabilme. Farklı süreçlerin ilerleme seviyeleri aynı ekranda karşılaştırılabilir.
• Tamamlanma yüzdesine göre görünüm değiştirme. Örneğin: %100 olduğunda rengin yeşile dönmesi gibi koşullu stiller kullanılabilir (Styling Panel üzerinden).

2.1. Element Ayarları (Properties)

Progress Bar elementini seçtiğinizde, sağ tarafta yer alan Properties paneli üzerinden ilerleme yüzdesi, renk geçişleri, boyutlandırma ve yönlendirme ayarlarını detaylı biçimde yapılandırabilirsiniz. Aşağıdaki tüm ayarlar madde madde açıklanmıştır:

İlerleme Ayarları

• Percent: Progress Bar’ın doluluk oranını yüzde cinsinden belirler. Değer 0 ile 100 arasında olmalıdır. Yüzde arttıkça Progress Bar’ın dolu kısmı genişler.

Renk ve Stil Ayarları (Gradient Colors)

• First Gradient Color: Progress Bar’ın başlangıç (sol veya üst) kısmında kullanılacak rengidir.
• Second Gradient Color: İlk ve son renk arasında yumuşak bir renk geçişi sağlar. Üç renkli bir gradient oluşturmak için isteğe bağlı olarak kullanılabilir.
• Third Gradient Color: Progress Bar’ın bitiş (sağ veya alt) kısmında kullanılacak rengidir. Tasarım ihtiyaçlarına göre sadece iki veya üç renk birlikte kullanılabilir.

Boyut ve Yerleşim Ayarları

• Size: Progress Bar’ın genişlik ve yükseklik değerlerini belirler. İnce, kalın veya tam genişlikte progress bar tasarımları bu ayarla oluşturulabilir.

Yüzde Gösterim Ayarları

• Hide Percentage: İlerleme yüzdesinin kullanıcıya gösterilip gösterilmeyeceğini belirler.
  
  • Açık: Yüzde değeri gizlenir.
  • Kapalı: Yüzde değeri Progress Bar üzerinde veya yanında görüntülenir.
    
    
• Percentage Direction: Yüzde değerinin hangi yönde ilerleyeceğini belirler. Kullanım örnekleri:
  
  
  • Sol → Sağ
  • Sağ → Sol
  • Bu ayar özellikle ters animasyon veya RTL (sağdan sola) tasarımlarda kullanılır.

İlerleme Yönü Ayarı

• Direction: Progress Bar’ın genel ilerleme yönünü belirler.
  Desteklenen yön tipleri:
  
  • Horizontal (Yatay): Sol–sağ veya sağ–sol ilerleme
  • Vertical (Dikey): Aşağı–yukarı veya yukarı–aşağı ilerleme
  • Bu ayar dikey progress bar gerektiren durumlarda kullanılır.

2.2. Elemente Eklenebilen Aksiyonlar

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

Aksiyon yapısına dair önemli noktalar:

• Progress Bar üzerinde tıklama, hover veya sürükleme ile aksiyon tetiklemesi yapılamaz.
• İlerleme yüzdesinin (Percent) güncellenmesi, Progress Bar ile ilişkili veri kaynağını tetikleyen harici bir UI elementine (Button, Dropdown, Action Trigger vb.) aksiyon atanarak yapılır.
• Progress Bar yalnızca bir değeri görsel olarak temsil eder, kendiliğinden işlem başlatmaz.
• Eğer ilerleme dinamik olarak güncellenecekse, bu güncelleme mutlaka bağlı aksiyon üzerinden gerçekleştirilmelidir.

Progress Bar üzerinde aksiyon tanımlanamaz; tüm süreç yönetimi, yüzde değeri güncelleyen dış UI elementleri tarafından tetiklenir.

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

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

Senaryo: Aylık Hedef Tamamlama Oranının Gösterimi

Bir mobil uygulamada veya yönetim panelinde, belirli bir hedefin ne kadarının tamamlandığını kullanıcıya hızlı ve görsel olarak göstermek için Progress Bar kullanılır.

Senaryoda:

• Aylık satış hedefi
• Gerçekleşen satış tutarı

değerleri kullanılarak tamamlanma yüzdesi hesaplanır ve Progress Bar üzerinde görsel bir ilerleme göstergesi olarak sunulur.

Örneğin (Aylık Satış Dağılımı Verileri):

• Aylık Satış Hedefi → 120.000 ₺
• Gerçekleşen Satış → 98.000 ₺
• Tamamlama Oranı → %81,67

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

DataSources modülünde tablo oluşturma: 

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

• Önemli Alan adları:
  
  • PeriodLabel: Verinin ait olduğu dönemi (ay veya yıl–ay formatında) ifade eder. Progress Bar üzerinde hangi dönemin hedef gerçekleşmesinin gösterildiğini belirtir ve kullanıcıya zaman bilgisini sunar.
  • MonthlyTarget: İlgili dönem için belirlenmiş toplam satış hedefini ifade eder. Progress Bar’ın maksimum değerini temsil eder ve hedefin ne kadarının tamamlandığını hesaplamak için temel referanstır.
  • CurrentSales: Belirlenen satış hedefi içinde o ana kadar gerçekleşmiş toplam satış tutarını gösterir. Progress Bar’ın doluluk oranını belirleyen temel 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 SalesTargets (Id, PeriodLabel, MonthlyTarget, CurrentSales)
VALUES
(NEWID(), '2025-01', 100000.00, 72500.00),   -- %72,5 tamamlanma
(NEWID(), '2025-02', 120000.00, 98000.00),   -- %81,7 tamamlanma
(NEWID(), '2025-03', 150000.00, 45000.00);   -- %30 tamamlanma

Uygularken SalesTargets kısmını silip tekrar SalesTargets 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 (GetSalesTargets):

SELECT 
    PeriodLabel,
    MonthlyTarget,
    CurrentSales,
    CAST((CurrentSales / MonthlyTarget) * 100 AS DECIMAL(5,2)) AS CompletionRate
FROM SalesTargets
WHERE PeriodLabel = @SelectedPeriod;

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

• Periyodları Sağlayan Aksiyon (GetSalesTargetsPeriod):

SELECT Id, PeriodLabel FROM SalesTargets;

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

• UI Design modülünü açın.
• Sayfaya ADD ACTION butonundan Initial Actions > Custom > Managed Db > GetSalesTargetsPeriod aksiyonunu ekleyin. 
• İkinci aksiyon olarak ADD ACTION butonundan Initial Actions > Custom > Managed Db > GetSalesTargets aksiyonunu ekleyin.  
• GetSalesTargets > SelectedPeriod 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 “Aylık Satış Hedefleri’ olarak tanımlayın.
• Label > Styling > Layout > Align alanında dikey ve yatay olarak ortalayın.

• Panel elementinin boyutunu  Panel > Styling > Layout > Width ve Height (250,300) 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.

• 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 > ProgressBar elementini ekleyin.

• Renk geçişi için ProgressBar > FirstGradientColor > Kırmızı (E13C39) tanımlamasını yapın.

• İkinci renk için benzer şekilde ProgressBar > SecondGradientColor > Yeşil (72C240) tanımlamasını yapın.

•  Vertical Stack içerisine Progress Bar ‘ı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ı

• Yüzdelik bilgisini ProgressBar > Properties > Percent > Action Result > GetSalesTargets > First > CompletionRate değerini ekleyin. 

• Başlangıç değeri için SelectBox > Properties > Value alanında aşağıdaki tanımlamayı yapın.

• Benzer şekilde ön değeri gösterebilmek için SelectBox > Properties > Placeholder alanına önceki adımdaki gibi PeriodLabel aksiyon sonucunu tanımlayın.
• Seçenekleri listelemek için SelectBox > Properties > Options alanına aşağıdaki tanımlamayı yapın.

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

• Select Box seçim bilgilerinin getirilmesi için SelectBox > onChange > GetSalesTargets > Components > SelectBox > value > PeriodLabel tanımlamasını yapın.

• İlk sütundaki ilk Label içerisinde  Label > Properties > Value  ‘Aylık Hedef’ olarak tanımlayın.
• İkinci sütun ilk Label içerisine Label > Properties > Value alanına aşağıdaki aksiyon sonucunu bağlayın.

• İkinci sütundaki ilk Label içerisinde  Label > Properties > Value  ‘Mevcut Tutar’ olarak tanımlayın.
• İ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 döneme ait satış hedefi ve gerçekleşen satış tutarının Progress Bar üzerinde doğru oranda yansıtıldığı görülür. Select Box aracılığıyla görüntülenecek döneme ait ayı seçebilirsiniz.

‍

4. Ortak Özellikler (Properties)

Progress Bar 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 Bar’ın daha etkili, okunabilir ve kullanıcı dostu olması için aşağıdaki öneriler dikkate alınmalıdır:

• Gradient renk geçişlerini anlamlı ve uyumlu seçin. Özellikle üç renkli gradientlerde renkler birbirine uyumlu olmalıdır.
• Hide Percentage ayarını tasarıma göre kullanın. Karmaşık UI tasarımlarında yüzdeleri gizlemek sade bir görünüm sağlar.
• Progress Bar’ın kalınlığını (Size → height) sürecin önemine göre belirleyin. Önemli süreçlerde daha kalın, arka planda kalan süreçlerde ince bar tercih edilebilir.
• Yüzdeyi yalnız göstermeyin; gerekiyorsa açıklayıcı metin ekleyin. Örneğin: “Yükleniyor… %40” gibi.
• Yavaş ilerleyen süreçlerde kullanıcıyı yönlendirmek için mikro metin ekleyin.
  Örnek: “Lütfen bekleyin, rapor hazırlanıyor.”

6. Kısıtlamalar

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

• Kullanıcı etkileşimi ile aksiyon tetiklenemez. Progress Bar yalnızca bir görselleştirme aracıdır.
• Datasource bağlanmadığı sürece dinamik ilerleme mümkün değildir. Percent değeri yalnızca manuel olarak veya bir aksiyonla güncellenebilir.
• Progress Bar tek bir metriği göstermek için uygundur; birden fazla ilerleme değerini gösteremez.