Document elementi, backend’de kayıtlı bir dokümanı versionId (GUID) üzerinden çağırarak tarayıcı üzerinde görüntülemek veya uygun yetkilere bağlı olarak düzenlemek için kullanılan bir UI elementidir.
Bu element sayesinde kullanıcılar, sisteme kayıtlı dokümanları uygulama dışına çıkmadan görüntüleyebilir veya düzenleyebilir. Belge türüne göre uygun görüntüleyici veya editör otomatik olarak devreye girer ve içerik tarayıcı üzerinde işlenir. Böylece belge yönetimi süreçleri daha merkezi, kontrollü ve kullanıcı dostu hale gelir.
Document elementi; OnlyOffice veya Collabora entegrasyonu üzerinden Office dosyalarını (DOCX, XLSX, PPTX), PDF.js ile PDF dosyalarını, Monaco Editor ile kod dosyalarını, TUI Image Editor ile görselleri ve three.js ile 3D modelleri render edebilir.
Document elementi yalnızca web uygulamalarda desteklenmektedir.
1.1. Sık Kullanım Senaryoları
Document elementi aşağıdaki senaryolarda yaygın olarak kullanılır:
Backend’de kayıtlı bir dokümanı versionId bilgisi ile çağırarak uygulama içerisinde göstermek için kullanılabilir.
PDF, DOCX, XLSX, PPTX dosyaların kullanıcıya uygulama içerisinde sunulması gereken yapılarda tercih edilir.
Kullanıcının bir dokümanı yalnızca görüntülemesi ya da yetkisi varsa düzenlemesi gereken senaryolarda kullanılabilir.
Belge detay ekranlarında, seçilen dokümanın ayrı bir panelde veya sayfada açılması için uygundur.
Document Management System (DMS) yapılarında, doküman içeriklerinin güvenli biçimde tarayıcı üzerinden yönetilmesi için kullanılabilir.
Farklı doküman tiplerinin tek bir yapı üzerinden yönetilmesi gereken uygulamalarda, dosya tipine göre uygun görüntüleyici veya editörün otomatik seçilmesini sağlar.
2. Temel Özellikler
Document elementi, belge görüntüleme ve düzenleme süreçleri için aşağıdaki temel özellikleri sunar:
Tam genişlik ve yükseklikte bir konteyner içinde doküman içeriğini render eder.
Office dokümanları için OnlyOffice veya Collabora editörüne ait toolbar (ribbon) görüntülenir.
PDF dosyaları için sayfa navigasyonu ve zoom kontrolleri sunulur.
Yükleme sırasında ekranın ortasında “Loading...” göstergesi görüntülenir.
Hata durumunda kullanıcıya kırmızı metin ile hata mesajı gösterilir.
versionId verilmediğinde veya tasarım zamanında kesik çizgili bir yer tutucu (placeholder) gösterilir. Bu alanda ortada bir doküman ikonu ve “Document” yazısı yer alır.
Watermark desteği bulunur. Metinsel filigran doküman üzerine dijital olarak bindirilebilir.
2.1. Element Ayarları (Properties)
Document elementini seçtiğinizde, sağ tarafta yer alan Properties paneli üzerinden bu elementin belgeye ait veri bağlantısını ve çalışma davranışını kontrol edebilirsiniz.
Bu elementte kullanılabilen temel özellikler aşağıdaki gibidir:
VersionId: Görüntülenecek veya düzenlenecek dokümanın versiyon kimliğini belirtir. Bu alan zorunludur. Document elementi hangi belge ile çalışacağını bu alan üzerinden belirler. Backend, versionId üzerinden documentId ve dil bilgisini otomatik olarak çözer.
Mode: Dokümanın hangi davranışla açılacağını belirler. Kullanılabilen değerler:
view → standart görüntüleme
readonly → sadece görüntüleme (değişiklik yapılamaz)
edit → düzenleme modu
Mode ayarı, kullanıcı deneyimini ve yetki kontrolünü doğrudan etkiler. Bu nedenle kullanım senaryosuna göre dikkatli yapılandırılmalıdır.
Locale: Arayüz dilini belirler. Özellikle çok dilli uygulamalarda önemlidir. OnlyOffice ve Collabora gibi editörler bu ayarı kullanır. Desteklenen örnek değerler:
tr
en
OfficeEngine: Office dokümanlarının hangi motor ile açılacağını belirler.
Desteklenen değerler:
onlyoffice
collabora
Belirtilmediğinde sistem varsayılan motoru kullanılır.
2.2. Elemente Eklenebilen Event Aksiyonları
Document elementi, kullanıcı etkileşimlerine göre aksiyon çalıştırabilen bir yapıya sahiptir. Element seçildiğinde ADD ACTION butonu üzerinden aşağıdaki Event’lere aksiyon eklenebilir:
OnLoad: Document yüklendiğinde tetiklenir. Belge açılışında yapılması gereken işlemler için kullanılır. Örneğin veri çekme, kontrol çalıştırma veya kullanıcı bilgilendirme.
OnError: Belge yüklenirken veya render edilirken hata oluştuğunda tetiklenir. Hata yönetimi ve kullanıcıya geri bildirim sağlamak için kullanılabilir.
OnTempLoaded: Temp katmanından veri yüklendiğinde tetiklenir. Recovery (kurtarma) senaryolarında kullanılabilir.
2.3. Temp Tabanlı Kaydetme Yapısı
Tüm OnlyOffice ve Collabora kaydetme işlemleri önce Temp tampon katmanına yazılır. Kullanıcı açıkça onaylayana kadar hiçbir değişiklik Draft veya Version’a yansımaz.
Kaydetme akışı aşağıdaki şekilde çalışır:
OnlyOffice üzerinden yapılan Ctrl+S veya otomatik kaydetme işlemleri doğrudan Temp katmanına yazılır. Bu katman yalnızca düzenleme yapan kullanıcı tarafından görülür.
Kullanıcı aksiyonuna göre aşağıdaki işlemler gerçekleştirilebilir:
SaveTemp → Temp verisini günceller (ara kaydetme senaryoları için kullanılır)
PublishTempAsNewVersion → Yeni bir versiyon oluşturur
SaveTempAsDraft → İçeriği taslak olarak kaydeder
DiscardTemp → Temp verisini siler ve değişiklikleri iptal eder
Document elementi mode="edit" ile açıldığında, mevcut bir Temp kaydı varsa otomatik olarak bir kurtarma diyalogu (Recovery Dialog) gösterilir.
Bu diyalog kullanıcıya aşağıdaki seçenekleri sunar:
Kurtarılan içerikle devam et → Temp verisi yüklenir ve düzenleme bu veri üzerinden devam eder
Son yayınlanmış versiyonla başla → Temp verisi silinir ve orijinal versiyon yüklenir
İptal → Düzenleme moduna geçiş iptal edilir
saveMode ayarı kaydetme davranışını belirler.
newVersion → yeni versiyon oluşturur
draft → taslak olarak kaydeder
overwrite → mevcut versiyonun üzerine yazar
2.4. OnlyOffice / Collabora Entegrasyonu
Document elementi, Office dokümanlarını görüntülemek ve düzenlemek için iki farklı motor destekler:
Metin, tablo ve sunum düzenlemeleri dahil olmak üzere tam düzenleme yeteneği sunar.
PDF dosyaları da OnlyOffice üzerinden görüntülenebilir (Collabora PDF desteklemez).
saveMode özelliği yalnızca OnlyOffice ile çalışır.
Kullanılabilmesi için sunucu tarafında documentServerUrl yapılandırmasının yapılmış olması gerekir.
Collabora
DOCX, XLSX, PPTX ve ODF formatları için LibreOffice tabanlı görüntüleme ve düzenleme sağlar.
Değişiklik takibi (track changes) senaryolarında daha güçlü destek sunar.
officeEngine: "collabora" ayarı ile aktif edilir.
Kullanılabilmesi için sunucu tarafında serverUrl yapılandırmasının yapılmış olması gerekir.
Motor Seçim Mantığı
officeEngine prop’u tanımlanmışsa belirtilen motor kullanılır.
Tanımlı değilse sunucu tarafında yapılandırılmış activeProvider devreye girer.
Hiçbiri yoksa varsayılan olarak OnlyOffice kullanılır.
PDF dosyaları hiçbir zaman Collabora’ya gönderilmez. OnlyOffice aktifse PDF’ler OnlyOffice ile açılır; aksi durumda PDF.js ile salt okunur olarak görüntülenir.
Görsel dosyalar her zaman TUI Image Editor ile, 3D modeller ise three.js ile render edilir.
2.5. Temp Auto-Save (Monaco ve Draw.io)
Monaco Editor (CodeAdapter) ve Draw.io (DiagramAdapter), yapılan değişiklikleri otomatik olarak kaydetmek için debounce mekanizması ile çalışır.
Kullanıcı düzenleme yaptığında, yaklaşık 5 saniyelik gecikme (debounce) sonrası SaveTemp aksiyonu otomatik olarak tetiklenir ve değişiklikler Temp katmanına kaydedilir.
recoverTemp() metodu, kurtarılan Temp verisini ilgili editör içerisine yüklemek için kullanılır.
2.6. OnlyOffice Version-Specific Destek
Document elementi, versionId bilgisini SDC (Software Development Container) katmanı üzerinden OnlyOfficeAdapter’a iletir.
OnlyOfficeAdapter, bu değer ile POST /onlyoffice/config endpoint’ini çağırır ve ilgili doküman konfigürasyonunu oluşturur.
DownloadVersionById endpoint’i, oo_token ve AllowAnonymous desteği sağlar. Bu sayede OnlyOffice Document Server, belirli bir doküman versiyonunu doğrudan indirebilir ve render edebilir.
3. Document Elementi Kullanım Senaryosu
Directory ile Entegre Kullanım
Document elementi genellikle Directory ile birlikte kullanılır. Kullanıcı ağaç yapısından bir doküman seçtiğinde aşağıdaki akış gerçekleşir:
