====== WvdS.DokuWiki.Snippet Dodatak ======

**Dodatak:** wvdssnippet\\
**Verzija:** 2.0.0\\
**Namespace:** ''lib/plugins/wvdssnippet/''\\
**Autor:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**Licenca:** GPL 2

----

===== Definicija =====

Dodatak **wvdssnippet** omogućuje višekratno korištenje HTML blokova (snippeta) s centralnim upravljanjem. Pruža sigurnu alternativu za ''htmlok'' i omogućuje kombiniranje HTML-a s višejezičnim prijevodima.

===== Slučajevi korištenja =====

  * **Navigacijski izbornici** - Centralno upravljanje glavnim izbornikom i sidebar navigacijom
  * **Ponavljajući elementi** - Footer, zaglavlja, gumbi
  * **Lokalizirane komponente** - HTML s integriranom višejezičnošću
  * **Widget blokovi** - Linkovi društvenih mreža, kontakt kutije
  * **Proširenja predložaka** - Složene HTML strukture na wiki stranicama

----

===== Sintaksa =====

<code>
{{wvds:snippet>key}}
</code>

==== Parametri ====

^ Parametar ^ Tip ^ Opis ^
| **key** | string | Naziv datoteke snippeta (bez .html ekstenzije) |

----

===== Definicija snippeta =====

==== Pohrana u datotekama ====

Snippeti se pohranjuju kao pojedinačne HTML datoteke u direktoriju dodatka:

**Direktorij:** ''lib/plugins/wvdssnippet/snippets/''

**Format datoteke:** ''{key}.html''

<code>
lib/plugins/wvdssnippet/snippets/
├── main_menu.html
├── go_back.html
├── social_links.html
├── contact_box.html
└── footer.html
</code>

==== Pravila ====

^ Pravilo ^ Opis ^
| Naziv datoteke | Odgovara ključu snippeta (npr. ''main_menu.html'' → ''<nowiki>{{wvds:snippet>main_menu}}</nowiki>'') |
| Sadržaj | Potpuni HTML kod u datoteci |
| Višeredni | Moguće proizvoljan broj redova |
| wvdsi18n | ''<nowiki>{{wvds:i18n>...}}</nowiki>'' oznake se obrađuju |
| HTML | Potpuni HTML dopušten |

==== Dopušteni sadržaji ====

^ Tip sadržaja ^ Primjer ^
| HTML oznake | ''<div>'', ''<nav>'', ''<ul>'', itd. |
| CSS klase | ''class="my-class"'' |
| Inline stilovi | ''style="color: red;"'' |
| JavaScript | ''onclick="..."'' (s oprezom) |
| Font Awesome | ''<i class="fa fa-home"></i>'' |
| wvdsi18n oznake | ''<nowiki>{{wvds:i18n>menu_home}}</nowiki>'' |
| Inline prijevodi | ''<nowiki>{{wvds:i18n>de:Text|en:Text}}</nowiki>'' |

----

===== Konfiguracija =====

==== Administratorske postavke ====

Preko **Admin → Konfiguracija → wvdssnippet**:

^ Postavka ^ Tip ^ Standard ^ Opis ^
| ''allowPhp'' | Da/Ne | Ne | Dopusti PHP kod u snippetima (sigurnosni rizik!) |

==== Administratorsko sučelje ====

Preko **Admin → WvdS Snippets** možete izravno upravljati snippetima:

^ Funkcija ^ Opis ^
| Lista snippeta | Prikaži sve dostupne snippete s pregledom |
| Uredi snippet | Izmijeni HTML sadržaj u textarea editoru |
| Novi snippet | Kreiraj novi ključ snippeta |
| Obriši snippet | Ukloni datoteku snippeta (s potvrdom) |

==== Primjer snippeta (main_menu.html) ====

**Datoteka:** ''lib/plugins/wvdssnippet/snippets/main_menu.html''

<code html>
<nav class="main-menu">
    <ul class="menu-list">
        <li class="menu-item"><a href="?id=start">{{wvds:i18n>menu_home}}</a></li>
        <li class="menu-item"><a href="?id=docs">{{wvds:i18n>menu_docs}}</a></li>
        <li class="menu-item"><a href="?id=contact">{{wvds:i18n>menu_contact}}</a></li>
    </ul>
</nav>
</code>

==== Primjer snippeta (go_back.html) ====

**Datoteka:** ''lib/plugins/wvdssnippet/snippets/go_back.html''

<code html>
<div class="go-back">
    <i class="fa fa-arrow-left"></i>
    <a href="javascript:history.back()">{{wvds:i18n>menu_back}}</a>
</div>
</code>

----

===== Primjeri =====

==== Primjer 1: Glavni izbornik u sidebaru ====

**Zahtjev:** Centralni navigacijski izbornik za sve stranice.

