TreeView: osnove

1. Pregled in namen

Stanje: [Live]. Vir: lib/plugins/wkfluentui/helper/widgets.php, metoda tree() (vrstica 44).

tree() izriše rekurzivno navigacijsko drevo iz gnezdenih <details>/<summary> elementov — povsem uporabno brez JavaScripta. Ciljna publika: vsak vtičnik, ki potrebuje hierarhično navigacijo strani/predmetov (npr. drevo predmetov v stranski vrstici), brez gradnje lastne logike tipkovnice/razširjanja-strnjevanja.

Pomembno razmejevanje: tree() je navigacijsko drevo — vsako vozlišče s href je povezava na drugo stran, ne odjemalsko izbirljivo podatkovno drevo z lastnim stanjem (za to glej Selection / Checkboxes).

2. Predpogoji

DokuWiki z omogočenim vtičnikom wkfluentui.
helper_plugin_wkfluentui_widgets naložen prek plugin_load('helper', 'wkfluentui_widgets').

3. Pojmi

Nativna semantika namesto obnove ARIA: <details>/<summary> brezplačno ponuja razširjanje/strnjevanje, upravljanje s tipkovnico (Enter/preslednica) in implicitno semantiko za bralnik zaslona — obnova role="tree" ni potrebna, dokler ni aktivna nobena izbira (glej Accessibility za razliko, ko se doda selection).

Rekurzija: vozlišče z children se samo znova izriše prek tree() — ista metoda gradi hierarhije poljubne globine.

4. Prvi koraki

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
echo $widgets->tree([
    ['label' => 'Povezave', 'href' => wl($ID, ['ns' => 'connections'])],
    [
        'label' => 'Tabele',
        'children' => [
            ['label' => 'naloge', 'href' => wl($ID, ['t' => 'naloge']), 'active' => true],
            ['label' => 'uporabniki', 'href' => wl($ID, ['t' => 'uporabniki'])],
        ],
    ],
]);

Napačno: ustvariti vozlišče brez href IN brez children, v pričakovanju, da se bo pojavilo kot klikljivo mesto za zapolnitev. Brez obojega se vozlišče izriše kot golo, neinteraktivno besedilo — to je pravilna, dokumentirana degradacija, ne napaka.

5. Uporaba

Primer uporabe	Vzorec
Drevo predmetov v stranski vrstici	`tree()` neposredno v regiji stranske vrstice — prvi porabnik `wksqliteds`
Oznaka trenutne strani	nastaviti `active ⇒ true` na ustreznem listnem vozlišču
Kontekstni podatki na povezavi	`dataSql` za prosto uporabne atribute `data-sql` (konvencija SQL Workbencha)

6. API referenca

Metapodatek	Vrednost
Jezik	PHP
Imenski prostor	`helper_plugin_wkfluentui_widgets`
Datoteka	`lib/plugins/wkfluentui/helper/widgets.php`
Vidnost	public
Stabilnost	stabilno (raven 1)

public function tree(array $nodes): string

Povzetek: izriše rekurzivno, brez JavaScripta delujoče navigacijsko drevo iz gnezdenih definicij vozlišč.

Vrnjena vrednost: string — <ul class="wk-tree">…</ul>. Prazen niz pri praznem $nodes.

7. Parametri, možnosti in stanja

$nodes (na vnos, rekurzivno)

Ključ	Tip	Obvezno	Pomen
`label`	string	Da	besedilo vozlišča (ubežano prek `hsc()`)
`href`	string	Ne	ciljni URL; če manjka, je vozlišče golo združevalno besedilo (brez povezave)
`active`	bool	Ne	označi trenutno vozlišče; pri skupinskem vozlišču dodatno odpre njegov `<details>`
`dataSql`	string	Ne	prosto uporaben atribut `data-sql` na povezavi (prvi porabnik: SQL Workbench)
`children`	array	Ne	gnezdena vozlišča, ista shema — spremeni vozlišče v skupino `<details>/<summary>`

Generiran izris

<ul class="wk-tree"> → na vozlišče <li>, pri children gnezdeno kot <details><summary>Label</summary><ul>…</ul></details>.

Vedenje ob napaki

Pogoj	Vedenje
`$nodes` prazen	vrne prazen niz, brez napake
Vozlišče brez `href` in brez `children`	izriše se kot golo, neinteraktivno besedilo — brez napake
`active ⇒ true` na več vozliščih hkrati	brez preverjanja — vsa označena vozlišča dobijo aktivni razred, klicatelj je odgovoren za enoličnost

8. Popolni primeri

echo $widgets->tree([
    [
        'label' => 'de',
        'children' => [
            ['label' => 'wiki', 'href' => wl($ID, ['ns' => 'de:wiki']), 'active' => true],
            ['label' => 'blog', 'href' => wl($ID, ['ns' => 'de:blog'])],
        ],
    ],
    ['label' => 'en', 'href' => wl($ID, ['ns' => 'en'])],
]);

9. Omejitve in robni primeri

active označi le trenutni ogled strani; pravo izbiro (radio/checkbox na vozlišče, form-POST) zagotavlja način selection — Selection / Checkboxes.
Brez lenega nalaganja — vsi children morajo biti popolnoma prisotni ob klicu; za zelo velika drevesa (tisoče vozlišč) je to praktična zgornja meja, analogno manjkajoči virtualizaciji pri dataGrid().
Premikanje vozlišč: Drag & Drop (vidne povezave ▲/▼ plus izbirna plast vlečenja).

10. Dostopnost in združljivost

Celoten pregled: Accessibility (konsolidirano, tu ni podvojeno).
Povsem uporabno brez JavaScripta — brez odvisnosti od postopnega izboljšanja za osnovno funkcijo.
Združljivost brskalnikov: odvisno od nativne podpore za <details> (vsi trenutni brskalniki; starejši brskalniki brez podpore prikažejo vsebino trajno razširjeno namesto zložljive — degradirano, ne neuporabno).

11. Odpravljanje težav

Simptom: skupinsko vozlišče se ne odpre samodejno, čeprav ima podrejeno vozlišče active ⇒ true.

Vzrok: active mora biti nastavljen na samem skupinskem vozlišču, da se njegov <details> izriše odprt — označitev podrejenega vozlišča ne odpre samodejno nadrejene skupine.

Rešitev: dodatno nastaviti active ⇒ true na nadrejenem vozlišču, če naj bo skupina začetno odprta.

12. Sorodne teme

predstavitveni pregled — vsaka kategorija
FluentUI: javni API pomočnika — popolna pogodba metod
SQLite Data Studio — prvi porabnik (drevo predmetov v stranski vrstici)