====== WvdS.DokuWiki.Image Dodatak ======

**Dodatak:** wvdsimage\\
**Verzija:** 1.2.0\\
**Namespace:** ''lib/plugins/wvdsimage/''\\
**Autor:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**Licenca:** GPL 2

----

===== Definicija =====

Dodatak **wvdsimage** omogućuje **base64-kodirane slike kao Data-URI** izravno u ''src'' atributu ''<img>'' oznaka.

<note important>
**Zašto ovaj dodatak?**

DokuWiki nema ugrađeni mehanizam za base64 inline slike. Standardno se slike uvijek ugrađuju kao URL reference:
<code html>
<!-- Standardni DokuWiki -->
<img src="/lib/exe/fetch.php?media=wiki:logo.png" />

<!-- S wvdsimage -->
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..." />
</code>

Dodatak rješava ovaj problem serverskim renderiranjem s inteligentnim cachingom.
</note>

**Ključne funkcije:**
  * **base64-inline izlaz** - Slike izravno ugrađene u HTML
  * **Serversko resizanje** - Automatska prilagodba veličine
  * **Konverzija formata** - PNG/JPEG/GIF u WebP
  * **Inteligentno caching** - Obrađene slike se cacheiraju
  * **Helper API** - Programski pristup za predloške i dodatke
  * **Inline-CSS podrška** - ''style'' parametar za složeno pozicioniranje
  * **wvdssnippet integracija** - Korištenje u HTML snippetima

===== Slučajevi korištenja =====

  * **Responzivni logotipi** - Slike visoke rezolucije koje se prilagođavaju kontejneru
  * **Optimizirane minijature** - Automatsko smanjenje bez ručnih verzija slika
  * **Konverzija formata** - JPEG u WebP za manje datoteke
  * **Offline dokumenti** - PDF izvoz s ugrađenim slikama
  * **Logotipi predloška** - Flat predložak koristi wvdsimage za renderiranje logotipa
  * **Smanjeni HTTP zahtjevi** - Nisu potrebna odvojena preuzimanja slika
  * **Overlay slike** - Složeno pozicioniranje s ''style'' parametrom
  * **Višekratno korištivi snippeti** - Integracija s wvdssnippet za HTML blokove

----

===== Sintaksa =====

<code>
{{wvds:image>mediaId|parametar1=vrijednost1|parametar2=vrijednost2}}
</code>

==== Minimalni primjer ====

<code>
{{wvds:image>wiki:logo.png}}
</code>

==== Potpuni primjer ====

<code>
{{wvds:image>wiki:logo.png|width=100%|maxwidth=600|quality=85|format=webp|cache=1w|alt=Logo tvrtke|class=logo-responsive|style=border-radius:8px|lazy=1}}
</code>

----

===== Parametri =====

==== Obavezni parametri ====

^ Parametar ^ Tip ^ Opis ^
| **mediaId** | string | DokuWiki Media-ID izvorne slike. Format: ''namespace:nazivdatoteke.ext'' |

==== Parametri veličine ====

^ Parametar ^ Tip ^ Standard ^ Opis ^
| ''width'' | string | //auto// | CSS širina. Podržava ''px'', ''%'', ''em'', ''vw''. Primjer: ''width=100%'' |
| ''height'' | string | //auto// | CSS visina. Podržava ''px'', ''%'', ''em'', ''vh''. Primjer: ''height=200px'' |
| ''maxwidth'' | integer | //1200// | Maksimalna širina u pikselima za resize. Slika se nikad ne skalira veća od ove vrijednosti. |
| ''maxheight'' | integer | //null// | Maksimalna visina u pikselima za resize. Opcionalno, održava omjer stranica. |

<note tip>
**Logika resizanja:** Dodatak skalira izvornu sliku na maksimalno ''maxwidth'' × ''maxheight'' piksela uz održavanje omjera stranica. Parametri ''width''/''height'' su čiste CSS vrijednosti i ne utječu na stvarnu veličinu slike.
</note>

==== Parametri kvalitete ====

^ Parametar ^ Tip ^ Standard ^ Valjane vrijednosti ^ Opis ^
| ''quality'' | integer | 85 | 10-100 | JPEG/WebP kvaliteta kompresije. Veće = bolje, ali veća datoteka. |
| ''format'' | string | //auto// | jpeg, png, gif, webp | Izlazni format. Kod ''auto'' se zadržava izvorni format. |

<note>
**Preporuke formata:**
  * **webp** - Najbolja kompresija, moderni preglednici
  * **jpeg** - Fotografije, gradijenti boja
  * **png** - Transparentnost, oštre ivice, logotipi
  * **gif** - Jednostavne grafike, animacije (bez podrške za resize animacija)
