1. Tree Elementine Genel Bakış

Kuika’nın Tree elementi, hiyerarşik veri yapılarının kullanıcıya katmanlı ve düzenli bir şekilde sunulmasını sağlayan güçlü bir görselleştirme elementidir. Bir öğenin alt öğelerini açıp kapatmaya imkân tanıyan bu yapı, karmaşık veri setlerini kolay anlaşılır bir formatta göstererek kullanıcı deneyimini artırır.

Tree elementi; klasör yapıları, menüler, kategoriler–alt kategoriler, organizasyon şemaları veya ilişkisel veri listeleri gibi çok seviyeli içerikleri göstermek için kullanılabilir. Özellikle büyük veri gruplarının düzenli görünmesi gereken arayüzlerde tercih edilir.

Tree elementi yalnızca web uygulamalarında desteklenmektedir.

1.1. Tree Elementinin Sık Kullanım Senaryoları

• Dosya / Klasör Yapıları: Bir dosya yöneticisinde klasörlerin ve alt klasörlerin gösterimi. Örneğin: Dokümanlar > Projeler > 2025 > Taslaklar
• Kategori ve Alt Kategori Listeleri: E-ticaret uygulamalarında ürün kategorilerinin seviyelendirilmiş sunumu. Örn: Elektronik → Bilgisayar → Laptop → Aksesuarlar
• Organizasyon Şemaları: Şirket yapısını birim → alt birim → çalışan seviyesinde göstermek.
• İçerik Yönetim Sistemleri (CMS): Sayfa → alt sayfa → modül → içerik yapılarının sunumu.
• Rol ve Yetki Yönetimi: Rol → izin → alt izin ilişkilerinin görsel olarak gösterilmesi.
• Menü Yapılarının Yönetimi: Çok seviyeli menü veya navigasyon ağaçlarının yönetimi ve düzenlenmesi.
• İlişkisel Veri Gösterimleri: Bir kayda bağlı alt kayıtların, onların alt kayıtlarının hiyerarşik şekilde sunulması.
• Proje & Görev Yönetimi: Proje → ana görev → alt görev → alt-alt görev şeklinde yapıların gösterimi.
  
  

2. Temel Özellikler

• Hiyerarşik yapı desteği: Tree elementi, çok seviyeli veri yapılarını (ana öğe → alt öğe → alt-alt öğe) temiz ve düzenli bir biçimde sunar.
• Dinamik veri bağlama: Veri kaynağından (Datasource, REST API, Managed DB) gelen kayıtlar otomatik olarak hiyerarşik yapıya dönüştürülerek görüntülenebilir.
• Seviye bazlı görsel hiyerarşi: Her seviye için girinti, ikon, çizgi ve yapı farklılaşarak kullanıcıya daha anlaşılır bir görünüm sağlar.
• Tıklanabilir node yapısı: Her node üzerinde yer alan elementler (Label, Icon, Image vb.) kullanıcı etkileşimini destekler.
• Çok yönlü kullanım: Menü, klasör görünümü, CMS içerik listesi, kategori ağaçları, organizasyon şemaları gibi pek çok farklı yapıda kullanılabilir.

2.1.Tree Elementi Özellikleri

Tree elementi, özel bir liste olarak kullanılamaz; bu nedenle bir veri tablosuna bağlıdır. Veri bağlama işlemi için aşağıdaki adımları izleyin:

1. Datasource Oluşturma

1. Datasource modülüne girin.
2. Yeni bir tablo oluşturun ve aşağıdaki kolonları tanımlayın:
   
   • ID (Guid): Verinin benzersiz kimliği
   • Title (String): Görüntülenecek öğenin başlığı
   • ParentID (Guid): Verinin bağlı olduğu üst öğenin kimliği (Ana öğeler için null değerini kullanın)

2. SQL Action Oluşturma

1. Actions modülüne gidin.
2. + ikonuna tıklayın ve New SQL Action seçeneğini seçin.
3. Aşağıdaki SQL komutunu girin:

SELECT * FROM your_datasource_name

