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: Options, Backend’den gelen flat node listesini ifade eder. Directory elementi bu veri kümesini kullanarak klasör ve doküman yapısını oluşturur. Bu nedenle Options alanına verilen veri yapısının parent-child ilişkilerini doğru şekilde içermesi gerekir.

Bu alanda kullanılan her node için genellikle aşağıdaki alanlar bulunur:

• id
• name
• parentId
• nodeType

DataTextField: Her Node’un ekranda gösterilecek metin alanını belirler. Varsayılan olarak name alanı kullanılır. Eğer veri kaynağında görüntülenecek metin farklı bir alanda tutuluyorsa bu property üzerinden ilgili alan adı tanımlanabilir.

DataValueField: Her Node’un benzersiz kimliğini temsil eden alanı belirler. Varsayılan olarak id kullanılır. Seçim, event ve binding işlemlerinin doğru çalışabilmesi için bu alanın benzersiz olması gerekir.

DataParentField: Node’lar arasındaki üst-alt ilişkiyi belirleyen alanı tanımlar. Varsayılan olarak parentId kullanılır. Root seviyesindeki kayıtlar için bu alanın boş veya null olması gerekir.

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.

Desteklenen örnek değerler:

• folder
• document
• virtualFolder
• version
• draft
• temp

Theme: 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.

ShowSearch: Bu özellik aktif edildiğinde Directory elementinin üst kısmında bir arama alanı gösterilir. Arama istemci tarafında çalışır ve Türkçe karakter uyumlu normalizasyon desteği sunar.

Bu özellik sayesinde kullanıcılar:

• klasör adı
• doküman adı
• eşleşen içerik yolu

üzerinden daha hızlı arama yapabilir.

ShowAddressBar: Bu özellik aktif edildiğinde elementin üst kısmında breadcrumb yapısı ve gezinme kontrolleri gösterilir. Kullanıcı bulunduğu klasör yolunu takip edebilir ve geri / ileri / yukarı mantığında hareket edebilir.

Bu özellik özellikle çok seviyeli klasör yapılarında gezinmeyi kolaylaştırır.

ClientPageSize: İstemci tarafında sayfalama yapılmasını sağlar. Özellikle çok fazla node bulunan klasör yapılarında performansı ve okunabilirliği iyileştirmek için kullanılabilir.

Örneğin bu alana 50 değeri verilirse, bir klasörde aynı anda en fazla 50 kayıt gösterilir. Sonraki kayıtlar için sayfa geçişi yapılabilir.

Style: Directory elementinin kapsayıcı alanına uygulanacak stil ayarlarını tanımlamak için kullanılır. Boyut, boşluk, hizalama veya özel görünüm ihtiyaçlarında kullanılabilir.

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.