**Datoteka snippeta:** ''lib/plugins/wvdssnippet/snippets/main_menu.html''
<code html>
<nav class="main-menu">
    <ul>
        <li><a href="?id=start">{{wvds:i18n>menu_home}}</a></li>
        <li><a href="?id=de:docs:start">{{wvds:i18n>menu_docs}}</a></li>
    </ul>
</nav>
</code>

**Korištenje u sidebar.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>main_menu}}
</code>

**Rezultat:**
  * Izbornik se pojavljuje na svim stranicama
  * Prijevodi se automatski primjenjuju
  * Promjene preko admin sučelja ili izravno u datoteci

==== Primjer 2: Link za povratak s ikonom ====

**Zahtjev:** Ujednačen link za povratak u pod-namespaceovima.

**Datoteka snippeta:** ''lib/plugins/wvdssnippet/snippets/go_back.html''
<code html>
<div class="go-back" style="margin-bottom: 1em;">
    <i class="fa fa-arrow-left" style="margin-right: 0.5em;"></i>
    <a href="javascript:history.back()">{{wvds:i18n>de:Zurück|en:Back|hr:Natrag}}</a>
</div>
</code>

**Korištenje u sidebar1.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== Primjer 3: Kontakt kutija ====

**Zahtjev:** Višekratno korištenje kontaktnih informacija.

**Datoteka snippeta:** ''lib/plugins/wvdssnippet/snippets/contact_box.html''
<code html>
<div class="contact-box">
    <h4>{{wvds:i18n>de:Kontakt|en:Contact|hr:Kontakt}}</h4>
    <p>
        <i class="fa fa-envelope"></i> info@example.com<br>
        <i class="fa fa-phone"></i> +49 123 456789
    </p>
</div>
</code>

**Korištenje:**
<code>
{{wvds:snippet>contact_box}}
</code>

==== Primjer 4: Višejezični footer ====

**Zahtjev:** Footer s dinamičkom godinom i lokaliziranim linkovima.

**Datoteka snippeta:** ''lib/plugins/wvdssnippet/snippets/footer.html''
<code html>
<footer class="site-footer">
    <div class="footer-content">
        <p>&copy; 2026 {{wvds:i18n>conf:title}}</p>
        <nav class="footer-links">
            <a href="?id=impressum">{{wvds:i18n>menu_imprint}}</a> |
            <a href="?id=datenschutz">{{wvds:i18n>menu_privacy}}</a> |
            <a href="?id=sitemap">{{wvds:i18n>menu_sitemap}}</a>
        </nav>
    </div>
</footer>
</code>

----

===== Način rada =====

==== Cjevovod obrade ====

<code>
1. Prepoznavanje sintakse
   └── Pronalazi sve {{wvds:snippet>...}} oznake

2. Pretraga snippeta
   └── Traži datoteku snippeta: snippets/{key}.html
   └── Učitava HTML sadržaj iz datoteke

3. wvdsi18n obrada
   └── Zamjenjuje {{wvds:i18n>...}} oznake u snippetu
   └── Primjenjuje trenutni jezik

4. HTML izlaz
   └── Umeće obrađeni HTML kod u stranicu
   └── Bez dodatnog escapinga (Raw HTML)
</code>

==== Redoslijed obrade ====

^ Prioritet ^ Dodatak ^ Sort vrijednost ^
| 1 | wvdsi18n | 305 |
| 2 | wvdssnippet | 310 |
| 3 | wvdsimage | 319 |

<note>
wvdsi18n se obrađuje **prije** wvdssnippet kako bi prijevodi u snippetima funkcionirali.
</note>

----

===== Integracija =====

==== S wvdsi18n ====

Snippeti podržavaju sve wvdsi18n sintakse:

**Datoteka:** ''lib/plugins/wvdssnippet/snippets/multilingual_block.html''
<code html>
<div class="info">
    {{wvds:i18n>greeting}}
    {{wvds:i18n>de:Hallo|en:Hello|hr:Bok}}
    {{wvds:lang:en>english_only_text}}
</div>
</code>

==== S wvdsacmenu ====

Tipična struktura sidebara:

<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== S wvdsimage ====

Snippeti mogu sadržavati i slike:

**Datoteka:** ''lib/plugins/wvdssnippet/snippets/logo_block.html''
<code html>
<div class="logo">
    {{wvds:image>wiki:logo.png|width=100%|maxwidth=200}}
</div>
</code>

----

===== Sigurnost =====

==== Prednosti u odnosu na htmlok ====

^ Aspekt ^ htmlok ^ wvdssnippet ^
| HTML unos | Slobodan na svakoj stranici | Samo preko Admina |
| Sigurnosni rizik | Visok (XSS, Injection) | Nizak (kontrolirano) |
| Revizija | Teška (raspršeno) | Jednostavna (centralno) |
| Korisnička prava | Svatko s uređivanjem | Samo administratori |