</note>

==== Cache parametri ====

^ Parametar ^ Tip ^ Standard ^ Valjane vrijednosti ^ Opis ^
| ''cache'' | string | 1d | 1h, 6h, 1d, 1w, 1m | Trajanje cachea za obrađenu sliku. |

^ Kratica ^ Značenje ^
| ''h'' | Sati |
| ''d'' | Dani |
| ''w'' | Tjedni |
| ''m'' | Mjeseci (30 dana) |

==== HTML atributi ====

^ Parametar ^ Tip ^ Standard ^ Opis ^
| ''alt'' | string | //(prazno)// | Alternativni tekst za pristupačnost. **Uvijek bi trebao biti postavljen!** |
| ''class'' | string | wvdsimage | Dodatne CSS klase. Više razdvojiti razmakom. |
| ''style'' | string | //(prazno)// | **Novo u 1.2.0:** Inline-CSS za individualno pozicioniranje i stiliziranje. |
| ''lazy'' | boolean | 1 | Aktiviraj lazy učitavanje. ''1'' = aktivno, ''0'' = deaktivirano. |
| ''inline'' | boolean | 1 | Base64-inline izlaz. ''1'' = Data-URI, ''0'' = vanjski URL (budućnost). |

<note tip>
**Style parametar:** Omogućuje složeno CSS pozicioniranje izravno u oznaci. Idealno za overlay efekte, apsolutno pozicioniranje i transformacije.
</note>

----

===== Primjeri =====

==== Primjer 1: Responzivni logotip ====

**Zahtjev:** Logotip koji se prilagođava širini kontejnera, ali nikad nije veći od 300px.

<code>
{{wvds:image>wiki:logo_hires.png|width=100%|maxwidth=300|alt=WvdS Logo}}
</code>

**Rezultat:**
  * Izvorna slika (npr. 1200×480) se skalira na 300×120
  * CSS ''width: 100%'' čini je responzivnom
  * ''max-width: 300px'' sprječava povećanje preko 300px

==== Primjer 2: WebP konverzija za fotografije ====

**Zahtjev:** Optimizacija JPEG fotografije za brže učitavanje.

<code>
{{wvds:image>fotos:team.jpg|maxwidth=800|quality=80|format=webp|alt=Naš tim}}
</code>

**Rezultat:**
  * Konvertira JPEG u WebP (oko 30% manje)
  * Skalira na maksimalno 800px širine
  * Kvaliteta 80% za dobar kompromis

==== Primjer 3: Galerija minijatura ====

**Zahtjev:** Ujednačene minijature za galeriju slika.

<code>
| {{wvds:image>galerie:slika1.jpg|maxwidth=150|maxheight=150|alt=Slika 1}} | {{wvds:image>galerie:slika2.jpg|maxwidth=150|maxheight=150|alt=Slika 2}} |
</code>

==== Primjer 4: Hero banner s dugotrajnim cacheom ====

**Zahtjev:** Velika banner slika koja se rijetko mijenja.

<code>
{{wvds:image>design:hero-banner.png|width=100%|maxwidth=1920|quality=90|cache=1m|alt=Dobrodošli}}
</code>

==== Primjer 5: Overlay slike sa style parametrom ====

**Zahtjev:** Dvije slike jedna preko druge (npr. laptop s tabletom ispred).

<code html>
<div style="position: relative; display: inline-block;">
  {{wvds:image>hr:laptop.png|maxwidth=400|alt=Laptop|style=display:block}}
  {{wvds:image>hr: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)}}
</div>
</code>

**Rezultat:**
  * Laptop kao bazna slika (''display:block'')
  * Tablet apsolutno pozicioniran, lagano rotiran sa sjenom
  * Obje slike kao base64 inline (bez HTTP zahtjeva)

----

===== Način rada =====

==== Cjevovod obrade ====

<code>
1. Parsiranje sintakse
   └── Izvlači mediaId i parametre iz {{wvds:image>...}}

2. Učitavanje izvorne slike
   └── Čita datoteku iz data/media/{namespace}/{datoteka}
   └── Validira format slike (PNG, JPEG, GIF, WebP)

3. Provjera cachea
   └── Generira hash: MD5(putanja + mtime + širina + visina + kvaliteta + format)
   └── Provjerava data/cache/wvdsimage/{hash}.{format}
   └── Kod cache pogotka: Učitava cacheiranu sliku

4. Obrada slike (kod cache promašaja)
   └── imagecreatefrom{format}() - Učitava izvornu sliku
   └── imagecreatetruecolor() - Kreira ciljnu sliku
   └── imagecopyresampled() - Visokokvalitetno skaliranje
   └── image{format}() - Sprema u ciljni format

