DocumentViewer

Bir dokümanı formun içine gömülü olarak gösteren görsel nesnedir. Kullanıcı, dosyayı indirmeden ya da yeni bir sekme açmadan PDF, Word ya da resim gibi içerikleri doğrudan form üzerinde görebilir.

Bu nesnenin bir değeri yoktur. Veri tutmaz; yalnızca hedef gösterdiğiniz dokümanı ekranda görüntüler. Sınıf zinciri DocumentViewer : VisualControl : BaseControl olduğundan Value / Text üyesi yoktur ve değer/seçim olayları taşımaz.

Ne zaman kullanılır?

Forma bağlı bir belgeyi (sözleşme, fatura, teklif PDF'i, taranmış evrak) kullanıcının önüne doğrudan getirmek istediğinizde idealdir. Kullanıcının dosyayı tek tek açmasına gerek kalmaz, içerik formla birlikte gelir.

Dosya yükleme/seçme için FileSelector, forma bağlı doküman listesi için RelatedDocuments, harici bir web sayfasını gömmek için Iframe daha uygundur.

Tasarımcı özellikleri

Bir DocumentViewer seçildiğinde Özellik Görüntüleyici sekmelere ayrılır. Bu nesnenin görünür bir etiketi (Label) yoktur.

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. DocumentViewer1). Koddan bu adla erişirsiniz.

Behavior

DocumentViewer'ın hangi belgeyi göstereceği üç hedefleme özelliği ile belirlenir. Çoğu senaryoda yalnızca TargetPath yeterlidir; TargetId ve TargetSecretKey ise belgeyi yol yerine kimlik/gizli anahtar ile işaret etmenizi sağlar.

Özellik	Açıklama
TargetPath	Görüntülenecek dokümanın yolu/adresi. En çok kullanılan hedefleme özelliğidir; hangi belgenin gösterileceğini buradan verirsiniz. (String)
TargetId	Belgenin kimlik numarası ile hedeflenmesi. TargetPath'in eşi; doküman yönetiminden gelen bir belgeyi id üzerinden göstermek için kullanılır. (Int64)
TargetSecretKey	Belgeyi gizli anahtar (secret key) üzerinden hedefler. (String)
AllowEdit	Belge üzerinde düzenlemeye (ör. işaretleme) izin verir. (Boolean)
Height	Görüntüleyicinin yüksekliği (piksel). (Int32)
ShowOn	Nesnenin hangi ortamda gösterileceğini belirler (ShowOn enum).

Appearance

Özellik	Açıklama
Visible / Client Visible	Nesnenin görünürlüğü (sunucu / tarayıcı tarafı).
Enabled / Client Enabled	Nesnenin aktif olup olmadığı (sunucu / tarayıcı tarafı).
Loading	Yükleniyor durumunu açıp kapatır; belge hazırlanırken bir yükleniyor göstergesi sunar. (Boolean)
Title	Nesnenin başlığı (MultiLanguageText, çok dilli olabilir).
Caption	Nesnenin başlık/etiket bilgisi (ControlCaption).
Style / Container Style	Nesnenin ve kapsayıcısının stil ayarları (Style).
Custom Class Name	Nesneye özel CSS sınıf adı. (String)

Olaylar

DocumentViewer görsel bir nesnedir; metin ya da değer taşımadığı için kendine ait değer/seçim olayı yoktur. Sınıf üzerinde tanımlı bir EventHandler üyesi bulunmaz: OnValueChanged, OnTextChanged, OnDataLoad gibi olaylar bu nesnede tetiklenmez.

Yalnızca her görsel nesnenin ortak olarak sahip olduğu, VisualControl üzerinden gelen tıklama olayları kullanılabilir. BaseControl kaynaklı OnInit / OnLoad / OnPreRender / OnRender gibi yaşam döngüsü kancaları genel çatı imzalarıdır ve ServerEvents üzerinden bağlanır; bu nesneye özel bir davranış sunmazlar.

İstemci olayları (Client)

Olay	Ne zaman çalışır
OnClick / OnDoubleClick	Nesneye tıklanınca / çift tıklanınca. (VisualControl kaynaklı.)

Yaşam döngüsü olayları

OnInit / OnLoad / OnPreRender / OnRender BaseControl üzerinde tanımlı genel imzalardır; DocumentViewer bunları kendi başına özel bir amaçla tetiklemez. Belgenin görünmesini bir koşula bağlamak istiyorsanız, olayı bu nesneye değil, koşulu tetikleyen başka bir nesneye (ör. bir onay kutusunun OnValueChanged olayına) yazıp oradan DocumentViewer'ı yönetin.

Kod örnekleri

DocumentViewer'ın değeri olmadığı için Value / Text ile okuma yazma yapılmaz. Koddan genellikle hedef belgeyi (SetTarget / TargetPath) ve görünürlük/aktiflik ayarlarını yönetirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz. Belgeyi hedeflemek için ya SetTarget metodunu çağırır ya da TargetPath özelliğini ayarlarsınız:

