Vodnik: gradnja prvega skrbniškega zaslona z FluentUI

Nazaj: FluentUI (knjižnica oblikovalskega sistema)

Za koga: za razvijalce, ki nimajo predznanja o wkfluentui in želijo zgraditi lasten skrbniški modul DokuWiki (AdminPlugin) v slogu Fluent/ADS. Ta vodnik pelje od začetka do delujočega zaslona s seznamom in zaslona z več območji — korak za korakom, z enim samim vodilnim primerom. Ne ponavlja pogodb metod; vsak korak vodi na referenco API pomočnika za podrobnosti.

Referenčni primer: zasloni do=admin&page=wksqliteds (vtičnik wksqliteds) so v živo uveljavljena, popolna različica vsakega tukajšnjega koraka — območje „Povezave„ (admin.php::renderConnList()) za koraka 1–2, območje „Podatkovna baza“ → Table Designer/Browse (dbadmin/DbAdmin.php::renderStructure()/ renderBrowse()) za korake 3–5. Izvorna koda: lib/plugins/wksqliteds/{admin.php, dbadmin/DbAdmin.php}.

Vaš vtičnik naloži pomočnika wkfluentui kot vsak drug pomočnik DokuWiki:

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');

Ni potreben argument konstruktorja niti konfiguracija — vsaka metoda je čista funkcija svojih argumentov (glej FluentUI: javni API pomočnika, razdelek „Lastnosti„). CSS/JS se naložita samodejno za celotno spletno mesto prek lib/exe/css.php/lib/exe/js.php (glej kljucni_pojmi) — ročno vključevanje ni potrebno.

Najpreprostejši arhetip: seznam brez drevesa/auxbarja, uokvirjen z .wkq-shell–flat (modifikatorski razred, brez lastnega klica pomočnika — glej FluentUI: osnovna postavitev podrobno za popolno tabelo modifikatorjev) in vrstico stanja na dnu:

echo '<div class="wkq-shell wkq-shell--flat">';
echo '<div class="wk-shell-content">';
 
echo '<h2>Moj seznam</h2>';
echo '<table class="inline" style="width:100%">…</table>';
 
echo '</div>'; // wk-shell-content
echo '<div class="wk-shell-statusbar"><span>3 vnosi</span><span></span></div>';
echo '</div>'; // wkq-shell

Živ vzor: wksqliteds/admin.php::renderConnList() (območje „Povezave“). Vrstica stanja je tu preprost trak dveh <span>-ov brez lastnega pomočnika — pri več zaslonih v istem vtičniku se splača zasebna metoda renderStatusbar($summary), kot je tista tam, vendar je to konvencija in ne obvezen gradnik.

Razpršene gumbe zamenjajte z toolbar() — ta samodejno doda role=„toolbar“ in tipkovnični roving tabindex (scripts/toolbar.js), brez lastnega JS-a:

echo $widgets->toolbar([
    ['label' => 'Novo',     'element' => $widgets->button(
        ['label' => 'Novo', 'href' => '…', 'tone' => 'primary'])],
    ['label' => 'Izbriši', 'element' => $widgets->button(
        ['label' => 'Izbriši', 'type' => 'submit', 'tone' => 'danger']),
     'group' => 'danger'],
]);

Popolna pogodba parametrov ($opts['ariaLabel'], pravila združevanja, primer s tremi barvnimi skupinami): Toolbar → osnove, metoda „toolbar()". Barvna semantika gumbov (bela/modra/rdeča): Styles Contract (--wk-*).

Takoj ko zaslon potrebuje navigacijsko strukturo levo in delovno površino desno, se sestava mreže preklopi z –flat na polno štiriregijsko obliko (.wkq-shell brez modifikatorja oz. z –no-auxbar; glej FluentUI: osnovna postavitev podrobno):

echo '<div class="wkq-shell">';
echo '<div class="wk-shell-sidebar">';
echo $widgets->tree([
    ['label' => 'povezavaA', 'href' => '…', 'active' => true, 'children' => [
        ['label' => 'tabela1', 'href' => '…'],
    ]],
]);
echo '</div>'; // wk-shell-sidebar
echo '<div class="wk-shell-content">…delovna površina…</div>';
echo '<div class="wk-shell-auxbar">…lastnosti…</div>';
echo '<div class="wk-shell-statusbar">…</div>';
echo '</div>'; // wkq-shell

tree() gradi gnezdljiva vozlišča <details>/<summary> — popolnoma dostopna brez JavaScripta (vključno s tipkovnico in bralniki zaslona). Popolna podatkovna pogodba vozlišča (label/href/active/children): TreeView → osnove, metoda „tree()". Živ vzor: wksqliteds/dbadmin/DbAdmin.php::renderObjectTree() — en sam delni prikaz drevesa, deljen med vsemi zasloni podatkovne baze.

Območje wk-shell-auxbar iz koraka 3 je namenoma prazno, dokler zaslon nima izbire, s katero bi ga zapolnil. Vzorec prvega poskusa (brez potrebnega JS-a v živo): klik na povezavo nastavi parameter izbire, zaslon ga prebere pri naslednjem izrisu in zapolni auxbar z propertyGrid():

$sel = $INPUT->str('sel'); // npr. "stolpec1"
echo '<div class="wk-shell-auxbar">';
if ($sel !== '') {
    echo $widgets->propertyGrid([
        ['label' => 'Ime', 'controlHtml' => '<code>' . hsc($sel) . '

'],

      ['label' => 'Tip', 'controlHtml' => 'TEXT'],
  ]);

} else {

  echo '<p style="color:#666">Za prikaz lastnosti izberite element.</p>';

} echo '</div>'; </code>

Popolna pogodba vrstice (label/controlHtml): Property Grid → osnove, metoda „propertyGrid()". Živ vzor (dve popolni izvedbi, izbira stolpca/indeksa/tujega ključa oz. izbira vrstice): wksqliteds/dbadmin/DbAdmin.php::renderStructureAuxbar()/ renderBrowseAuxbar(). Naslednik z JS v živo brez ponovnega nalaganja strani (ustreznik ADS-ovega onActiveCellChanged) je zabeležen kot cilj ravni Tier 2, glej FluentUI: osnovni katalog gradnikov.

Na zaslonih z več območji vrstica stanja običajno prikazuje aktivni kontekst (ime povezave, opozorilo o načinu samo za branje) namesto preprostega štetja kot v koraku 1:

echo '<div class="wk-shell-statusbar">';
echo '<span>' . hsc($connName) . '</span>';
echo '<span>' . ($readonly ? 'Samo za branje' : '') . '</span>';
echo '</div>';

Živ vzor: wksqliteds/dbadmin/DbAdmin.php::renderStatusbar(), vključno z modifikatorskim razredom .wkq-statusbar-readonly za opozorilo.

• Recepti za posamezne gradnike (namesto celotne poti zgoraj): Navodila: dodajanje posameznih gradnikov.
• Normativna pravila za skrbniške zaslone (naštevanje modulov, semantika barv, konvencija predala): FluentUI: skrbniško območje podrobno.
• Popolne pogodbe metod: FluentUI: javni API pomočnika.
• Oblikovalski tokeni (barva/radij/razmik): FluentUI: oblikovalski tokeni.

Preverjeno glede na: wkfluentui@a477094, wk-dw-msqlite-plugin@240c064