FluentUI: reference komponent
Trenutno dejavna stran: start » sl » Interna dokumentacija » Razširitve DokuWikija (WvdS) » FluentUI (knjižnica oblikovalskega sistema) » FluentUI: reference komponent » FluentUI: urejevalniki in prikaz kode

FluentUI: urejevalniki in prikaz kode

Nazaj: FluentUI (knjižnica oblikovalskega sistema)

1. Pregled in namen

Stanje: mešano — štirje gradniki [Live] (vsak z lastnim nosilcem, vključno s codeEditor()) plus preklop urejevalnik/označevanje (preklop WYSIWYG, namerno voden zunaj te strani — nosilec wvdsmd), navedeno po odseku.

Ta stran razvršča štiri različne gradnike urejevalnika/prikaza kode in poveže vsak vir resnice — ne nadomešča nobene dokumentacije vtičnikov. Ciljna publika: vsak razvijalec, ki se mora odločiti, kateri gradnik je pravi za „prikaz kode„ proti „urejanje kode“ proti „urejanje vsebine wiki„ (odsek 5).

2. Predpogoji

  • Za codeEditor(): DokuWiki z omogočenim vtičnikom wkfluentui in naloženim helper_plugin_wkfluentui_widgets.
  • Za GeSHi: nobenih — osnovna funkcija, vedno na voljo.
  • Za urejevalnik Markdown: omogočen vtičnik wvdsmd, stran nosi oznako Markdown (samodejno zaznano).

3. Pojmi

Skupen vzorec vseh štirih gradnikov: postopno izboljšanje nad delujočim textarea — ista konvencija kot pri razširitvah JS Helper-API (brez druge poti kode, izris ostane format shranjevanja).

