DataGrid: sorting

Nazaj: predstavitveni pregled

Stanje: [Live]. Vir: lib/plugins/wkfluentui/helper/widgets.php (oznake glave) in lib/plugins/wkfluentui/scripts/datagrid.js (razvrščanje na strani odjemalca).

Poglobi ključa sort/sortUrl iz osnovne pogodbe dataGrid(): dve medsebojno izključujoči poti razvrščanja na stolpec — na strani odjemalca (privzeto) in na strani strežnika (nadomestilo brez JS oz. za straničene/filtrirane podatke).

• Že razumljena osnovna pogodba dataGrid() ($columns/$rows/$opts).
• Za razvrščanje na strani strežnika: shema parametrov zahtevka (npr. sort/dir), ki jo klicatelj sam določi in preveri.

Medsebojno izključujoče na stolpec: ko je nastavljen $opts['sortUrl'], vsak razvrstljiv stolpec izriše povezavo namesto gumba za razvrščanje — razvrščanje na strani odjemalca ostane izklopljeno za celotno tabelo, brž ko je nastavljen sortUrl (brez mešanega načina na stolpec).

Ločevanje izrisovanja in razvrščanja: pri razvrščanju na strani strežnika dataGrid() ne razvrsti $rows sam — sortUrl zagotovi le povezavo; klicatelj razvrsti podatke pred klicem (tipično prek SQL ORDER BY).

echo $widgets->dataGrid($columns, $rows, [
    'sort' => ['name', 'asc'],
]);

Napačno: posredovati $_GET['sort'] brez preverjanja kot ključ stolpca v stavek SQL ORDER BY (glej odsek 7, varnost).

echo $widgets->dataGrid($columns, $rows, [
    'sort' => ['name', 'asc'],   // začetno razvrščanje: stolpec 'name', naraščajoče
]);

Klik na razvrstljivo glavo stolpca znova razvrsti vrstice, ki so že v DOM — številčno zavedno („10“ se razvrsti za „9“, ne leksikografsko pred njim), s kazalnikom puščice in atributom aria-sort. Če je dodatno nastavljen $opts['persistKey'], si mreža zapomni nazadnje izbrano razvrščanje med ogledi strani (podrobnosti: osnove → širine stolpcev in obstojnost).

$sortUrl = function ($key) {
    return wl($ID, ['sort' => $key, 'dir' => ($_GET['sort'] ?? '') === $key
        && ($_GET['dir'] ?? '') === 'asc' ? 'desc' : 'asc']);
};
 
echo $widgets->dataGrid($columns, $rows, [
    'sort'    => [$_GET['sort'] ?? 'name', $_GET['dir'] ?? 'asc'],
    'sortUrl' => $sortUrl,
]);

Varnost: wl() ustvari notranji URL, varen glede na CWE-601 (brez odprte preusmeritve prek uporabniškega vnosa v ciljnem URL-ju). Vrednost $_GET['sort'] mora klicatelj pred vsako uporabo SQL preveriti glede na znan seznam stolpcev (in_array($_GET['sort'], array_column($columns, 'key'), true)) — sicer je mogoč vbrizg SQL prek parametra razvrščanja (CWE-89). dataGrid() sam tega preverjanja ne izvede, ker stolpca nikoli ne primerja s poizvedbo SQL.

Obnašanje ob napaki: nerazvrstljiv stolpec (sortable ⇒ false) z nastavljenim sort kot začetnim razvrščanjem → brez napake, stolpec se kljub temu izriše brez uporabniškega vmesnika za razvrščanje, aria-sort ostane nenastavljen nanj.

$columns = [
    ['key' => 'id',     'label' => 'ID'],
    ['key' => 'status', 'label' => 'Stanje', 'sortable' => false],
];

• Razvrščanje po več stolpcih (razvrsti po stolpcu A, nato B) ni izvedeno — vsako razvrščanje popolnoma nadomesti prejšnjega.
• Razvrščanje na strani odjemalca bere vidno besedilo celice; stolpci s celicami ['html' => …] se razvrstijo po besedilni vsebini HTML, ne po ločeni vrednosti za razvrščanje.

• aria-sort je pravilno nastavljen le na trenutno razvrščenem, razvrstljivem stolpcu — popoln pregled: accessibility.
• Brez JavaScripta stolpec z nastavljenim sortUrl ostane povsem uporaben (prava povezava); stolpec brez sortUrl ostane nerazvrstljiv brez JavaScripta — to je dokumentirano stanje brez JS, ne napaka.

Simptom: klik na glavo stolpca ne razvrsti.

Vzrok: bodisi sortable ⇒ false na tem stolpcu, bodisi je nastavljen $opts['sortUrl'] (onemogoči razvrščanje na strani odjemalca za celo mrežo) in končna točka strežnika za povezavo dejansko ne razvrsti podatkov znova.

Rešitev: preverite vrednost sortable stolpca; pri nastavljenem sortUrl preverite, ali ciljna končna točka dejansko razvrsti $rows glede na parameter zahtevka, preden znova pokliče dataGrid().

• predstavitveni pregled — vse kategorije
• DataGrid: osnove — osnovna pogodba dataGrid(), referenca stolpcev
• DataGrid: accessibility — aria-sort v popolnem pregledu