1. Big File Upload Elementine Genel Bakış

Big File Upload elementi, kullanıcıların yüksek boyutlu dosyaları uygulama içerisine güvenli, hızlı ve kontrollü bir şekilde yüklemesini sağlayan gelişmiş bir dosya yükleme elementidir. Büyük dosyalarla çalışmaya uygun yapısı sayesinde, standart file upload çözümlerinin yetersiz kaldığı senaryolarda kullanılabilir. 

Big File Upload elementi; medya dosyaları (video, yüksek çözünürlüklü görseller), proje dosyaları, arşivler ve büyük veri setleri gibi içeriklerin yüklenmesi gereken durumlarda kullanılır. Yükleme sürecinin izlenebilmesi ve limitlerin yapılandırılabilmesi, kullanıcı deneyimini ve sistem güvenliğini artırır.

Big File Upload elementi yalnızca web uygulamalarında desteklenmektedir.

1.1. Sık Kullanım Senaryoları

• Video ve yüksek boyutlu medya dosyası yükleme
• Proje, tasarım veya arşiv dosyalarının aktarılması
• Büyük veri setlerinin sisteme yüklenmesi
• İçerik yönetim ve paylaşım platformları
• Dosya tabanlı iş akışları ve başvuru süreçleri

2. Temel Özellikler

• Büyük dosya yükleme desteği:  Yüksek boyutlu dosyalar (video, arşiv, proje dosyaları vb.) sorunsuz şekilde yüklenebilir.
• Yükleme limiti yapılandırma: Dosya boyutu sınırları tanımlanarak sistem kaynakları kontrollü şekilde kullanılır.
• Yükleme süreci takibi: Kullanıcılar, dosya yükleme durumunu ve ilerleme sürecini takip edebilir.
• Güvenli dosya aktarımı: Büyük dosya yüklemelerinde veri bütünlüğü korunarak aktarım sağlanır.

2.1.Big File Upload Elementi Özellikleri

• Chunk Size: Büyük dosyaların sunucuya yüklenirken küçük parçalara bölünmesini sağlayan parametredir. Özellikle 100 MB ve üzerindeki dosyaların yüklenmesi sırasında bağlantı kopmaları gibi sorunları minimize eder. Örneğin, 10 MB’lık parçalar halinde yükleme ayarlanırsa, dosya 10 MB’lık bloklar şeklinde gönderilir ve yükleme sırasında yaşanabilecek kesintilerde sadece ilgili parça yeniden yüklenir. Bu sayede hem ağ trafiği dengelenir hem de yükleme daha stabil hale gelir. Chunk Size ayarı, uygulamanın performansı ve kullanıcı deneyimi için kritik bir parametredir. Dosya boyutuna ve hedef kitlenin internet hızına göre optimum değer belirlenmelidir. 
• Label: Dosya yükleme alanının ne amaçla kullanıldığını açıklayan kısa bir bilgilendirme metnidir. Yüklenmesi gereken dosyanın türünü ve sistemin beklentisini net şekilde anlar. Örneğin, “Lütfen kimlik belgenizi yükleyin” şeklinde yazılan bir label, kullanıcıyı yönlendirir ve yanlış dosya yüklemesini engeller. Label metni, uygulamanın kullanım senaryosuna göre değiştirilebilir ve kullanıcı deneyimini artıracak açıklıkta olmalıdır. 
• Hint: Dosya yükleme süreciyle ilgili ipucu veya teknik kısıtlamaları bildiren metindir. Dosya formatı, maksimum boyut veya özel yükleme talimatları yer alabilir. Örneğin, “Yalnızca .pdf veya .jpg dosyaları yükleyebilirsiniz” veya “En fazla 200 MB dosya yükleyebilirsiniz” gibi bir metin yazılabilir. Yükleme alanında ya da yükleme butonunun hemen altında görünecek şekilde konumlandırılır ve sürecin sorunsuz tamamlanmasını sağlar. 
• Upload Confirmation Message: Dosya yükleme işlemi tamamlandığında kullanıcıya gösterilecek onay mesajını belirler.
• Show Delete Icon: Yüklenen dosyanın silinebilmesi için delete (çöp kutusu) ikonunun gösterilip gösterilmeyeceğini belirler.
• Show Upload Confirmation: Dosya yükleme işleminden önce kullanıcıya onay mesajı gösterilip gösterilmeyeceğini belirler.
• Show Cancel Icon: Yükleme işlemi sırasında işlemi iptal etmek için cancel ikonunun gösterilmesini sağlar.

2.2. File Upload Path (Dosya Yükleme Dizini) Ayarı

Dosya yükleme işlemleri için yükleme dizin ayarını yapmak üzere aşağıdaki adımları izleyin:

1. Configuration Manager modülüne gidin.

2. File Upload Path alanını bulun.
3. Dosyaların yükleneceği sunucu dizin yolunu yazın. (Örnek: /userUploads/)
4. Ayarları kaydedin.

Dosya yükleme dizini Configuration Manager modülündeki File Upload Path ayarı üzerinden tanımlanır. Dinamik dosya yolu ayarlama yapılmaz.

2.3. Dosya Yükleme, İndirme ve Silme İşlemleri

2.3.1. Dosya Yükleme

İstemci tarafında seçtiği veya sürükleyip bıraktığı büyük boyutlu dosyaları HTTP multipart/form-data formatında sunucuya yükler. İşlem, ağ performansını optimize etmek ve olası kesintilerde veri kaybını önlemek amacıyla chunk (parça) mantığıyla gerçekleştirilir. 

• Dosyayı doğrudan element üzerine sürükleyip bırakın.
• Sistem dosyayı Chunk Size parametresine göre parçalara böler (örnek: 10 MB). 
• Her parça sırayla sunucuya iletilir ve geçici bellekte tutulur. 

• Yükleme tamamlandığında On Upload Finish aksiyonu tetiklenir. Bu aksiyonla birlikte aşağıdaki değerler üretilir ve yönetim için kullanılmalıdır: 
  
  • File ID (GUID): Yüklenen dosyaya sistem tarafından atanan benzersiz kimlik.
  • File Name: Kullanıcının yüklediği orjinal dosya adı.

File ID veritabanında saklanmalı ve tüm indirme-silme işlemleri bu ID üzerinden yönetilmelidir. Aksi takdirde dosya üzerinde işlem yapılamaz. 

2.3.2. Dosya İndirme

1. Big File Upload elementine tıklayın.
2. Sağ kenardaki Properties panelini açın.

3. +ADD ACTION menüsünden On Upload Finish → Device → Download File From Server seçeneğini seçin.
4. Aşağıdaki alanları yapılandırın:

• File ID: İndirilecek dosyanın benzersiz kimlik numarasını girin. (Örn: "{{uploadedFileId}}")
• File Name: İndirilecek dosya için bir isim belirleyin. Dosya, belirlediğiniz bu adla kullanıcının cihazına indirilecektir. (Örn: "Rapor_2024.pdf")

File ID eksik veya hatalı girilirse sistem dosyayı bulamaz ve indirme işlemi başarısız olur. ID mutlaka yükleme sırasında alınmalı ve saklanmalıdır. 

İndirme isteği tetiklendiğinde:

• Sistem belirtilen File Path ve File ID ile dosyayı doğrular. 
• MIME tipi kontrol edilerek dosya HTTP üzerinden istemciye aktarılır. 
• Tarayıcı kullanıcının ayarlarına göre dosyayı otomatik indirir veya kaydetme seçeneğini sunar. 

İndirme işlemi tetiklenmeden önce kullanıcının ilgili dosya üzerinde yetkisi olup olmadığı kontrol edilmelidir. 

2.3.4. Dosya Silme

1. Big File Upload elementine tıklayın.
2. Sağ kenardaki Properties panelini açın.

3. +ADD ACTION menüsünden On Upload Finish → Device → Delete File From Server seçeneğini seçin.
4. Aşağıdaki alanları yapılandırın:

• File ID: Silinecek dosyanın benzersiz kimlik numarası.

File Path ve File ID eşleşmezse dosya tespit edilemez ve işlem başarısız olur. File ID yükleme sonrası mutlaka kayıt altına alınmalıdır. 

Silme işlemi tetiklendiğinde: 

• Sistem, File Path ve File ID bilgilerine göre dosyayı doğrular. 
• Doğrulama tamamlandığında dosya sunucudan kalıcı olarak silinir. 
• Silinen dosya kurtarılamaz. 

Silme işleminden önce, dosyanın sistemde kullanılmadığı ve başka işlemler tarafından referans alınmadığı mutlaka kontrol edilmelidir. Aksi durumda sistemsel hatalar ve veri kayıpları yaşanabilir. 

2.2. Elemente Eklenebilen Aksiyonlar

Big File Upload elementi, dosya yükleme sürecinin tamamlanmasına bağlı olarak olay (event) bazlı aksiyonlar tetiklenmesini destekler. Aksiyonlar, elementin kendisine değil; yükleme işlemi başarıyla tamamlandığında tetiklenen event’e bağlanır.

Big File Upload elementi için aksiyonlar, Properties > Add Action alanı üzerinden aşağıdaki event aracılığıyla tanımlanabilir.

Desteklenen Aksiyon Tetikleyicisi

onUploadFinish: Dosya yükleme işlemi başarıyla tamamlandığında tetiklenir.

