1. Directory Elementine Genel Bakış

Directory elementi, uygulama içerisinde klasör ve doküman yapısını hiyerarşik bir ağaç görünümünde sunmak için kullanılan bir UI elementidir. Özellikle Document Management System (DMS) senaryolarında, kullanıcıların klasörler ve dokümanlar arasında VS Code benzeri bir gezgin yapısı ile rahatça ilerleyebilmesini sağlar.

Bu element sayesinde Backend’den gelen klasör ve doküman kayıtları tek seviyeli (flat) bir veri yapısında olsa bile, ekranda ağaç yapısına dönüştürülerek gösterilebilir. Kullanıcılar klasörleri açabilir, alt klasörlerde gezinebilir, dokümanları seçebilir ve bulunduğu konumu breadcrumb üzerinden takip edebilir. Böylece çok katmanlı içerik yapıları daha düzenli, okunabilir ve yönetilebilir hale gelir.

Directory elementi yalnızca web uygulamalarda desteklenmektedir.

1.1. Sık Kullanım Senaryoları

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

• Klasör ve dokümanları hiyerarşik bir yapıda göstermek için kullanılabilir. Örneğin proje klasörleri, departman bazlı evraklar veya kullanıcıya ait belge arşivleri bu yapı ile sunulabilir.
• Belge yönetim sistemlerinde, klasör-doküman ilişkisini kullanıcıya dosya gezgini benzeri bir deneyimle göstermek için tercih edilir.
• Yardım merkezi, dokümantasyon kütüphanesi veya içerik arşivi gibi yapılarda kategori ve alt kategori mantığıyla ilerleyen içeriklerin gösterimi için uygundur.
• Kullanıcının belirli bir klasör ya da dokümanı seçerek işlem yapması gereken senaryolarda kullanılabilir. Örneğin doküman detayını açma, önizleme gösterme veya seçilen klasöre ait içerikleri listeleme gibi işlemler bu element ile desteklenebilir.
• Breadcrumb destekli gezinme gerektiren yapılarda, kullanıcıların bulunduğu klasör yolunu görmesi ve geri / ileri / yukarı mantığında hareket etmesi için kullanılabilir.
• Arama yapılan içerik yapılarında, eşleşen kayıtların ilgili üst klasörleriyle birlikte görünmesini sağlayarak kullanıcıya daha anlaşılır bir navigasyon deneyimi sunar.

2. Temel Özellikler

Directory elementi, klasör ve doküman yapılarının yönetimi için aşağıdaki temel özellikleri sunar:

• Hiyerarşik görüntüleme desteği sağlar. Klasörler, alt klasörler ve dokümanlar ağaç yapısında gösterilebilir.
• Backend’den gelen flat node listesi, element içerisinde ağaç yapısına dönüştürülerek kullanılabilir.
• Klasör ve doküman ayrımını destekler. Böylece kullanıcı hangi kaydın klasör, hangisinin doküman olduğunu kolayca ayırt edebilir.
• Client-side arama desteği sunar. Arama sırasında Türkçe karakter duyarlılığı gözetilerek normalize edilmiş filtreleme yapılabilir.
• Arama sonucunda eşleşen Node’ların yalnızca kendisi değil, ilgili Node’a ulaşmayı sağlayan tüm parent klasörler de otomatik olarak gösterilebilir.
• State yönetimi ile çalışır. Açık klasörler (expandedIds) ve seçili öğe (selectedId) senkronize biçimde yönetilir.
• Breadcrumb tabanlı adres çubuğu desteği sağlar. Böylece kullanıcı bulunduğu hiyerarşik konumu görebilir ve klasörler arasında daha kolay gezinebilir.
• Tema desteği sunar. Element, light veya dark tema ile kullanılabilir.

2.1. Element Ayarları (Properties)

Directory elementini seçtiğinizde, sağ tarafta yer alan Properties paneli üzerinden bu elementin veri yapısını ve görsel görünümünü kontrol edebilirsiniz.

Bu elementte kullanılabilen temel özellikler aşağıdaki gibidir:

Options: Backend'den veri çekmek için kullanılan aksiyon ve alan eşleştirme ayarlarını içeren bölümdür. Directory elementinin klasör/doküman yapısını oluşturabilmesi için gerekli veri kaynağı ve alan tanımları bu bölümden yapılır. Alt alanları:

• Action: Verinin hangi backend aksiyonu/servisi üzerinden çekileceğini belirler. Bu aksiyon, ilgili node listesini (klasör ve dokümanları) döndürür.
• Field to display: Node listesinde ekranda gösterilecek/kullanılacak alanı belirler. Seçilen aksiyonun döndürdüğü veri setindeki hangi alanın görüntüleneceğini tanımlar.
• Field to Use as Key: Her node için benzersiz kimlik olarak kullanılacak alanı belirler (örneğin id). Seçim, event ve binding işlemlerinin doğru çalışabilmesi için bu alanın benzersiz olması gerekir.
• Field to Use as Parent: Node'lar arasındaki üst-alt (parent-child) ilişkisini kurmak için kullanılacak alanı belirler (örneğin parentId). Root seviyesindeki kayıtlar için bu alanın boş/null olması beklenir.

