====== WvdS.DokuWiki.AcMenu Dodatak ====== **Dodatak:** wvdsacmenu\\ **Verzija:** 1.3.0\\ **Namespace:** ''lib/plugins/wvdsacmenu/''\\ **Osnova:** [[https://www.dokuwiki.org/plugin:acmenu|AcMenu]] od Torpedo\\ **Proširenja:** Wolfgang van der Stille \\ **Licenca:** GPL 2 ---- ===== Definicija ===== Dodatak **wvdsacmenu** prikazuje harmonika izbornik za namespaceove i stranice. Proširuje izvorni AcMenu wiki sintaksom, dinamičkim prepoznavanjem namespacea, **lazy učitavanjem**, **ACL-aware navigacijom** i višejezičnom podrškom. ---- ===== Motivacija ===== ==== Problem sa standardnom navigacijom ==== DokuWiki standardna navigacija i izvorni AcMenu imaju nekoliko ograničenja u poslovnim okruženjima: * **ACL sljepoća:** Kad je ''sneaky_index=1'' aktivan, zaštićene mape su potpuno skrivene - čak i ako **dublje** postoje javni sadržaji * **Nema lazy učitavanja:** Kod velikih dokumentacijskih struktura (100+ stranica) bočna traka postaje spora i nepregledna * **Jezična izolacija:** Višejezični wikiji zahtijevaju ručnu konfiguraciju po namespaceu * **Nema integracije s predloškom:** Odabir bočne trake je statičan i ne poznaje hijerarhiju namespacea ==== Primjer: Javna putanja u zaštićenom području ==== ACL konfiguracija: de:int:* @ALL 0 (zaključano) de:int:vsce:fpc:p:* @ALL 1 (javno) Rezultat standardnog AcMenu: 📂 de 📁 pub ← vidljivo (vsce nedostaje!) ← PROBLEM: cijela putanja je skrivena Rezultat wvdsacmenu: 📂 de 📁 pub 📂 int 📂 vsce ← partial (bez linka) 📂 fpc ← partial (bez linka) 📁 p ← vidljivo i navigabilno Korisnik vidi putanju do javnih sadržaja, čak i ako mape u sredini nisu izravno čitljive. ---- ===== Ciljevi ===== ==== Poslovna navigacija ==== wvdsacmenu je razvijen za složene dokumentacijske strukture s diferenciranim pravima pristupa: ^ Zahtjev ^ Rješenje ^ | Velike strukture | Lazy učitavanje (''dynamic="N"'') | | Diferencirani ACL-ovi | Partial namespaceovi, ACL-aware "Idi gore" | | Višejezičnost | Automatsko prepoznavanje jezika, ''ns="auto"'' | | Performanse | Serversko obnavljanje cookieja | | UX | Total Commander način, FontAwesome ikone | ==== Usporedba s izvornim AcMenu ==== ^ Značajka ^ Izvorni AcMenu ^ wvdsacmenu ^ | ACL podrška | Samo read/hide | Partial namespaceovi, duboke putanje | | Lazy učitavanje | Ne | Da (AJAX) | | Obnavljanje cookieja | Samo klijent | Server + klijent | | Višejezičnost | Ručno | Automatski (''ns="auto"'') | | Ikone | Ne | FontAwesome | | Integracija s predloškom | Ne | Namespace-aware bočna traka | | "Idi gore" navigacija | Ne | Na temelju ACL-a | | Nevidljivi naslov | Ne | ''%%{{wvds:title>...}}%%'' | ==== Načela dizajna ==== - **Minimalno otkrivanje:** Prikaži samo ono što korisnik smije vidjeti, ali prikaži **putanju** do toga - **Progresivno učitavanje:** Učitaj malo na početku, proširi po potrebi - **Obnova bez stanja:** Stanje cookieja se obnavlja na serveru (bez treperenja) - **Duboka integracija:** Dodatak tijesno surađuje s predloškom i ACL sustavom ---- ===== Slučajevi korištenja ===== * **Navigacija namespacea** - Automatski izbornik za strukturu dokumentacije * **Višejezični wikiji** - Odvojeni izbornici po jezičnom namespaceu * **Projektna dokumentacija** - Hijerarhijska navigacija u pod-namespaceovima * **Integracija s bočnom trakom** - Kompaktna navigacija u sidebar-u * **Optimizacija performansi** - Lazy učitavanje za velike strukture izbornika * **ACL-aware navigacija** - Prikazuje mape čak i kad su samo dijelovi čitljivi ---- ===== Sintaksa ===== ==== Sintaksa izbornika ==== {{wvds:acmenu}} {{wvds:acmenu ns="namespace"}} {{wvds:acmenu dynamic="N"}} {{wvds:acmenu startns="current" icons="fa"}} ==== Sintaksa naslova (nevidljivi naslov) ==== {{wvds:title>Naslov moje stranice}} Definira naslov za stranicu koji se prikazuje u izborniku, bez da je vidljiv na samoj stranici. Korisno za stranice s hero sekcijama ili posebnim layoutima. ==== Parametri ==== ^ Parametar ^ Tip ^ Standard ^ Opis ^ | ''ns'' | string | //(auto)// | Namespace za izbornik (vidi dolje) | | ''dynamic'' | integer | ''1'' | Broj prethodno učitanih razina (lazy učitavanje) | | ''startns'' | string | //(auto)// | ''current'' = Počni s trenutnim namespaceom s linkom "Idi gore" | | ''icons'' | string | ''none'' | ''fa'' = FontAwesome ikone za mape/datoteke | **Vrijednosti ns parametra:** ^ Vrijednost ^ Opis ^ | ''ns="de:docs"'' | Eksplicitni namespace | | ''ns="auto"'' | **Pametni Auto:** Fokusiran prikaz + susjedni s Partial sadržajem | | //(prazno)// | Automatsko prepoznavanje preko pozicije bočne trake | ---- ===== Detalji parametara ===== ==== ns - Eksplicitni namespace ==== Prikazuje određeni namespace neovisno o trenutnoj stranici: {{wvds:acmenu ns="hr:crypto"}} {{wvds:acmenu ns="hr:docs:api"}} ==== dynamic - Dubina lazy učitavanja ==== Kontrolira koliko razina se inicijalno učitava. Dublje razine se naknadno učitavaju putem **AJAX-a**: ^ Vrijednost ^ Ponašanje ^ | ''dynamic="0"'' | Prikaži samo stranice (bez podmapa) | | ''dynamic="1"'' | 1 razina prethodno učitana, ostalo putem AJAX-a (standard) | | ''dynamic="2"'' | 2 razine prethodno učitane, ostalo putem AJAX-a | | ''dynamic="3"'' | 3 razine prethodno učitane, ostalo putem AJAX-a | **Važno:** Namespace se uvijek računa relativno prema **poziciji bočne trake**, ne prema trenutnoj stranici. ==== startns - Total Commander način ==== Slično Total Commanderu: Prikazuje samo trenutni namespace s linkom "Idi gore": {{wvds:acmenu startns="current"}} {{wvds:acmenu startns="current" dynamic="2"}} ^ Vrijednost ^ Ponašanje ^ | ''startns="current"'' | Počinje s namespaceom trenutne stranice | | (kombinirano s dynamic) | Ograničava dubinu kao i inače | **Prednosti:** * Preglednije kod velikih struktura * Fokus na trenutno područje * Link "Idi gore" za navigaciju ==== icons - FontAwesome ikone ==== Aktivira vizualne ikone za mape i datoteke: {{wvds:acmenu icons="fa"}} {{wvds:acmenu startns="current" icons="fa"}} ^ Ikona ^ Element ^ FA klasa ^ | 📁 | Zatvorena mapa | ''fa-folder-o'' | | 📂 | Otvorena mapa | ''fa-folder-open-o'' | | 📄 | Stranica/Dokument | ''fa-file-text-o'' | | ↗ | Vanjski namespace | ''fa-external-link'' | | ↑ | Idi gore | ''fa-level-up'' | **Preduvjet:** FontAwesome mora biti učitan u predlošku (u ''flat'' predlošku već je uključen). ==== ns="auto" - Pametni Auto način ==== Način ''auto'' kombinira **fokusiranu navigaciju** s **ACL-aware prepoznavanjem susjednih**: {{wvds:acmenu ns="auto" icons="fa" dynamic="1"}} **Način rada:** - **Fokusirani prikaz:** Počinje s trenutnim namespaceom (kao ''startns="current"'') - **ACL-aware "Idi gore":** Link na home namespace korisnika temeljen na ACL pravilima - **Susjedni s Partial sadržajem:** Prikazuje druge namespaceove na razini jezika koji imaju čitljiv sadržaj - Može se kombinirati s ''dynamic'' za lazy učitavanje **Razlika prema ''startns="current"'':** ^ Način ^ Ponašanje ^ | ''startns="current"'' | Samo trenutni namespace + "Idi gore" na parent | | ''ns="auto"'' | Trenutni namespace + "Idi gore" na home + **svi susjedni s Partial sadržajem** | **Slučaj korištenja:** Jedna ''sidebar1.txt'' za sve namespaceove jednog jezika: # hr/sidebar1.txt (radi za hr:pub:*, hr:int:*, itd.) ~~NOCACHE~~ {{wvds:acmenu ns="auto" icons="fa" dynamic="1"}} **Primjer 1: Anonimni korisnik na ''hr:pub:start''** ACL: ''hr:int:vsce:fpc:p:*'' je javno, ostatak ''hr:int:*'' je zaključan ↑ .. ← Idi gore (izostavlja se ako je već na home) 📂 pub ← trenutni namespace (fokusirano) 📄 start 📁 services 📂 int ← susjedni s Partial sadržajem 📂 vsce ← partial (klikljivo za proširenje) 📂 fpc ← partial 📁 p ← čitljivo **Primjer 2: Anonimni korisnik na ''hr:int:vsce:fpc:p:start''** ↑ .. ← Idi gore na hr:pub:start (home za @ALL) 📁 p ← trenutni namespace (fokusirano) 📄 start 📄 download **Primjer 3: @user na ''hr:int:dwe:start''** ↑ .. ← Idi gore na hr:int:start (home za @user) 📁 dwe ← trenutni namespace (fokusirano) 📄 start 📁 wvdsacmenu 📁 wvdssnippet 📁 vsce ← susjedni (potpuno čitljivo) 📁 pqcrypt ← susjedni (potpuno čitljivo) **Zašto pametni Auto?** | Problem | Rješenje | | Velike strukture su preopterećujuće | Fokusirani prikaz pokazuje samo relevantno područje | | "Idi gore" vodi na zaključane stranice | ACL-aware: link uvijek vodi na čitljivi namespace | | Javne putanje u zaštićenim područjima nevidljive | Susjedni s Partial sadržajem se prikazuju | | Korisnik gubi orijentaciju | Uvijek vidljivo: trenutna lokacija + dostupne alternative | ---- ===== Lazy učitavanje ===== ==== Način rada ==== - Pri učitavanju stranice renderira se samo prvih ''N'' razina (''dynamic'') - Mape na granici dubine dobivaju CSS klasu ''lazy'' - Klikom na ''lazy'' mapu sadržaj se učitava putem AJAX-a - Stanje učitavanja se prikazuje klasom ''loading'' ==== Obnavljanje cookieja ==== Otvorene mape se spremaju u cookie. Pri sljedećem učitavanju stranice te mape se **serverski** prethodno učitavaju, čak i ako su dublje od ''dynamic''. To sprječava "treperenje" pri učitavanju. ==== AJAX krajnja točka ==== GET /lib/exe/ajax.php?call=plugin_wvdsacmenu_load&ns=hr:crypto:subfolder **Odgovor:** { "success": true, "html": "
  • ...
  • ", "ns": "hr:crypto:subfolder" }
    ---- ===== Prepoznavanje namespacea ===== ==== Prepoznavanje granice bočne trake ==== Dodatak prepoznaje granice namespacea putem ''sidebar*'' datoteka: * ''sidebar.txt'' * ''sidebar1.txt'' * ''sidebar2.txt'' * ''sidebar_name.txt'' ==== Logika prepoznavanja ==== 1. Bez parametra └── Traži uzlazno sidebar* datoteku └── Pokreće izbornik od tog namespacea 2. S ns="..." └── Koristi navedeni namespace izravno 3. S dynamic="N" └── Pronalazi namespace bočne trake └── Učitava N razina unaprijed, ostatak putem AJAX-a ---- ===== ACL-aware navigacija ===== Dodatak uzima u obzir DokuWiki ACL pravila i inteligentno prikazuje mape, čak i ako nisu svi sadržaji čitljivi za korisnika. ==== Partial namespaceovi ==== Kad je ''sneaky_index'' aktiviran i mapa nije izravno čitljiva (npr. ''hr:int:vsce:start'' za anonimne korisnike), **ali** čitljivi sadržaji postoje dublje u stablu (npr. ''hr:int:vsce:fpc:p:*''), mapa se ipak prikazuje: 📂 vsce ← partial (bez linka, samo oznaka) 📂 fpc ← partial (bez linka, samo oznaka) 📁 p ← normalno (link na p:start) 📄 start 📄 download **Ponašanje:** * Mape s klasom ''partial'' prikazuju samo oznaku (bez linka na start stranicu) * **Klikljivo:** Klik na mapu proširuje/skuplja djecu * Mapa je inicijalno otvorena kako bi se prikazala čitljiva djeca * Stiliziranje se može prilagoditi putem CSS-a ==== "Idi gore" temeljen na ACL-u ==== Kod ''startns="current"'' link "Idi gore" ne skače jednostavno na parent namespace, nego na **home namespace** korisnika temeljen na ACL pravilima: ^ Korisnik ^ ACL pravilo ^ Cilj "Idi gore" ^ | Anonimni (@ALL) | ''hr:pub:* @ALL 1'' | ''hr:pub:start'' | | @user grupa | ''hr:int:* @user 1'' | ''hr:int:start'' | | @wvdse grupa | ''hr:int:* @wvdse 8'' | ''hr:int:start'' | **Prioritet:** - Namespace wildcardovi (npr. ''hr:pub:*'') imaju prednost - Pojedinačni ACL-ovi stranica (npr. ''hr:int:start'') su sekundarni - Preferira se najkraći (najviši) namespace **Primjer:** Anonimni korisnik na ''hr:int:vsce:fpc:p:start'' vidi link "Idi gore" na ''hr:pub:start'', ne na ''hr:int:start''. ---- ===== Integracija s predloškom ===== Predložak ''flat'' učitava stranice bočne trake **specifično za namespace**. ==== Namespace-aware učitavanje bočne trake ==== Predložak traži datoteku bočne trake (npr. ''sidebar1.txt'') počevši od trenutnog namespacea prema gore: Stranica: hr:int:vsce:fpc:p:start Potraga za sidebar1.txt: 1. hr:int:vsce:fpc:p:sidebar1 → nije pronađeno 2. hr:int:vsce:fpc:sidebar1 → nije pronađeno 3. hr:int:vsce:sidebar1 → nije pronađeno 4. hr:int:sidebar1 → PRONAĐENO ✓ **Rezultat:** Za ''hr:int:*'' stranice učitava se ''hr:int:sidebar1.txt'', za ''hr:pub:*'' stranice učitava se ''hr:sidebar1.txt''. ==== ACL za bočne trake ==== Stranice bočne trake u zaštićenim namespaceovima moraju biti čitljive za @ALL kako bi navigacija funkcionirala! **Primjer ACL unosa:** hr:int:sidebar @ALL 1 hr:int:sidebar1 @ALL 1 hr:int:sidebar2 @ALL 1 ---- ===== Nevidljivi naslov ===== Za stranice bez vidljivog naslova (npr. landing stranice s hero sekcijom) može se definirati naslov za izbornik: ~~NOTOC~~ {{wvds:title>NIS2 Provjera usklađenosti}} {{wvds:snippet>nis2check_hero}} {{wvds:snippet>nis2check_content}} Naslov se: * Prikazuje u izborniku * Sprema u metapodatke * **Ne** renderira na stranici ==== Prioritet naslova ==== Izbornik koristi naslove sljedećim redoslijedom: - ''%%{{wvds:title>...}}%%'' (Nevidljivi naslov) - Prva zaglavlje stranice (ako je ''useheading'' aktiviran) - ID stranice kao fallback ---- ===== Primjeri ===== ==== Primjer 1: Automatski izbornik ==== **sidebar1.txt:** ~~NOCACHE~~ {{wvds:snippet>go_back}} {{wvds:acmenu}} ==== Primjer 2: Preporučena konfiguracija (ns="auto") ==== Jedna datoteka bočne trake za sve namespaceove jednog jezika: **hr/sidebar1.txt:** ~~NOCACHE~~ {{wvds:acmenu ns="auto" icons="fa" dynamic="1"}} Ova konfiguracija: * **Fokusirano:** Prikazuje primarno trenutni namespace * **Pametni "Idi gore":** Link na home namespace temeljen na ACL-u * **Prepoznavanje susjednih:** Prikazuje druge namespaceove s čitljivim sadržajem * **Partial namespaceovi:** Putanje do javnih područja u zaštićenim zonama * Koristi FontAwesome ikone * Učitava samo 1 razinu inicijalno, ostatak putem AJAX-a ==== Primjer 3: Klasična konfiguracija ==== **hr/sidebar1.txt:** ~~NOCACHE~~ {{wvds:snippet>go_back}} {{wvds:acmenu dynamic="2"}} ==== Primjer 4: Eksplicitni namespace ==== {{wvds:acmenu ns="hr:api"}} ==== Primjer 5: Total Commander način ==== Za velike strukture - prikazuje samo trenutno područje s linkom "Idi gore": {{wvds:acmenu startns="current" icons="fa"}} Rezultat (za stranicu ''hr:crypto:openssl:start''): ↑ .. 📂 openssl 📄 start 📁 commands 📄 examples ==== Primjer 6: Kompaktni izbornik s ikonama ==== {{wvds:acmenu startns="current" dynamic="1" icons="fa"}} ---- ===== CSS klase ===== ^ Klasa ^ Opis ^ | ''.acmenu'' | Glavni kontejner | | ''.acmenu-icons'' | Kontejner s FontAwesome ikonama | | ''.acmenu-up'' | Link "Idi gore" (startns=current) | | ''.open'' | Otvorena mapa | | ''.closed'' | Zatvorena mapa | | ''.partial'' | Mapa s samo djelomično čitljivim sadržajem (ACL) | | ''.ns-label'' | Oznaka bez linka (za partial_ns mape) | | ''.curid'' | Trenutna stranica | | ''.divert'' | Vanjski namespace | | ''.lazy'' | Mapa s još neučitanim sadržajima | | ''.loading'' | Mapa se upravo učitava putem AJAX-a | ==== Stiliziranje za Partial namespaceove ==== /* Partial namespaceovi - klikljivo za proširenje */ div.acmenu li.partial > div.li { cursor: pointer; } div.acmenu li.partial > div.li .ns-label { color: #666; font-style: italic; } /* Boja ikone za partial mape */ div.acmenu.acmenu-icons li.partial > div.li .fa { color: #999; } Partial namespaceovi su **klikljivi** i proširuju se/skupljaju pri kliku, baš kao normalne mape. Razlika je samo u tome što nemaju link na start stranicu (jer ona nije čitljiva). ==== Stiliziranje za lazy učitavanje ==== /* Indikator učitavanja */ div.acmenu li.loading > div.li:after { content: " ⟳"; animation: spin 1s linear infinite; } @keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } } /* Vizualno označavanje lazy mapa */ div.acmenu li.lazy > div.li { cursor: pointer; } ---- ===== Konfiguracija ===== ^ Postavka ^ Tip ^ Standard ^ Opis ^ | ''startOpen'' | Da/Ne | Ne | Sve mape standardno otvorene | | ''sortType'' | Izbor | alpha | Sortiranje | | ''showPageTitle'' | Da/Ne | Da | Naslov stranice umjesto ID-a | | ''maxDepth'' | Broj | 0 | Maks. dubina (0 = neograničeno) | ---- ===== Pohrana cookieja ===== Otvorene mape se spremaju u cookie ''plugin_wvdsacmenu_open_items''. ==== Format cookieja ==== // Naziv cookieja plugin_wvdsacmenu_open_items // Vrijednost (JSON polje) ["hr:crypto:start","hr:docs:api:start"] ==== Serversko obnavljanje ==== Pri renderiranju dodatak čita cookie i prethodno učitava sve tamo spremljene mape - čak i ako su dublje od ''dynamic''. To obnavlja stanje izbornika bez JavaScript treperenja. ---- ===== Napomene o verzijama ===== ^ Verzija ^ Datum ^ Promjene ^ | 1.3.0 | 2026-01-29 | **ACL-aware navigacija:** ''ns="auto"'' Pametni Auto način (fokusirano + susjedni s Partial sadržajem), Partial namespaceovi (''partial_ns''), "Idi gore" temeljen na ACL-u na home namespace, ''_hasPartialChildren()'' za automatsko proširenje, ''_renderAutoSiblings()'' za prepoznavanje susjednih | | 1.2.0 | 2026-01-29 | ''startns="current"'' (Total Commander način), ''icons="fa"'' (FontAwesome ikone) | | 1.1.0 | 2026-01-29 | Lazy učitavanje, obnavljanje cookieja, ''%%{{wvds:title>...}}%%'' sintaksa | | 1.0.0 | 2025-01-06 | WvdS proširenja: Wiki sintaksa, višejezična podrška | ---- ===== Vidi također ===== * [[.:wvdssnippet]] - HTML blokovi * [[.:wvdsi18n]] - Višejezični tekstovi * [[.:flat]] - Predložak s bočnom trakom ---- ===== Tehnička referenca ===== ==== Klasa: syntax_plugin_wvdsacmenu ==== **Datoteka:** ''lib/plugins/wvdsacmenu/syntax.php'' ^ Metoda ^ Opis ^ | ''getType()'' | Vraća ''substition'' | | ''getSort()'' | Vraća ''320'' | | ''_findSidebar()'' | Traži sidebar* datoteku | | ''_tree()'' | Gradi stablo izbornika (s lazy podrškom i partial_ns) | | ''_hasReadableContent()'' | Provjerava postoje li čitljivi sadržaji u namespaceu | | ''_hasPartialChildren()'' | Provjerava sadrži li namespace partial_ns djecu | | ''_findUserHomeNamespace()'' | Pronalazi home namespace temeljen na ACL-u | | ''_renderAutoSiblings()'' | Renderira susjedne namespaceove s Partial sadržajem (za ns="auto") | | ''_shouldForceLoad()'' | Provjerava treba li namespace biti obnovljen putem cookieja | | ''_getPageTitle()'' | Dohvaća naslov stranice (wvds:title > heading > ID) | | ''buildSubTree()'' | Javno: Gradi podstablo za AJAX | | ''renderSubTree()'' | Javno: Renderira podstablo kao HTML | ==== Funkcija predloška: tpl_findSidebarInNamespace() ==== **Datoteka:** ''lib/tpl/flat/lang_helper.php'' ^ Parametar ^ Tip ^ Opis ^ | ''$sidebarName'' | string | Naziv datoteke bočne trake (npr. ''sidebar1'') | | **Povratna vrijednost** | string/null | Puni Page-ID ili null ako nije pronađeno | Traži datoteku bočne trake počevši od trenutnog namespacea prema gore. ==== Klasa: action_plugin_wvdsacmenu ==== **Datoteka:** ''lib/plugins/wvdsacmenu/action.php'' ^ Metoda ^ Opis ^ | ''_add_user_conf()'' | Konfiguracija za JavaScript (JSINFO) | | ''_ajax_load_ns()'' | AJAX handler za lazy učitavanje | ==== JavaScript: script.js ==== **Datoteka:** ''lib/plugins/wvdsacmenu/script.js'' ^ Funkcija ^ Opis ^ | ''get_cookie()'' | Čita otvorene stavke iz cookieja | | ''set_cookie()'' | Sprema otvorene stavke | | ''saveCookie()'' | Ažurira cookie nakon promjene | | ''trim_url()'' | Izvlači Page-ID iz URL-a | | ''handleLazyLoad()'' | AJAX učitavanje sadržaja mapa | | ''toggleItem()'' | Otvara/zatvara mapu | | ''hasIcons()'' | Provjerava jesu li ikone aktivirane | | ''updateFolderIcon()'' | Mijenja ikonu mape pri otvaranju/zatvaranju | ---- [x][x][x][x] [x][x][x][x][x] [x][x][x][-][-] ~~DISCUSSION~~