Rate

Kullanıcının yıldızlara tıklayarak puan vermesini sağlayan nesnedir. Memnuniyet, kalite ya da öncelik gibi değerlerin sayısal bir puanla toplanması için kullanılır.

Değer tipi: decimal?

Ne zaman kullanılır?

Bir konunun puanlanması gereken yerlerde idealdir: anket memnuniyeti, ürün değerlendirmesi, önceliklendirme. Kullanıcıya hazır seçenekler arasından seçim yaptırmak istiyorsanız ComboBox, evet/hayır gibi tek bir tercih için CheckBox daha uygundur.

Tasarımcı özellikleri

Bir Rate seçildiğinde Özellik Görüntüleyici sekmelere ayrılır.

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. Rate1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanın adı.

Label

Nesnenin yanındaki etiketi yönetir.

Özellik	Açıklama
Caption / Text	Etiketin yazısı (çok dilli olabilir).
Position	Etiketin yeri: solda (Left) veya üstte (Top).
Width / Height	Etiketin boyutu.
Font	Yazı tipi, kalın / italik / altı çizili.
Show Colon	Etiketin sonuna iki nokta (:) ekler.
Horizontal Align / Vertical Align	Etiketin hizası.
Visible	Etiketi gösterir veya gizler.

Data Source

Her yıldızın üzerine gelindiğinde gösterilecek ipuçlarını besler.

Özellik	Açıklama
Items	Yıldızlara karşılık gelen metinlerin listesi (List<String>). Örneğin "Çok kötü", "Kötü", "Orta", "İyi", "Mükemmel".

Behavior

Özellik	Açıklama
Count	Kaç yıldız gösterileceği. Varsayılan genelde 5.
AllowHalf	Yarım yıldız (ör. 3.5) verilmesine izin verir.
AllowClear	Aynı yıldıza tekrar tıklayınca puanın sıfırlanmasına izin verir.
ReadOnly	Alanı salt okunur yapar; puan değiştirilemez.
Required	Alanı zorunlu yapar; puan verilmezse form kaydedilmez.
Tab Index	Tab tuşuyla geçiş sırasını belirler.
Tooltips	Her yıldız için ayrı ipucu metinleri (çok dilli).

Appearance

Özellik	Açıklama
Visible / Client Visible	Nesnenin görünürlüğü.
Enabled / Client Enabled	Nesnenin aktif olup olmadığı.
Title	Nesnenin başlık / ipucu metni (çok dilli).
Placeholder	Alan boşken görünen soluk ipucu yazısı.
Text Align	İçeriğin hizası.

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı yıldıza tıklayınca da ayrı olaylar çalışır. Doğru kodu doğru olaya yazmak için bu sırayı bilmek işinizi kolaylaştırır.

Açılış sırası: OnInit → OnLoad → OnDataLoad → OnPreRender → OnRender

Kullanıcı puan verince: OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. Rate'in iki tarafta sunduğu olaylar farklıdır.

Sunucu olayları (Server)

Olay	Ne zaman çalışır
OnInit	Form açılırken nesne oluşturulduğunda, en başta.
OnLoad	OnInit'in hemen ardından, nesne yüklenince.
OnRender	Nesne ekrana çizilirken.
OnValueChanging	Puan değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı puanı verip değer kesinleştiğinde. En sık kullanılan olaydır.
OnTextChanging / OnTextChanged	Görünen metin değişmeden önce / sonra.
OnValidating	Form kaydedilirken değer doğrulanırken.

İstemci olayları (Client)

Sunucudaki olaylara ek olarak tarayıcı tarafında şunlar da vardır:

Olay	Ne zaman çalışır
OnDataLoad	Nesnenin verisi yüklendiğinde.
OnPreRender	Nesne ekrana çizilmeden hemen önce.
OnClick / OnDoubleClick	Nesneye tıklanınca / çift tıklanınca.
OnPropertyChanging / OnPropertyChanged	Bir özellik kodla değiştirilmeden önce / sonra.

Olay parametreleri

OnValueChanging olayının parametresi (args TS, e C#) şunları taşır:

• newValue / NewValue — verilmek istenen yeni puan
• oldValue / OldValue — önceki puan
• cancel / Cancel — true yapılırsa değişiklik iptal edilir (yalnızca Changing olaylarında)

Changed olaylarında cancel yoktur (değişiklik artık gerçekleşmiştir).

Kod örnekleri

Bir Rate'e üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Değer decimal? tipindedir, yani puan verilmemişse null olabilir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz:

// Oku
decimal? puan = Rate1.Value;

// Yaz
Rate1.Value = 4;

Akış (Flow) kodu (C#, sunucu)

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz:

// Oku
decimal? puan = Document1.Controls["Rate1"].Value;

// Yaz
Document1.Controls["Rate1"].Value = 4;

İstemci kodu (TypeScript, tarayıcı)

İstemci tarafında nesnelere this. ile erişilir ve özellik adı küçük harfle yazılır (value):

this.Rate1.value = 4;

Puan verilmemiş olabilir

Value tipi decimal? olduğu için kullanıcı hiç puan vermediyse değer null gelir. Hesap yapmadan önce if (Rate1.Value != null) ile kontrol edin, yoksa hata alırsınız.

Örnek: düşük puanda uyarı (OnValueChanging)

OnValueChanging puan değişmeden hemen önce çalışır; istemediğiniz bir değeri burada iptal edebilirsiniz. Aşağıdaki örnekte 2'nin altındaki puanlar için kullanıcı uyarılır.

İstemci (TypeScript):

async Rate1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<number>) {
    if (args.newValue < 2) {
        this.showMessage("Uyarı", "Düşük puan verdiniz, lütfen sebebini açıklayın.", "Validation");
    }
}

Sunucu (C#):

void Rate1_OnValueChanging(object sender, PropertyChangingEventArgs<decimal?> e)
{
    if (e.NewValue < 2)
    {
        ShowMessage("Uyarı", "Düşük puan verdiniz, lütfen sebebini açıklayın.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Yarım yıldız puanları (ör. 4.5) toplamak istiyorsanız AllowHalf özelliğini açın; değer tipi zaten decimal? olduğu için ondalık puanı saklayabilir.
• Her yıldızın ne anlama geldiğini kullanıcıya göstermek için Tooltips ya da Items ile metin verin (ör. 1 = "Çok kötü", 5 = "Mükemmel").
• Puanın zorunlu olmasını istiyorsanız Required özelliğini açın; böylece kod ile boş kontrolü yapmanıza gerek kalmaz.

Tüm tasarımcı özellikleri (tam liste)

General: Name, Field Name

Label: Caption, Text, Position, Left, Width, Height, Font (Bold / Italic / Underline), Ellipsis, Visible, Show Colon, Horizontal Align, Vertical Align, Mark Char, Mark Position

Data Source: Items

Behavior: Count, AllowHalf, AllowClear, ReadOnly, Required, Tab Index, Tooltips

Appearance: Visible, Client Visible, Enabled, Client Enabled, Title, Value, Placeholder, Text, Text Align

Olaylar (Client): OnInit, OnLoad, OnPreRender, OnRender, OnPropertyChanging, OnPropertyChanged, OnClick, OnDoubleClick, OnDataLoad, OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating

Olaylar (Server): OnInit, OnLoad, OnRender, OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating