Referenca skladnje in API

Referenca vseh javnih elementov vtičnika wkacmenu: skladnja wikija, stran vrstnega reda, nastavitve, končni točki AJAX, PHP API, razredi CSS, piškotek. Uvod in koncepti: Pregled.

Podpis:

{{wk:acmenu>}}
{{wk:acmenu>parameter=vrednost|parameter=vrednost|...}}

Povzetek: Izriše meni v obliki harmonike na mestu, kjer je zapisan (običajno na strani stranske vrstice). Oznake ~~NOCACHE~~ ne potrebujete: oznaka menija sama izklopi predpomnjenje strani.

Parametri (ločeni z navpičnico; > za wk:acmenu je obvezen, sicer DokuWiki zapis razume kot skladnjo za medije in izriše pokvarjeno povezavo):

Opombe:

• Brez ns/startns vtičnik navzgor poišče stran sidebar* in meni začne pri njenem imenskem prostoru.
• V osredotočenih načinih (ns=auto, startns=current) zbirka nikoli ne postane osnova menija; osnova se premakne v nadrejeni imenski prostor najbolj zunanje zbirke.
• Rodovnik imenskih prostorov trenutne strani je vedno vnaprej naložen na strežniku – odprto vozlišče na trenutni poti prikaže svoje podrejene vnose tudi onkraj globine dynamic.
• Brez dynamic odloča nastavitev default_depth (privzeto 1): eno raven pripravi strežnik, globlji imenski prostori se naložijo ob kliku. Neomejeno pomeni, da se ob vsakem odprtju strani pregleda celoten nabor strani – meni namenoma ni predpomnjen, ker je odvisen od trenutne strani, pravic bralca in njegovih odprtih vej.
• Pri sneaky_index se zaščiteni vmesni imenski prostori, pod katerimi je berljiva vsebina, prikažejo kot delni: napis brez povezave, ki ga je mogoče razširiti.

Primer:

{{wk:acmenu>ns=auto|icons=fa|dynamic=1}}

Podpis:

{{wk:title>Besedilo naslova}}
{{wk:title>de:Text|en:Text}}

Povzetek: V metapodatke strani shrani nevidni naslov za meni.

Vrednost: poljubno besedilo; po izbiri z vgnezdenim izrazom ... (vtičnik wki18n).

Opombe: Prednost naslovov v meniju: označevalec naslova pred prvim naslovom strani (useheading) pred ID-jem strani. Učinkuje po naslednjem izrisu strani.

Primer: glej Kako: nastaviti naslov v meniju brez vidnega naslova strani.

Podpis:

~~COLLECTION~~

Povzetek: Na strani start imenskega prostora ta imenski prostor označi kot zbirko strani.

Vrednost: brez; presledki pred zaključnim ~~ so dovoljeni.

Opombe: Učinek (ikona, obnašanje ob kliku, premik osnove menija, brez podrejenega lista start): Kako: urediti imenski prostor kot zbirko strani. Označevalec je shranjen samo v trenutnih metapodatkih – ko ga odstranite in stran znova izrišete, ga ni več. Na straneh Markdown ni prepoznan.

Primer: glej Kako: urediti imenski prostor kot zbirko strani.

Podpis: stran <ns>:<orderpagename> (privzeto: <ns>:order), golo besedilo:

# komentar
ime-vnosa
drugo-ime-vnosa

Povzetek: Določi vrstni red vnosov menija na eni ravni imenskega prostora.

Vrednosti: eno ime vnosa na vrstico – ime strani ali ime podrejenega imenskega prostora, relativno glede na imenski prostor, brez polnih ID-jev; prazne vrstice in komentarji # se prezrejo; dvojniki štejejo enkrat.

Opombe: Navedeni vnosi so na vrhu v vrstnem redu datoteke, nenavedeni sledijo v privzeti razvrstitvi (imenski prostori pred stranmi, po abecedi, start prva). Stran se bere brez preverjanja ACL (je nastavitev razvrščanja), nikoli se ne prikaže kot vnos menija in naj bo skrita prek hidepages. Urejate jo lahko ročno ali s povleci in spusti.

Primer: glej Kako: določiti vrstni red menija.

Od različice 1.6.0 (poenotenje oblikovalskega sistema) izris v celoti poteka prek skupne komponente tree() vtičnika wkfluentui (Referenca API) – obe spodnji končni točki to odražata v obliki svojega odgovora.

Podpis: GET lib/exe/ajax.php?call=plugin_wkacmenu_load&ns=<ns>&icons=<0|1>

