1. Dokumentace
  2. Reference
  3. Datový model

<Img>

Pole typu <Img> slouží k uložení obrázků ve formátu JPG. Kromě samotného uložení je možné při nahrávání obrázek zmenšit na rozměry určené vnitřními tagy Size, včetně případného ořezu. Ve .aspx se obrázek vypíše pomocí <je:img>.

<Img name="photo">
    <Size name="original" />
    <Size name="fullHD" />
    <Size name="thumb" />
</Img>

Sadu obrázků lze připojit pomocí pole <ImgCollection>. Pro obrázky v jiných formátech (PNG, GIF, SVG) je k dispozici pole typu <SimpleImg>. To se používá i v situacích, kdy není žádoucí, aby JellyPot s nahrávaným JPG jakkoliv manipuloval.

Atributy

  • allowEditFor nepovinný [seznam skupin uživatelů]

    Skupiny uživatelů, kterým je pole přístupné k editaci. Pokud není atribut zadán, je pole přístupné k editace všem, kteří mají přístup do administrace. Více v článku Zabezpečení před neoprávněným přístupem do administrace.

  • denyEditFor nepovinný [seznam skupin uživatelů]

    Skupiny uživatelů, kterým je pole znepřístupněné k editaci. Pokud není atribut zadán, je pole přístupné k editace všem, kteří mají přístup do administrace. Více v článku Zabezpečení před neoprávněným přístupem do administrace.

  • desc nepovinný [string]

    Uživatelský popis pole, který se zobrazí v administračním rozhraní. Slouží k zapsání doplňujících údajů, jako například pokyny pro editora apod.

  • langDepend nepovinný [none, firstValue, values]

    Určuje chování pole, má-li web více jazykových mutací (viz Jazyky). Možné hodnoty jsou:

    • none – obsah pole je pro všechny jazyky shodný
    • firstValue – pole má v každém definovaném jazyce jinou hodnotu. Pokud není hodnota pro daný jazyk zadána, použije se hodnota výchozího jazyka.
    • values – pole má v každém definovaném jazyce jinou hodnotu. Pokud není hodnota v daném jazyce zadána, je pole pro daný jazyk prázdné.

  • name povinný [string]

    Jméno pole. V rámci jednoho typu musí být jedinečné. Smí obsahovat pouze číslice a písmena bez diakritiky. Doporučuje se jména polí uvádět s počátečním malým písmenem (viz Konvence pojmenování).

  • required nepovinný [false, true]

    Při nastavení na true se pole stane povinným a při editaci v administraci je vyžadováno připojení obrázku.

  • title nepovinný [string]

    Uživatelský název pole, který se zobrazí v administračním rozhraní. Není-li title uvedeno, zobrazí se name.

  • useAlt nepovinný [false, true]

    Určuje, zda se má v administračním rozhraní v dialogu uploadu obrázku zobrazovat pole pro zadání alternativního názvu. Tento název může být automaticky vypsán do HTML při generování značky img (viz <je:img>, atribut alt). Zadaný alternativní název je taktéž dostupný přes vnitřní pole alt (viz níže).

Vnitřní tag <Size>

Size je vnitřní tag uváděný v rámci deklarace pole typu <Img> nebo <ImgCollection>. Určuje rozměry, na které bude nahraný obrázek upraven. Tagů Size lze použít libovolný počet, JellyPot pak nahraný obrázek uloží do všech požadovaných rozměrů.

