1. Document Uploader Elementine Genel Bakış

Document Uploader elementi, kullanıcıların DMS’e dosya yüklemesini sağlayan, drag & drop destekli bir UI elementidir. Dosyalar, chunked upload (parçalı yükleme) yöntemi ile backend’e aktarılır. Bu sayede büyük dosyalar parça parça gönderilerek daha güvenli ve stabil bir yükleme süreci sağlanır.

Bu element sayesinde kullanıcılar dosyaları sürükle-bırak veya dosya seçme yöntemiyle ekleyebilir. Yükleme öncesinde dosya tipi doğrulaması yapılır ve güvenlik amacıyla magic byte analizi uygulanır. Böylece yalnızca izin verilen ve güvenli dosyaların sisteme yüklenmesi sağlanır.

Document Uploader elementi; belge yönetim sistemleri, başvuru ekranları, destek talepleri, onboarding akışları ve klasör bazlı dosya yükleme gerektiren senaryolarda kullanılabilir.

Document Uploader elementi yalnızca web uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

Document Uploader elementi aşağıdaki senaryolarda yaygın olarak kullanılır:

• Kullanıcıdan belge veya evrak toplamak için kullanılabilir. Örneğin kimlik belgesi, sözleşme, başvuru dokümanı veya ek dosyalar bu element ile sisteme yüklenebilir.
• Belirli bir klasöre dosya yükleme gereken yapılarda tercih edilir. Özellikle Document Management yapılarında, yüklenen dosyanın hedef klasör ile ilişkilendirilmesi için uygundur.
• Form süreçlerinde ek belge toplamak amacıyla kullanılabilir. Başvuru, onboarding veya destek talebi gibi ekranlarda dosya ekleme alanı olarak değerlendirilebilir.
• Yönetim panellerinde veya içerik operasyon ekranlarında editör ya da yönetici kullanıcıların sisteme belge eklemesi için kullanılabilir.
• Birden fazla dosyanın sıraya alınarak kontrollü biçimde yüklenmesi gereken yapılarda kullanılabilir.
• Büyük dosyaların tek seferde değil, parçalara bölünerek Backend’e aktarılması gereken senaryolarda etkili bir çözüm sunar.

2. Temel Özellikler

Document Uploader elementi dosya yükleme süreçleri için aşağıdaki temel özellikleri sunar:

• Üst kısımda drag & drop alanı bulunur. Kesik çizgili bir kutu içerisinde “Inbox” ikonu, ana metin (label) ve yardımcı metin (hint) yer alır. Kullanıcı dosyaları bu alana sürükleyip bırakabilir veya tıklayarak dosya seçebilir.
• Dosyalar seçildiğinde, alt kısımda dosya listesi görüntülenir. Her satırda dosya ikonu, düzenlenebilir dosya adı alanı, dosya boyutu ve silme butonu bulunur.
• Listenin üst kısmında toplam dosya sayısı ve “Upload” butonu yer alır.
• Yükleme başlatıldığında her dosya için ilerleme çubuğu gösterilir.
• Başarılı yüklemelerde yeşil ilerleme çubuğu ve onay durumu, hatalı yüklemelerde ise kırmızı ilerleme çubuğu, hata mesajı ve yeniden deneme seçeneği görüntülenir.
• Desteklenmeyen dosya tipleri için kullanıcıya sarı uyarı bildirimi (toast) gösterilir.

2.1. Element Ayarları (Properties)

DocumentUploader elementini seçtiğinizde, sağ tarafta yer alan Properties paneli üzerinden yükleme davranışını ve kullanıcıya gösterilecek içerikleri yapılandırabilirsiniz.

Bu elementte öne çıkan ayarlar aşağıdaki gibidir:

folderId: Yüklenen dosyaların kaydedileceği hedef klasörün ID bilgisini belirtir. Directory elementinin selectedFolderId binding’ine bağlanabilir. Bu alan tanımlandığında, yüklenen tüm dokümanlar ilgili klasör altında oluşturulur.

documentId: Yükleme işleminin mevcut bir doküman üzerinde mi yoksa yeni bir doküman olarak mı gerçekleşeceğini belirleyen ID bilgisidir.