5. Pohrana cachea
   └── Zapisuje obrađenu sliku u data/cache/wvdsimage/

6. HTML izlaz
   └── Generira <img src="data:image/{mime};base64,{podaci}" .../>
</code>

==== Cache direktorij ====

Cacheirane slike se pohranjuju u:

  data/cache/wvdsimage/

Format naziva datoteke: ''{MD5-hash}.{format}''

----

===== Konfiguracija =====

==== Administratorske postavke ====

Preko **Admin → Konfiguracija → wvdsimage**:

^ Postavka ^ Tip ^ Standard ^ Opis ^
| ''defaultQuality'' | Broj | 85 | Zadana kvaliteta ako nije navedena |
| ''defaultCache'' | Tekst | 1d | Zadano trajanje cachea |
| ''defaultMaxWidth'' | Broj | 1200 | Zadana maksimalna širina |
| ''enableWebp'' | Da/Ne | Da | Aktiviraj WebP podršku |
| ''lazyLoad'' | Da/Ne | Da | Standardno aktiviraj lazy učitavanje |

----

===== Rukovanje greškama =====

==== Poruke grešaka ====

^ Greška ^ Uzrok ^ Rješenje ^
| ''Image not found: {mediaId}'' | Media datoteka ne postoji | Provjeri putanju, prenesi datoteku |
| ''Invalid image: {mediaId}'' | Datoteka nije valjana slika | Provjeri format slike, ponovno prenesi |
| ''Image processing failed'' | Greška GD biblioteke | Provjeri PHP GD ekstenziju, povećaj memoriju |

==== Preduvjeti ====

  * **PHP GD ekstenzija** - Mora biti aktivirana
  * **WebP podrška** - Za ''format=webp'' potrebno (PHP 7.1+ s libwebp)
  * **Prava pisanja** - Za ''data/cache/wvdsimage/''

----

===== Performanse =====

==== Preporuke ====

| Scenarij | Preporučene postavke |
| Logotipi, ikone | ''maxwidth=300'', ''format=png'', ''cache=1w'' |
| Fotografije | ''maxwidth=800'', ''quality=80'', ''format=webp'', ''cache=1d'' |
| Hero banneri | ''maxwidth=1920'', ''quality=85'', ''cache=1m'' |
| Minijature | ''maxwidth=150'', ''quality=75'', ''cache=1w'' |

==== Potrošnja memorije ====

<note warning>
Velike slike zahtijevaju puno radne memorije tijekom obrade:
  * 1920×1080 PNG: ~8 MB RAM
  * 4000×3000 JPEG: ~48 MB RAM

Kod problema s memorijom povećajte ''memory_limit'' u ''php.ini''.
</note>

----

===== Thread sigurnost =====

Dodatak je **thread-safe**. Paralelni zahtjevi za istu sliku mogu privremeno pokrenuti dvostruku obradu, ali cache se zapisuje atomski.

----

===== Integracija s wvdssnippet =====

**Novo u verziji 1.2.0:** Oznaka ''wvds:image'' može se koristiti izravno u [[.:wvdssnippet]] snippetima.

==== Način rada ====

Dodatak wvdssnippet automatski obrađuje ''<nowiki>{{wvds:image>...}}</nowiki>'' oznake unutar snippet datoteka preko wvdsimage helpera.

==== Primjer: Hero-Images Snippet ====

**Datoteka:** ''lib/plugins/wvdssnippet/snippets/hero_images.html''

<code html>
<div class="hero-devices" style="position: relative; display: inline-block; margin: 20px 0;">
  {{wvds:image>hr:laptop.png|maxwidth=400|alt=Laptop|style=display:block}}
  {{wvds:image>hr: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)}}
</div>
</code>

**Korištenje na wiki stranici:**

<code>
{{wvds:snippet>hero_images}}
</code>

==== Prednosti ====

| Aspekt | Bez wvdsimage | S wvdsimage |
| Optimizacija slike | Nema (originalna veličina) | Resize na maxwidth, caching |
| HTTP zahtjevi | 2 odvojena zahtjeva | 0 (base64 inline) |
| Održivost | HTML putanje hardkodirane | DokuWiki Media-ID |
| Offline sposobnost | Ne | Da (ugrađeno) |

----

===== Napomene o verzijama =====

^ Verzija ^ Datum ^ Promjene ^
| 1.2.0 | 2026-01-26 | ''style'' parametar za inline-CSS, integracija s wvdssnippet |
| 1.1.0 | 2026-01-08 | Helper API za programski pristup iz predložaka i dodataka |
| 1.0.0 | 2026-01-06 | Prva objava |

----