Atributy

  • alwaysResize nepovinný [false, true]

    Při nastavení na true dojde k přeuložení obrázku, i když z hlediska rozměrů není přeuložení potřeba.

  • enlargeMode nepovinný [maintain, minimize, maximize]

    Umožňuje ovlivnit výsledné rozměry obrázku, pokud zadané rozměry umožňují více interpretací. Atribut může mít tyto hodnoty:

    • maintain – rozměry obrázku jsou upraveny tak, aby vyhovovaly zadaným hodnotám a zároveň aby prováděná změna rozměrů byla co nejmenší.
    • minimize – rozměry obrázku jsou upraveny tak, aby vyhovovaly zadaným hodnotám a zároveň byly co nejmenší.
    • maximize – rozměry obrázku jsou upraveny tak, aby vyhovovaly zadaným hodnotám a zároveň byly co největší.

    Atribut zpravidla není nutné uvádět, v drtivé většině případů vyhovuje jeho výchozí hodnota enlargeMode="maintain". Více níže, viz Určení výsledných rozměrů.

  • height nepovinný [int, max int, min int, int-int, *]

    Požadovaný výška obrázku v px, případně maximální nebo minimální výška nebo rozmezí. Není-li atribut uveden, výška může být libovolná.

  • name povinný [string]

    Jméno velikosti. V rámci jednoho pole typu <Img> musí být jedinečné. Smí obsahovat pouze písmena bez diakritiky a číslice. Jméno se doporučuje uvádět s počátečním malým písmenem.

  • path nepovinný [název složky]

    Název podsložky ve složce upItems/imgs, do které se má nahrávaný obrázek uložit. Hodí se pro udržení pořádku ve složce s obrázky. Název složky smí obsahovat pouze písmena bez diakritiky, čísla a znaky - a ..

  • quality nepovinný [int 0–100]

    Kvalita ukládaného obrázku. Vyšší hodnota znamená nižší kompresi. Atribut má význam pouze tehdy, pokud dochází k přeuložení obrázku. Výchozí hodnota je 80.

  • width nepovinný [int, max int, min int, int-int, *]

    Požadovaná šířka obrázku v px, případně maximální nebo minimální šířka nebo rozmezí. Není-li atribut uveden, šířka může být libovolná.

Určení výsledných rozměrů

Atributy width a height

Rozměry nahraného obrázku se upraví tak, aby vyhovovaly hodnotám uvedeným v atributech width a height příslušeného vnitřního tagu Size. Do atributů width a height lze uvést tyto hodnoty:

AtributPopis
width="300"výsledná šířka obrázku bude přesně 300 px,
width="min 300"výsledná šířka obrázku bude 300 px nebo více,
width="max 300"výsledná šířka obrázku bude 300 px nebo méně,
width="100-300"výsledná šířka obrázku bude nejméně 100 px a nejvýše 300 px,
width="*" nebo atribut není uvedenvýsledná šířka bude libovolná.

Analogicky pro atribut height.

Pokud rozměry nahraného obrázku vyhovují hodnotám zadaným v atributech width a height, JellyPot obrázek beze změny uloží. Pokud rozměry nevyhovují, JellyPot obrázek při zachování poměru stran zvětší nebo zmenší co nejméně tak, aby limitům vyhověl. Pokud to není možné – je např. určeno width="200" height="200" a obrázek má rozlišení 300 × 200 px – pak se obrázek ořízne na střed.

enlargeMode

V některých případech rozměry určené atributy width a height připouštějí více výkladů – např. je určeno width="min 200" height="min 200" a obrázek má velikost 350 × 250 px. To podmínce vyhovuje, obrázek má víc než 200 px na šířku i na výšku. Při neuvedeném atributu enlargeMode (což odpovídá jeho nastavení enlargeMode="maintain") JellyPot obrázek beze změny rozměrů uloží.

Pokud bychom však chtěli, aby obrázek měl alespoň 200 × 200 px, ale ne zbytečně víc, pak použitím enlargeMode="minimize" změnší JellyPot rozměry obrázku na 280 x 200 px, což je nejmenší možná velikost, která vyhovuje zadání.

Hodnota enlargeMode="minimize" tedy systému JellyPot říká: „udělej obrázek co nejmenší tak, aby ještě vyhovoval daným rozměrům“. enlargeMode="maximize" je pak přesným opakem: říká „udělej obrázek co největší tak, aby ještě vyhovoval daným rozměrům“.