Gradnik Kaj je to Uporaba Nosilec / vir resnice Stanje
GeSHi (izris kode) Skladenjsko poudarjanje ob izrisu — ni urejevalnik, brez lastnega API-ja <code sql>…</code>/<file> v besedilu wiki in fenced-code-bloki (```lang) v vdelavah Markdown ({{md>…}} / <markdown>); oznaka jezika = ime jezika GeSHi Jedro DokuWiki (inc/parser/xhtml.php → vključen GeSHi); videz prek žetonov --wk-wiki-code-* izvedeno (jedro)
Urejevalnik izvorne kode CodeMirror, postopno nad navadnim <textarea> — brez JavaScripta textarea ostane povsem funkcionalna vsak administratorski modul prek codeEditor() (prvi porabnik: SQL Workbench v wksqliteds) skupna kopija pod wkfluentui/cm/ + gradnik codeEditor() (pogodba: odseka 6/7 spodaj) izvedeno
Standardni urejevalnik DokuWiki jedrni urejevalnik strani: orodna vrstica (krepko/povezava/…) + textarea + predogled, tok osnutka/zaklepa vsaka wiki-stran, do=edit Jedro DokuWiki izvedeno (jedro)
Urejevalnik Markdown vključen EasyMDE nadomesti textarea na straneh Markdown; vrstica oznake ostane nevidna, tok shranjevanja/osnutka DokuWiki nespremenjen; rezervni način brez JS = textarea strani z oznako Markdown (samodejno zaznano) vtičnik wvdsmd — vir resnice: Markdown (wvdsmd) izvedeno

4. Prvi koraki

Minimalen primer: aktivirati urejevalnik CodeMirror prek obstoječega textarea SQL. 

/** @var helper_plugin_wkfluentui_widgets $widgets */
$widgets = plugin_load('helper', 'wkfluentui_widgets');
?>
<textarea id="sql-input" name="sql"></textarea>
<?php echo $widgets->codeEditor('sql-input', 'sql'); ?>

Napačno: usmeriti codeEditor() na textarea, ki ob klicu še ni v DOM (npr. klic pred oznako <textarea>). Aktivacijski izris napotuje prek id na element, ki mora obstajati — vrstni red v zgornjem primeru (textarea najprej) je zavezujoč.

5. Uporaba: vodnik „kateri gradnik za kaj"

Potreba Gradnik
Prikazati kodo v vsebini <code lang> (GeSHi) — nikoli vdelati urejevalnika
Urediti kodo/SQL v administratorskem modulu codeEditor() (en klic ob textarea, brez potrebe po vtičniku-lokalnem vendoringu)
Urediti vsebino wiki jedrni urejevalnik; strani Markdown samodejno prek wvdsmd
Brez obnove urejevalnikov v slogu Monaco/VS Code namerna meja, tako kot mehanika postavitve (layout)

6. API referenca: codeEditor()

Metapodatek Vrednost
Jezik PHP
Imenski prostor helper_plugin_wkfluentui_widgets
Datoteka lib/plugins/wkfluentui/helper/widgets.php
Vidnost public
Stabilnost stabilno (raven 1) 
public function codeEditor(string $textareaId, string $language, array $opts = []): string

Povzetek: priskrbi aktivacijski izris brez <script> (atributi data-wk-code-editor) za obstoječo, poimenovano textarea; scripts/codeeditor.js (postopno izboljšanje) jo ob nalaganju nadomesti z instanco CodeMirror.

Vrnjena vrednost: string — aktivacijski izris. Prazen niz pri neznani oznaki $language ali praznem $textareaId — v obeh primerih textarea ostane nedotaknjena, navadna textarea, brez napake.

7. Parametri, možnosti in stanja

Parameter Tip Obvezno Opis
$textareaId string Da id obstoječega ciljnega textarea
$language string Da ena od sql|php|css|javascript|markdown; vsaka druga oznaka vrne prazen niz
$opts['submitId'] string Ne id gumba za pošiljanje, ki ga klikne Ctrl+Enter — urejevalnik prej sinhronizira v textarea

Dostop do instance (odjemalec): wkCodeEditor.get(textareaId) — null, dokler/če CodeMirror ni naložen; razrešiti ob kliku, ne ob gradnji strani. Dogodek wk-codeeditor-ready se dodatno sproži na textarea.

Leno nalaganje: sredstva vendor se naložijo le na straneh z vsaj eno aktivacijsko oznako — brez povečanja obsega po celotnem spletnem mestu.

Vendoring (utemeljen popravek specifikacije): skupna kopija CodeMirror (5.65.16 + načini sql/php/css/javascript/markdown skupaj z odvisnostmi clike/xml/htmlmixed, datoteka licence MIT) leži pod wkfluentui/cm/ — ne v prvotno začrtanem vendor/cm/, ker spletna plast DokuWiki zavrne neposreden dostop do map vendor/ (empirično preverjeno na tej instanci, 404).

Vedenje ob napaki:

Pogoj Vedenje
neznana oznaka $language vrne prazen niz, textarea ostane nedotaknjena
prazen $textareaId vrne prazen niz
ciljna textarea ne obstaja v DOM brez napake PHP (gradnik ne preverja DOM); scripts/codeeditor.js ob nalaganju ne najde cilja in ničesar ne aktivira — tiha degradacija na strani odjemalca

8. Popolni primeri: preklop urejevalnik ↔ označevanje [Live]

Nosilec wvdsmd — vir: lib/plugins/wvdsmd/script.js.

Na straneh Markdown orodna vrstica EasyMDE nosi preklop med pogledom urejevalnika (EasyMDE z orodno vrstico oblikovanja in predogledom) in pogledom označevanja (surova textarea, vključno z vidno vrstico oznake — enako stanju brez JS). Preklop deluje kadar koli v obe smeri in učinkuje takoj, brez shranjevanja; nazadnje izbrani pogled si sistem zapomni po uporabniku (localStorage, wk-editor-view:<login>); vsak preklop se naznani prek regije aria-live. Lastnosti:

  1. Označevanje ostane format shranjevanja (Markdown) — oba pogleda urejata isto osnovno textarea, brez ponovne serializacije, zato so preklopi po zasnovi brez izgub (bajtno enako izvorno besedilo, potrjeno v testnem zagonu).
  2. Rezervni način brez JS ostane surova textarea; preklop obstaja le v pogledu, izboljšanem z JS.
  3. Strani s sintakso DokuWiki ohranijo jedrni urejevalnik z lastno orodno vrstico sintakse in gumbom „predogled“ — tam obstaja le en pogled urejanja, preklop bi bil brez pomena.

Poglobitev — konkretni ukazi orodne vrstice: dve podstrani dokumentirata, katere žetone sintakse DokuWiki/Markdown vstavljajo orodne vrstice urejevalnika (EasyMDE za Markdown, jedrna orodna vrstica za sintakso DokuWiki), po shemi kategorij predstavitvenega nabora DevExpress ASPxHtmlEditor (https://demos.devexpress.com/ASPxHTMLEditorDemos/Default.aspx), a prenesenih na dejanski ciljni format te knjižnice namesto splošnih oznak HTML:

9. Omejitve in robni primeri

  • GeSHi določi seznam jezikov; neznane oznake se izrišejo kot navadno besedilo (brez napake). Enako velja v vdelavah Markdown: ParsedownRenderer pri wvdsdwmd poudari fenced-bloke z znano oznako jezika prek poti GeSHi DokuWiki (p_xhtml_cached_geshi()); bloki brez oznake ali z neznano oznako ostanejo surovi Parsedown <pre> — degradirano, nikoli izgubljeno. Oznaka pogona parsedown-1.7.4-geshi1 izniči stare predpomnilnike.
  • CodeMirror/EasyMDE sta vključena (brez povezave, brez odvisnosti od CDN) — posodobitve so namerne, različicirane spremembe vtičnika.
  • Površine urejevalnika ležijo v panelu z vsebino in sledijo receptu zapolnjevanja panela iz datagrid (sestavine 1–3 veljajo enako za urejevalnike).
  • Brez obnove urejevalnikov v slogu Monaco/VS Code (odsek 5).

10. Dostopnost in združljivost

  • Celoten pregled: Accessibility (konsolidirano, tu ni podvojeno).
  • Brez JavaScripta vsak gradnik ostane navadna, povsem dostopna textarea.
  • CodeMirror/EasyMDE sta vključena — združljivost brskalnikov sledi lastnim opombam izdaje vsakega ponudnika (v tej knjižnici ni ločeno testirano).

11. Odpravljanje težav

Simptom: codeEditor() ne izriše ničesar (prazen niz), čeprav textarea in jezik izgledata pravilno.

Vzrok: $language nosi oznako zunaj sql/php/css/javascript/markdown (paziti na velike/male črke — preverjanje je natančno, brez normalizacije).

Rešitev: preveriti oznako glede na natančen seznam v odseku 7.

Simptom: fenced-code-blok Markdown ni poudarjen.

Vzrok: neznana ali manjkajoča oznaka jezika za tremi obrnjenimi narekovaji, ali predpomnilnik še nosi staro oznako pogona.

Rešitev: preveriti oznako jezika glede na seznam GeSHi; ob sumu na zastarel predpomnilnik: oznaka pogona parsedown-1.7.4-geshi1 vsili izničenje.

12. Sorodne teme

sl/wiki/dwe/wkfluentui/component/editors/start.txt · Zadnja sprememba: uporabnika 0.0.0.0