4. CREATE butonuna tıklayarak SQL Action’ı oluşturun.

3. Tree Elementine Veri Bağlama

1. Tree elementini seçin.
2. Sağ kenardaki Properties panelinden Options bölümüne gidin.
3. Actions alanına tıklayın ve oluşturduğunuz SQL Action’ı seçin.
4. Aşağıdaki alanları yapılandırın:
   
   • Field to Display ID: Verilerin gösterileceği veri tabanı kolonunu seçin (örneğin, Title).
   • Field to Use as Key: Verinin benzersiz anahtarı olarak kullanılacak kolon (genellikle ID seçilir).
   • Field to Use as Parent: Alt öğelerin hangi üst öğeye ait olduğunu belirleyen kolon (ParentID). Eğer veri en üst seviyede yer alacaksa, bu alanın değeri null olarak döndürülmelidir.
   • Checkable: Bu seçenek aktif hale getirildiğinde, Tree öğeleri yanlarında seçim kutusu (checkbox) ile birlikte görüntülenir. Kullanıcıların birden fazla öğe seçmesine olanak tanır.
   • Default Checked Keys: Uygulama ilk açıldığında hangi node'ların otomatik seçili gelmesini istediğinizi belirleyen alandır.
     
     • Statik bir ID listesi girebilirsiniz.
     • Symbol Picker üzerinden dinamik olarak da doldurulabilir.
     • Checkable özelliği kapalıysa çalışmaz.

2.2. Elemente Eklenebilen Aksiyonlar

Tree elementi, kullanıcı etkileşimlerine bağlı olarak üç farklı aksiyon tetikleyebilir. Bu aksiyonlar, kullanıcı bir node’u seçtiğinde, değiştirdiğinde veya checkbox kullanıyorsa işaretleme yaptığında devreye girer. Tree elementini seçtikten sonra sağ panelde Actions bölümünde aşağıdaki tetikleyiciler görünür:

onChange

Kullanıcı Tree yapısında bir seçim veya genişletme/daraltma işlemi yaptığında tetiklenir. Bu aksiyon genellikle aşağıdaki senaryolarda kullanılır:

• Seçilen node bilgisine göre sayfa içeriğini güncelleme
• Seçilen kategoriye göre liste veya tablo filtreleme
• Node değiştiğinde detay alanını doldurma

onSelect

Kullanıcı bir node’a tıkladığında veya bir node’u seçtiğinde tetiklenir. onSelect, özellikle “hangi öğeye tıklandığını” yakalamak için kullanılır.

Kullanım örnekleri:

• Tıklanan öğenin detay sayfasını açmak
• Node ID’sini başka bir aksiyonda parametre olarak kullanmak
• Alt öğeleri dinamik olarak yüklemek

onCheck

Checkable özelliği açıksa aktif olur. Kullanıcı bir node’un yanındaki checkbox'ı işaretlediğinde veya işareti kaldırdığında tetiklenir.

Kullanım örnekleri:

• Birden fazla node seçimi gerektiren izin/rol yönetimi
• Seçili node ID’lerinin bir listeye kaydedilmesi
• Çoklu seçim sonrası toplu işleme başlatılması

3. Tree Elementi Nasıl Kullanılır? 

Bu bölümde Tree elementinin uçtan uca kullanımını hiyerarşik bir veri yapısı üzerinden ele alacağız.

Senaryo: Kategori ve Alt Kategori Yapısının Tree ile Gösterimi

Bir yönetim paneli veya içerik yönetim sisteminde, kullanıcıların kategori ve alt kategori yapılarını düzenli bir şekilde inceleyebilmesi gerekir. Bu tür veriler, düz liste yerine Tree elementi ile gösterildiğinde çok daha anlaşılır hale gelir.

Senaryoda:

• Hiyerarşik veriler SQL Action ile dinamik olarak üretilir.
• Sayfa açıldığında Tree verileri otomatik yüklenir.
• Kullanıcı parent öğeleri genişletip daraltabilir.
• Alt öğeler doğru hiyerarşiyle listelenir.

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

