DataGrid: osnove

Osrednji gradnik za veliko enakovrstnih zapisov: tabela, ki zapolni ploščo in prenese spremembo velikosti, z razvrščanjem, izborom vrstic in množičnimi dejanji.

dataGrid() iz stolpcev in vrstic izriše tabelo, ki zapolni svojo površino: glava stolpcev ostane na mestu, pomikajo se le podatkovne vrstice. Ta stran opisuje osnovno pogodbo – stolpce, vrstice, vrstni red in širino stolpcev.

Nazaj: predstavitveni pregled

Stanje: [Live].

dataGrid() izriše namizno tabelo, ki zapolni podokno in je odporna na spremembo velikosti, z izbirnim razvrščanjem, izbiro vrstic in množičnimi dejanji – osrednji gradnik za »veliko podobnih zapisov kot tabela« v tej knjižnici. Ta stran dokumentira osnovno pogodbo (stolpci, vrstice, ustvarjene oznake, videz tabele, obstojnost širine stolpcev); podrobnosti, specifične za funkcije (razvrščanje, izbira, množična dejanja, filtriranje, straničenje, izvoz, dostopnost), so na pripadajočih podstraneh predstavitvenega pregleda.

Ciljna publika: vsak vtičnik DokuWiki, ki želi prikazati seznam podobnih zapisov (vrstice zbirke podatkov, seznam datotek, konfiguracijske vnose …) kot tabelo, namesto da bi gradil lastno logiko izrisovanja tabele.

• DokuWiki z omogočenim vtičnikom wkfluentui.
• helper_plugin_wkfluentui_widgets naložen prek plugin_load('helper', 'wkfluentui_widgets') – ne plugin_load('helper', 'wkfluentui') (vrne null, glej api → odsek »odpravljanje težav«).
• Za sortUrl/bulkActions s končnimi točkami strežnika: obravnavalec POST obrazca s preverjanjem sectok na strani klicatelja (gradnik zagotavlja le oznake, brez logike strežnika).

Nativna <table>, ne ponovna izvedba z div. Namerna arhitekturna odločitev: ločeni tabeli glave/telesa ali mreža div desinhronizirata širine stolpcev brez JavaScripta; nativna <table> ohranja glavo in telo poravnana ter brezplačno prinaša pravilno implicitno tabelarično semantiko. role=„grid“ (poleg aria-multiselectable pri multi) je nastavljen šele, ko je aktiven model izbire – čista prikazovalna tabela brez izbire ostane semantično tabela, ne gradnik »grid«.

Navadno besedilo proti HTML, ki mu je mogoče zaupati: vrednosti celic v $rows so privzeto navadno besedilo (gradnik jih ubeži prek hsc()); vrednost oblike ['html' => string] namesto tega izriše nespremenjen HTML, ki ga je že ubežal klicatelj – enaka konvencija kot povsod v tem API-ju (glej api → odsek »koncepti«, konvencija ubežanja).

Z vsebnikom vodena prilagodljivost: brez prelomne točke vidnega polja, mreža sledi širini svojega podokna – podrobnosti: adaptivity.

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
$columns = [
    ['key' => 'id',     'label' => 'ID',     'align' => 'right', 'mono' => true, 'width' => '4rem'],
    ['key' => 'name',   'label' => 'Ime'],
    ['key' => 'status', 'label' => 'Stanje', 'sortable' => false],
];
 
$rows = [
    ['id' => 1, 'name' => 'Preveri pravilo požarnega zidu', 'status' => 'odprto'],
    ['id' => 2, 'name' => 'Preveri opravilo varnostne kopije', 'status' => 'opravljeno'],
];
 
echo $widgets->dataGrid($columns, $rows, [
    'ariaLabel' => 'Seznam opravil',
    'empty'     => 'Ni vnosov.',
]);

Napačno: posredovati $rows kot navaden nabor vrednosti brez ključev stolpcev ([1, 'Preveri pravilo požarnega zidu', 'odprto']). dataGrid() prebere vrednosti celic prek $row[$col['key']] – brez ujemajočih ključev vsaka celica ostane prazna, brez sporočila o napaki (glej odsek 11, odpravljanje težav).

public function dataGrid(array $columns, array $rows, array $opts = []): string

Povzetek: izriše namizno podatkovno tabelo iz definicij stolpcev in podatkov vrstic, izbirno z razvrščanjem, izbiro vrstic in orodno vrstico množičnih dejanj.

Povratna vrednost: string – popoln fragment HTML (<div class="wk-datagrid">…</div>). Prazen niz, kadar je $columns prazen (brez tabele brez stolpcev) – ne glede na to, ali $rows vsebuje vnose.