===== Vidi također =====

  * [[.:wvdssnippet]] - Višekratno korištivi HTML snippeti (podržava wvds:image oznake)
  * [[.:flat]] - Predložak koristi wvdsimage za renderiranje logotipa
  * [[.:wvdsopengraph]] - Open Graph meta oznake (koristi slike)
  * [[https://www.php.net/manual/de/book.image.php|PHP GD dokumentacija]]

----

===== Tehnička referenca =====

==== Klasa: syntax_plugin_wvdsimage ====

**Datoteka:** ''lib/plugins/wvdsimage/syntax.php''

^ Metoda ^ Opis ^
| ''getType()'' | Vraća ''substition'' |
| ''getSort()'' | Vraća ''319'' (prioritet) |
| ''connectTo($mode)'' | Registrira pattern ''\{\{wvds:image>[^}]+\}\}'' |
| ''handle($match, ...)'' | Parsira sintaksu, izvlači parametre |
| ''render($mode, ...)'' | Generira HTML izlaz |

==== Privatne metode ====

^ Metoda ^ Parametri ^ Povratna vrijednost ^ Opis ^
| ''calculateDimensions()'' | $origW, $origH, $opts | array | Izračunava ciljnu veličinu |
| ''processImage()'' | $file, $mime, $w, $h, $q, $fmt | string | Obrađuje sliku |
| ''getCacheKey()'' | $file, $w, $h, $q, $fmt | string | Generira cache hash |
| ''buildHtml()'' | $data, $fmt, $opts, $w, $h | string | Kreira HTML izlaz |

----

==== Klasa: helper_plugin_wvdsimage ====

**Datoteka:** ''lib/plugins/wvdsimage/helper.php''

Helper omogućuje **programski pristup** obradi slika za predloške i dodatke.

=== Korištenje ===

<code php>
// Učitaj helper
$wvdsimage = plugin_load('helper', 'wvdsimage');

// Renderiraj sliku iz Wiki-Media
$html = $wvdsimage->renderImage('wiki', 'wiki:logo.png', array(
    'maxwidth' => 300,
    'quality' => 90,
    'alt' => 'Logo',
    'class' => 'my-logo',
));

// Slika iz direktorija predloška
$html = $wvdsimage->renderImage('template', 'logo.png', array(
    'maxwidth' => 300,
));

// Slika iz apsolutne putanje datoteke
$html = $wvdsimage->renderImage('file', '/path/to/image.jpg', array(
    'maxwidth' => 800,
    'format' => 'webp',
));
</code>

=== Metoda: renderImage() ===

^ Parametar ^ Tip ^ Opis ^
| ''$source'' | string | Izvor: ''wiki'', ''template'', ''file'' |
| ''$path'' | string | Putanja ovisno o izvoru |
| ''$options'' | array | Opcionalni parametri renderiranja |

=== Options parametri ===

^ Opcija ^ Tip ^ Standard ^ Opis ^
| ''maxwidth'' | int | 300 | Maksimalna širina u pikselima |
| ''maxheight'' | int | null | Maksimalna visina u pikselima |
| ''quality'' | int | 85 | Kvaliteta slike (10-100) |
| ''format'' | string | auto | Izlazni format (jpeg, png, webp) |
| ''class'' | string | '' | CSS klase (''wvdsimage'' se automatski dodaje) |
| ''alt'' | string | '' | Alt tekst |
| ''style'' | string | '' | **Novo:** Inline-CSS za pozicioniranje i stiliziranje |
| ''cache'' | string | '1w' | Trajanje cachea |

<note>
**Automatski atributi:** Helper automatski dodaje ''loading="lazy"'' i ''decoding="async"''.
</note>

=== Povratna vrijednost ===

Vraća potpunu ''<img>'' oznaku s base64 Data-URI:

<code html>
<img src="data:image/png;base64,iVBORw0KGgoAAAA..." width="300" height="120" alt="Logo" class="my-logo"/>
</code>

Kod grešaka vraća HTML komentar:

<code html>
<!-- wvdsimage: file not found: wiki:missing.png -->
</code>

=== Primjer: Flat Template Logo ===

Flat predložak koristi helper za renderiranje logotipa:

<code php>
// U 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 bez wvdsimage
    return '<img src="..." />';
}
</code>

----

<wvds:audit stack="doku" title="wvdsimage Dodatak">
  <wvds:include ref="code:qualitaet" critical="true">[x][x][x][x]</wvds:include>
  <wvds:include ref="stacks:dokuwiki-php">[x][x][x][x][x]</wvds:include>
  <wvds:include ref="sicherheit:kritis" critical="true">[x][x][x][-][-]</wvds:include>
</wvds:audit>

~~DISCUSSION~~