• uploadMode = "newVersion" ise bu alan zorunludur ve güncellenecek dokümanın ID’sini ifade eder.
• uploadMode = "draft" ise:
  
  • documentId verilirse mevcut dokümana taslak versiyon eklenir
  • verilmezse yeni bir doküman taslak olarak oluşturulur
• uploadMode = "newDocument" modunda kullanılmaz

uploadMode: Yükleme davranışını belirler.

• newDocument → Seçilen klasöre yeni bir doküman (yayınlanmış) oluşturur
• newVersion → Mevcut dokümanın yeni bir versiyonunu yükler (documentId zorunludur)
• draft → Dokümanı taslak olarak kaydeder

maxFileSizeMb: Tek bir dosya için izin verilen maksimum boyutu MB cinsinden belirler. Bu sınırı aşan dosyalar yüklenmez ve kullanıcıya uyarı gösterilir.

maxFileCount: Aynı anda yükleme kuyruğuna alınabilecek maksimum dosya sayısını belirler. Belirlenen sınır aşıldığında fazla dosyalar reddedilir.

chunkSizeMb: Dosyaların backend’e gönderilirken kaç MB’lık parçalara bölüneceğini belirler. Varsayılan değer 10 MB’tır. Büyük dosyaların daha stabil yüklenmesi için kullanılır.

Label: Drag & drop alanında kullanıcıya gösterilen ana metindir. Kullanıcıya bu alanın ne amaçla kullanıldığını açık şekilde anlatmak için kullanılır.

Hint: Kullanıcıya ek bilgilendirme sunan yardımcı metindir. Desteklenen dosya tipleri, maksimum boyut veya kullanım amacı gibi bilgiler burada gösterilebilir.

autoClearSeconds: Başarılı yüklemelerin, belirtilen süre (saniye) sonunda listeden otomatik olarak kaldırılmasını sağlar.

maxVisibleEntries: Dosya listesinde aynı anda görüntülenecek maksimum satır sayısını belirler. Fazla kayıtlar scroll ile görüntülenir.

Language: Yükleme bileşeninin arayüz dilini belirler.

2.2. Elemente Eklenebilen Event Aksiyonları

DocumentUploader elementi, kullanıcı etkileşimlerine bağlı olarak aksiyon tetikleyebilen event’ler sunar. Bu event’ler, yükleme sürecini kontrol etmek ve ek iş akışları tanımlamak için kullanılabilir.

onUploadFinish: Kuyruktaki tüm dosyaların yükleme işlemi tamamlandığında (başarılı veya hatalı fark etmeksizin) tetiklenir. Genellikle yükleme sonrası veri yenileme işlemleri için kullanılır. Örneğin, Document ağacını güncellemek amacıyla GetDocumentTree aksiyonu bu event üzerinden çağrılabilir.

onFileSelect: Bir veya daha fazla geçerli dosya yükleme kuyruğuna eklendiğinde tetiklenir. Kullanıcının dosya seçimi yaptığı anı yakalamak ve buna bağlı kontroller veya bilgilendirme işlemleri gerçekleştirmek için kullanılabilir.

onUploadStart: Kullanıcı “Upload” butonuna tıklayıp yükleme sürecini başlattığında tetiklenir. Yükleme öncesi hazırlık işlemleri, loglama veya kullanıcıya bilgilendirme gösterme gibi senaryolarda kullanılabilir.

2.3. Drag & Drop Desteği

DocumentUploader elementi, Ant Design Dragger bileşeni üzerine inşa edilmiştir ve aşağıdaki özellikleri sunar:

Çoklu dosya seçimi:  Multiple özelliği aktif olarak çalışır. Kullanıcı birden fazla dosyayı aynı anda sürükleyip bırakabilir veya seçebilir.

Accept filtresi: İzin verilen dosya uzantıları otomatik olarak accept HTML Attribute’una aktarılır. Bu sayede tarayıcı yalnızca desteklenen dosya tiplerini seçilebilir olarak gösterir.

İstemci taraflı doğrulama: Yükleme öncesinde her dosya için aşağıdaki kontroller yapılır:

• Dosya uzantısı, sistemde tanımlı desteklenen dosya tipleri arasında mı?
• Dosya boyutu maxFileSizeMb sınırını aşıyor mu?
• Dosyanın ilk 16 byte’ı güvenlik açısından riskli bir içerik barındırıyor mu? 
  
  • (ör. EXE/MZ, ELF, Shebang kontrolleri)
• Toplam dosya sayısı maxFileCount sınırını aşıyor mu?

Hata durumunda kullanıcı bilgilendirme: Reddedilen dosyalar için kullanıcıya toast bildirimleri gösterilir. Hata nedenine göre farklı mesajlar sunulur:

• format (desteklenmeyen dosya tipi)
• security (güvenlik riski)
• size (dosya boyutu sınırı)
• count (dosya sayısı sınırı)

Gösterilen bildirimler yaklaşık 3.2 saniye sonra otomatik olarak kapanır.

2.4  Chunked Upload Süreci

DocumentUploader elementi, özellikle büyük dosyaların güvenli ve stabil şekilde yüklenebilmesi için chunked upload (parçalı yükleme) mekanizmasını kullanır.

Yeni doküman yükleme (uploadMode: "newDocument")

Yükleme süreci aşağıdaki adımlardan oluşur:

1. Init (Başlatma): POST /documentmanagement/chunks/init. Dosya adı, MIME tipi, hedef klasör, toplam parça sayısı ve boyut bilgileri gönderilir. Sunucu bu isteğe karşılık bir uploadId döner.

2. Chunk Gönderimi: POST /documentmanagement/chunks/{uploadId}/{chunkIndex} Dosya, belirlenen chunk boyutuna göre parçalara ayrılır ve her parça application/octet-stream formatında sırayla gönderilir. Her parça sonrası ilerleme çubuğu güncellenir.

3. Finalize (Tamamlama): POST /documentmanagement/chunks/{uploadId}/finalize
Tüm parçalar gönderildikten sonra sunucu bu parçaları birleştirir, dokümanı oluşturur ve documentId bilgisini döner.

4. Hata Durumu: Yükleme sürecinin herhangi bir adımında hata oluşursa: DELETE /documentmanagement/chunks/{uploadId} çağrısı ile yükleme oturumu temizlenir.

Versiyon yükleme (uploadMode: "newVersion" / "draft")

Bu modlarda chunked upload kullanılmaz. Yükleme işlemi doğrudan aşağıdaki endpoint üzerinden tek seferde gerçekleştirilir:

PUT /documentmanagement/{documentId}/file

Dosya, FormData formatında gönderilir ve mevcut doküman üzerinde versiyon veya taslak olarak kaydedilir.

2.5. Desteklenen Dosya Tipleri

DocumentUploader elementi, aşağıdaki dosya kategorilerini destekler:

• Office Dosyaları: docx, doc, xlsx, xls, pptx, ppt, odt, ods, odp, csv, rtf
• PDF / E-kitap: pdf, epub, fb2, djvu, xps
• Görsel Dosyaları: jpg, jpeg, png, gif, bmp, webp, svg, tiff, tif, ico, psd
• 3D Model Dosyaları: glb, gltf, obj, stl, 3ds, ply, dae, fbx, 3mf, ifc, step, stp, dwg, dxf
• Kod / Metin Dosyaları: js, ts, jsx, tsx, css, scss, py, java, cs, go, rs, cpp, c, h, sh, yaml, sql, json, xml, html, md, txt, log
• Arşiv Dosyaları: zip, rar, 7z, tar, gz, bz2, xz
• Diyagram Dosyaları: vsdx, vsd, vdx, vssx, vstx, drawio
• E-posta Dosyaları: eml, msg

2.6. İşlem Bilgi Etiketleri (Operation Info Tags)

Her yükleme satırında, yapılan işleme göre görsel bilgi etiketleri gösterilir. Bu etiketler, yükleme tipini kullanıcıya açık şekilde ifade eder:

• New Document: Yeni doküman oluşturma (uploadMode: "newDocument")
• New Version: Mevcut dokümana yeni versiyon ekleme (uploadMode: "newVersion")
• Draft: Dokümanı taslak olarak yükleme (uploadMode: "draft")

