WvdS Snippet Plugin

Snippet setzt wiederverwendbare HTML-Bausteine in eine Seite ein – über die Marke {{wk:snippet>kennung}}, unabhängig von der Einstellung htmlok. Ein Snippet wird einmal definiert und überall dort eingesetzt, wo es gebraucht wird. Gedacht ist das Paket für Autoren, die wiederkehrende Blöcke nicht abschreiben wollen, und für Verwalter, die den Bestand an Snippets pflegen.

Schnelleinstieg: Ein Snippet anlegen und einbinden – der kürzeste Weg zum ersten Ergebnis, in drei Schritten.

Snippet anlegen → Marke auf einer Seite setzen → Ergebnis prüfen

Das wksnippet 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.

• 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

{{wk:snippet>key}}

Jedes Snippet ist eine eigene HTML-Datei. Das Paket liest zwei Verzeichnisse:

Snippets der Site: <savedir>/wksnippet/ – hierhin schreibt der Verwaltungsbildschirm. Das Verzeichnis liegt neben data/pages, gehört damit zur selben Sicherung und übersteht jede Neuinstallation des Plugins.

Mitgelieferte Snippets: lib/plugins/wksnippet/snippets/ – Vorgaben, die mit dem Plugin kommen; nur lesend, bei jeder Installation ersetzt.

Dateiformat: {key}.html. Hat ein Snippet der Site denselben Schlüssel wie ein mitgeliefertes, gilt das der Site; wird es gelöscht, gilt wieder das mitgelieferte.

<savedir>/wksnippet/
├── main_menu.html
├── contact_box.html
└── footer.html

lib/plugins/wksnippet/snippets/
├── alert_box.html
├── breadcrumb_separator.html
├── go_back.html
└── social_links.html

Über Admin → Konfiguration → wksnippet:

PHP-Code in einem Snippet wird nur ausgeführt, wenn drei Bedingungen zugleich erfüllt sind: Die Marke trägt den Zusatz |php ({{wk:snippet>key|php}}), allowPhp ist eingeschaltet, und die DokuWiki-Einstellung phpok ist eingeschaltet. allowPhp gibt die Ausführung für dieses Plugin frei, phpok für das ganze Wiki; keiner der beiden Schalter ersetzt den anderen. Fehlt eine Bedingung, wird der Inhalt unverändert ausgegeben und kein PHP ausgeführt.

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

In der Vorschau erscheint jeder Platzhalter ({{wk:lang>…}}, {{wk:image>…}}) als unteilbarer Chip mit dem vollen Token im Tooltip – er wird byteweise unverändert gespeichert. <style>- und <script>-Blöcke eines Snippets wirken nur innerhalb der Vorschau (Sandbox-iframe ohne Skriptausführung), nicht auf die Admin-Seite.

Eine Bearbeitung in der Vorschau schreibt den Quelltext neu formatiert zurück; ein einzelnes Strg+Z im Quelltextfeld nimmt das zurück. Wer nur links arbeitet, ändert an der Formatierung der Datei nichts.

Datei: <savedir>/wksnippet/main_menu.html

<nav class="main-menu">
    <ul class="menu-list">
        <li class="menu-item"><a href="?id=start">Home</a></li>
        <li class="menu-item"><a href="?id=docs">Project Documentation</a></li>
        <li class="menu-item"><a href="?id=contact">Contact</a></li>
    </ul>
</nav>

Datei: lib/plugins/wksnippet/snippets/go_back.html

<div class="go-back">
    <i class="fa fa-arrow-left"></i>
    <a href="javascript:history.back()">Go Back</a>
</div>

Anforderung: Zentrales Navigationsmenü für alle Seiten.

Snippet-Datei: <savedir>/wksnippet/main_menu.html

<nav class="main-menu">
    <ul>
        <li><a href="?id=start">Home</a></li>
        <li><a href="?id=de:docs:start">Project Documentation</a></li>
    </ul>
</nav>

Verwendung in sidebar.txt:

~~NOCACHE~~
{{wk:snippet>main_menu}}

Ergebnis:

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

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

