Vertical Grid: osnove

Nazaj: predstavitveni pregled

Stanje: povsem [Live] — osnovna mreža, skupine/odseki, način samo za branje, stanje validacije in oznaka obveznega polja so implementirani (vir: lib/plugins/wkfluentui/helper/widgets.php, metoda propertyGrid()).

propertyGrid() prikaže en predmet kot dvostolpčno mrežo oznaka/vrednost — atribute kot vrstice, ne kot stolpce (ustreznica dataGrid()-u, ki prikazuje veliko predmetov kot vrstice). Ciljna publika: vsak obrazec ali inšpektor lastnosti, ki potrebuje pare oznaka+kontrolnik, brez gradnje lastnega CSS-ja za mrežo obrazca.

• DokuWiki z omogočenim vtičnikom wkfluentui.
• helper_plugin_wkfluentui_widgets naložen prek plugin_load('helper', 'wkfluentui_widgets').
• Kontrolnike (controlHtml) priskrbi klicatelj — propertyGrid() ne izriše niti enega vnosnega polja, le okvir okoli njega (glej polja obrazca za ustrezne gradnike kontrolnikov).

Dve vlogi, en gradnik: mreža obrazca (vnosna polja s stolpcem oznak) in inšpektor lastnosti (kontekstno občutljiv prikaz izbranega predmeta, tipično v auxbarju) uporabljata isto metodo — razlika je le v $opts['mode'] (odsek 7).

Navadno besedilo proti zaupanja vrednemu HTML-ju: label je ubežan (escape) prek hsc(); controlHtml je zaupanja vreden HTML, ki ga je že izdelal klicatelj — enaka konvencija kot povsod v tem API-ju (glej api → odsek „pojmi").

Povratna združljivost: propertyGrid($rows) brez naknadno dodanih ključev (section/value/state/required) se izriše bajtno identično prvotni različici z enim parametrom.

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
 
echo $widgets->propertyGrid([
    ['label' => 'Ime', 'controlHtml' => '<input type="text" name="name" required>'],
    ['label' => 'Aktivno', 'controlHtml' => '<input type="checkbox" name="active">'],
]);

Napačno: neposredno posredovanje surovega uporabniškega vnosa kot controlHtml ('controlHtml' => $_POST['x']). controlHtml se izpiše nepreverjen — klicatelj tu nosi polno odgovornost za XSS (CWE-79).

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

Povzetek: izriše dvostolpčno mrežo obrazca oznaka/kontrolnik (CSS-mreža, fit-content(22rem) minmax(0, 1fr)) iz definicij vrstic, po izbiri združenih v zložljive odseke in/ali v načinu samo za branje.

Vrnjena vrednost: string — celoten HTML-fragment (<div class="wk-property-grid">…</div>). Prazen niz pri praznem $rows.

Vrstice z isto vrednostjo section se združijo pod naslovom odseka (polna širina, polkrepko s tanko ločnico — videz fieldset-legend iz _admin-forms.css); naslov je zložljiv s klikom/Enter-jem (temelji na <details>-u, deluje brez JavaScripta). Vrstice brez section se izrišejo pred prvim odsekom. Referenca: kategorije DevExpress VerticalGrid, skupine Table Designerja ADS.

propertyGrid($rows, ['mode' => 'display']): vrstice brez controlHtml-ja sprejmejo value (odsek zgoraj); vsebnik nosi .wk-property-grid--display (brez vnosnega chroma, vrednosti so izbirljive, lebdenje vrstice prek --wk-admin-hover). To je privzeto za inšpektor lastnosti — slog obrazca le tam, kjer se vsebina dejansko ureja.

Obrazec z dvema odsekoma, validacijo obveznega polja in obstojnostjo stanja odseka:

echo $widgets->propertyGrid([
    ['section' => 'Povezava', 'label' => 'Gostitelj', 'controlHtml' => '<input type="text" name="host" required>', 'required' => true],
    ['section' => 'Povezava', 'label' => 'Vrata', 'controlHtml' => '<input type="number" name="port" value="3306">'],
    ['section' => 'Poverilnice', 'label' => 'Uporabnik', 'controlHtml' => '<input type="text" name="user">'],
    ['section' => 'Poverilnice', 'label' => 'Geslo', 'controlHtml' => '<input type="password" name="pass">', 'state' => 'warning', 'stateText' => 'Shranjeno šifrirano.'],
], ['persistKey' => 'connect-dialog']);

• Brez ponovne izvedbe DevExpress-ovega načina primerjave več zapisov (več predmetov kot stolpci) — po potrebi samostojna pobuda; do takrat en propertyGrid() na predmet, drug ob drugem.
• Vedenje zapolnjevanja panela (mreža zapolni predal/auxbar, se pomika znotraj) — podrobnosti: adaptivity.
• aria-describedby med stateText-om in kontrolnikom nastane le z nastavljenim ključem controlId vrstice (glej odsek 7) — starejši klicatelji brez tega ključa se izrišejo nespremenjeno; podrobnosti: accessibility.

• Celoten pregled: accessibility (konsolidirano, tu ni podvojeno).
• Brez JavaScripta vsak odsek ostane odprt in upravljiv (nativna semantika <details>); izgubi se le obstojnost odprtega stanja med ponovnimi nalaganji.
• Združljivost brskalnikov: brez zahtev onkraj osnovne podpore CSS Grid.

Simptom: obvezno polje ne prikaže rdeče zvezdice kljub required ⇒ true.

Vzrok: required v definiciji vrstice in required kot HTML-atribut v controlHtml-ju sta dve ločeni stvari — le prvo upravlja zvezdico.

Rešitev: nastaviti 'required' => true na vrstici in sam dodati atribut required v controlHtml-ju, če je želena nativna validacija brskalnika.

Simptom: odprto stanje odseka se izgubi ob vsakem ogledu strani.

Vzrok: $opts['persistKey'] manjka.

Rešitev: nastaviti persistKey, ki je stabilen med ogledi strani in enoličen na obrazec.

• predstavitveni pregled — vsaka kategorija
• FluentUI: javni API pomočnika — popolna pogodba metod
• FluentUI: osnovni katalog gradnikov — razvrstitev FormLayout (ADS)
• form-fields — vnosna polja za controlHtml
• Vodnik: gradnja prvega skrbniškega zaslona z FluentUI — vodnik po korakih
• FluentUI: skrbniško območje podrobno — metrika obrazcev/barvna semantika