====== WvdS.DokuWiki.Snippet Vticnik ======

**Vticnik:** wvdssnippet\\
**Verzija:** 2.0.0\\
**Imenski prostor:** ''lib/plugins/wvdssnippet/''\\
**Avtor:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**Licenca:** GPL 2

----

===== Definicija =====

Vticnik **wvdssnippet** omogoca veckratno uporabne HTML gradnike (snippete) s centraliziranim upravljanjem. Ponuja varno alternativo ''htmlok'' in omogoca kombiniranje HTML z vecjezicnimi prevodi.

===== Primeri uporabe =====

  * **Navigacijski meniji** - Glavni meni, stranska navigacija centralno upravljana
  * **Ponavljajoci elementi** - Podnozje, glave, gumbi
  * **Lokalizirane komponente** - HTML z integrirano vecjezicnostjo
  * **Bloki podobni pripomockom** - Povezave do druzabnih omrezij, kontaktne skatle
  * **Razsiritve predlog** - Kompleksne HTML strukture v wiki straneh

----

===== Sintaksa =====

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

==== Parametri ====

^ Parameter ^ Tip ^ Opis ^
| **key** | string | Ime snippeta iz konfiguracije |

----

===== Definicija snippetov =====

==== Format ====

Snippeti so definirani v konfiguraciji vticnika v naslednjem formatu:

<code>
[snippet_name]
HTML vsebina tukaj
lahko je vecvrsticna
{{wvds:i18n>key}} oznake so dovoljene
</code>

==== Pravila ====

^ Pravilo ^ Opis ^
| Vrstica z imenom | Zacne se z ''[ime]'' v svoji vrstici |
| Vsebina | Vse po vrstici z imenom do naslednjega ''[...]'' |
| Vecvrsticno | Mozno poljubno stevilo vrstic |
| Prazne vrstice | Dovoljene znotraj snippeta |
| wvdsi18n | ''<nowiki>{{wvds:i18n>...}}</nowiki>'' oznake se obdelajo |
| HTML | Popolni HTML dovoljen |

==== Dovoljena vsebina ====

^ Vrsta vsebine ^ Primer ^
| HTML oznake | ''<div>'', ''<nav>'', ''<ul>'', itd. |
| CSS razredi | ''class="my-class"'' |
| Vgrajeni slogi | ''style="color: red;"'' |
| JavaScript | ''onclick="..."'' (uporabljajte previdno) |
| Font Awesome | ''<i class="fa fa-home"></i>'' |
| wvdsi18n oznake | ''<nowiki>{{wvds:i18n>menu_home}}</nowiki>'' |
| Vgrajeni prevodi | ''<nowiki>{{wvds:i18n>de:Besedilo|en:Text}}</nowiki>'' |

----

===== Konfiguracija =====

==== Skrbniške nastavitve ====

Preko **Skrbnik → Konfiguracija → wvdssnippet**:

^ Nastavitev ^ Tip ^ Opis ^
| ''enabled'' | Vklop/Izklop | Omogoci/onemogoci vticnik |
| ''snippets'' | Textarea | Definicije snippetov v formatu podobnem INI |

==== Primer konfiguracije ====

<code>
[main_menu]
<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>

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

[social_links]
<div class="social-links">
    <a href="https://github.com/myorg" target="_blank"><i class="fa fa-github"></i></a>
    <a href="https://twitter.com/myorg" target="_blank"><i class="fa fa-twitter"></i></a>
</div>

[footer]
<footer class="site-footer">
    <div class="copyright">
        &copy; 2025 {{wvds:i18n>conf:title}}
    </div>
    <div class="links">
        <a href="?id=kolofon">{{wvds:i18n>menu_imprint}}</a>
        <a href="?id=zasebnost">{{wvds:i18n>menu_privacy}}</a>
    </div>
</footer>
</code>

----

===== Primeri =====

==== Primer 1: Glavni meni v stranski vrstici ====

**Zahteva:** Centralni navigacijski meni za vse strani.

**Definicija snippeta:**
<code>
[main_menu]
<nav class="main-menu">
    <ul>
        <li><a href="?id=start">{{wvds:i18n>menu_home}}</a></li>
        <li><a href="?id=sl:docs:start">{{wvds:i18n>menu_docs}}</a></li>
    </ul>
</nav>
</code>

**Uporaba v sidebar.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>main_menu}}
</code>

**Rezultat:**
  * Meni se pojavi na vseh straneh
  * Prevodi se samodejno uporabijo
  * Spremembe so centralizirane v konfiguraciji

==== Primer 2: Povezava nazaj z ikono ====

**Zahteva:** Enotna povezava nazaj v pod-imenskih prostorih.

**Definicija snippeta:**
<code>
[go_back]
<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|sl:Nazaj}}</a>
</div>
</code>

**Uporaba v sidebar1.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== Primer 3: Kontaktna skatla ====

**Zahteva:** Veckratno uporabne kontaktne informacije.