Kullanım amaçları:

• Yüklenen dosya bilgilerini (dosya adı, boyut, URL vb.) state veya değişkene kaydetmek
• Yükleme sonrası form akışını bir sonraki adıma geçirmek
• Dosya yüklendikten sonra önizleme veya bilgilendirme göstermek
• API veya workflow tetikleyerek dosyayı sisteme kaydetmek
• Yükleme tamamlandı mesajı veya başarı bildirimi göstermek

Örnek senaryo: Kullanıcı büyük boyutlu bir video dosyasını yüklediğinde, yükleme tamamlanır tamamlanmaz dosya URL’si state’e kaydedilir ve “Yükleme Başarılı” mesajı gösterilir.

Aksiyonlara İlişkin Temel Kurallar

• Big File Upload elementi aksiyonları event bazlı çalıştırır; onUploadFinish yalnızca yükleme işlemi başarıyla tamamlandığında tetiklenir.
• Aynı onUploadFinish event’i için birden fazla aksiyon tanımlanabilir.
• Büyük dosyalarla çalışıldığında, yükleme sonrası tetiklenen aksiyonların performans etkisi dikkate alınmalıdır.

Big File Upload elementi, özellikle yükleme sonrası işlem başlatılması gereken senaryolarda onUploadFinish event’i ile birlikte kullanıldığında kontrollü ve güvenilir bir kullanıcı deneyimi sunar.

3. Big File Upload Elementi Nasıl Kullanılır? 

Bu bölümde Big File Upload elementinin uçtan uca kullanımını örnek senaryo üzerinden ele alacağız.

Senaryo: Doküman Yükleme ve Yönetimi

Kullanıcı, sisteme dosya eklemek için Big File Upload elementini kullanır. Dosya, sürükle-bırak alanına taşınarak ya da alana tıklanarak seçilir. Dosya seçimi tamamlandıktan sonra yükleme işlemi başlatılır ve 'Upload File' butonuna tıklanarak ilgili kayıt sisteme eklenir. Başarıyla yüklenen dosya, ekranın alt bölümünde yer alan tabloda File id ve File name bilgileriyle listelenir.

Senaryoda:

• Kullanıcı, tabloda listelenen kayıtlar üzerinden daha önce yüklediği dosyalara erişebilir. 
• İlgili satırdaki Download File butonu ile dosya indirilebilir, Delete File butonu ile ise sistemden silinebilir. 
• Böylece kullanıcı, yüklediği dosyaları tek bir ekran üzerinden görüntüleyebilir, indirebilir ve yönetebilir.

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

DataSources modülünde tablo oluşturma: 

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

• Önemli Alan adları:
  
  • FileId: Her dosya için benzersiz bir kimlik oluşturur ve tutulur. 
  • FileName: Kullanıcının yüklediği dosyanın sistemde görünen adıdır.

Adım 2 - Gerekli Aksiyonun Tanımlanması

Arayüzde verileri göstermek için: 

1. Örnek bir aksiyon tanımlamanız gerekir.
2. Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.

• Kullanıcı Tercihlerini Getiren Aksiyon  (UploadedFiles):

SELECT * FROM Files;

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

Başlangıçta anasayfada: 

1. Liste üzerinde mevcut yüklenen dosyaların gösterimi için Add Action > Initial Action > Custom > Managed DB > UploadedFiles aksiyonunu ekleyin.
   

Adım 4 - Big File Upload Elementini Ekleme ve Aksiyon Tanımlama

Başlangıçta anasayfada: 

• Sol yan panelden Elements > Special > Big File Upload elementini sayfaya sürükleyip bırakın.
  

• Big File Upload elementi altına eklenen dosyanın kaydı için Elements > Navigation > Button elementini ekleyin.
• Button üzerindeki yazıyı Button > Properties > Label > “Upload File” olarak tanımlayın.
  

• Button içerisine yüklenen dosyanın kaydı için Button > Properties > Add Action > onClick > Save Record aksiyonunu ekleyin.
  

• Save Record aksiyonu içerisinde Select Table > Files tablosunu seçin ve Columns alanında FileId ve FileName seçimini yapın.

• FileId alanına Components > BigFileUpload > FileId tanımlamasını yapın.
  

• FileName alanına Components > BigFileUpload > FileName tanımlamasını yapın.
  

• Save Record aksiyonundan sonra kayıt sonrası listeyi güncellemek için Button > Properties > Add Action > Custom > Managed DB > UploadedFiles aksiyonunu ekleyin.
  

• Sol yan paneldeki Action Tree alanından UploadedFiles aksiyonu yanındaki ikondan sayfaya sürükleyin.
  

• Açılan ekranda aşağıdaki tanımlamayı yapın.
  

