Tree List: osnove

Nazaj: predstavitveni pregled

Pogodba metode treeList(): katere ključe potrebuje vrstica, kako se navedejo otroci in kaj od tega prihaja nespremenjeno iz mreže.

1. Pregled in namen

Stanje: [Live]. Vir: lib/plugins/wkfluentui/helper/widgets.php, metoda treeList(). Gradi na pogodbi dataGrid(), namesto da bi jo podvajala.

2. Predpogoji

osnovna pogodba dataGrid() že razumljena – Tree List podeduje $columns (key/label/align/mono/width) in konvencijo celic (navadno besedilo ubežano, ['html' => …] ubeže klicatelj) nespremenjeno.

3. Pojmi

Ena mreža, hierarhične vrstice: edina strukturna razlika glede na dataGrid() je v $rows – vrstice lahko nosijo gnezdene podrejene vrstice (rekurzivno, tako kot children pri tree()-u).

4. Prvi koraki

$rows = [
    [
        'id' => 1, 'name' => 'de', 'size' => '', 'children' => [
            ['id' => 2, 'name' => 'wiki', 'size' => ''],
            ['id' => 3, 'name' => 'blog', 'size' => ''],
        ],
    ],
    ['id' => 4, 'name' => 'en', 'size' => ''],
];
 
echo $widgets->treeList($columns, $rows, [
    'rowKey'      => 'id',
    'childrenKey' => 'children',
]);

5. Uporaba

Umešča se med DataGrid (veliko podobnih vrstic, ravno) in TreeView (hierarhija, vendar le en stolpec) – za hierarhične podatke z več stolpci (npr. raziskovalec datotečnega sistema s stolpci velikosti/datuma).

6. API referenca

treeList(array $columns, array $rows, array $opts = []): string v helper_plugin_wkfluentui_widgets. Prazen niz pri praznem $columns; prazen $rows izriše vrstico glave plus vrstico praznega stanja (besedilo empty).

7. Parametri, možnosti in stanja

Ključ	Tip	Pomen
`rowKey`	string	ključ stolpca z enolično vrednostjo vrstice – obvezen za `expanded`/`expandUrl`/`selection`
`childrenKey`	string	ključ v `$rows`, pod katerim so podrejene vrstice (rekurzivno, kot `children` pri `tree()`-u), privzeto `children`
`expanded`	polje vrednosti `rowKey`	začetno razširjene nadrejene vrstice; brez navedbe so vse nadrejene vrstice strnjene
`expandUrl`	callable `(string $key, bool $expand): string`	povezava za preklop brez JS na nadrejeno vrstico; psevdoključa `all`/`none` priskrbita URL-je za orodno vrstico »razširi/strni vse« – Expand/Collapse
`maxDepthIndent`	int (privzeto 6)	meja zamika – Adaptivity
`selection`	`'none'\|'multi'`	stolpec s potrditvenim poljem (`selection[]` v obrazcu klicatelja, kot `dataGrid()`); zahteva `rowKey`
`rowActions`	callable	celica dejanj na vrstico (kot `dataGrid()`)
`empty`, `ariaLabel`	string	tako kot pri `dataGrid()`

Generiran izris

Ena sama nativna <table role="treegrid"> (ista utemeljitev kot pri dataGrid(): ločena poddrevesa bi razsinhronizirala širine stolpcev) – vsaka vrstica nosi data-wk-depth="<n>" plus aria-level/aria-setsize/aria-posinset, nadrejene vrstice dodatno data-wk-expanded="true|false" in aria-expanded. Zamik prvega stolpca je strežniški vgrajeni slog (15 px na raven, omejen z maxDepthIndent-om).

Meja izrisa (zavezujoče): podrejene vrstice strnjene nadrejene vrstice se ne izrišejo v DOM (ne le hidden) – pri zelo globokih drevesih bi sicer ostala ista meja izrisa kot pri manjkajoči virtualizaciji v DataGridu, le nevidna namesto preprečena.

8. Popolni primeri

Glej odsek 4 plus Expand/Collapse za sodelovanje z expandUrl-om.

9. Omejitve in robni primeri

Brez razvrščanja, brez filtriranja, brez straničenja – hierarhični vrstni red je merodajen; kdor želi ravno razvrščati/filtrirati, uporabi dataGrid().
Podeduje omejitve dataGrid()-a: brez navideznega pomikanja, brez uredljivih celic (za to declarativeTable()).

10. Dostopnost in združljivost

Celoten pregled: Accessibility.

11. Odpravljanje težav

Simptom: nadrejena vrstica ne prikaže preklopnega trikotnika kot povezave.

Vzrok: manjka expandUrl ali vrstica nima vrednosti rowKey – brez obojega se izriše le statični trikotnik.

Rešitev: nastaviti rowKey + expandUrl (odsek 7).

12. Sorodne teme

predstavitveni pregled – vsaka kategorija
DataGrid: osnove – podedovana osnovna pogodba
TreeView: osnove – sorodna ideja hierarhije brez stolpcev

Zakasnjeno nalaganje poddrevesa

Ta dva ključa sta navedena za vsako vrstico, ne v $opts:

Ključ	Tip	Pomen
`lazy`	bool	Vrstica ima podrejene vrstice, vendar jih ne vsebuje. Kljub temu se izriše kot nadrejeno vozlišče, ki ga je mogoče razširiti.
`lazyUrl`	string	Naslov, s katerega `scripts/treelist.js` ob prvi razširitvi prenese poddrevo.

Prihranek je na strežniku, ne v brskalniku. treeList() skrčenih podrejenih vrstic tako ali tako ne izriše v DOM – klicatelj pa jih je doslej moral kljub temu vse sestaviti, ker metoda teče prek $row[$childrenKey]. Z lazy odpade prav ta sestava.

Naslov mora vrniti golo zaporedje elementov <tr> z enakimi vrednostmi data-wk-depth in aria-level, kot bi jih ta metoda ustvarila za ustrezno raven. Če globina ne ustreza, se logika krčenja zlomi: pripadnost poddrevesa izpelje le iz globine.

Obnašanje med delovanjem:

Za vsako vrstico se nalaga največ enkrat. Nato oznaka odpade in vrstica je običajno razširjeno nadrejeno vozlišče – krčenje in ponovna razširitev ne staneta ničesar več.
Če prenos ne uspe, oznaka prav tako odpade: naslednji klik sledi povezavi. Ponovni poskus na istem mestu bi uporabniku pustil gumb, ki poljubnokrat vidno ne naredi ničesar; navigacija deluje vedno in poddrevo prav tako prikaže.
Brez JavaScripta preklopnik sledi svojemu href. Če naj ta vodi na celotno stran namesto na zaporedje vrstic, nastavite še expandUrl – ta ima tedaj prednost.
Priložene podrejene vrstice imajo prednost pred lazy: delo je že opravljeno, drugi prenos pa bi lahko nasprotoval temu, kar je na zaslonu.