2.7. Tamamlananları Temizle (Clear Completed)

Yükleme tamamlandıktan sonra başarılı yüklemeler için “Clear completed” butonu görüntülenir.

Bu butona tıklandığında, başarılı şekilde yüklenmiş tüm dosyalar listeden kaldırılır.

autoClearSeconds özelliği tanımlanmışsa, başarılı yüklemeler belirtilen süre sonunda otomatik olarak listeden temizlenir.

3. Document Uploader Elementi Kullanım Senaryosu

Senaryo: Kullanıcı, sol panelde yer alan “Sözleşmeler” klasörünü seçer ve bu klasöre yeni bir PDF dokümanı yükler.

Akış

1. Klasör Seçimi: Kullanıcı Directory üzerinden bir klasör seçtiğinde:

Directory.onFolderSelect

1. SetValueOf(DocumentUploader.folderId, Directory.selectedFolderId)
   → Seçilen klasör, yükleme hedefi olarak belirlenir

2. Dosya Seçimi: Kullanıcı dosyayı sürükleyip bırakır veya manuel olarak seçer:

DocumentUploader.onFileSelect

→ Seçilen dosyalar yükleme kuyruğuna eklenir
→ Kullanıcı, gerekirse dosya adını düzenleyebilir

3. Yükleme Başlatma: Kullanıcı “Upload” butonuna tıklar:

DocumentUploader.onUploadStart

→ Yükleme süreci başlatılır
→ Her dosya için ilerleme çubuğu gösterilir

4. Yükleme Tamamlanması: Tüm dosyaların yüklenmesi tamamlandığında:

DocumentUploader.onUploadFinish

1. GetDocumentTree → dsDocumentTree
   → Güncel doküman ağacı backend’den alınır
2. SetValueOf(Directory.options, dsDocumentTree)
   → Directory yeniden render edilir ve yeni dokümanlar görünür
3. ShowNotification("Yükleme tamamlandı!")
   → Kullanıcıya işlem sonucu bildirilir

4. Kullanım Tavsiyeleri (Best Practices)

• folderId alanını mutlaka doğru bağlayın. Yanlış veya boş bırakılması durumunda dosyalar beklenen klasöre yüklenmez.
• uploadMode ayarını senaryoya uygun seçin. Yeni doküman oluşturma, versiyon ekleme veya taslak yükleme davranışları farklı çalışır.
• maxFileSizeMb ve maxFileCount değerlerini sistem kapasitesine göre belirleyin. Çok yüksek değerler performans sorunlarına neden olabilir.
• Büyük dosya yüklemelerinde chunkSizeMb değerini optimize edin. Daha küçük parçalar daha stabil yükleme sağlar ancak istek sayısını artırır.
• Kullanıcıya doğru yönlendirme yapmak için label ve hint alanlarını açık ve anlaşılır şekilde doldurun.
• Yükleme sonrası veri güncelleme işlemlerini onUploadFinish event’i üzerinden yönetin. Örneğin Directory ağacını bu event ile yenileyin.

5. Kısıtlamalar

• Desteklenmeyen dosya tipleri yüklenemez. Dosya uzantısı ve içerik (magic byte) kontrolünden geçmeyen dosyalar sistem tarafından reddedilir.
• Dosya boyutu maxFileSizeMb sınırını aşarsa yükleme yapılmaz.
• Toplam dosya sayısı maxFileCount sınırını aşarsa fazla dosyalar kuyruğa alınmaz.
• Chunked upload yalnızca yeni doküman yükleme (uploadMode: "newDocument") senaryosunda kullanılır. Versiyon ve taslak yüklemeleri tek seferde gerçekleştirilir.
• Yükleme işlemi sırasında oluşan hatalar satır bazında yönetilir. Başarısız dosyalar manuel olarak yeniden denenmelidir.
• Tasarım zamanında (design-time) drag & drop alanı ve Upload butonu aktif değildir.
• MIME tipi tespiti kesin olmayabilir. Tarayıcıdan gelen bilgi, uzantı haritası ve fallback mekanizmasına bağlı olarak belirlenir.