====== WvdS.DokuWiki.Image Plugin ====== **Plugin:** wvdsimage\\ **Versione:** 1.2.0\\ **Namespace:** ''lib/plugins/wvdsimage/''\\ **Autore:** Wolfgang van der Stille \\ **Licenza:** GPL 2 ---- ===== Definizione ===== Il plugin **wvdsimage** consente **immagini codificate base64 come Data-URI** direttamente nell'attributo ''src'' dei tag ''''. **Perché questo plugin?** DokuWiki non ha un meccanismo integrato per immagini inline base64. Di default le immagini sono sempre incorporate come riferimenti URL: Il plugin risolve questo problema con rendering lato server e caching intelligente. **Funzioni principali:** * **Output inline base64** - Immagini incorporate direttamente nell'HTML * **Ridimensionamento lato server** - Adattamento automatico delle dimensioni * **Conversione formato** - PNG/JPEG/GIF a WebP * **Caching intelligente** - Le immagini elaborate vengono cachate * **Helper API** - Accesso programmatico per template e plugin * **Supporto CSS inline** - Parametro ''style'' per posizionamento complesso * **Integrazione wvdssnippet** - Utilizzabile negli snippet HTML ===== Casi d'uso ===== * **Logo responsive** - Immagini ad alta risoluzione che si adattano al container * **Miniature ottimizzate** - Riduzione automatica senza versioni manuali * **Conversione formato** - JPEG a WebP per file più piccoli * **Documenti offline** - Export PDF con immagini incorporate * **Logo template** - Il template Flat usa wvdsimage per il rendering del logo * **Riduzione richieste HTTP** - Nessun download separato delle immagini * **Overlay immagini** - Posizionamento complesso con parametro ''style'' * **Snippet riutilizzabili** - Integrazione con wvdssnippet per blocchi HTML ---- ===== Sintassi ===== {{wvds:image>mediaId|parametro1=valore1|parametro2=valore2}} ==== Esempio minimale ==== {{wvds:image>wiki:logo.png}} ==== Esempio completo ==== {{wvds:image>wiki:logo.png|width=100%|maxwidth=600|quality=85|format=webp|cache=1w|alt=Logo aziendale|class=logo-responsive|style=border-radius:8px|lazy=1}} ---- ===== Parametri ===== ==== Parametri obbligatori ==== ^ Parametro ^ Tipo ^ Descrizione ^ | **mediaId** | string | DokuWiki Media-ID dell'immagine sorgente. Formato: ''namespace:nomefile.ext'' | ==== Parametri dimensione ==== ^ Parametro ^ Tipo ^ Default ^ Descrizione ^ | ''width'' | string | //auto// | Larghezza CSS. Supporta ''px'', ''%'', ''em'', ''vw''. Esempio: ''width=100%'' | | ''height'' | string | //auto// | Altezza CSS. Supporta ''px'', ''%'', ''em'', ''vh''. Esempio: ''height=200px'' | | ''maxwidth'' | integer | //1200// | Larghezza massima in pixel per il resize. L'immagine non viene mai scalata oltre questo valore. | | ''maxheight'' | integer | //null// | Altezza massima in pixel per il resize. Opzionale, mantiene le proporzioni. | **Logica di ridimensionamento:** Il plugin scala l'immagine sorgente a massimo ''maxwidth'' × ''maxheight'' pixel mantenendo le proporzioni. I parametri ''width''/''height'' sono puri valori CSS e non influenzano la dimensione effettiva dell'immagine. ==== Parametri qualità ==== ^ Parametro ^ Tipo ^ Default ^ Valori validi ^ Descrizione ^ | ''quality'' | integer | 85 | 10-100 | Qualità compressione JPEG/WebP. Maggiore = migliore ma più grande. | | ''format'' | string | //auto// | jpeg, png, gif, webp | Formato output. Con ''auto'' viene mantenuto il formato sorgente. | **Raccomandazioni formato:** * **webp** - Migliore compressione, browser moderni * **jpeg** - Foto, gradienti * **png** - Trasparenza, bordi netti, logo * **gif** - Grafiche semplici, animazioni (nessun supporto resize per animazioni) ==== Parametri cache ==== ^ Parametro ^ Tipo ^ Default ^ Valori validi ^ Descrizione ^ | ''cache'' | string | 1d | 1h, 6h, 1d, 1w, 1m | Durata cache per l'immagine elaborata. | ^ Abbreviazione ^ Significato ^ | ''h'' | Ore | | ''d'' | Giorni | | ''w'' | Settimane | | ''m'' | Mesi (30 giorni) | ==== Attributi HTML ==== ^ Parametro ^ Tipo ^ Default ^ Descrizione ^ | ''alt'' | string | //(vuoto)// | Testo alternativo per accessibilità. **Dovrebbe sempre essere impostato!** | | ''class'' | string | wvdsimage | Classi CSS aggiuntive. Separare più classi con spazio. | | ''style'' | string | //(vuoto)// | **Nuovo in 1.2.0:** CSS inline per posizionamento individuale e styling. | | ''lazy'' | boolean | 1 | Attiva lazy loading. ''1'' = attivo, ''0'' = disattivato. | | ''inline'' | boolean | 1 | Output inline base64. ''1'' = Data-URI, ''0'' = URL esterno (futuro). | **Parametro style:** Consente posizionamento CSS complesso direttamente nel tag. Ideale per effetti overlay, posizionamento assoluto e trasformazioni. ---- ===== Esempi ===== ==== Esempio 1: Logo responsive ==== **Requisito:** Logo che si adatta alla larghezza del container, ma mai più grande di 300px. {{wvds:image>wiki:logo_hires.png|width=100%|maxwidth=300|alt=WvdS Logo}} **Risultato:** * Immagine sorgente (es. 1200×480) viene scalata a 300×120 * CSS ''width: 100%'' la rende responsive * ''max-width: 300px'' impedisce l'ingrandimento oltre 300px ==== Esempio 2: Conversione WebP per foto ==== **Requisito:** Ottimizzazione foto JPEG per caricamento più veloce. {{wvds:image>fotos:team.jpg|maxwidth=800|quality=80|format=webp|alt=Il nostro team}} **Risultato:** * Converte JPEG in WebP (circa 30% più piccolo) * Scala a massimo 800px di larghezza * Qualità 80% per buon compromesso ==== Esempio 3: Galleria miniature ==== **Requisito:** Miniature uniformi per galleria immagini. | {{wvds:image>galleria:img1.jpg|maxwidth=150|maxheight=150|alt=Immagine 1}} | {{wvds:image>galleria:img2.jpg|maxwidth=150|maxheight=150|alt=Immagine 2}} | ==== Esempio 4: Hero banner con cache a lungo termine ==== **Requisito:** Grande immagine banner che cambia raramente. {{wvds:image>design:hero-banner.png|width=100%|maxwidth=1920|quality=90|cache=1m|alt=Benvenuto}} ==== Esempio 5: Overlay immagini con parametro style ==== **Requisito:** Due immagini sovrapposte (es. laptop con tablet davanti).
{{wvds:image>it:laptop.png|maxwidth=400|alt=Laptop|style=display:block}} {{wvds:image>it: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)}}
**Risultato:** * Laptop come immagine base (''display:block'') * Tablet posizionato in modo assoluto, leggermente ruotato con ombra * Entrambe le immagini come base64 inline (nessuna richiesta HTTP) ---- ===== Funzionamento ===== ==== Pipeline di elaborazione ==== 1. Parsing sintassi └── Estrae mediaId e parametri da {{wvds:image>...}} 2. Caricamento immagine sorgente └── Legge file da data/media/{namespace}/{file} └── Valida formato immagine (PNG, JPEG, GIF, WebP) 3. Verifica cache └── Genera hash: MD5(percorso + mtime + larghezza + altezza + qualità + formato) └── Verifica data/cache/wvdsimage/{hash}.{format} └── Su cache hit: Carica immagine cachata 4. Elaborazione immagine (su cache miss) └── imagecreatefrom{format}() - Carica immagine sorgente └── imagecreatetruecolor() - Crea immagine destinazione └── imagecopyresampled() - Scaling di alta qualità └── image{format}() - Salva nel formato destinazione 5. Salvataggio cache └── Scrive immagine elaborata in data/cache/wvdsimage/ 6. Output HTML └── Genera ==== Directory cache ==== Le immagini cachate vengono salvate in: data/cache/wvdsimage/ Formato nome file: ''{MD5-hash}.{formato}'' ---- ===== Configurazione ===== ==== Impostazioni amministratore ==== Tramite **Admin → Configurazione → wvdsimage**: ^ Impostazione ^ Tipo ^ Default ^ Descrizione ^ | ''defaultQuality'' | Numero | 85 | Qualità predefinita se non specificata | | ''defaultCache'' | Testo | 1d | Durata cache predefinita | | ''defaultMaxWidth'' | Numero | 1200 | Larghezza massima predefinita | | ''enableWebp'' | On/Off | On | Attiva supporto WebP | | ''lazyLoad'' | On/Off | On | Attiva lazy loading di default | ---- ===== Gestione errori ===== ==== Messaggi di errore ==== ^ Errore ^ Causa ^ Soluzione ^ | ''Image not found: {mediaId}'' | File media non esiste | Verificare percorso, caricare file | | ''Invalid image: {mediaId}'' | File non è immagine valida | Verificare formato immagine, ricaricare | | ''Image processing failed'' | Errore libreria GD | Verificare estensione PHP GD, aumentare memoria | ==== Prerequisiti ==== * **Estensione PHP GD** - Deve essere attivata * **Supporto WebP** - Per ''format=webp'' richiesto (PHP 7.1+ con libwebp) * **Permessi scrittura** - Per ''data/cache/wvdsimage/'' ---- ===== Performance ===== ==== Raccomandazioni ==== | Scenario | Impostazioni consigliate | | Logo, icone | ''maxwidth=300'', ''format=png'', ''cache=1w'' | | Foto | ''maxwidth=800'', ''quality=80'', ''format=webp'', ''cache=1d'' | | Hero banner | ''maxwidth=1920'', ''quality=85'', ''cache=1m'' | | Miniature | ''maxwidth=150'', ''quality=75'', ''cache=1w'' | ==== Consumo memoria ==== Immagini grandi richiedono molta memoria durante l'elaborazione: * 1920×1080 PNG: ~8 MB RAM * 4000×3000 JPEG: ~48 MB RAM In caso di problemi di memoria aumentare ''memory_limit'' in ''php.ini''. ---- ===== Thread safety ===== Il plugin è **thread-safe**. Richieste parallele per la stessa immagine possono temporaneamente causare elaborazione doppia, ma la cache viene scritta in modo atomico. ---- ===== Integrazione con wvdssnippet ===== **Nuovo nella versione 1.2.0:** Il tag ''wvds:image'' può essere usato direttamente negli snippet [[.:wvdssnippet]]. ==== Funzionamento ==== Il plugin wvdssnippet elabora automaticamente i tag ''{{wvds:image>...}}'' all'interno dei file snippet tramite l'helper wvdsimage. ==== Esempio: Snippet Hero-Images ==== **File:** ''lib/plugins/wvdssnippet/snippets/hero_images.html''
{{wvds:image>it:laptop.png|maxwidth=400|alt=Laptop|style=display:block}} {{wvds:image>it: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)}}
**Utilizzo nella pagina wiki:** {{wvds:snippet>hero_images}} ==== Vantaggi ==== | Aspetto | Senza wvdsimage | Con wvdsimage | | Ottimizzazione immagine | Nessuna (dimensione originale) | Resize a maxwidth, caching | | Richieste HTTP | 2 richieste separate | 0 (base64 inline) | | Manutenibilità | Percorsi HTML hardcoded | DokuWiki Media-ID | | Capacità offline | No | Sì (incorporato) | ---- ===== Note sulla versione ===== ^ Versione ^ Data ^ Modifiche ^ | 1.2.0 | 2026-01-26 | Parametro ''style'' per CSS inline, integrazione con wvdssnippet | | 1.1.0 | 2026-01-08 | Helper API per accesso programmatico da template e plugin | | 1.0.0 | 2026-01-06 | Prima pubblicazione | ---- ===== Vedi anche ===== * [[.:wvdssnippet]] - Snippet HTML riutilizzabili (supporta tag wvds:image) * [[.:flat]] - Template usa wvdsimage per rendering logo * [[.:wvdsopengraph]] - Meta tag Open Graph (usa immagini) * [[https://www.php.net/manual/it/book.image.php|Documentazione PHP GD]] ---- ===== Riferimento tecnico ===== ==== Classe: syntax_plugin_wvdsimage ==== **File:** ''lib/plugins/wvdsimage/syntax.php'' ^ Metodo ^ Descrizione ^ | ''getType()'' | Restituisce ''substition'' | | ''getSort()'' | Restituisce ''319'' (priorità) | | ''connectTo($mode)'' | Registra pattern ''\{\{wvds:image>[^}]+\}\}'' | | ''handle($match, ...)'' | Parsa sintassi, estrae parametri | | ''render($mode, ...)'' | Genera output HTML | ==== Metodi privati ==== ^ Metodo ^ Parametri ^ Ritorno ^ Descrizione ^ | ''calculateDimensions()'' | $origW, $origH, $opts | array | Calcola dimensione target | | ''processImage()'' | $file, $mime, $w, $h, $q, $fmt | string | Elabora immagine | | ''getCacheKey()'' | $file, $w, $h, $q, $fmt | string | Genera hash cache | | ''buildHtml()'' | $data, $fmt, $opts, $w, $h | string | Crea output HTML | ---- ==== Classe: helper_plugin_wvdsimage ==== **File:** ''lib/plugins/wvdsimage/helper.php'' L'helper consente **accesso programmatico** all'elaborazione immagini per template e plugin. === Utilizzo === // Carica helper $wvdsimage = plugin_load('helper', 'wvdsimage'); // Renderizza immagine da Wiki-Media $html = $wvdsimage->renderImage('wiki', 'wiki:logo.png', array( 'maxwidth' => 300, 'quality' => 90, 'alt' => 'Logo', 'class' => 'my-logo', )); // Immagine dalla directory template $html = $wvdsimage->renderImage('template', 'logo.png', array( 'maxwidth' => 300, )); // Immagine da percorso file assoluto $html = $wvdsimage->renderImage('file', '/path/to/image.jpg', array( 'maxwidth' => 800, 'format' => 'webp', )); === Metodo: renderImage() === ^ Parametro ^ Tipo ^ Descrizione ^ | ''$source'' | string | Sorgente: ''wiki'', ''template'', ''file'' | | ''$path'' | string | Percorso in base alla sorgente | | ''$options'' | array | Parametri di rendering opzionali | === Parametri options === ^ Opzione ^ Tipo ^ Default ^ Descrizione ^ | ''maxwidth'' | int | 300 | Larghezza massima in pixel | | ''maxheight'' | int | null | Altezza massima in pixel | | ''quality'' | int | 85 | Qualità immagine (10-100) | | ''format'' | string | auto | Formato output (jpeg, png, webp) | | ''class'' | string | '' | Classi CSS (''wvdsimage'' viene aggiunto automaticamente) | | ''alt'' | string | '' | Testo alt | | ''style'' | string | '' | **Nuovo:** CSS inline per posizionamento e styling | | ''cache'' | string | '1w' | Durata cache | **Attributi automatici:** L'helper aggiunge automaticamente ''loading="lazy"'' e ''decoding="async"''. === Valore di ritorno === Restituisce un tag '''' completo con Data-URI base64: In caso di errori restituisce un commento HTML: ---- [x][x][x][x] [x][x][x][x][x] [x][x][x][-][-] ~~DISCUSSION~~