**Definicija snippeta:**
<code>
[contact_box]
<div class="contact-box">
    <h4>{{wvds:i18n>de:Kontakt|en:Contact|sl: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>

**Uporaba:**
<code>
{{wvds:snippet>contact_box}}
</code>

==== Primer 4: Vecjezicno podnozje ====

**Zahteva:** Podnozje z dinamicnim letom in lokaliziranimi povezavami.

**Definicija snippeta:**
<code>
[footer]
<footer class="site-footer">
    <div class="footer-content">
        <p>&copy; 2025 {{wvds:i18n>conf:title}}</p>
        <nav class="footer-links">
            <a href="?id=kolofon">{{wvds:i18n>menu_imprint}}</a> |
            <a href="?id=zasebnost">{{wvds:i18n>menu_privacy}}</a> |
            <a href="?id=zemljevid">{{wvds:i18n>menu_sitemap}}</a>
        </nav>
    </div>
</footer>
</code>

----

===== Kako deluje =====

==== Procesni cevovod ====

<code>
1. Zaznava sintakse
   └── Najde vse {{wvds:snippet>...}} oznake

2. Iskanje snippeta
   └── Išce ime snippeta v konfiguraciji
   └── Izvlece HTML vsebino

3. Obdelava wvdsi18n
   └── Zamenja {{wvds:i18n>...}} oznake v snippetu
   └── Uporabi trenutni jezik

4. HTML izhod
   └── Vstavi obdelano HTML kodo v stran
   └── Brez dodatnega escaping-a (surov HTML)
</code>

==== Vrstni red obdelave ====

^ Prioriteta ^ Vticnik ^ Sort vrednost ^
| 1 | wvdsi18n | 305 |
| 2 | wvdssnippet | 310 |
| 3 | wvdsimage | 319 |

<note>
wvdsi18n se obdela **pred** wvdssnippet, da prevodi v snippetih delujejo pravilno.
</note>

----

===== Integracija =====

==== Z wvdsi18n ====

Snippeti podpirajo vse variante sintakse wvdsi18n:

<code>
[multilingual_block]
<div class="info">
    {{wvds:i18n>greeting}}
    {{wvds:i18n>de:Hallo|en:Hello|sl:Zdravo}}
    {{wvds:lang:en>english_only_text}}
</div>
</code>

==== Z wvdsacmenu ====

Tipicna struktura stranske vrstice:

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

==== Z wvdsimage ====

Snippeti lahko vsebujejo tudi slike:

<code>
[logo_block]
<div class="logo">
    {{wvds:image>wiki:logo.png|width=100%|maxwidth=200}}
</div>
</code>

----

===== Varnost =====

==== Prednosti pred htmlok ====

^ Vidik ^ htmlok ^ wvdssnippet ^
| HTML vnos | Prosto v vsaki strani | Samo preko skrbnika |
| Varnostno tveganje | Visoko (XSS, vbrizgavanje) | Nizko (nadzorovano) |
| Revizija | Tezka (razpršeno) | Enostavna (centralno) |
| Uporabniške pravice | Kdorkoli s pravicami urejanja | Samo skrbniki |

==== Dobre prakse ====

  * **Ohranjajte JavaScript minimalen** - Samo ko je nujno potrebno
  * **Zunanje povezave s target="_blank"** - Varnost z ''rel="noopener"''
  * **Brez obcutljivih podatkov** - Brez API kljucev, gesel v snippetih
  * **Edinstvena imena** - Izberite opisna imena snippetov

----

===== Obravnava napak =====

==== Vedenje ob napakah ====

^ Scenarij ^ Vedenje ^
| Snippet ni najden | Izpise ''[snippet_name not found]'' |
| Prazen snippet | Ne izpise nicesar |
| Neveljaven format | Ignorira neveljavne vrstice |
| wvdsi18n napaka | Vrne kljuc (nadomestna vrednost) |

==== Razhroščevanje ====

Ce se pojavijo tezave, preverite:

  * Ali je ime snippeta pravilno zapisano?
  * Ali se definicija zacne z ''[ime]''?
  * Ali je ''~~NOCACHE~~'' nastavljen za dinamicno vsebino?
  * Ali wvdsi18n oznake delujejo posamezno?

----

===== Zmogljivost =====

==== Priporocila ====

| Scenarij | Priporocilo |
| Staticni snippeti | Pustite predpomnilnik omogocen |
| Dinamicni snippeti (jezik) | Uporabite ''~~NOCACHE~~'' |
| Veliki snippeti | Razdelite v manjše |
| Veliko snippetov | Ne definirajte vec kot 50 |

==== Predpomnjenje ====

<note tip>
Strani z jezikovno odvisnimi snippeti naj imajo ''~~NOCACHE~~'' na zacetku, da se prikaže pravilna jezikovna razlicica.
</note>

----

===== Zgodovina verzij =====

^ Verzija ^ Datum ^ Spremembe ^
| 2.0.0 | 2026-01-06 | Preimenovanje iz wvdschunk v wvdssnippet |
| 1.0.0 | 2025-01-06 | Zacetna izdaja |

----

===== Glej tudi =====

  * [[wvdsi18n]] - Vecjezicni prevodi
  * [[wvdsacmenu]] - Harmonika meni
  * [[wvdsimage]] - Odzivne slike
  * [[flat]] - Razsiritve predloge

----

===== Tehnicna referenca =====

==== Razred: syntax_plugin_wvdssnippet ====

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

^ Metoda ^ Opis ^
| ''getType()'' | Vrne ''substition'' |
| ''getSort()'' | Vrne ''310'' (po wvdsi18n) |
| ''connectTo($mode)'' | Registrira vzorec ''\\{\\{wvds:snippet>[^}]+\\}\\}'' |
| ''handle($match, ...)'' | Izvlece ime snippeta |
| ''render($mode, ...)'' | Izda HTML vsebino |

==== Zasebne metode ====

^ Metoda ^ Parametri ^ Vrne ^ Opis ^
| ''getSnippet()'' | $name | string | Išce snippet v konfiguraciji |
| ''parseSnippets()'' | $config | array | Razcleni definicije snippetov |
| ''processSnippet()'' | $content | string | Obdela wvdsi18n oznake |

==== Format konfiguracije ====

<code>
# Komentarji z # (so ignorirani)

[snippet_name_1]
HTML vsebina za snippet 1
lahko je vecvrsticna

[snippet_name_2]
HTML vsebina za snippet 2
</code>

----

{{wvds:snippet>wvds_audit_badge}}

~~DISCUSSION~~