Snippet-Datei: <savedir>/wksnippet/go_back.html (überdeckt das mitgelieferte Snippet mit demselben Schlüssel)

<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()">de:Zurück|en:Back|sl:Nazaj</a>
</div>

Verwendung in sidebar1.txt:

~~NOCACHE~~
{{wk:snippet>go_back}}
{{wk:acmenu}}

Anforderung: Wiederverwendbare Kontaktinformationen.

Snippet-Datei: <savedir>/wksnippet/contact_box.html

<div class="contact-box">
    <h4>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>

Verwendung:

{{wk:snippet>contact_box}}

Anforderung: Footer mit dynamischem Jahr und lokalisierten Links.

Snippet-Datei: <savedir>/wksnippet/footer.html

<footer class="site-footer">
    <div class="footer-content">
        <p>&copy; 2026 conf:title</p>
        <nav class="footer-links">
            <a href="?id=impressum">menu_imprint</a> |
            <a href="?id=datenschutz">menu_privacy</a> |
            <a href="?id=sitemap">menu_sitemap</a>
        </nav>
    </div>
</footer>

1. Syntax-Erkennung
   └── Findet alle {{wk:snippet>...}} Tags

2. Snippet-Lookup
   └── Sucht {key}.html: zuerst <savedir>/wksnippet/,
       sonst lib/plugins/wksnippet/snippets/
   └── Lädt den HTML-Inhalt aus der Datei

3. Marken im Snippet
   └── Ersetzt {DOKU_BASE}, {{wk:image>...}} und ...
   └── Wendet aktuelle Sprache an

4. HTML-Ausgabe
   └── Entfernt HTML-Kommentare des Snippets
   └── Fügt den HTML-Code in die Seite ein
   └── Keine zusätzliche Escaping (Raw HTML)

Snippets unterstützen alle wki18n-Syntaxen:

Datei: <savedir>/wksnippet/multilingual_block.html

<div class="info">
    greeting
    de:Hallo|en:Hello|sl:Zdravo
    {{wk:lang:en>english_only_text}}
</div>

Typische Sidebar-Struktur:

~~NOCACHE~~
{{wk:snippet>go_back}}
{{wk:acmenu}}

Snippets können auch Bilder enthalten:

Datei: <savedir>/wksnippet/logo_block.html

<div class="logo">
    {{wk:image>wiki:logo.png|width=100%|maxwidth=200}}
</div>

• 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

Bei Problemen prüfen:

• Ist der Snippet-Name korrekt geschrieben?
• Existiert die Datei <savedir>/wksnippet/{key}.html oder lib/plugins/wksnippet/snippets/{key}.html?
• Hat die Datei die Erweiterung .html?
• Ist gesetzt für dynamische Inhalte?
• Funktionieren die wki18n-Tags einzeln?

• WvdS Internationalization (i18n) - Mehrsprachige Übersetzungen
• AcMenu Plugin - Akkordeon-Menü
• WvdS Responsive Image Plugin - Responsive Bilder
• WvdS.DokuWiki.Flat Template - Template-Erweiterungen

Datei: lib/plugins/wksnippet/syntax.php

Datei: lib/plugins/wksnippet/helper.php

Datei: lib/plugins/wksnippet/admin.php

lib/plugins/wksnippet/
├── 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/          → mitgelieferte Snippets (nur lesend)
    ├── go_back.html
    ├── social_links.html
    └── ...

<savedir>/wksnippet/   → Snippets der Site (hierhin schreibt der Verwaltungsbildschirm)

<wk:audit stack=“doku” title=“wksnippet Plugin”>

<wk:include ref="code:qualitaet" critical="true">[x][x][x][x]</wk:include>
<wk:include ref="stacks:dokuwiki-php">[x][x][x][x][x]</wk:include>
<wk:include ref="sicherheit:kritis" critical="true">[x][x][x][-][-]</wk:include>

</wk:audit>

DISCUSSION

Plugin: wksnippet
Version: 2.1.0
Namespace: lib/plugins/wksnippet/
Autor: Wolfgang van der Stille Wolfgang.van.der.Stille@gmail.com (The White Knight Labs)
Lizenz: GPL 2