====== WvdS.DokuWiki.Image Plugin ====== **Plugin:** wvdsimage\\ **Version:** 1.2.0\\ **Namespace:** ''lib/plugins/wvdsimage/''\\ **Autor:** Wolfgang van der Stille \\ **Lizenz:** GPL 2 ---- ===== Definition ===== Das **wvdsimage** Plugin ermöglicht **base64-kodierte Bilder als Data-URI** direkt im ''src''-Attribut von ''''-Tags. **Warum dieses Plugin?** DokuWiki hat keinen eingebauten Mechanismus für base64-Inline-Bilder. Standardmäßig werden Bilder immer als URL-Referenzen eingebunden: Das Plugin löst dieses Problem durch serverseitiges Rendering mit intelligentem Caching. **Kernfunktionen:** * **base64-Inline-Ausgabe** - Bilder direkt im HTML eingebettet * **Serverseitiges Resizing** - Automatische Größenanpassung * **Format-Konvertierung** - PNG/JPEG/GIF zu WebP * **Intelligentes Caching** - Verarbeitete Bilder werden gecacht * **Helper-API** - Programmatischer Zugriff für Templates und Plugins * **Inline-CSS Support** - ''style'' Parameter für komplexe Positionierung * **wvdssnippet Integration** - Verwendbar in HTML-Snippets ===== Anwendungsfälle ===== * **Responsive Logos** - Hochauflösende Quellbilder, die sich an Container anpassen * **Optimierte Thumbnails** - Automatische Verkleinerung ohne manuelle Bildversionen * **Format-Konvertierung** - JPEG zu WebP für kleinere Dateigrößen * **Offline-Dokumente** - PDF-Export mit eingebetteten Bildern * **Template-Logos** - Flat Template nutzt wvdsimage für Logo-Rendering * **Reduzierte HTTP-Requests** - Keine separaten Bild-Downloads nötig * **Bild-Overlays** - Komplexe Positionierung mit ''style'' Parameter * **Wiederverwendbare Snippets** - Integration mit wvdssnippet für HTML-Bausteine ---- ===== Syntax ===== {{wvds:image>mediaId|parameter1=wert1|parameter2=wert2}} ==== Minimalbeispiel ==== {{wvds:image>wiki:logo.png}} ==== Vollständiges Beispiel ==== {{wvds:image>wiki:logo.png|width=100%|maxwidth=600|quality=85|format=webp|cache=1w|alt=Firmenlogo|class=logo-responsive|style=border-radius:8px|lazy=1}} ---- ===== Parameter ===== ==== Pflichtparameter ==== ^ Parameter ^ Typ ^ Beschreibung ^ | **mediaId** | string | DokuWiki Media-ID des Quellbildes. Format: ''namespace:dateiname.ext'' | ==== Größen-Parameter ==== ^ Parameter ^ Typ ^ Standard ^ Beschreibung ^ | ''width'' | string | //auto// | CSS-Breite. Unterstützt ''px'', ''%'', ''em'', ''vw''. Beispiel: ''width=100%'' | | ''height'' | string | //auto// | CSS-Höhe. Unterstützt ''px'', ''%'', ''em'', ''vh''. Beispiel: ''height=200px'' | | ''maxwidth'' | integer | //1200// | Maximale Pixel-Breite für Resize. Das Bild wird nie größer als dieser Wert skaliert. | | ''maxheight'' | integer | //null// | Maximale Pixel-Höhe für Resize. Optional, hält Seitenverhältnis. | **Resize-Logik:** Das Plugin skaliert das Quellbild auf maximal ''maxwidth'' × ''maxheight'' Pixel unter Beibehaltung des Seitenverhältnisses. Die ''width''/''height'' Parameter sind reine CSS-Angaben und beeinflussen nicht die tatsächliche Bildgröße. ==== Qualitäts-Parameter ==== ^ Parameter ^ Typ ^ Standard ^ Gültige Werte ^ Beschreibung ^ | ''quality'' | integer | 85 | 10-100 | JPEG/WebP-Kompressionsqualität. Höher = besser, aber größer. | | ''format'' | string | //auto// | jpeg, png, gif, webp | Ausgabeformat. Bei ''auto'' wird das Quellformat beibehalten. | **Format-Empfehlungen:** * **webp** - Beste Kompression, moderne Browser * **jpeg** - Fotos, Farbverläufe * **png** - Transparenz, scharfe Kanten, Logos * **gif** - Einfache Grafiken, Animationen (keine Resize-Unterstützung für Animationen) ==== Cache-Parameter ==== ^ Parameter ^ Typ ^ Standard ^ Gültige Werte ^ Beschreibung ^ | ''cache'' | string | 1d | 1h, 6h, 1d, 1w, 1m | Cache-Dauer für das verarbeitete Bild. | ^ Kürzel ^ Bedeutung ^ | ''h'' | Stunden | | ''d'' | Tage | | ''w'' | Wochen | | ''m'' | Monate (30 Tage) | ==== HTML-Attribute ==== ^ Parameter ^ Typ ^ Standard ^ Beschreibung ^ | ''alt'' | string | //(leer)// | Alternativer Text für Barrierefreiheit. **Sollte immer gesetzt werden!** | | ''class'' | string | wvdsimage | Zusätzliche CSS-Klassen. Mehrere mit Leerzeichen trennen. | | ''style'' | string | //(leer)// | **Neu in 1.2.0:** Inline-CSS für individuelle Positionierung und Styling. | | ''lazy'' | boolean | 1 | Lazy Loading aktivieren. ''1'' = aktiviert, ''0'' = deaktiviert. | | ''inline'' | boolean | 1 | Base64-Inline-Ausgabe. ''1'' = Data-URI, ''0'' = externe URL (zukünftig). | **Style-Parameter:** Ermöglicht komplexe CSS-Positionierung direkt im Tag. Ideal für Overlay-Effekte, absolute Positionierung und Transformationen. ---- ===== Beispiele ===== ==== Beispiel 1: Responsives Logo ==== **Anforderung:** Logo soll sich an die Containerbreite anpassen, aber nie größer als 300px werden. {{wvds:image>wiki:logo_hires.png|width=100%|maxwidth=300|alt=WvdS Logo}} **Ergebnis:** * Quellbild (z.B. 1200×480) wird auf 300×120 skaliert * CSS ''width: 100%'' macht es responsiv * ''max-width: 300px'' verhindert Vergrößerung über 300px ==== Beispiel 2: WebP-Konvertierung für Fotos ==== **Anforderung:** JPEG-Foto optimieren für schnellere Ladezeit. {{wvds:image>fotos:team.jpg|maxwidth=800|quality=80|format=webp|alt=Unser Team}} **Ergebnis:** * Konvertiert JPEG zu WebP (ca. 30% kleiner) * Skaliert auf maximal 800px Breite * Qualität 80% für guten Kompromiss ==== Beispiel 3: Thumbnail-Galerie ==== **Anforderung:** Einheitliche Thumbnails für Bildergalerie. | {{wvds:image>galerie:bild1.jpg|maxwidth=150|maxheight=150|alt=Bild 1}} | {{wvds:image>galerie:bild2.jpg|maxwidth=150|maxheight=150|alt=Bild 2}} | ==== Beispiel 4: Hero-Banner mit Langzeit-Cache ==== **Anforderung:** Großes Banner-Bild, das sich selten ändert. {{wvds:image>design:hero-banner.png|width=100%|maxwidth=1920|quality=90|cache=1m|alt=Willkommen}} ==== Beispiel 5: Bild-Overlay mit style-Parameter ==== **Anforderung:** Zwei Bilder übereinander positionieren (z.B. Laptop mit Tablet davor).
{{wvds:image>de:laptop.png|maxwidth=400|alt=Laptop|style=display:block}} {{wvds:image>de:tablet.png|maxwidth=180|alt=Tablet|style=position:absolute;right:-30px;bottom:10px;transform:rotate(-5deg);box-shadow:0 4px 15px rgba(0,0,0,0.3)}}
**Ergebnis:** * Laptop als Basis-Bild (''display:block'') * Tablet absolut positioniert, leicht gedreht mit Schatten * Beide Bilder als base64 inline (keine HTTP-Requests) ---- ===== Funktionsweise ===== ==== Verarbeitungs-Pipeline ==== 1. Syntax-Parsing └── Extrahiert mediaId und Parameter aus {{wvds:image>...}} 2. Quellbild laden └── Liest Datei aus data/media/{namespace}/{datei} └── Validiert Bildformat (PNG, JPEG, GIF, WebP) 3. Cache-Prüfung └── Generiert Hash: MD5(pfad + mtime + breite + höhe + qualität + format) └── Prüft data/cache/wvdsimage/{hash}.{format} └── Bei Cache-Hit: Lädt gecachtes Bild 4. Bildverarbeitung (bei Cache-Miss) └── imagecreatefrom{format}() - Lädt Quellbild └── imagecreatetruecolor() - Erstellt Zielbild └── imagecopyresampled() - Hochwertige Skalierung └── image{format}() - Speichert in Zielformat 5. Cache-Speicherung └── Schreibt verarbeitetes Bild nach data/cache/wvdsimage/ 6. HTML-Ausgabe └── Generiert ==== Cache-Verzeichnis ==== Gecachte Bilder werden gespeichert in: data/cache/wvdsimage/ Dateinamen-Format: ''{MD5-Hash}.{format}'' ---- ===== Konfiguration ===== ==== Admin-Einstellungen ==== Über **Admin → Konfiguration → wvdsimage**: ^ Einstellung ^ Typ ^ Standard ^ Beschreibung ^ | ''defaultQuality'' | Zahl | 85 | Standard-Qualität wenn nicht angegeben | | ''defaultCache'' | Text | 1d | Standard-Cache-Dauer | | ''defaultMaxWidth'' | Zahl | 1200 | Standard maximale Breite | | ''enableWebp'' | An/Aus | An | WebP-Unterstützung aktivieren | | ''lazyLoad'' | An/Aus | An | Lazy Loading standardmäßig aktivieren | ---- ===== Fehlerbehandlung ===== ==== Fehlermeldungen ==== ^ Fehler ^ Ursache ^ Lösung ^ | ''Image not found: {mediaId}'' | Media-Datei existiert nicht | Pfad prüfen, Datei hochladen | | ''Invalid image: {mediaId}'' | Datei ist kein gültiges Bild | Bildformat prüfen, neu hochladen | | ''Image processing failed'' | GD-Bibliothek Fehler | PHP GD-Extension prüfen, Speicher erhöhen | ==== Voraussetzungen ==== * **PHP GD-Extension** - Muss aktiviert sein * **WebP-Unterstützung** - Für ''format=webp'' benötigt (PHP 7.1+ mit libwebp) * **Schreibrechte** - Für ''data/cache/wvdsimage/'' ---- ===== Performance ===== ==== Empfehlungen ==== | Szenario | Empfohlene Einstellungen | | Logos, Icons | ''maxwidth=300'', ''format=png'', ''cache=1w'' | | Fotos | ''maxwidth=800'', ''quality=80'', ''format=webp'', ''cache=1d'' | | Hero-Banner | ''maxwidth=1920'', ''quality=85'', ''cache=1m'' | | Thumbnails | ''maxwidth=150'', ''quality=75'', ''cache=1w'' | ==== Speicherverbrauch ==== Große Bilder benötigen viel Arbeitsspeicher während der Verarbeitung: * 1920×1080 PNG: ~8 MB RAM * 4000×3000 JPEG: ~48 MB RAM Bei Speicherproblemen ''memory_limit'' in ''php.ini'' erhöhen. ---- ===== Thread-Sicherheit ===== Das Plugin ist **thread-safe**. Parallele Anfragen für dasselbe Bild können temporär doppelte Verarbeitung auslösen, aber der Cache wird atomar geschrieben. ---- ===== Integration mit wvdssnippet ===== **Neu in Version 1.2.0:** Das ''wvds:image'' Tag kann direkt in [[.:wvdssnippet]]-Snippets verwendet werden. ==== Funktionsweise ==== Das wvdssnippet-Plugin verarbeitet ''{{wvds:image>...}}'' Tags innerhalb von Snippet-Dateien automatisch über den wvdsimage-Helper. ==== Beispiel: Hero-Images Snippet ==== **Datei:** ''lib/plugins/wvdssnippet/snippets/hero_images.html''
{{wvds:image>de:laptop.png|maxwidth=400|alt=Laptop|style=display:block}} {{wvds:image>de:tablet.png|maxwidth=180|alt=Tablet|style=position:absolute;right:-30px;bottom:10px;transform:rotate(-5deg);box-shadow:0 4px 15px rgba(0,0,0,0.3)}}
**Verwendung in Wiki-Seite:** {{wvds:snippet>hero_images}} ==== Vorteile ==== | Aspekt | Ohne wvdsimage | Mit wvdsimage | | Bild-Optimierung | Keine (Original-Größe) | Resize auf maxwidth, Caching | | HTTP-Requests | 2 separate Requests | 0 (base64 inline) | | Wartbarkeit | HTML-Pfade hardcoded | DokuWiki Media-IDs | | Offline-Fähigkeit | Nein | Ja (eingebettet) | ---- ===== Versionshinweise ===== ^ Version ^ Datum ^ Änderungen ^ | 1.2.0 | 2026-01-26 | ''style'' Parameter für Inline-CSS, Integration mit wvdssnippet | | 1.1.0 | 2026-01-08 | Helper-API für programmatischen Zugriff aus Templates und Plugins | | 1.0.0 | 2026-01-06 | Erstveröffentlichung | ---- ===== Siehe auch ===== * [[.:wvdssnippet]] - Wiederverwendbare HTML-Snippets (unterstützt wvds:image Tags) * [[.:flat]] - Template nutzt wvdsimage für Logo-Rendering * [[.:wvdsopengraph]] - Open Graph Meta-Tags (nutzt Bilder) * [[https://www.php.net/manual/de/book.image.php|PHP GD-Dokumentation]] ---- ===== Technische Referenz ===== ==== Klasse: syntax_plugin_wvdsimage ==== **Datei:** ''lib/plugins/wvdsimage/syntax.php'' ^ Methode ^ Beschreibung ^ | ''getType()'' | Gibt ''substitution'' zurück | | ''getSort()'' | Gibt ''319'' zurück (Priorität) | | ''connectTo($mode)'' | Registriert Pattern ''\{\{wvds:image>[^}]+\}\}'' | | ''handle($match, ...)'' | Parst Syntax, extrahiert Parameter | | ''render($mode, ...)'' | Generiert HTML-Ausgabe | ==== Private Methoden ==== ^ Methode ^ Parameter ^ Rückgabe ^ Beschreibung ^ | ''calculateDimensions()'' | $origW, $origH, $opts | array | Berechnet Zielgröße | | ''processImage()'' | $file, $mime, $w, $h, $q, $fmt | string | Verarbeitet Bild | | ''getCacheKey()'' | $file, $w, $h, $q, $fmt | string | Generiert Cache-Hash | | ''buildHtml()'' | $data, $fmt, $opts, $w, $h | string | Erstellt HTML-Output | ---- ==== Klasse: helper_plugin_wvdsimage ==== **Datei:** ''lib/plugins/wvdsimage/helper.php'' Der Helper ermöglicht **programmatischen Zugriff** auf die Bildverarbeitung für Templates und Plugins. === Verwendung === // Helper laden $wvdsimage = plugin_load('helper', 'wvdsimage'); // Bild aus Wiki-Media rendern $html = $wvdsimage->renderImage('wiki', 'wiki:logo.png', array( 'maxwidth' => 300, 'quality' => 90, 'alt' => 'Logo', 'class' => 'my-logo', )); // Bild aus Template-Verzeichnis $html = $wvdsimage->renderImage('template', 'logo.png', array( 'maxwidth' => 300, )); // Bild aus absolutem Dateipfad $html = $wvdsimage->renderImage('file', '/path/to/image.jpg', array( 'maxwidth' => 800, 'format' => 'webp', )); === Methode: renderImage() === ^ Parameter ^ Typ ^ Beschreibung ^ | ''$source'' | string | Quelle: ''wiki'', ''template'', ''file'' | | ''$path'' | string | Pfad je nach Quelle | | ''$options'' | array | Optionale Rendering-Parameter | === Options-Parameter === ^ Option ^ Typ ^ Standard ^ Beschreibung ^ | ''maxwidth'' | int | 300 | Maximale Breite in Pixel | | ''maxheight'' | int | null | Maximale Höhe in Pixel | | ''quality'' | int | 85 | Bildqualität (10-100) | | ''format'' | string | auto | Ausgabeformat (jpeg, png, webp) | | ''class'' | string | '' | CSS-Klassen (''wvdsimage'' wird automatisch hinzugefügt) | | ''alt'' | string | '' | Alt-Text | | ''style'' | string | '' | **Neu:** Inline-CSS für Positionierung und Styling | | ''cache'' | string | '1w' | Cache-Dauer | **Automatische Attribute:** Der Helper fügt automatisch ''loading="lazy"'' und ''decoding="async"'' hinzu. === Rückgabe === Gibt einen vollständigen ''''-Tag mit base64 Data-URI zurück: Bei Fehlern wird ein HTML-Kommentar zurückgegeben: === Beispiel: Flat Template Logo === Das Flat Template nutzt den Helper für Logo-Rendering: // In lib/tpl/flat/lang_helper.php function tpl_renderLogo() { $wvdsimage = plugin_load('helper', 'wvdsimage'); if ($wvdsimage) { return $wvdsimage->renderImage('wiki', $logoPath, array( 'maxwidth' => $maxWidth, 'quality' => $quality, 'alt' => $siteTitle, 'class' => 'logo-img', )); } // Fallback ohne wvdsimage return ''; } ---- [x][x][x][x] [x][x][x][x][x] [x][x][x][-][-] ~~DISCUSSION~~