Seznam asociativnih polj ključ => vrednost celice. Niz se ubeži kot navadno besedilo; ['html' => string] izriše HTML, ki mu je mogoče zaupati in ga je ubežal klicatelj, brez preverjanja.

<div class="wk-datagrid" data-wk-selection="…" data-wk-persist="…"> → izbirno <div class="wk-datagrid__bulkbar"> → nativna <div class="wk-datagrid__body"><table>…</table></div> z lepljivim <thead class="wk-datagrid__head">. Vsaka celica glave nosi scope="col" (izrecna semantika glave stolpca – skladno z odločitvijo za uporabo nativne tabelarične semantike namesto ponovne izvedbe ARIA, glej odsek 3).

Stolpci si sledijo v tem vrstnem redu, da se vsak seznam v hiši bere enako:

1. gumb za razširitev vrstice (inspector), če obstaja
2. potrditveno polje za izbiro (selection => 'multi')
3. glavni stolpec – polje, ki vrstico poimenuje (primary, privzeto prvi stolpec)
4. meni vrstice (rowMenu) – meni s tremi pikami je za imenom, h kateremu spada
5. vsebinski stolpci

Glava je ena vrstica. Podatkovna celica besedilo skrajša (max-width: 0 in text-overflow), zato širino stolpca določa celica glave – ta pa se ne prelomi. Če stolpci ne gredo drug ob drugega, tabela zavzame svojo naravno širino, preostanek pa se pomika vodoravno; glava in podatki se pri tem premikajo skupaj, ker so v istem okvirju. Brez tega pravila brskalnik razdeli razpoložljivo širino in pri dovolj stolpcih zloži naslove črko za črko drugo pod drugo – izmerjeno pri 37 stolpcih: 270 px visoka vrstica glave proti 28 px danes.

Če stolpec zožite, vidite skrajšan naslov z title – enako zagotovilo kot v podatkovni celici.

Tabela, ki jo je mogoče razvrščati in večkratno izbrati, z množičnim dejanjem (združuje osnove + razvrščanje + izbiro + množična dejanja):

$columns = [
    ['key' => 'id', 'label' => 'ID', 'align' => 'right', 'mono' => true, 'width' => '4rem'],
    ['key' => 'name', 'label' => 'Ime'],
    ['key' => 'status', 'label' => 'Stanje'],
];
 
echo $widgets->dataGrid($columns, $rows, [
    'sort'        => ['name', 'asc'],
    'persistKey'  => 'opravila:seznam',
    'selection'   => 'multi',
    'rowKey'      => 'id',
    'bulkActions' => [
        ['label' => 'Označi kot opravljeno', 'element' =>
            '<button type="submit" name="do" value="done" class="wk-btn">Označi kot opravljeno</button>'],
    ],
    'ariaLabel' => 'Seznam opravil',
    'empty'     => 'Ni opravil.',
]);

• Brez navideznega drsenja – glej Data Paging and Scrolling.
• Brez urejljivih celic na tej stopnji – glej Data Editing (množična dejanja), odsek urejanja mreže.
• Brez filtra glave stolpca – glej filtering.
• Brez razvrščanja po več stolpcih – glej sorting → omejitve.
• persistKey mora biti stabilen med ogledi strani in edinstven na primerek mreže – dve mreži z enakim persistKey si po nesreči delita isto stanje localStorage.

• Popoln pregled ARIA/tipkovnice: accessibility (konsolidirano, tu ni podvojeno).
• Brez JavaScripta tabela ostane povsem uporabna; razvrščanje brez JS zahteva sortUrl (nadomestilo na strani strežnika), sicer glave ostanejo tiho nerazvrstljive.
• Združljivost brskalnikov: brez zahtev, ki bi presegale osnovno podporo CSS Grid/Flexbox (enako preostanku knjižnice).

Simptom: celice ostanejo prazne, čeprav $rows vsebuje podatke.

Vzrok: ključi vrstic v $rows se ne ujemajo z $columns[]['key'] (tipkarska napaka ali navaden nabor vrednosti namesto asociativnega polja).

Rešitev: preverite vsak $columns[]['key'] glede na dejanske array_keys() vrstice v $rows.

Simptom: stolpec s potrditvenimi polji manjka kljub selection => 'multi'.

Vzrok: rowKey manjka v $opts – gradnik tiho degradira na none (glej odsek 7, obnašanje ob napaki).

Rešitev: nastavite $opts['rowKey'] na edinstven ključ stolpca.

• predstavitveni pregled – vse kategorije
• FluentUI: javni API pomočnika – popolna pogodba metod vseh pomočnikov
• FluentUI: osnovni katalog gradnikov – DeclarativeTable (katalog stopnja 2)
• SQLite Data Studio: skrbniški vmesnik – prvi porabnik (SQL Workbench)