DataSources modülünde tablo oluşturma: 

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

• Önemli Alan adları:
  
  • Id: Kategori kayıtlarının benzersiz kimliğini temsil eder ve Tree yapısındaki her bir node’un anahtar alanıdır.
  • Title: Tree elementinde kullanıcıya gösterilen kategori adını ifade eder.
  • ParentCategoryId: Kategoriler arasındaki hiyerarşik ilişkiyi kurmak için kullanılan üst kategori bilgisidir.
  • IsChecked: Tree yüklendiğinde ilgili kategorinin varsayılan olarak seçili olup olmayacağını belirler.
• Ek olarak “ProductCategories” adında bir yeni tablo daha oluşturun.
• Kurulması gereken tablo yapısı aşağıdaki gibidir:
  

• Önemli Alan adları:
  
  • Id: Ürün kayıtlarının benzersiz kimliğini temsil eder.
  • ProductName: Ürünün liste ve detay ekranlarında gösterilen ad bilgisidir.
  • CategoryId: Ürünün bağlı olduğu kategori bilgisini tutar ve Tree elementinden yapılan seçime göre filtreleme yapılmasını sağlar.
  • Price: Ürünün satış fiyatı bilgisini ifade eder.
  • Stock: Ürünün mevcut stok miktarını gösterir ve envanter takibi için kullanılır.

Adım 2 - Gerekli Aksiyonları Tanımlama

Arayüzde verileri göstermek ve veri eklemek için: 

• Üç aksiyon tanımlamanız gerekir.
• Datasources modülü içerisinde Actions > New SQL Action sekmesinden yeni aksiyon ekleyin.

• Örnek Verileri Ekleyen Aksiyon (InsertProductCategories): Uygulamayı örnek verilerle test etmek için aşağıdaki SQL aksiyonunu ekleyin ve TEST butonuna basın.

DECLARE @Electronics UNIQUEIDENTIFIER = NEWID();
DECLARE @Computers UNIQUEIDENTIFIER = NEWID();
DECLARE @Laptops UNIQUEIDENTIFIER = NEWID();
DECLARE @Desktops UNIQUEIDENTIFIER = NEWID();
DECLARE @Phones UNIQUEIDENTIFIER = NEWID();
DECLARE @Smartphones UNIQUEIDENTIFIER = NEWID();
DECLARE @Accessories UNIQUEIDENTIFIER = NEWID();
DECLARE @Chargers UNIQUEIDENTIFIER = NEWID();
DECLARE @Cables UNIQUEIDENTIFIER = NEWID();

INSERT INTO ProductCategories (Id, Title, ParentCategoryId, IsChecked)
VALUES
(@Electronics, 'Electronics', NULL, 0),
(@Computers, 'Computers', @Electronics, 0),
(@Laptops, 'Laptops', @Computers, 0),
(@Desktops, 'Desktops', @Computers, 0),
(@Phones, 'Phones', @Electronics, 0),
(@Smartphones, 'Smartphones', @Phones, 0),
(@Accessories, 'Accessories', NULL, 0),
(@Chargers, 'Chargers', @Accessories, 0),
(@Cables, 'Cables', @Accessories, 0);

INSERT INTO Products (Id, ProductName, CategoryId, Price, Stock)
VALUES
(NEWID(), 'Dell XPS 13',           @Laptops,     54999.00, 12),
(NEWID(), 'Lenovo ThinkPad T14',   @Laptops,     46999.00, 8),
(NEWID(), 'HP ProDesk',            @Desktops,    32999.00, 5),
(NEWID(), 'iPhone 15',             @Smartphones, 69999.00, 7),
(NEWID(), 'Samsung Galaxy S24',    @Smartphones, 64999.00, 9),
(NEWID(), 'USB-C Charger 65W',     @Chargers,      899.00, 40),
(NEWID(), 'HDMI Cable 2m',         @Cables,        249.00, 55);

Uygularken ProductCategories ve Products kısımlarını silip tekrar yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