•  Sayfa eklenen Tablo elementi ayarlarında Table > Properties > +TableTemplateColumn alanından tabloya yeni sütun ekleyin.
  

•  Yeni oluşan sütunun adını TableTemplateColumn> Title alanından temizleyin.
  

• Yeni Sütun içerisine Elements > Container > Horizontal Stack elementini sürükleyip bırakın.
  

•  Horizontal Stack içerisine Elements > Navigation > Button elementini sürükleyip bırakın.
  

• Button yazısını Button > Properties > Label > “Download File” olarak güncelleyin.
  

• Button içerisine dosyayı indirmek için Button > Properties > Add Action > onClick > Device > Download File From Server aksiyonunu ekleyin.
  

•  Download File From Server aksiyonunda fileId değeri için Current > fileId tanımlamasını yapın.
  

• FileName alanına Current > fileName tanımlamasını yapın.
  

•  Download File butonu yanına Horizontal Stack elementi içerisine Elements > Navigation > Button elementini daha ekleyin.
  

•  Button yazısını Button > Properties > Label > “Delete File” olarak güncelleyin.
•  Button içerisine dosyayı silmek için Button > Properties > Add Action > onClick > Device > Delete File From Server aksiyonunu ekleyin.
  

• Delete File From Server aksiyonunda fileId değeri için Current > fileId tanımlamasını yapın.
  

•  Tablodaki kayıtlardan silmek için ek olarak Button > Properties > Add Action > ManagedDb > Delete Record aksiyonunu ekleyin.
  

•  Delete Record aksiyonunda Select Table > Files ve Id > Current > Id tanımlamalarını yapın.
  

• Son olarak silme işlemi sonrasında listeyi yenilemek için Button > Properties > Add Action > onClick > Custom > Managed DB > UploadedFiles aksiyonunu ekleyin.
  

•  Silme işlemini vurgulamak için Button > Styling > Fill > Color > “E13C39” rengini tanımlayın.
  

•  Horizontal Stack içerisine eklenen button elementleri için uygulanan sabit 100 px Genişlik (Width) tanımını kaldırmak amacıyla, Button > Styling > Layout > Width alanını boş bırakın.
  

•  Son durumda sayfa yapısı aşağıdaki gibidir.
  

Preview:

Big File Upload elementi sayesinde kullanıcılar dosyalarını sürükleyip bırakarak veya yükleme alanına tıklayarak sisteme ekleyebilir. Seçilen dosya, yükleme sürecini gösteren bir ilerleme çubuğu ile birlikte görüntülenir ve dosyanın sisteme aktarılma durumu kullanıcıya gösterilir.

Dosya yükleme işlemi tamamlandıktan sonra Upload File butonuna basılarak dosyanın listeye kaydedilmesi sağlanır. Butona tıklandığında liste otomatik olarak güncellenir ve yüklenen dosya File id ve File name bilgileriyle tabloda görüntülenir.

Kullanıcılar, tabloda yer alan kayıtlar üzerinden dosya yönetimini gerçekleştirebilir. İlgili satırdaki Download File butonu ile dosyayı indirebilir, Delete File butonu ile ise dosyayı listeden kaldırabilir. Böylece kullanıcılar yükledikleri dokümanları tek bir ekran üzerinden görüntüleyebilir, indirebilir ve silebilir.

4. Ortak Özellikler (Properties)

Big File Upload 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)

• Yükleme sürecini kullanıcıya görünür kılın. İlerleme göstergeleri veya bilgilendirici metinler, kullanıcıların yükleme durumunu takip etmesini sağlar.
• onUploadFinish event’ini ana tetikleyici olarak kullanın. Yükleme tamamlandıktan sonra çalışması gereken tüm işlemleri bu event’e bağlayın.
• Yükleme sonrası geri bildirim sağlayın. Başarılı veya başarısız yükleme durumlarında kullanıcıya açık mesajlar gösterin.
• Büyük dosyalar için ek doğrulamalar ekleyin. Dosya türü, format veya içerik kontrolü gibi ek doğrulamalar güvenliği artırır.
• Uzun süren yüklemelerde kullanıcıyı bilgilendirin. Büyük dosyalarda yükleme süresi uzayabileceği için kullanıcıya bekleme süresi hakkında bilgi verilmesi önerilir.

6. Kısıtlamalar

• Big File Upload elementi yalnızca web uygulamalarında desteklenir.
• Yükleme performansı, kullanıcının internet bağlantı hızına ve dosya boyutuna bağlıdır.
• Aksiyonlar yalnızca onUploadFinish event’i üzerinden tetiklenebilir.
• Yükleme sırasında bağlantı kesilmesi durumunda işlemin yeniden başlatılması gerekebilir.