Povzetek: Vrne eno raven imenskega prostora kot HTML (leno nalaganje). Imenski prostori v njej so spet vozlišča za naknadno nalaganje; scripts/treeview.js jih v vstavljenem odseku znova poveže.

Odgovor: surov odlomek HTML (Content-Type: text/html), en sam <ul class=„wk-tree“>…</ul> – ne več JSON. scripts/treeview.js (vtičnik wkfluentui) naslov naloži neposredno s fetch() in z odgovorom zamenja prazno nadomestno vozlišče; vtičnik sam za to nima več nobene kode JavaScript. Napake vrnejo prazno telo s statusom, ki ni 2xx (400 manjka parameter ns, 403 ACL, 503 wkfluentui ni na voljo), namesto objekta JSON z napako.

Opombe: Zahteva pravico branja na strani start imenskega prostora; vrnjeni vnosi so filtrirani po ACL.

Podpis: POST lib/exe/ajax.php?call=plugin_wkacmenu_order s polji wk-tree-move (ID premaknjene strani ali začetne strani imenskega prostora), wk-tree-ref (ciljni ID), wk-tree-pos (before/after), sectok (JSINFO.plugins.wkfluentui.sectok, ne več lasten žeton vtičnika).

Povzetek: Zapiše stran vrstnega reda imenskega prostora na podlagi ene same operacije premika, ki jo sproži vgrajeno nativno vlečenje HTML5 komponente tree()s (scripts/treeview.js). Strežnik prizadeto raven imenskega prostora izpelje sam iz obeh polnih, enoličnih ID-jev (syntax_plugin_wkacmenu::orderOwnerNs()) in zavrne premike med ravnmi – za razliko od stanja pred 1.6.0 od odjemalca ne sprejme več niza z imenskim prostorom.

Odgovor: ne več JSON – pravi POST obrazca (nativna oddaja <form> iz treeview.js, ne fetch() v ozadju), odgovor je preusmeritev HTTP na stran, s katere je prišla zahteva. Ob uspehu brez dodatnega obvestila (potrditev je novo mesto vnosa po ponovnem nalaganju – zlate utripajoče animacije ni več); ob napaki z rdečim sporočilom o napaki na ciljni strani (razlog napake potuje kot preverjen parameter poizvedbe wkacmenu_order_msg, ker DokuWikijev msg() preusmeritve ne preživi).

Opombe: Samo skrbnik (superuser); samo POST; žeton CSRF se preveri; vsako izpeljano ime vnosa se na strežniku znova preveri (cleanID, en segment); preveri se zaklep strani vrstnega reda; vsak klic ustvari novo revizijo strani. Vrstni red na odjemalcu je predstavitev, nikoli pooblastilo. Cilj preusmeritve se preveri glede na lastni gostitelj (ni odprte preusmeritve prek ponarejene glave Referer).

Javne metode razreda syntax_plugin_wkacmenu za druge vtičnike in predloge:

Od 1.6.0 osnovni videz (drevesna struktura, povezave, aktivno stanje, obarvanje vsebnika) prihaja iz razredov .wk-tree* v wkfluentui/style.css (pogodba za stransko vrstico in auxbar, različica »dokument«, pogodba slogov v16). wkacmenu/style.css prispeva le še izpopolnitve, lastne vtičniku:

Odpadlo (nadomestilo ni potrebno, delo prevzame nativna semantika <details>): .acmenu-up (vnos »navzgor« je običajno vozlišče), .open/ .closed (stanje atributa open elementa <details>), .curid (nadomešča ga .wk-tree__link–active), .acmenu-drag/ .acmenu-sort-placeholder/.acmenu-saved (nativno vlečenje HTML5, brez ročaja in brez utripajoče animacije ob shranjevanju).

Odprta vozlišča so shranjena v piškotku plugin_wkacmenu_open_items (polje JSON z ID-ji strani). Vtičnik ga ob izrisu prebere na strežniku in vnaprej naloži vozlišča, ki so v njem navedena – stanje menija tako preživi menjavo strani brez utripanja. Od 1.6.0 script.js piškotek zapisuje ob nativnem dogodku toggle elementa <details> namesto ob kliku; to je edina naloga JavaScripta, ki je ostala temu vtičniku – izris drevesa, leno nalaganje ter povleci in spusti v celoti tečejo prek wkfluentui/scripts/treeview.js.

Pot menija od sprožilca do končnega drevesa. Koraki od 2 do 5 pripadajo vtičniku, koraki od 6 do 8 kompletu gradnikov – to je meja, ki velja od različice 1.6.0: pridobivanje podatkov tu, izris tam (glejte Zgodovino različic).