// Belgeyi hedefle: yol + kimlik birlikte (asıl eylem metodu)
DocumentViewer1.SetTarget("/Belgeler/Sozlesme.pdf", 12345);

// Yalnızca yol vermek yeterliyse
DocumentViewer1.TargetPath = "/Belgeler/Sozlesme.pdf";

// Kimlik ya da gizli anahtar ile hedefleme
DocumentViewer1.TargetId = 12345;
DocumentViewer1.TargetSecretKey = secretKey;

// Görünürlük ve aktiflik
DocumentViewer1.Visible = true;
DocumentViewer1.Enabled = true;

// Belge hazırlanırken yükleniyor göstergesi
DocumentViewer1.ShowLoading();
// ... belge hedeflendikten sonra
DocumentViewer1.HideLoading();

SetTarget(string targetPath, Int64 targetId) nesnenin asıl eylem metodudur; yol ve kimliği tek çağrıda birlikte ayarlar. ShowLoading() / HideLoading() / ToggleLoading(), Loading özelliğini yöneten yardımcı metotlardır.

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Bu genel tutamaç tipli üyeleri (TargetPath, Visible gibi) SetPropertyValue / GetPropertyValue ile yönetir:

// Hedef belgeyi ayarla
Document1.Controls["DocumentViewer1"].SetPropertyValue("TargetPath", "/Belgeler/Sozlesme.pdf");

// Görünürlük
Document1.Controls["DocumentViewer1"].SetPropertyValue("Visible", true);

// Mevcut hedefi oku
string yol = Document1.Controls["DocumentViewer1"].GetPropertyValue<string>("TargetPath");

İstemci kodu (TypeScript, tarayıcı)

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

this.DocumentViewer1.visible = true;
this.DocumentViewer1.enabled = true;

TargetPath nesnenin kalbidir

DocumentViewer'ın ne gösterdiğini hedefleme özellikleri (TargetPath, TargetId, TargetSecretKey) belirler. En pratik yol SetTarget(targetPath, targetId) metodudur. Belge görünmüyorsa önce bu hedefin doğru bir belgeye işaret edip etmediğini kontrol edin. Kullanıcının yalnızca bakmasını istiyorsanız AllowEdit özelliğini kapalı bırakın.

Örnek: koşula göre belgeyi gösterme

Belge yalnızca belirli bir durumda görünsün istiyorsanız, koşulu tetikleyen nesnenin (DocumentViewer'ın kendisinin değil) değer olayında görüntüleyiciyi açıp kapatın. Aşağıdaki istemci örneğinde bir onay kutusu işaretliyken belge görünür, değilse gizlenir.

İstemci (TypeScript):

async OnayKutusu1_OnValueChanged(args: Controls.EventArgs.IPropertyChangedEventArgs<boolean>) {
    this.DocumentViewer1.visible = args.newValue === true;   // İşaretliyse belgeyi göster
}

Örnek: seçilen belgeyi koddan hedefleme

Başka bir nesnede seçilen bir belgeyi DocumentViewer'a yansıtmak için SetTarget kullanın. Aşağıdaki form kodu, hedef belgeyi gösterirken yükleniyor durumunu da yönetir.

Sunucu (C#):

void Belgeyi_Goster(string yol, long id)
{
    DocumentViewer1.ShowLoading();
    DocumentViewer1.SetTarget(yol, id);   // yol + kimlik birlikte
    DocumentViewer1.Visible = true;
    DocumentViewer1.HideLoading();
}

İpuçları

• DocumentViewer veri tutmaz; forma bir dosya yüklemek/seçmek için FileSelector kullanın, sonra o dosyayı görüntülemek için DocumentViewer'ı SetTarget ile hedefleyin.
• Hedef belgeyi koddan tek seferde ayarlamak için SetTarget(targetPath, targetId) en temiz yoldur; yalnızca yol elinizdeyse TargetPath, yalnızca kimlik varsa TargetId kullanın.
• Uzun belgelerde Height özelliğini yeterince büyük tutarak kullanıcının fazla kaydırma yapmasını önleyin.
• Belge yüklenirken kullanıcıya bekleme göstermek için ShowLoading() / HideLoading() (veya Loading özelliği) kullanın.
• Kullanıcının belgeyi yalnızca okumasını istiyorsanız AllowEdit özelliğini kapalı bırakın.

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

General: Name

Behavior: AllowEdit, Height, ShowOn, TargetPath, TargetId, TargetSecretKey

Appearance: Visible, Client Visible, Enabled, Client Enabled, Loading, Title, Caption, Style, Container Style, Custom Class Name, Context Menu Key, Context Menu Column Key, Context Menu Target, Default Enabled, Default Client Enabled, Control Id

Metotlar: SetTarget(targetPath, targetId), Show(), Hide(), ShowLoading(), HideLoading(), ToggleLoading(), ScrollTo(), FireClick()

Olaylar: Bu nesnenin kendine ait değer/metin/veri olayı yoktur. Yalnızca VisualControl kaynaklı OnClick / OnDoubleClick ve BaseControl kaynaklı genel yaşam döngüsü imzaları (OnInit, OnLoad, OnPreRender, OnRender) bulunur.