==== Najbolje prakse ====

  * **JavaScript minimalan** - Samo ako je nužno
  * **Vanjski linkovi s target="_blank"** - Sigurnost s ''rel="noopener"''
  * **Bez osjetljivih podataka** - Bez API ključeva, lozinki u snippetima
  * **Jedinstvena imena** - Odabir opisnih naziva snippeta

----

===== Rukovanje greškama =====

==== Ponašanje pri greškama ====

^ Scenarij ^ Ponašanje ^
| Snippet nije pronađen | Ispisuje ''[snippet_name not found]'' |
| Prazan snippet | Ne ispisuje ništa |
| Nevažeći format | Ignorira nevažeće redove |
| wvdsi18n greška | Vraća ključ (Fallback) |

==== Debugging ====

Kod problema provjerite:

  * Je li naziv snippeta ispravno napisan?
  * Postoji li datoteka ''lib/plugins/wvdssnippet/snippets/{key}.html''?
  * Ima li datoteka ekstenziju ''.html''?
  * Je li ''~~NOCACHE~~'' postavljen za dinamične sadržaje?
  * Funkcioniraju li wvdsi18n oznake pojedinačno?

----

===== Performanse =====

==== Preporuke ====

| Scenarij | Preporuka |
| Statični snippeti | Ostaviti cache aktiviran |
| Dinamični snippeti (jezik) | Koristiti ''~~NOCACHE~~'' |
| Veliki snippeti | Podijeliti na manje |
| Mnogo snippeta | Ne više od 50 definiranih |

==== Caching ====

<note tip>
Stranice s jezično ovisnim snippetima trebaju imati ''~~NOCACHE~~'' na početku kako bi se prikazala ispravna jezična verzija.
</note>

----

===== Napomene o verzijama =====

^ Verzija ^ Datum ^ Promjene ^
| 2.1.0 | 2026-01-26 | Admin sučelje, pohrana u datotekama (HTML datoteke) |
| 2.0.0 | 2026-01-06 | Preimenovanje iz wvdschunk u wvdssnippet |
| 1.0.0 | 2025-01-06 | Prva objava |

----

===== Vidi također =====

  * [[.:wvdsi18n]] - Višejezični prijevodi
  * [[.:wvdsacmenu]] - Harmonika izbornik
  * [[.:wvdsimage]] - Responzivne slike
  * [[.:flat]] - Proširenja predloška

----

===== Tehnička referenca =====

==== Klasa: syntax_plugin_wvdssnippet ====

**Datoteka:** ''lib/plugins/wvdssnippet/syntax.php''

^ Metoda ^ Opis ^
| ''getType()'' | Vraća ''substition'' |
| ''getSort()'' | Vraća ''310'' (nakon wvdsi18n) |
| ''connectTo($mode)'' | Registrira pattern ''\\{\\{wvds:snippet>[^}]+\\}\\}'' |
| ''handle($match, ...)'' | Izvlači naziv snippeta |
| ''render($mode, ...)'' | Ispisuje HTML sadržaj |

==== Klasa: helper_plugin_wvdssnippet ====

**Datoteka:** ''lib/plugins/wvdssnippet/helper.php''

^ Metoda ^ Parametri ^ Povratna vrijednost ^ Opis ^
| ''getSnippets()'' | - | array | Učitava sve snippete iz direktorija snippets |
| ''get()'' | $name | string | Vraća sadržaj snippeta |

==== Klasa: admin_plugin_wvdssnippet ====

**Datoteka:** ''lib/plugins/wvdssnippet/admin.php''

^ Metoda ^ Opis ^
| ''html()'' | Renderira admin sučelje |
| ''handle()'' | Obrađuje akcije forme (spremi, obriši, kreiraj) |

==== Struktura datoteka ====

<code>
lib/plugins/wvdssnippet/
├── admin.php          → Admin sučelje
├── helper.php         → Učitavanje i obrada snippeta
├── syntax.php         → Wiki sintaksa parser
├── conf/
│   ├── default.php    → Zadane postavke
│   └── metadata.php   → Admin UI metapodaci
└── snippets/          → Snippet HTML datoteke
    ├── main_menu.html
    ├── go_back.html
    └── ...
</code>

----

<wvds:audit stack="doku" title="wvdssnippet Dodatak">
  <wvds:include ref="code:qualitaet" critical="true">[x][x][x][x]</wvds:include>
  <wvds:include ref="stacks:dokuwiki-php">[x][x][x][x][x]</wvds:include>
  <wvds:include ref="sicherheit:kritis" critical="true">[x][x][x][-][-]</wvds:include>
</wvds:audit>

~~DISCUSSION~~