FluentUI: storitve za register WvdS-DW

Paketi družin DW in DWDO svojega vmesnika ne rišejo sami: tri storitve dobijo iz registra paketa wkcore. Ta stran pove, katere.

Nazaj: FluentUI (knjižnica oblikovalskega sistema) · Sorodno: FluentUI: javni API pomočnika · FluentUI: oblikovalski žetoni

1. Namen

Stanje: stopnja 1 – opisuje dejansko izvedeno kodo.

Paketi družin WvdS-DW in DWDO (wksourceview, wkdogit, wkdoado, wkdoadogit, wkdocore) svojega vmesnika ne rišejo sami, temveč iz registra storitev paketa wkcore dobijo tri storitve:

ui.components – pet osnovnih gradnikov: button, badge, card, alert, icon; poleg njih ta wiki dodaja še skupno glavo dokumenta header (razdelek 4)
ui.icons – iz vzdevka ikone naredi končne oznake HTML
ui.tokens – barvne vrednosti kot polje PHP, za porabnike na strežniku

Za to je predviden paket wvdsdwui. Tu namenoma ni nameščen: ta wiki ima z wkfluentui že oblikovalski sistem, dva nabora žetonov in dva ponudnika ikon v istem wikiju pa bi pomenila, da o barvi odloča vrstni red nalaganja in ne namen. Namesto tega tri storitve prijavi wkfluentui sam.

2. Kako poteka prijava

action/dwdobridge.php se priključi na dogodek WKCORE_REGISTER_SERVICES in vpiše tri storitve v register. Povezava je neobvezna v obe smeri:

Če wkcore ni nameščen, se dogodek nikoli ne sproži – ta paket se vede natanko tako kot prej.
Če paket DWDO storitve ne najde, po lastni pogodbi preide na preproste oznake HTML.

Prijava ničesar ne prepiše: če bi bil wvdsdwui vendarle nameščen, zmaga tisti, ki se prijavi prvi – namesto da bi eden drugega tiho izpodrinil.

Pomočniki ne izvajajo vmesnika (interface). Pogodba (wvdsdwui\ComponentContract, wvdsdwui\IconProvider) pripada prav paketu, ki ga ta rešitev nadomešča, torej je ni. Porabniki storitve tako ali tako kličejo dinamično in nikoli ne tipizirajo proti vmesniku – enakost podpisov je zato vsa pogodba. Spremenjen podpis klicatelje zlomi brez opozorila.

3. ''ui.components''

Izvedba: helper/uicomponents.php.

