====== WvdS.DokuWiki.Image Plugin ====== **Plugin:** wvdsimage\\ **Version:** 1.1.0\\ **Namespace:** ''lib/plugins/wvdsimage/''\\ **Author:** Wolfgang van der Stille \\ **License:** GPL 2 ---- ===== Definition ===== The **wvdsimage** plugin enables **base64-encoded images as Data-URI** directly in the ''src'' attribute of '''' tags. **Why this plugin?** DokuWiki has no built-in mechanism for base64 inline images. By default, images are always embedded as URL references: The plugin solves this problem through server-side rendering with intelligent caching. **Core Features:** * **base64 Inline Output** - Images embedded directly in HTML * **Server-side Resizing** - Automatic size adjustment * **Format Conversion** - PNG/JPEG/GIF to WebP * **Intelligent Caching** - Processed images are cached * **Helper API** - Programmatic access for templates and plugins ===== Use Cases ===== * **Responsive Logos** - High-resolution source images that adapt to containers * **Optimized Thumbnails** - Automatic resizing without manual image versions * **Format Conversion** - JPEG to WebP for smaller file sizes * **Offline Documents** - PDF export with embedded images * **Template Logos** - Flat Template uses wvdsimage for logo rendering * **Reduced HTTP Requests** - No separate image downloads needed ---- ===== Syntax ===== {{wvds:image>mediaId|parameter1=value1|parameter2=value2}} ==== Minimal Example ==== {{wvds:image>wiki:logo.png}} ==== Complete Example ==== {{wvds:image>wiki:logo.png|width=100%|maxwidth=600|quality=85|format=webp|cache=1w|alt=Company Logo|class=logo-responsive|lazy=1}} ---- ===== Parameters ===== ==== Required Parameters ==== ^ Parameter ^ Type ^ Description ^ | **mediaId** | string | DokuWiki media ID of the source image. Format: ''namespace:filename.ext'' | ==== Size Parameters ==== ^ Parameter ^ Type ^ Default ^ Description ^ | ''width'' | string | //auto// | CSS width. Supports ''px'', ''%'', ''em'', ''vw''. Example: ''width=100%'' | | ''height'' | string | //auto// | CSS height. Supports ''px'', ''%'', ''em'', ''vh''. Example: ''height=200px'' | | ''maxwidth'' | integer | //1200// | Maximum pixel width for resizing. Image will never be scaled larger than this value. | | ''maxheight'' | integer | //null// | Maximum pixel height for resizing. Optional, maintains aspect ratio. | **Resize Logic:** The plugin scales the source image to a maximum of ''maxwidth'' × ''maxheight'' pixels while maintaining aspect ratio. The ''width''/''height'' parameters are pure CSS values and do not affect actual image dimensions. ==== Quality Parameters ==== ^ Parameter ^ Type ^ Default ^ Valid Values ^ Description ^ | ''quality'' | integer | 85 | 10-100 | JPEG/WebP compression quality. Higher = better quality but larger size. | | ''format'' | string | //auto// | jpeg, png, gif, webp | Output format. With ''auto'', source format is preserved. | **Format Recommendations:** * **webp** - Best compression, modern browsers * **jpeg** - Photos, gradients * **png** - Transparency, sharp edges, logos * **gif** - Simple graphics, animations (no resize support for animations) ==== Cache Parameters ==== ^ Parameter ^ Type ^ Default ^ Valid Values ^ Description ^ | ''cache'' | string | 1d | 1h, 6h, 1d, 1w, 1m | Cache duration for processed image. | ^ Abbreviation ^ Meaning ^ | ''h'' | Hours | | ''d'' | Days | | ''w'' | Weeks | | ''m'' | Months (30 days) | ==== HTML Attributes ==== ^ Parameter ^ Type ^ Default ^ Description ^ | ''alt'' | string | //(empty)// | Alternative text for accessibility. **Should always be set!** | | ''class'' | string | wvdsimage | Additional CSS classes. Separate multiple with spaces. | | ''lazy'' | boolean | 1 | Enable lazy loading. ''1'' = enabled, ''0'' = disabled. | | ''inline'' | boolean | 1 | Base64 inline output. ''1'' = data URI, ''0'' = external URL (future). | ---- ===== Examples ===== ==== Example 1: Responsive Logo ==== **Requirement:** Logo should adapt to container width but never exceed 300px. {{wvds:image>wiki:logo_hires.png|width=100%|maxwidth=300|alt=WvdS Logo}} **Result:** * Source image (e.g., 1200×480) is scaled to 300×120 * CSS ''width: 100%'' makes it responsive * ''max-width: 300px'' prevents enlargement beyond 300px ==== Example 2: WebP Conversion for Photos ==== **Requirement:** Optimize JPEG photo for faster loading. {{wvds:image>photos:team.jpg|maxwidth=800|quality=80|format=webp|alt=Our Team}} **Result:** * Converts JPEG to WebP (approx. 30% smaller) * Scales to maximum 800px width * Quality 80% for good compromise ==== Example 3: Thumbnail Gallery ==== **Requirement:** Uniform thumbnails for image gallery. | {{wvds:image>gallery:image1.jpg|maxwidth=150|maxheight=150|alt=Image 1}} | {{wvds:image>gallery:image2.jpg|maxwidth=150|maxheight=150|alt=Image 2}} | ==== Example 4: Hero Banner with Long-term Cache ==== **Requirement:** Large banner image that rarely changes. {{wvds:image>design:hero-banner.png|width=100%|maxwidth=1920|quality=90|cache=1m|alt=Welcome}} ---- ===== How It Works ===== ==== Processing Pipeline ==== 1. Syntax Parsing └── Extracts mediaId and parameters from {{wvds:image>...}} 2. Load Source Image └── Reads file from data/media/{namespace}/{file} └── Validates image format (PNG, JPEG, GIF, WebP) 3. Cache Check └── Generates hash: MD5(path + mtime + width + height + quality + format) └── Checks data/cache/wvdsimage/{hash}.{format} └── On cache hit: Loads cached image 4. Image Processing (on cache miss) └── imagecreatefrom{format}() - Loads source image └── imagecreatetruecolor() - Creates target image └── imagecopyresampled() - High-quality scaling └── image{format}() - Saves in target format 5. Cache Storage └── Writes processed image to data/cache/wvdsimage/ 6. HTML Output └── Generates ==== Cache Directory ==== Cached images are stored in: data/cache/wvdsimage/ Filename format: ''{MD5-hash}.{format}'' ---- ===== Configuration ===== ==== Admin Settings ==== Via **Admin → Configuration → wvdsimage**: ^ Setting ^ Type ^ Default ^ Description ^ | ''defaultQuality'' | Number | 85 | Default quality when not specified | | ''defaultCache'' | Text | 1d | Default cache duration | | ''defaultMaxWidth'' | Number | 1200 | Default maximum width | | ''enableWebp'' | On/Off | On | Enable WebP support | | ''lazyLoad'' | On/Off | On | Enable lazy loading by default | ---- ===== Error Handling ===== ==== Error Messages ==== ^ Error ^ Cause ^ Solution ^ | ''Image not found: {mediaId}'' | Media file does not exist | Check path, upload file | | ''Invalid image: {mediaId}'' | File is not a valid image | Check image format, re-upload | | ''Image processing failed'' | GD library error | Check PHP GD extension, increase memory | ==== Requirements ==== * **PHP GD Extension** - Must be enabled * **WebP Support** - Required for ''format=webp'' (PHP 7.1+ with libwebp) * **Write Permissions** - For ''data/cache/wvdsimage/'' ---- ===== Performance ===== ==== Recommendations ==== | Scenario | Recommended Settings | | Logos, Icons | ''maxwidth=300'', ''format=png'', ''cache=1w'' | | Photos | ''maxwidth=800'', ''quality=80'', ''format=webp'', ''cache=1d'' | | Hero Banners | ''maxwidth=1920'', ''quality=85'', ''cache=1m'' | | Thumbnails | ''maxwidth=150'', ''quality=75'', ''cache=1w'' | ==== Memory Usage ==== Large images require significant memory during processing: * 1920×1080 PNG: ~8 MB RAM * 4000×3000 JPEG: ~48 MB RAM For memory issues, increase ''memory_limit'' in ''php.ini''. ---- ===== Thread Safety ===== The plugin is **thread-safe**. Parallel requests for the same image may temporarily trigger duplicate processing, but the cache is written atomically. ---- ===== Version History ===== ^ Version ^ Date ^ Changes ^ | 1.1.0 | 2026-01-08 | Helper API for programmatic access from templates and plugins | | 1.0.0 | 2026-01-06 | Initial release | ---- ===== See Also ===== * [[flat]] - Template uses wvdsimage for logo rendering * [[wvdsopengraph]] - Open Graph meta tags (uses images) * [[https://www.php.net/manual/en/book.image.php|PHP GD Documentation]] ---- ===== Technical Reference ===== ==== Class: syntax_plugin_wvdsimage ==== **File:** ''lib/plugins/wvdsimage/syntax.php'' ^ Method ^ Description ^ | ''getType()'' | Returns ''substition'' | | ''getSort()'' | Returns ''319'' (priority) | | ''connectTo($mode)'' | Registers pattern ''\{\{wvds:image>[^}]+\}\}'' | | ''handle($match, ...)'' | Parses syntax, extracts parameters | | ''render($mode, ...)'' | Generates HTML output | ==== Private Methods ==== ^ Method ^ Parameters ^ Return ^ Description ^ | ''calculateDimensions()'' | $origW, $origH, $opts | array | Calculates target size | | ''processImage()'' | $file, $mime, $w, $h, $q, $fmt | string | Processes image | | ''getCacheKey()'' | $file, $w, $h, $q, $fmt | string | Generates cache hash | | ''buildHtml()'' | $data, $fmt, $opts, $w, $h | string | Creates HTML output | ---- ==== Class: helper_plugin_wvdsimage ==== **File:** ''lib/plugins/wvdsimage/helper.php'' The helper provides **programmatic access** to image processing for templates and plugins. === Usage === // Load helper $wvdsimage = plugin_load('helper', 'wvdsimage'); // Render image from wiki media $html = $wvdsimage->renderImage('wiki', 'wiki:logo.png', array( 'maxwidth' => 300, 'quality' => 90, 'alt' => 'Logo', 'class' => 'my-logo', )); // Render image from template directory $html = $wvdsimage->renderImage('template', 'logo.png', array( 'maxwidth' => 300, )); // Render image from absolute file path $html = $wvdsimage->renderImage('file', '/path/to/image.jpg', array( 'maxwidth' => 800, 'format' => 'webp', )); === Method: renderImage() === ^ Parameter ^ Type ^ Description ^ | ''$source'' | string | Source: ''wiki'', ''template'', ''file'' | | ''$path'' | string | Path depending on source | | ''$options'' | array | Optional rendering parameters | === Options Parameters === ^ Option ^ Type ^ Default ^ Description ^ | ''maxwidth'' | int | 300 | Maximum width in pixels | | ''maxheight'' | int | null | Maximum height in pixels | | ''quality'' | int | 85 | Image quality (10-100) | | ''format'' | string | auto | Output format (jpeg, png, webp) | | ''class'' | string | '' | CSS classes | | ''alt'' | string | '' | Alt text | | ''style'' | string | '' | Inline CSS | | ''cache'' | string | '1w' | Cache duration | === Return Value === Returns a complete '''' tag with base64 Data-URI: On errors, an HTML comment is returned: === Example: Flat Template Logo === The Flat Template uses the helper for 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 without wvdsimage return ''; } ---- [x][x][x][x] [x][x][x][x][x] [x][x][x][-][-] ~~DISCUSSION~~