FluentUI: strani obrazcev, podprte s shemo
1. Pregled in namen
Stanje: [Live] — izvedba pobude
FluentUI: prihodnja usmeritev — strani obrazcev, podprte s shemo kot možnost
(a), po odločitvi uporabnika vgrajena v wkfluentui (ne
lasten vtičnik). Vrsto strani opredeli datoteka sheme XML (obvezna
polja, tipi, seznami izbire); ustvarjanje in urejanje potekata prek
ustvarjenega obrazca namesto prostega besedila, shrani pa se navadna
stran DokuWiki, ki se izriše kot chrome obrazca.
Idejni vzor je Wdx-ov Page Contract (ločitev deklaracije/logike, uveljavljena validacija polj) — skladno z odločitvijo na FluentUI: prihodnja usmeritev — Wdx kot vir navdiha, izključno kot navdih, brez runtime-odvisnosti.
2. Predpogoji
Aktiven vtičnik wkfluentui; za ustvarjanje AUTH_CREATE, za
urejanje AUTH_EDIT na ciljni strani (ACL DokuWiki).
3. Pojmi
Tri komponente, en podatkovni tok:
helper/formpage.php— nalagalnik sheme (schemas/<vrsta>.xml), strežniška validacija, serializacija/razčlenjevanje bloka strani, izris obrazca.action/formpage.php— dve akcijido=wkformpage_new&fptype=<vrsta>(ustvarjanje, stran še ne sme obstajati) indo=wkformpage_edit(urejanje; vrsta izhaja iz shranjene strani, nikoli iz zahteve).syntax/formpage.php— izriše shranjeni blok<wkform type="...">kot chrome obrazca (seznam definicij v vrstnem redu sheme, gumb za urejanje le priAUTH_EDIT). To je prva sintaksna komponenta knjižnice; ta izris zapiše izključno lasten tok shranjevanja, avtorji ga nikoli ne pišejo ročno.
Format shranjevanja: ustvarjen naslov (naslov strani = vrednost prvega obveznega besedilnega polja, rezervno naslov sheme) plus blok z vrednostmi kot JSON. Stran ostane navadna stran wiki: surovi urejevalnik ostane uporaben kot rezerva, pri onemogočenem vtičniku pa JSON ostane berljiv kot besedilo strani (dokumentirana degradacija).
4. Prvi koraki
Ustvarjanje strani BUG-WI (priložena vzorčna shema
schemas/bug-wi.xml):
doku.php?id=projekt:hrosci:izvoz-500&do=wkformpage_new&fptype=bug-wi
Obrazec izriše devet polj sheme s skupno pogodbo polj (Polja obrazca: osnove); shranjevanje validira na strani strežnika, ustvari stran in preusmeri na izrisan pogled.
5. Uporaba
| Potreba | Pot |
|---|---|
| Opredeliti novo vrsto strani | datoteka XML pod lib/plugins/wkfluentui/schemas/<vrsta>.xml (pogodba sheme: odsek 7) |
| Ustvariti stran | povezava na do=wkformpage_new&fptype=<vrsta> (npr. s portalne strani ali iz izrezka) |
| Urediti stran | gumb za urejanje v glavi chroma ali do=wkformpage_edit |
| Urediti surovo besedilo | navaden urejevalnik wiki (do=edit) — ostane nespremenjeno mogoč |
6. API referenca
helper_plugin_wkfluentui_formpage — naložiti prek
plugin_load('helper', 'wkfluentui_formpage'):
| Metoda | Pogodba |
|---|---|
loadSchema($type) | polje sheme ali null (neznana/pokvarjena vrsta); ime vrste je pred dostopom do datoteke preverjeno z belim seznamom (CWE-22) |
validate($schema, $input) | ['values' => normalizirano, 'errors' => polje => ključ sporočila] — neodvisno od odjemalca (obvezna polja, vrednosti izbire, format datuma, vrivanje polja) |
serialize($schema, $values) | popolno besedilo strani wiki (naslov + blok) |
parse($text) | ['type', 'values'] ali null |
formFields($schema, $values, $errors) | HTML polj obrazca (pogodba .wk-field), brez ovoja <form> |
7. Parametri, možnosti in stanja: pogodba sheme
| XML | Pomen |
|---|---|
<schema title="..."> | prikazno ime vrste (značka chroma, rezervni naslov strani) |
<field name= type= required= label= hint= rows=> | eno polje; name = [a-z0-9_]{1,64} (postane ime obrazca in ključ JSON) |
type | text · textarea · select · date · checkbox — neznana vrsta izniči celotno shemo (fail-closed) |
<option> | vrednosti možnosti za select; poslana vrednost se mora natanko ujemati z enim vnosom |
8. Popolni primeri
Priložena vzorčna shema bug-wi: naslov (obvezno), resnost (obvezen
select), sistem/okolje, najdeno dne (datum), koraki za obnovitev /
pričakovano / dejansko (obvezna besedilna polja textarea), merila
sprejemljivosti, potrditveno polje regresije.
9. Omejitve in robni primeri
- Namerne meje v1: brez integracije zaklepanja strani (zmaga zadnje shranjevanje — tako kot pri vsakem zunanjem urejevalniku) in brez integracije osnutkov; surovi urejevalnik je rezervna pot za oboje.
- Ustvarjanje zavrne obstoječo ciljno stran (brez tihega prepisovanja tuje vsebine).
- Potrditvena polja izrecno pošljejo
0/1(vzorec skritega polja) — manjkajoča vrednost nikoli ni dvoumna.
10. Dostopnost in združljivost
Polja obrazca sledijo skupni pogodbi polj (label[for],
aria-required, aria-invalid + aria-describedby na sporočilo
napake, obvezna zvezdica z besedilom za bralnik zaslona). Brez
JavaScripta je celoten tok povsem funkcionalen (čist vzorec
obrazec-POST); brskalnikov required je udobnost, strežniška
validacija je meja.
11. Odpravljanje težav
Simptom: „Neznana ali pokvarjena vrsta strani„.
Vzrok: ime vrste ni v obliki belega seznama, datoteka sheme manjka,
XML je pokvarjen, neznana vrsta polja ali select brez možnosti
(fail-closed).
Rešitev: preveriti shemo glede na pogodbo v odseku 7.
Simptom: chrome prikaže polje napake + blok kode JSON. Vzrok: shranjeni blok se sklicuje na odstranjeno/preimenovano vrsto — vsebina se prikaže berljivo namesto skrito.
12. Sorodne teme
- FluentUI: prihodnja usmeritev — strani obrazcev, podprte s shemo — podlaga za odločanje in primerjava možnosti (zgodovinsko)
- FluentUI: prihodnja usmeritev — Wdx kot vir navdiha — idejni vzor Page Contract, odločitev o neintegraciji
- Polja obrazca: osnove — skupna pogodba polj
- FluentUI: javni API pomočnika — imenik pomočnikov
Preverjeno glede na: wkfluentui@1366902