Theme: Directory elementinin görsel temasını belirler. Desteklenen değerler: light, dark. Tema seçimi, özellikle yoğun veri içeren ekranlarda okunabilirlik ve görsel uyum açısından önemlidir.

DataNodeTypeField: Node'un tipini belirleyen alanı tanımlar. Varsayılan olarak nodeType kullanılır. Bu alan sayesinde klasör, doküman veya varsa virtual folder gibi farklı node tipleri ayrıştırılabilir. 

SelectedNodeType: Kullanıcı tarafından o an seçilmiş olan node'un tipini (folder, document, virtualFolder vb.) tutan alandır. Directory elementindeki seçim değiştikçe bu değer otomatik güncellenir ve dışarıdan bu alana bağlanan elementler seçili öğenin tipine göre davranış değiştirebilir (örneğin sadece "document" seçildiğinde bir aksiyon butonunu aktif etmek gibi).

SelectedVirtualFolder: Kullanıcının o an içinde bulunduğu veya seçtiği virtual folder'ı (sanal klasör) tutan alandır. Fiziksel klasör hiyerarşisinden bağımsız olarak oluşturulan sanal klasör yapılarında, hangi virtual folder'ın aktif/seçili olduğunu takip etmek için kullanılır.

SelectedLanguage: Seçili node'un (özellikle doküman) dil bilgisini tutan alandır. Çok dilli doküman yönetimi senaryolarında, seçilen dokümanın hangi dil versiyonunun görüntülendiğini veya seçildiğini belirtmek için kullanılır.

SelectedIsDraft: Seçili node'un taslak (draft) durumda olup olmadığını gösteren boolean bir alandır. Doküman yönetim sistemlerinde, kullanıcının seçtiği kaydın yayınlanmış mı yoksa henüz taslak halinde mi olduğunu ayırt etmek için kullanılır.

SelectedMimeType: Seçili node'un mime type (dosya türü) bilgisini tutan alandır. Örneğin "application/pdf", "image/png" gibi değerler alabilir. Seçilen dokümanın türüne göre önizleme, indirme veya işlem seçeneklerinin belirlenmesinde kullanılır.

HoverBgColor: Kullanıcının fare imlecini bir node satırının üzerine getirdiğinde, o satıra uygulanacak arka plan rengini belirler. Kullanıcının hangi satır üzerinde olduğunu görsel olarak ayırt etmesini sağlar.

SelectedBgColor: Seçili node satırına uygulanacak arka plan rengini belirler. Seçili öğeyi listedeki diğer öğelerden görsel olarak ayırt etmek için kullanılır.

SelectedFontColor: Seçili node'un metin (yazı) rengini belirler. SelectedBgColor ile birlikte kullanıldığında, seçili satırın arka plan-yazı renk kontrastının yeterli ve okunabilir olmasını sağlar.

2.2. Elemente Eklenebilen Event Aksiyonları

Directory elementi, kullanıcı etkileşimlerine göre aksiyon çalıştırabilen bir yapıya sahiptir. Element seçildiğinde ADD ACTION butonu görünür ve belirli event’ler üzerinden aksiyon tanımlanabilir.

Directory elementinde kullanılabilen event aksiyonları şunlardır:

OnNodeSelect: Kullanıcı Directory yapısında herhangi bir node seçtiğinde tetiklenir. Bu event, daha genel seçim senaryolarını yönetmek için kullanılır. Örneğin seçilen Node’a ait detay bilgisini göstermek, farklı bir panelde ilgili içeriği açmak ya da seçime göre veri filtrelemek için kullanılabilir.

OnDocumentSelect: Kullanıcı bir doküman seçtiğinde tetiklenir. Genellikle belge odaklı işlemlerde kullanılır. Örneğin seçilen dokümanın detay ekranı açılabilir, önizlemesi gösterilebilir, indirme işlemi başlatılabilir ya da belgeye ait ek bilgiler kullanıcıya sunulabilir.

OnFolderSelect: Kullanıcı bir klasör seçtiğinde tetiklenir. Seçilen klasörün içeriği listelenebilir, alt klasörler görüntülenebilir veya yalnızca ilgili klasöre bağlı dokümanlar ekrana getirilebilir. Özellikle klasör bazlı navigasyon senaryolarında oldukça kullanışlıdır.

2.3. Output (Binding) Değerleri

Directory elementi, seçili node ve kullanıcı etkileşimlerine bağlı olarak çeşitli output değerleri üretir. Bu değerler value() fonksiyonu ile okunabilir ve SetValueOf ile diğer elementlere aktarılabilir.