Z jiného úhlu pohledu lze říct, že pokud se v atributech vyskytuje rozlišení uvedené operátorem min, má smysl uvažovat o enlargeMode="minimize". Pokud se v atributech naopak vyskytuje rozlišení uvedené operátorem max, má smysl uvažovat o enlargeMode="maximize".

*Poznámka: Pokud se to zdá komplikované, nezoufejte, není to tak strašné. Změna rozměrů obrázku se v praxi chová tak, jak byste přirozeně očekávali – jen když se to přesně popíše, ukáže se, že přirozeně očekávané chování je vlastně docela komplexní ;)

Vnitřní pole

Pole typu <Img> obsahuje další vnitřní pole. Tato pole jsou včetně jejich obsahu generována automaticky. Jejich obsah lze v .aspx vypsat pomocí controlu <je:item>.

  • alt – alternativní název, který byl zadán při uploadu obrázku a který může být použit jako obsah atributu alt HTML značky <img> při vypsání obrázku do stránky (viz atribut useAlt),
  • ext – přípona souboru bez úvodní tečky, např. jpg,
  • fullPath – úplná cesta k obrázku včetně názvu serveru, např. http://www.example.com/app/uploads/obrazek.jpg,
  • height – výška obrázku v px,
  • imgID – řetězec s jednoznačným identifikátorem obrázku (všechny velikosti jednoho obrázku mají shodné imgID),
  • nameOnServer – název souboru tak, jak je uložen na serveru, např. someImage_someSize_0001.jpg,
  • originalName – název souboru, pod kterým byl obrázek na server nahrán, s případně odstraněnou diakritikou (viz atribut sanitizeName elementu Uploads),
  • path – úplná cesta k obrázku, např. /app/uploads/obrazek.jpg,
  • size – řetězec s přibližnou velikostí souboru. Může obsahovat hodnoty např. 873 B; 23 kB; 1,2 MB. Jednotka je určena automaticky podle velikosti daného souboru,
  • sizeInBytes – velikost souboru v bytech, vyjádřená jako číslo (např. 14147),
  • width – šířka obrázku v px.

Některá vnitřní pole jsou společná pro všechny velikosti daného obrázku, obsah jiných (nameOnServer, path, size, sizeAsNum, width, height) záleží na konkrétní velikosti. V těchto případech je potřeba název vnitřního pole zadávat v syntaxi názevVelikosti-názevPole. Tedy např. šířka obrázku ve velikosti thumb je dostupná přes pole s názvem thumb-width (<je:item runat="server" field="image.thumb-width" />).

Uložení souborů na serveru

Nahrávané obrázky jsou ukládány do složky upItems/imgs umístěné v rootu webu. Více informací je uvedeno článku Složky pro upload souborů z administračního rozhraní.

JellyPot standardně upravuje jména nahrávaných souborů – tedy i obrázků. Odstraňuje mezery, nahrazuje znaky s diakritikou apod. Toto chování lze změnit, více viz Uploads.

JellyPot dále do názvu souboru doplňuje název velikosti a pořadové číslo, pokud již ve složce existuje soubor se stejným názvem. Výsledný název souboru uloženého na serveru tedy může být např. photo_thumb_002.jpg.

Příklady

V Site.config máme proměnnou page typu PageWithImage:

<Var name="pageWithImage"
     type="PageWithImage" />
...
<Type name="PageWithImage">
    <Img name="image">
        <Size name="original" />
        <Size name="fullHD"
              width="1920"
              height="1080" />
        <Size name="thumb"
              width="320"
              height="200" />
    </Img>
</Type>

Pro vypsání obrázku v .aspx musíme v controlu <je:img> uvést, kterou uloženou velikost obrázku chceme zobrazit. Tedy pro velikost fullHD:

<je:img runat="server"
        field="pageWithImage.image"
        size="fullHD" />

Pokud bychom chtěli obrázek jen v náhledové velikosti, pak:

<je:img runat="server"
        field="pageWithImage.image"
        size="thumb" />

Připomínky a postřehy

Máte-li nějakou připomínku, dobrý nápad nebo jste našli v dokumentaci chybu, rádi od vás uslyšíme.