====== WvdS.DokuWiki.Snippet Plugin ======

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

----

===== Definition =====

Das **wvdssnippet** Plugin ermöglicht wiederverwendbare HTML-Bausteine (Snippets) mit zentraler Verwaltung. Es bietet eine sichere Alternative zu ''htmlok'' und erlaubt die Kombination von HTML mit mehrsprachigen Übersetzungen.

===== Anwendungsfälle =====

  * **Navigationsmenüs** - Hauptmenü, Sidebar-Navigation zentral verwalten
  * **Wiederholende Elemente** - Footer, Kopfzeilen, Buttons
  * **Lokalisierte Komponenten** - HTML mit integrierter Mehrsprachigkeit
  * **Widget-ähnliche Blöcke** - Social Media Links, Kontaktboxen
  * **Template-Erweiterungen** - Komplexe HTML-Strukturen in Wiki-Seiten

----

===== Syntax =====

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

==== Parameter ====

^ Parameter ^ Typ ^ Beschreibung ^
| **key** | string | Dateiname des Snippets (ohne .html Extension) |

----

===== Snippet-Definition =====

==== Datei-basierte Speicherung ====

Snippets werden als einzelne HTML-Dateien im Plugin-Verzeichnis gespeichert:

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

**Dateiformat:** ''{key}.html''

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

==== Regeln ====

^ Regel ^ Beschreibung ^
| Dateiname | Entspricht dem Snippet-Key (z.B. ''main_menu.html'' → ''<nowiki>{{wvds:snippet>main_menu}}</nowiki>'') |
| Inhalt | Vollständiger HTML-Code in der Datei |
| Mehrzeilig | Beliebig viele Zeilen möglich |
| wvdsi18n | ''<nowiki>{{wvds:i18n>...}}</nowiki>'' Tags werden verarbeitet |
| HTML | Vollständiges HTML erlaubt |

==== Erlaubte Inhalte ====

^ Inhaltstyp ^ Beispiel ^
| HTML-Tags | ''<div>'', ''<nav>'', ''<ul>'', etc. |
| CSS-Klassen | ''class="my-class"'' |
| Inline-Styles | ''style="color: red;"'' |
| JavaScript | ''onclick="..."'' (mit Vorsicht) |
| Font Awesome | ''<i class="fa fa-home"></i>'' |
| wvdsi18n Tags | ''<nowiki>{{wvds:i18n>menu_home}}</nowiki>'' |
| Inline-Übersetzungen | ''<nowiki>{{wvds:i18n>de:Text|en:Text}}</nowiki>'' |

----

===== Konfiguration =====

==== Admin-Einstellungen ====

Über **Admin → Konfiguration → wvdssnippet**:

^ Einstellung ^ Typ ^ Standard ^ Beschreibung ^
| ''allowPhp'' | An/Aus | Aus | PHP-Code in Snippets erlauben (Sicherheitsrisiko!) |

==== Admin-Interface ====

Über **Admin → WvdS Snippets** können Snippets direkt verwaltet werden:

^ Funktion ^ Beschreibung ^
| Snippet-Liste | Alle verfügbaren Snippets mit Vorschau anzeigen |
| Snippet bearbeiten | HTML-Inhalt im Textarea-Editor ändern |
| Neues Snippet | Neuen Snippet-Key erstellen |
| Snippet löschen | Snippet-Datei entfernen (mit Bestätigung) |

==== Beispiel-Snippet (main_menu.html) ====

**Datei:** ''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>

==== Beispiel-Snippet (go_back.html) ====

**Datei:** ''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>

----

===== Beispiele =====

==== Beispiel 1: Hauptmenü in Sidebar ====

**Anforderung:** Zentrales Navigationsmenü für alle Seiten.

**Snippet-Datei:** ''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>

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

**Ergebnis:**
  * Menü erscheint auf allen Seiten
  * Übersetzungen werden automatisch angewendet
  * Änderungen über Admin-Interface oder direkt in der Datei

==== Beispiel 2: Zurück-Link mit Icon ====

**Anforderung:** Einheitlicher Zurück-Link in Unter-Namespaces.

**Snippet-Datei:** ''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|sl:Nazaj}}</a>
</div>
</code>

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

==== Beispiel 3: Kontaktbox ====

**Anforderung:** Wiederverwendbare Kontaktinformationen.

**Snippet-Datei:** ''lib/plugins/wvdssnippet/snippets/contact_box.html''
<code html>
<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>

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

==== Beispiel 4: Mehrsprachiger Footer ====

**Anforderung:** Footer mit dynamischem Jahr und lokalisierten Links.

**Snippet-Datei:** ''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>

----

===== Funktionsweise =====

==== Verarbeitungs-Pipeline ====

<code>
1. Syntax-Erkennung
   └── Findet alle {{wvds:snippet>...}} Tags

2. Snippet-Lookup
   └── Sucht Snippet-Datei: snippets/{key}.html
   └── Lädt den HTML-Inhalt aus der Datei

3. wvdsi18n-Verarbeitung
   └── Ersetzt {{wvds:i18n>...}} Tags im Snippet
   └── Wendet aktuelle Sprache an

4. HTML-Ausgabe
   └── Fügt verarbeiteten HTML-Code in Seite ein
   └── Keine zusätzliche Escaping (Raw HTML)
</code>

==== Verarbeitungsreihenfolge ====

