====== WvdS.DokuWiki.Image Vticnik ====== **Vticnik:** wvdsimage\\ **Verzija:** 1.1.0\\ **Imenski prostor:** ''lib/plugins/wvdsimage/''\\ **Avtor:** Wolfgang van der Stille \\ **Licenca:** GPL 2 ---- ===== Definicija ===== Vticnik **wvdsimage** omogoca **base64-kodirane slike kot Data-URI** neposredno v atributu ''src'' oznak ''''. **Zakaj ta vtičnik?** DokuWiki nima vgrajenega mehanizma za base64 vgrajene slike. Privzeto so slike vedno vgrajene kot URL reference: Vtičnik rešuje ta problem s strežniškim upodabljanjem z inteligentnim predpomnjenjem. **Osnovne funkcije:** * **base64 vgrajeni izhod** - Slike vgrajene neposredno v HTML * **Strežniško spreminjanje velikosti** - Samodejna prilagoditev velikosti * **Pretvorba formatov** - PNG/JPEG/GIF v WebP * **Inteligentno predpomnjenje** - Obdelane slike se predpomnijo * **Helper API** - Programski dostop za predloge in vtičnike ===== Primeri uporabe ===== * **Odzivni logotipi** - Visoko ločljivostne izvorne slike, ki se prilagajajo vsebnikom * **Optimizirane sličice** - Samodejno spreminjanje velikosti brez ročnih različic slik * **Pretvorba formatov** - JPEG v WebP za manjše datoteke * **Dokumenti brez povezave** - PDF izvoz z vgrajenimi slikami * **Logotipi predlog** - Predloga Flat uporablja wvdsimage za upodabljanje logotipov * **Zmanjšane HTTP zahteve** - Ni potrebe po ločenih prenosih slik ---- ===== Sintaksa ===== {{wvds:image>mediaId|parameter1=vrednost1|parameter2=vrednost2}} ==== Minimalni primer ==== {{wvds:image>wiki:logo.png}} ==== Popolni primer ==== {{wvds:image>wiki:logo.png|width=100%|maxwidth=600|quality=85|format=webp|cache=1w|alt=Logo podjetja|class=logo-responsive|lazy=1}} ---- ===== Parametri ===== ==== Obvezni parametri ==== ^ Parameter ^ Tip ^ Opis ^ | **mediaId** | string | DokuWiki media ID izvorne slike. Format: ''namespace:datoteka.ext'' | ==== Parametri velikosti ==== ^ Parameter ^ Tip ^ Privzeto ^ Opis ^ | ''width'' | string | //auto// | CSS širina. Podpira ''px'', ''%'', ''em'', ''vw''. Primer: ''width=100%'' | | ''height'' | string | //auto// | CSS višina. Podpira ''px'', ''%'', ''em'', ''vh''. Primer: ''height=200px'' | | ''maxwidth'' | integer | //1200// | Maksimalna širina v pikslih za spreminjanje velikosti. Slika nikoli ne bo večja od te vrednosti. | | ''maxheight'' | integer | //null// | Maksimalna višina v pikslih za spreminjanje velikosti. Neobvezno, ohranja razmerje stranic. | **Logika spreminjanja velikosti:** Vticnik pomanjša izvorno sliko na najvec ''maxwidth'' × ''maxheight'' pikslov ob ohranjanju razmerja stranic. Parametra ''width''/''height'' sta cisti CSS vrednosti in ne vplivata na dejanske dimenzije slike. ==== Parametri kakovosti ==== ^ Parameter ^ Tip ^ Privzeto ^ Veljavne vrednosti ^ Opis ^ | ''quality'' | integer | 85 | 10-100 | JPEG/WebP kakovost kompresije. Višje = boljša kakovost, vendar vecja datoteka. | | ''format'' | string | //auto// | jpeg, png, gif, webp | Izhodni format. Pri ''auto'' se ohrani izvorni format. | **Priporocila za formate:** * **webp** - Najboljša kompresija, moderni brskalniki * **jpeg** - Fotografije, barvni prehodi * **png** - Prosojnost, ostre robove, logotipi * **gif** - Enostavne grafike, animacije (brez podpore za spreminjanje velikosti animacij) ==== Parametri predpomnilnika ==== ^ Parameter ^ Tip ^ Privzeto ^ Veljavne vrednosti ^ Opis ^ | ''cache'' | string | 1d | 1h, 6h, 1d, 1w, 1m | Trajanje predpomnilnika za obdelano sliko. | ^ Okrajšava ^ Pomen ^ | ''h'' | Ure | | ''d'' | Dnevi | | ''w'' | Tedni | | ''m'' | Meseci (30 dni) | ==== HTML atributi ==== ^ Parameter ^ Tip ^ Privzeto ^ Opis ^ | ''alt'' | string | //(prazno)// | Nadomestno besedilo za dostopnost. **Vedno naj bo nastavljeno!** | | ''class'' | string | wvdsimage | Dodatni CSS razredi. Vec razredov locite s presledki. | | ''lazy'' | boolean | 1 | Omogoci pocasno nalaganje. ''1'' = omogoceno, ''0'' = onemogoceno. | | ''inline'' | boolean | 1 | Base64 vgrajeni izhod. ''1'' = data URI, ''0'' = zunanji URL (v prihodnosti). | ---- ===== Primeri ===== ==== Primer 1: Odziven logotip ==== **Zahteva:** Logotip naj se prilagaja širini vsebnika, vendar nikoli ne presega 300px. {{wvds:image>wiki:logo_hires.png|width=100%|maxwidth=300|alt=WvdS Logo}} **Rezultat:** * Izvorna slika (npr. 1200×480) je pomanjšana na 300×120 * CSS ''width: 100%'' jo naredi odzivno * ''max-width: 300px'' preprecuje povecanje preko 300px ==== Primer 2: WebP pretvorba za fotografije ==== **Zahteva:** Optimizirati JPEG fotografijo za hitrejše nalaganje. {{wvds:image>fotografije:ekipa.jpg|maxwidth=800|quality=80|format=webp|alt=Naša ekipa}} **Rezultat:** * Pretvori JPEG v WebP (pribl. 30% manjše) * Pomanjša na najvec 800px širine * Kakovost 80% za dober kompromis ==== Primer 3: Galerija sličic ==== **Zahteva:** Enotne sličice za galerijo slik. | {{wvds:image>galerija:slika1.jpg|maxwidth=150|maxheight=150|alt=Slika 1}} | {{wvds:image>galerija:slika2.jpg|maxwidth=150|maxheight=150|alt=Slika 2}} | ==== Primer 4: Hero pasica z dolgotrajnim predpomnilnikom ==== **Zahteva:** Velika pasica, ki se redko spreminja. {{wvds:image>oblikovanje:hero-banner.png|width=100%|maxwidth=1920|quality=90|cache=1m|alt=Dobrodošli}} ---- ===== Kako deluje ===== ==== Procesni cevovod ==== 1. Razčlenjevanje sintakse └── Izvlece mediaId in parametre iz {{wvds:image>...}} 2. Nalaganje izvorne slike └── Prebere datoteko iz data/media/{namespace}/{datoteka} └── Preveri format slike (PNG, JPEG, GIF, WebP) 3. Preverjanje predpomnilnika └── Ustvari zgoščeno vrednost: MD5(pot + mtime + širina + višina + kakovost + format) └── Preveri data/cache/wvdsimage/{hash}.{format} └── Ob zadetku predpomnilnika: Naloži predpomnjeno sliko 4. Obdelava slike (ob zgrešitvi predpomnilnika) └── imagecreatefrom{format}() - Naloži izvorno sliko └── imagecreatetruecolor() - Ustvari ciljno sliko └── imagecopyresampled() - Visokokakovostno skaliranje └── image{format}() - Shrani v ciljni format 5. Shranjevanje v predpomnilnik └── Zapiše obdelano sliko v data/cache/wvdsimage/ 6. HTML izhod └── Ustvari ==== Imenik predpomnilnika ==== Predpomnjene slike so shranjene v: data/cache/wvdsimage/ Format imena datoteke: ''{MD5-hash}.{format}'' ---- ===== Konfiguracija ===== ==== Skrbniške nastavitve ==== Preko **Skrbnik → Konfiguracija → wvdsimage**: ^ Nastavitev ^ Tip ^ Privzeto ^ Opis ^ | ''defaultQuality'' | Število | 85 | Privzeta kakovost, ce ni navedena | | ''defaultCache'' | Besedilo | 1d | Privzeto trajanje predpomnilnika | | ''defaultMaxWidth'' | Število | 1200 | Privzeta maksimalna širina | | ''enableWebp'' | Vklop/Izklop | Vklop | Omogoci podporo WebP | | ''lazyLoad'' | Vklop/Izklop | Vklop | Privzeto omogoci pocasno nalaganje | ---- ===== Obravnava napak ===== ==== Sporočila o napakah ==== ^ Napaka ^ Vzrok ^ Rešitev ^ | ''Image not found: {mediaId}'' | Medijska datoteka ne obstaja | Preverite pot, naložite datoteko | | ''Invalid image: {mediaId}'' | Datoteka ni veljavna slika | Preverite format slike, ponovno naložite | | ''Image processing failed'' | Napaka GD knjižnice | Preverite PHP GD razširitev, povecajte pomnilnik | ==== Zahteve ==== * **PHP GD razširitev** - Mora biti omogocena * **Podpora WebP** - Potrebna za ''format=webp'' (PHP 7.1+ z libwebp) * **Pravice za pisanje** - Za ''data/cache/wvdsimage/'' ---- ===== Zmogljivost ===== ==== Priporočila ==== | Scenarij | Priporocene nastavitve | | Logotipi, ikone | ''maxwidth=300'', ''format=png'', ''cache=1w'' | | Fotografije | ''maxwidth=800'', ''quality=80'', ''format=webp'', ''cache=1d'' | | Hero pasice | ''maxwidth=1920'', ''quality=85'', ''cache=1m'' | | Sličice | ''maxwidth=150'', ''quality=75'', ''cache=1w'' | ==== Poraba pomnilnika ==== Velike slike zahtevajo veliko pomnilnika med obdelavo: * 1920×1080 PNG: ~8 MB RAM * 4000×3000 JPEG: ~48 MB RAM Pri težavah s pomnilnikom povecajte ''memory_limit'' v ''php.ini''. ---- ===== Varnost niti ===== Vticnik je **varen za niti**. Vzporedne zahteve za isto sliko lahko zacasno sprozijo podvojeno obdelavo, vendar se predpomnilnik zapisuje atomarno. ---- ===== Zgodovina verzij ===== ^ Verzija ^ Datum ^ Spremembe ^ | 1.1.0 | 2026-01-08 | Helper API za programski dostop iz predlog in vtičnikov | | 1.0.0 | 2026-01-06 | Začetna izdaja | ---- ===== Glej tudi ===== * [[flat]] - Predloga uporablja wvdsimage za upodabljanje logotipov * [[wvdsopengraph]] - Open Graph meta oznake (uporablja slike) * [[https://www.php.net/manual/en/book.image.php|PHP GD dokumentacija]] ---- ===== Tehnicna referenca ===== ==== Razred: syntax_plugin_wvdsimage ==== **Datoteka:** ''lib/plugins/wvdsimage/syntax.php'' ^ Metoda ^ Opis ^ | ''getType()'' | Vrne ''substition'' | | ''getSort()'' | Vrne ''319'' (prioriteta) | | ''connectTo($mode)'' | Registrira vzorec ''\\{\\{wvds:image>[^}]+\\}\\}'' | | ''handle($match, ...)'' | Razcleniti sintakso, izvleci parametre | | ''render($mode, ...)'' | Ustvari HTML izhod | ==== Zasebne metode ==== ^ Metoda ^ Parametri ^ Vrne ^ Opis ^ | ''calculateDimensions()'' | $origW, $origH, $opts | array | Izračuna ciljno velikost | | ''processImage()'' | $file, $mime, $w, $h, $q, $fmt | string | Obdela sliko | | ''getCacheKey()'' | $file, $w, $h, $q, $fmt | string | Ustvari zgoščeno vrednost predpomnilnika | | ''buildHtml()'' | $data, $fmt, $opts, $w, $h | string | Ustvari HTML izhod | ---- ==== Razred: helper_plugin_wvdsimage ==== **Datoteka:** ''lib/plugins/wvdsimage/helper.php'' Helper omogoča **programski dostop** do obdelave slik za predloge in vtičnike. === Uporaba === // Nalaganje helperja $wvdsimage = plugin_load('helper', 'wvdsimage'); // Upodabljanje slike iz wiki medijev $html = $wvdsimage->renderImage('wiki', 'wiki:logo.png', array( 'maxwidth' => 300, 'quality' => 90, 'alt' => 'Logo', 'class' => 'my-logo', )); // Upodabljanje slike iz imenika predloge $html = $wvdsimage->renderImage('template', 'logo.png', array( 'maxwidth' => 300, )); // Upodabljanje slike iz absolutne poti datoteke $html = $wvdsimage->renderImage('file', '/pot/do/slike.jpg', array( 'maxwidth' => 800, 'format' => 'webp', )); === Metoda: renderImage() === ^ Parameter ^ Tip ^ Opis ^ | ''$source'' | string | Vir: ''wiki'', ''template'', ''file'' | | ''$path'' | string | Pot glede na vir | | ''$options'' | array | Neobvezni parametri upodabljanja | === Parametri opcij === ^ Opcija ^ Tip ^ Privzeto ^ Opis ^ | ''maxwidth'' | int | 300 | Maksimalna širina v pikslih | | ''maxheight'' | int | null | Maksimalna višina v pikslih | | ''quality'' | int | 85 | Kakovost slike (10-100) | | ''format'' | string | auto | Izhodni format (jpeg, png, webp) | | ''class'' | string | '' | CSS razredi | | ''alt'' | string | '' | Nadomestno besedilo | | ''style'' | string | '' | Vgrajeni CSS | | ''cache'' | string | '1w' | Trajanje predpomnilnika | === Vrnjena vrednost === Vrne popolno '''' oznako z base64 Data-URI: Ob napakah vrne HTML komentar: === Primer: Logotip predloge Flat === Predloga Flat uporablja helper za upodabljanje logotipov: // V 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', )); } // Rezervni način brez wvdsimage return ''; } ---- [x][x][x][x] [x][x][x][x][x] [x][x][x][-][-] ~~DISCUSSION~~