• Kategorileri Sağlayan Aksiyon (GetCategoryTree):
  

SELECT *
FROM ProductCategories
ORDER BY Title;

Uygularken ProductCategories kısmını silip tekrar ProductCategories yazıp Enter’a basınız. Böylelikle tablo adının önünde doğru şema adı eklenecektir.

• Ürünleri Filtreleyen ve Sağlayan Aksiyon (GetProducts):
  

DECLARE @Ids NVARCHAR(MAX) = CAST(@CategoryIds AS NVARCHAR(MAX));

SELECT
    Id,
    ProductName,
    Price,
    Stock
FROM Products
WHERE CategoryId IN (
    SELECT TRY_CAST(LTRIM(RTRIM(value)) AS UNIQUEIDENTIFIER)
    FROM STRING_SPLIT(@Ids, ',')
    WHERE TRY_CAST(LTRIM(RTRIM(value)) AS UNIQUEIDENTIFIER) IS NOT NULL
)
ORDER BY ProductName;

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

• UI Design modülünü açın.
• Sayfaya ADD ACTION butonundan Initial Actions > Custom > Managed Db > GetCategoryTree aksiyonunu ekleyin.
  

Adım 4 – Ana Sayfa Element Ekleme

• UI Design modülünü açın.
• Sol panelden Elements > Display > Tree elementini sayfaya sürükleyip bırakın.
• Tree elementine veri sağlayacak aksiyonu Tree > Properties > Options > Action > GetCategoryTree ekleyin. Açılan alanları aşağıdaki gibi tanımlayın.
  

• İşaretleyip filtreleme yapabilmek için Tree > Properties > Checkable > Açık olarak ayarlayın.
• Tree elementine, kategorilere tıklandığında filtrelenmesi için Tree > Properties > Add Action > onCheck > Custom > Managed Db > GetProducts aksiyonunu ekleyin.
  

1. Son olarak sol yan panelde yer alan Action Tree alanından GetProducts aksiyonunun yanındaki ikondan sayfaya sürükleyip bırakın.
   

• Açılan ekranda aşağıdaki seçimleri yapın ve oluştura basın. Böylelikle Tree elementinde kategori seçimleri sonrasında filtrelenmiş ürünleriniz listelenecektir.
  

Preview

Uygulama test edildiğinde, ekranın sol bölümünde hiyerarşik bir Tree (Ağaç) yapısı yer alır. Bu yapı üzerinden kullanıcılar ürün kategorilerini üst ve alt kırılımlarıyla birlikte görüntüleyebilir ve birden fazla kategori için seçim yapabilir.

Tree üzerinde Electronics → Computers → Desktops / Laptops gibi alt kategoriler işaretlendiğinde, seçilen kategorilere ait ürünler ürün listesinde otomatik olarak filtrelenerek görüntülenir. Liste alanında ürün adı, fiyat ve stok bilgileri eş zamanlı olarak güncellenir ve yalnızca seçili kategorilerle ilişkili ürünler gösterilir.

4. Ortak Özellikler (Properties)

Tree 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)

• Veri yapısını doğru kurgulayın. Tree elementi hiyerarşik yapı gerektirir; bu nedenle ID ve ParentID alanlarının tutarlı olması, görüntülemenin doğru çalışmasını sağlar.
• onSelect ve onCheck aksiyonlarını ayrıştırın. Seçim ile işaretlemenin farklı sonuçları vardır; her iki tetikleyiciyi doğru bağlamda kullanarak karmaşayı önleyin.

6. Kısıtlamalar

• Tree elementi yalnızca web uygulamalarında desteklenir. Mobil uygulamalarda Tree yapısı görüntülenemez.
• Parent–child ilişkisi doğru kurulmazsa veri görüntülenmez. ParentID boş veya hatalı tanımlandığında öğeler ağaç yapısında yer almayabilir.
• onCheck tetikleyicisi sadece Checkable aktifse çalışır. Checkable kapalı olduğunda checkbox davranışı veya işaretleme senaryoları desteklenmez.