^ Priorität ^ Plugin ^ Sort-Wert ^
| 1 | wvdsi18n | 305 |
| 2 | wvdssnippet | 310 |
| 3 | wvdsimage | 319 |

<note>
wvdsi18n wird **vor** wvdssnippet verarbeitet, damit Übersetzungen in Snippets funktionieren.
</note>

----

===== Integration =====

==== Mit wvdsi18n ====

Snippets unterstützen alle wvdsi18n-Syntaxen:

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

==== Mit wvdsacmenu ====

Typische Sidebar-Struktur:

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

==== Mit wvdsimage ====

Snippets können auch Bilder enthalten:

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

----

===== Sicherheit =====

==== Vorteile gegenüber htmlok ====

^ Aspekt ^ htmlok ^ wvdssnippet ^
| HTML-Eingabe | Frei in jeder Seite | Nur über Admin |
| Sicherheitsrisiko | Hoch (XSS, Injection) | Niedrig (kontrolliert) |
| Audit | Schwierig (verstreut) | Einfach (zentral) |
| Benutzer-Rechte | Jeder mit Bearbeitung | Nur Administratoren |

==== Best Practices ====

  * **JavaScript minimal halten** - Nur wenn unbedingt nötig
  * **Externe Links mit target="_blank"** - Sicherheit mit ''rel="noopener"''
  * **Keine sensiblen Daten** - Keine API-Keys, Passwörter in Snippets
  * **Eindeutige Namen** - Snippet-Namen aussagekräftig wählen

----

===== Fehlerbehandlung =====

==== Verhalten bei Fehlern ====

^ Szenario ^ Verhalten ^
| Snippet nicht gefunden | Gibt ''[snippet_name not found]'' aus |
| Leeres Snippet | Gibt nichts aus |
| Ungültiges Format | Ignoriert ungültige Zeilen |
| wvdsi18n-Fehler | Gibt Key zurück (Fallback) |

==== Debugging ====

Bei Problemen prüfen:

  * Ist der Snippet-Name korrekt geschrieben?
  * Existiert die Datei ''lib/plugins/wvdssnippet/snippets/{key}.html''?
  * Hat die Datei die Erweiterung ''.html''?
  * Ist ''~~NOCACHE~~'' gesetzt für dynamische Inhalte?
  * Funktionieren die wvdsi18n-Tags einzeln?

----

===== Performance =====

==== Empfehlungen ====

| Szenario | Empfehlung |
| Statische Snippets | Cache aktiviert lassen |
| Dynamische Snippets (Sprache) | ''~~NOCACHE~~'' verwenden |
| Große Snippets | In kleinere aufteilen |
| Viele Snippets | Nicht mehr als 50 definieren |

==== Caching ====

<note tip>
Seiten mit sprachabhängigen Snippets sollten ''~~NOCACHE~~'' am Anfang haben, damit die richtige Sprachversion angezeigt wird.
</note>

----

===== Versionshinweise =====

^ Version ^ Datum ^ Änderungen ^
| 2.1.0 | 2026-01-26 | Admin-Interface, Datei-basierte Speicherung (HTML-Dateien) |
| 2.0.0 | 2026-01-06 | Umbenennung von wvdschunk zu wvdssnippet |
| 1.0.0 | 2025-01-06 | Erstveröffentlichung |

----

===== Siehe auch =====

  * [[.:wvdsi18n]] - Mehrsprachige Übersetzungen
  * [[.:wvdsacmenu]] - Akkordeon-Menü
  * [[.:wvdsimage]] - Responsive Bilder
  * [[.:flat]] - Template-Erweiterungen

----

===== Technische Referenz =====

==== Klasse: syntax_plugin_wvdssnippet ====

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

^ Methode ^ Beschreibung ^
| ''getType()'' | Gibt ''substitution'' zurück |
| ''getSort()'' | Gibt ''310'' zurück (nach wvdsi18n) |
| ''connectTo($mode)'' | Registriert Pattern ''\\{\\{wvds:snippet>[^}]+\\}\\}'' |
| ''handle($match, ...)'' | Extrahiert Snippet-Namen |
| ''render($mode, ...)'' | Gibt HTML-Inhalt aus |

==== Klasse: helper_plugin_wvdssnippet ====

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

^ Methode ^ Parameter ^ Rückgabe ^ Beschreibung ^
| ''getSnippets()'' | - | array | Lädt alle Snippets aus dem snippets-Verzeichnis |
| ''get()'' | $name | string | Gibt Snippet-Inhalt zurück |

==== Klasse: admin_plugin_wvdssnippet ====

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

^ Methode ^ Beschreibung ^
| ''html()'' | Rendert Admin-Interface |
| ''handle()'' | Verarbeitet Formular-Aktionen (speichern, löschen, erstellen) |

==== Dateistruktur ====

<code>
lib/plugins/wvdssnippet/
├── admin.php          → Admin-Interface
├── helper.php         → Snippet-Laden und -Verarbeitung
├── syntax.php         → Wiki-Syntax Parser
├── conf/
│   ├── default.php    → Standard-Einstellungen
│   └── metadata.php   → Admin-UI Metadaten
└── snippets/          → Snippet HTML-Dateien
    ├── main_menu.html
    ├── go_back.html
    └── ...
</code>

----

<wvds:audit stack="doku" title="wvdssnippet Plugin">
  <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~~