Metoda	Podpis	Rezultat
`button()`	`(string $label, array $opts = [])`	`<button type=„button“>` oziroma `<a>`, če je nastavljen `href`. `opts`: `variant`, `icon` (vzdevek, ne oznake HTML), `href`
`badge()`	`(string $text, string $variant = '')`	`<span class=„wk-badge …“>`; oblikovane različice: `success`, `warn`, `error`, `info`
`card()`	`(string $title, string $bodyHtml)`	preda `widgets()→card()`
`alert()`	`(string $message, string $level = 'info')`	blok s sporočilom z `role=„status“` in simbolom stanja; neznana stopnja postane `info`
`icon()`	`(string $alias, array $attr = [])`	preda `ui.icons`; neznan vzdevek vrne ''''
`header()`	`(array $spec)`	ni del pogodbe s petimi metodami – skupna glava dokumenta, glejte razdelek 4

Kodiranje posebnih znakov: vsaka skalarna vrednost je kodirana tukaj. Edina izjema je $bodyHtml pri card() – končen delček HTML, za katerega kodiranje je po pogodbi odgovoren klicatelj.

Odstopanje od izvirnika: button() v href preveri izvršljive sheme (javascript:, vbscript:, data:) in jih nadomesti z '#'. Sam hsc() naredi javascript:alert(1) le varnega za atribut, ne prepreči pa izvršitve ob kliku. Relativne in absolutne poti, poizvedba, fragment, http(s): in mailto: gredo skozi nespremenjeni.

4. Skupna glava dokumenta

Izvedba: helper/docheader.php in pravila .wk-dochead* v style.css. Dosegljiva je kot šesta metoda storitve ui.components.

Zakaj obstaja

Dva paketa sta za isto nalogo gradila vsak svojo glavo – wksourceview za datoteko, wkdoadogit za repozitorij. Ista naloga, drugačen vrstni red elementov, drugačno krajšanje, drugačen barvni odtenek. Na strani z obema sta stali dve različni predstavi o tem, kaj je glava.

Pogodba je polje s specifikacijo, ne oznake HTML. Klicatelj opiše, kaj je v glavi; gradnik odloča o razporeditvi, vrstnem redu, krajšanju in pripenjanju. Klicatelj z njim drugače oblikovane glave ne more ustvariti – in prav to je namen.

Območja

Območje	Vsebina	Vedenje
`ident`	ikona + ime (+ za njim zadržano prikazan sklic)	zavzame prosto širino, krajša se
`meta`	značke stanja	kratke, nespremenljive, nikoli se ne skrčijo
`tabs`	sorodni pogledi istega predmeta	odpade, če sta zavihka manj kot dva
`actions`	povezave in gumbi za predmet	na koncu vrstice

Ključi polja s specifikacijo

Ključ	Pomen
`name`	prikazno ime – tisto, kar bralec išče
`icon`	vzdevek ikone (glejte razdelek 5), ne oznake HTML
`reference`	podrobnejša opredelitev za imenom; odpade, če ime le ponovi
`headingLevel`	2–6: ime postane pravi naslov. Brez navedbe `<span>`
`badges`	seznam z `text`, `variant`, `mono`
`tabs`	seznam z `label`, `href`, `active`, `disabled`
`actions`	seznam z `label`, `icon`, `href`, `title`, `class`, `attrs`
`layout`	`row` (cel bralni stolpec) ali `stacked` (ozek stolpec)
`sticky`	pripne glavo na vrh najbližjega nadrejenega elementa s pomikanjem
`class`	dodaten razred na korenskem elementu, za sidra posameznega paketa

stacked ni stvar okusa, temveč meritve. V 15 em široki stranski vrstici je ime edini element, ki se lahko skrči, poleg kratkih značk nespremenljive širine – v skupni vrstici se je skrčilo na en znak. Zato ima identiteta tam svojo vrstico.

Brez headingLevel ime namenoma ni naslov. Orodna vrstica, ki se drži vrha območja za pomikanje, je del upravljalnega okvira; če bi jo vpisali v zgradbo dokumenta, bi zavedla uporabnike bralnikov zaslona pri navigaciji.

Varnost

Vsaka skalarna vrednost je kodirana tukaj; ključa, prek katerega bi klicatelj predal surov HTML, ni. To je namerno: glava je sestavljena iz imen, poti in sklicev (refs), ki prihajajo iz repozitorijev in besedila strani.

href gre skozi isto preverjanje shem kot button() (glejte razdelek 3).
attrs se filtrira: dovoljena so samo imena z malimi črkami iz a–z0–9-; on… se zavrne, prav tako href, class, src, srcdoc, style, action, formaction, form in type – prva dva zato, ker imata svoja ključa in bi bila izpisana dvakrat (brskalnik obdrži prvo navedbo, torej nepreverjeno).
Vrednost true ustvari atribut brez vrednosti (download).

Nadomestna pot

Porabnik preveri z method_exists($ui, 'header'). Če metode ni (na primer ker storitve vendarle zagotavlja izvirni wvdsdwui), nariše svojo, namenoma preprosto glavo z isto vsebino. Ta nadomestna pot ne sme prerasti v drugo izvedbo iste oblike; to bi bilo natanko odstopanje, proti kateremu je gradnik nastal.

5. ''ui.icons''

Izvedba: helper/icons.php. Metode: has(), icon(), aliases(), name() (zadnja vrne 'wkfluentui-svg' in se prikaže v diagnostičnih pogledih).

Znaki so vgrajeni SVG, ne pisava z ikonami: brez dodatne zahteve, brez utripa pred nalaganjem, brez licenčnih obveznosti, barvo pa prek currentColor samodejno prevzamejo od okoliškega besedila. Narisani so na enotni mreži 16×16.

Neznan vzdevek ni napaka: has() vrne false, icon() vrne ''''''. Manjkajoča ikona strani nikoli ne pokvari, odpade le okras. * Dostopnost: brez ''label je ikona okrasna (aria-hidden=„true“). Z nepraznim label nosi pomen (role=„img“ + aria-label). Sam title ni dostopno ime – namigi se izpisujejo neenotno, na zaslonih na dotik pa nikoli.

Razpoložljivi vzdevki

project, dashboard, board, pipeline, wiki, org, home, menu, settings, account, repo, source, branch, commit, merge, tag, add, edit, delete, save, search, run, play, link, close, query, drawer, permalink, download, check, warning, error, info, bug, test, folder, file, rocket

Vzdevki se zahtevajo na dva načina: neposredno z →icon('alias') in posredno kot tretji parameter konstruktorja definicije Hub v wkdocore. Kdor išče samo klice icon(), drugo obliko spregleda – prav tako je manjkajoči vzdevek pipeline sprva ostal neopažen in vrstica vozlišč je prikazala vnos brez ikone.

6. ''ui.tokens''

Preprosto polje ime ⇒ barvna vrednost, brez predpone –wk- (oblika, ki jo objavlja wvdsdwui). Namenjeno je porabnikom v PHP – diagnostičnim pogledom in vrstičnim slogom, ki nastanejo na strežniku. Slogovne datoteke paketov DWDO v resnici berejo lastnosti CSS v style.css; oboje je treba vzdrževati skupaj.

7. Združljivostna plast v CSS

Slogovne datoteke DWDO rišejo z drugim besediščem: –wk-color-accent, –wk-color-bg, –wk-color-surface, –wk-color-border, –wk-color-text-muted in drugimi, poleg tega –wk-motion, –wk-easing in –wk-elevation-3. Ta wiki namesto tega pozna ploščato paleto (–wk-accent, –wk-ink, –wk-paper …).

Brez preslikave se klici var() v paketih DWDO razrešijo v nič: ni ozadja, ni obrobe, ni barve besedila – vidno pokvarjene površine, ne zgolj drug odtenek. Plast v style.css je zato nosilna, ne okrasna.

Vsaka vrstica je vzdevek ploščate palete, nikoli nova barva. Če predloga ploščato paleto preglasi, se zasloni DWDO samodejno obarvajo z njo – drugega mesta, ki bi ga bilo treba vzdrževati, ni.

–wk-color-bg je osnovna površina, –wk-color-surface pa dvignjena površina na njej. Ploščata paleta ju poimenuje ravno obratno (–wk-surface je najsvetlejša barva). Preslikava zato namenoma ni po enakih imenih.