Kullanılabilen Binding Değerleri

• nodeId: Seçili node’un benzersiz kimliği
• nodeName: Seçili node’un adı
• isNodeBranch: Seçili node’un klasör olup olmadığını belirtir
• selectedDocumentId: Seçili dokümanın ID bilgisi
• selectedDocumentName: Seçili dokümanın adı
• selectedFolderId: Seçili klasörün ID bilgisi
• selectedFolderName: Seçili klasörün adı
• selectedVersionId: Seçili dokümanın versiyon ID’si
• selectedNodeType: Node tipi (folder, document vb.)
• selectedVirtualFolder: Virtual folder tipi (ör: versions, drafts)
• selectedLanguage: Seçili dil kodu (ör: tr, en)
• selectedIsDraft: Node’un taslak olup olmadığını belirtir
• selectedMimeType: Dokümanın MIME tipi

2.4 Virtual Folder Smart Mode

Virtual Folder’lar akıllı (smart) modda çalışır. Bu mod, dokümanların dil ve versiyon yapısına göre otomatik olarak farklı görünümler oluşturur.

• Tek dilli dokümanlar: Düz liste gösterilir. Alt klasör veya dil etiketi oluşturulmaz.
• Çok dilli dokümanlar: Dil varyantları gruplanarak gösterilir. Her dil için “Current” klasörü oluşturulur.
• Versions klasörü: Yalnızca 2 veya daha fazla versiyon bulunduğunda gösterilir.
• Doküman Node’ları: currentVersionId bilgisi ile zenginleştirilmiştir. Bu sayede seçili dokümanın aktif versiyonu doğrudan erişilebilir.
• nodeType-duyarlı ikonlar: Virtual Folder’lar node tipine göre farklı ikonlarla gösterilir. Örneğin:
  
  • versiyon klasörü → mavi
  • taslak klasörü → turuncu

3. Directory Elementi Kullanım Senaryosu

DMS Ana Ekranında Doküman Yönetimi

Directory elementi, DMS ana ekranında sol panelde klasör ve doküman ağacını göstermek için kullanılabilir. Bu senaryoda kullanıcı soldaki ağaçtan seçim yapar, sağ panelde ise seçilen içeriğe göre işlem yapılır.

Page Init Akışı

• Sayfanın onPageLoad event’inde GetDocumentTree action’ı çağrılır:
  
  • folderId: boş (kök dizinden başlar)
  • pageSize: 100
  • hideEmptyFolders: true
• Action sonucu bir değişkene (örneğin dsDocumentTree) atanır.
• Directory elementinin options prop’u bu değişkene bağlanır.

Kullanıcı Etkileşimi

Kullanıcı ağaçta bir klasöre tıkladığında onFolderSelect tetiklenir.

• selectedFolderId güncellenir.
• Bu değer DocumentUploader.folderId alanına yansıtılır.

Kullanıcı bir dokümana tıkladığında onDocumentSelect tetiklenir.

• selectedVersionId güncellenir
• (doküman node’larında currentVersionId alanı mevcuttur)

Document elementi otomatik olarak yeni versiyonu yükler.

Örnek Aksiyon Bağlama

Page Init:

1. GetDocumentTree → dsDocumentTree

2. Directory.options = dsDocumentTree

Directory.onDocumentSelect:

1. SetValueOf(Document.versionId, Directory.selectedVersionId)

Directory.onFolderSelect:

1. SetValueOf(DocumentUploader.folderId, Directory.selectedFolderId)

4. Kullanım Tavsiyeleri (Best Practices)

• options dizisi değiştiğinde (örneğin GetDocumentTree tekrar çağrıldığında) ağaç otomatik olarak yenilenir. Platform yeni bir dizi referansı oluşturduğunda bileşen yeniden render edilir.
• Node ID’leri büyük/küçük harf duyarsız (case-insensitive) normalize edilir. Backend’den gelen GUID değerleri farklı formatlarda olsa bile doğru eşleşme yapılır.
• Dashboard modunda (tasarım zamanı) Directory elementi örnek veri ile önizleme gösterir.

5. Kısıtlamalar

• Yanlış options veri yapısı kullanıldığında ağaç yapısı doğru oluşturulmaz. Parent-child ilişkilerinin doğru tanımlanması gerekir.
• Id alanı benzersiz olmalıdır. Aksi durumda seçim ve event işlemleri hatalı çalışabilir.
• ParentId hatalıysa Node’lar yanlış konumda görünür veya hiyerarşi bozulur.
• NodeType yanlış tanımlanırsa klasör/doküman ayrımı ve ilgili event’ler doğru çalışmaz.
• Options datası değiştiğinde element yeniden render edilir ve seçim/expand state sıfırlanabilir.
• Arama yalnızca client-side çalışır. Büyük veri setlerinde performans düşebilir.
• Virtual Folder yapısı otomatik çalışır ve manuel kontrol sınırlıdır.