WvdS.DokuWiki.Theme Plugin

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

Definition

Das wvdstheme Plugin schaltet das aktive Template (Theme) pro Namespace um — nach demselben Vererbungsprinzip wie die Sidebar: Eine Seite namens theme in einem Namespace gilt für diesen Teilbaum, die nächstgelegene theme-Seite gewinnt.

Anwendungsfälle

Blog-Bereich — de:blog läuft im BizWay-Template, der Rest des Wikis in Flat
Marketing-Landingpages — eigenständige Optik für öffentliche Bereiche
Kunden-/Projektbereiche — abgegrenztes Erscheinungsbild ohne DokuWiki-Fork

Syntax

Seite <namespace>:theme anlegen mit:

{{wk:theme template="premium-navy-ivory"}}

Beim Anzeigen der theme-Seite erscheint eine Info-Box mit Template-Name, Geltungsbereich und Validierungsstatus.

Parameter

Parameter	Typ	Pflicht	Beschreibung
`template`	string	ja	Verzeichnisname unter `lib/tpl/`

Konfiguration

Option	Standard	Beschreibung
`pagename`	`theme`	Name der Theme-Seite pro Namespace (analog `$conf['sidebar']`)

Funktionsweise

Action-Hook DOKUWIKI_STARTED (Seiten), DETAIL_STARTED (Media-Detailseiten) bzw. MEDIAMANAGER_STARTED (Media-Manager-Popup, Namespace aus ns-Parameter) läuft vor dem Template-Include; ?do=admin ist bewusst ausgenommen (Config-Manager zeigt sonst die Template-Einstellungen des Override-Templates)
Helper sucht die nächstgelegene theme-Seite (Namespace-Walk aufwärts, wie page_findnearest(), bewusst ohne ACL-Prüfung — die Theme-Seite ist Konfiguration und wirkt auch für anonyme Besucher)
Template-Name wird per Regex aus dem Raw-Wikitext gelesen (kein Parser-Overhead)
Bei Erfolg: $conf['template'] wird umgesetzt — CSS/JS-URLs (css.php?t=…, js.php?t=…) und deren pro Template getrennte Caches folgen automatisch, keine Cache-Invalidierung nötig

Sicherheit

Prüfung	Lösung	CWE
Path Traversal	Allowlist: `^[a-zA-Z0-9_-]+$` und `is_dir(lib/tpl/<name>)`	CWE-22
XSS	`hsc()` auf alle Ausgaben der Info-Box	CWE-79

Ungültige oder nicht installierte Template-Namen deaktivieren den Override vollständig — das Standard-Template bleibt aktiv (kein stiller Fallback auf dokuwiki).

Einschränkungen

Ziel-Templates müssen tpl_basedir()/tpl_incdir() verwenden. Templates mit den beim Init eingefrorenen Konstanten DOKU_TPL/DOKU_TPLINC (z. B. flat) funktionieren nur als Standard-Template, nicht als Wechselziel.
Die theme-Seite gilt ab ihrem Namespace abwärts; eine tiefere theme-Seite überschreibt die höhere vollständig (auch bei ungültigem Namen — dann gilt das Standard-Template).

Styles-Contract (--wk-*)

Damit Komponenten (blogtng-Templates, Audit-Badges, Snippets) unter jedem Template stimmig aussehen, gilt ein verbindlicher Satz CSS Custom Properties. Jedes Template definiert dieselben Token-Namen mit eigener Palette:

Template	Definition	Palette
flat	`lib/tpl/flat/css/color-palette.css`	WvdS Meadow (Terracotta/Gold/Paper)
premium-navy-ivory	`lib/tpl/premium-navy-ivory/css/tokens.css` + `css/schemes/riviera.css` (Default)	Seit 2026-07-10 genau drei Marken-Akzente über die Option `colorscheme` wählbar: `riviera` (Standard, Navy/Steel-Azure/Gold/Ivory, vormals `navy-ivory`), `night` (volle dunkle Leinwand, Gold-Akzente), `white` (helle Leinwand, Navy-Rahmen). Die frühere WP-Farboptionen `meadow`/`green`/`red` wurden dabei entfernt. Das Area-Profil `wiki` rendert unabhängig von dieser Einstellung ausnahmslos mit `white` (siehe BizWay (Hausvorlage)).

Konsumenten schreiben var(–wk-accent, #fallback) — der Fallback greift nur unter Templates ohne Contract-Definition.

Token-Übersicht

Gruppe	Tokens
Kern	`–wk-ink`, `–wk-paper`, `–wk-accent[-dark\|-light]`, `–wk-gold[-dark\|-light]`, `–wk-rule`
Flächen	`–wk-surface`, `–wk-surface-alt`, `–wk-surface-muted`
Text	`–wk-text`, `–wk-text-alt`, `–wk-text-muted`, `–wk-text-on-dark`, `–wk-text-on-accent`
Links	`–wk-link`, `–wk-link-hover`, `–wk-link-missing`
Ränder	`–wk-border`, `–wk-border-light`, `–wk-highlight`
Sidebar	`–wk-sidebar-bg[-alt]`, `–wk-sidebar-text[-muted]`, `–wk-sidebar-border`, `–wk-sidebar-hover`
Feedback	`–wk-success`, `–wk-warning`, `–wk-error`, `–wk-error-bg`
Admin/Fokus/Buttons	`–wk-admin-*`, `–wk-focus[-shadow]`, `–wk-btn-primary[-hover\|-text]`

Semantik-Hinweis: –wk-gold ist der Sekundär-Akzent-Slot des Contracts. Flat belegt ihn mit Amber, BizWay mit Petrol-Blau — Konsumenten dürfen keine „goldene Farbe„ annehmen, nur „sekundärer Akzent“.

Pflicht für neue Templates: vollständigen Token-Satz definieren (Vorlage: eine der beiden Dateien oben), sonst fallen alle Konsumenten auf ihre Fallback-Werte zurück.

Verwandt

Premium Navy Ivory Template (Verzeichnis premium-navy-ivory; Rest-Plugin heißt seit 2026-07-09 wvdspremiumnavyivory und liefert nur noch die Landing-/Namespace-Weiterleitung, keine Optionen/Rendering mehr) — erstes Wechselziel-Template
wvdscond — bedingte Inhalte/Redirects (Render-Zeit, nicht für Template-Wechsel geeignet)