Tento návod se primárně zaměřuje – jak název napovídá – na vytvoření galerie, přičemž požadovaným výstupem bude náhodný výběr stanoveného počtu obrázků z předem neznámého počtu a jejich zobrazení na stránce. Současně ale prezentuje i možnosti značkovacího jazyka pro tvorbu šablon Twig a rovněž i možnosti značkovacího jazyka pro formátování obsahu Markdown. Okrajově pak představuje možnosti ukládání stránek do mezipaměti, nebo chcete-li do cache.

Jak již bylo uvedeno v článku Úložiště médií a možnosti přístupů k médiím, je v Gravu možné uložit soubory, potažmo pak obrázky, do několika úložišť, zvolených podle následujícího očekávání, konkrétně pak, zda budou užívány pouze v konkrétní stránce, nebo v rámci celého webu. Galerie je typickým příkladem první varianty, nicméně nic nebrání tomu, abychom obrázky následně použili na kterékoliv jiné stránce.

Začneme tedy vytvořením stránky /galerie a nahráním kolekce obrázků do této stránky. Pro naši potřebu je ideální, aby měly nastaveno výchozí třídění, tedy podle svého názvu, ale v konečném důsledku na tom nezáleží, protože budeme ve výstupu pracovat s náhodně uspořádanými hodnotami, z nichž použijeme pouze zvolenou část. Pokud tedy použijeme vlastní třídění prostřednictvím proměnné hlavičky stránky media_order, není to na překážku. Z článku Úložiště médií a možnosti přístupů k médiím víme, že soubory/obrázky uložené v konkrétní stránce jsou ze strany Gravu chápány jako Média stránky, a tyto jsou dostupné v proměnné stránky typu pole page.media. Abychom mohli s jednotlivými obrázky pracovat, je třeba je nejprve z pole načíst a upravit.

Nejprve si ukážeme jednoduchou variantu, která náhodně vybere vzorek obrázků z kolekce:

{% for image in page.media %}
    {% if random(100) < 10 %}
        {{ image.cropZoom(400, 400) }}
    {% endif %}
{% endfor %}

Uvedený kód prochází všechny obrázky uložené ve složce stránky. V rámci cyklu for generuje náhodná čísla v intervalu <0; 100> a v případě, že je číslo menší než 10, pak obrázek vykreslí, v opačném případě pokračuje v procházení. Pokud tedy máme v kolekci např. 320 obrázků, mělo by se jich na stránce zobrazit přibližně 32, což odpovídá 10 % celku.

Předchozí příklad má řadu nedostatků. Kromě toho, že není možné ovlivnit přesný počet obrázků, které budou vráceny ve výstupu, je rovněž skutečností, že obrázky jsou vždy řazeny ve shodném pořadí, což může – i nemusí – být překážkou, záleží na úhlu pohledu. Zásadní nevýhodou je pak variabilita, která se projeví při přidání (obecně změně) dalších obrázků. Pokud se nyní vrací cca 10 % obrázků z celkového počtu, pak při 1000 obrázcích by to již bylo okolo 100, což může vést ke zpomalení načítání stránky. V tomto případě bychom museli při každé změně nahraných obrázků upravit hodnotu ovlivňující výstup, např. na {% if random(100) < 2 %}, nebo zajistit ošetření podmínkami pro jednotlivé intervaly v kódu.

Vrátíme se tedy k původnímu zadání, které bude fungovat tak, že se vždy zobrazí shodný počet obrázků, a to ve zcela náhodném pořadí. K tomu použijeme následující Twig kód:

{% set images = [] %}
{% for image in page.media %}
    {% set key = random(1000) %}
    {% set images = images + ({(key): image}) %}
{% endfor %}

Kód si podrobně vysvětlíme. Nejprve vytvoříme prázdnou proměnnou typu pole images. Dále procházíme cyklem for kolekci obrázků, tedy jednotlivá média stránky, která postupně přiřazujeme do proměnné image. V následujícím kroku vygenerujeme náhodné číslo v intervalu <0; 1000>. A nakonec je tu nejdůležitější část, v rámci níž do dříve vytvořené proměnné typu pole images přidáváme položky ve dvojici klíč: hodnota, kdy klíčem je aktuálně vygenerované náhodné číslo a hodnotou aktuální položka přiřazená do proměnné image. Uvedeným kódem jsme docílili toho, že máme k dispozici indexované pole, obsahující teoreticky všechny obrázky, přičemž každý má přiřazený jedinečný celočíselný identifikátor v rozsahu stanoveném intervalem, který nám umožní další manipulaci dle našich potřeb.

Nyní již nic nebrání tomu, abychom data upravili a vypsali na stránku. K tomu slouží následující Twig kód.

{% set images = images|ksort %}
{% set images = images|slice(0, 10) %}
{% for image in images %}
    {{ image.cropZoom(400, 400) }}
{% endfor %}

Kód si opět podrobně vysvětlíme. V prvním kroku setřídíme pole images vzestupně podle hodnot klíčů. Jelikož jsou klíče tvořeny náhodnými hodnotami, dojde k náhodnému „zamíchání“ obrázků, čehož jsme přesně chtěli dosáhnout.

Ze setříděných obrázků dále použijeme pouze podmnožinu sestávající z prvních N prvků, v našem případě 10. K tomu nám poslouží filtr slice.

A nakonec jednotlivé obrázky, resp. jejich náhledy, vykreslíme na stránce.

Zde je k dispozici kompletní kód:

{% set images = [] %}
{% for image in page.media %}
    {% set key = random(1000) %}
    {% set images = images + ({(key): image}) %}
{% endfor %}
{% for image in images|ksort|slice(0, 10) %}
    {{ image.cropZoom(400, 400) }}
{% endfor %}

Kód můžeme vložit buď do nové šablony stránky gallery.html.twig, za předpokladu, že plánujeme na webu více galerií, popř. přímo do těla stránky, pokud se jedná spíše o ojedinělou záležitost. V tomto případě je nutné aktivovat položku Twig v nastavení Zpracování stránky (výchozí je pouze Markdown), stejně jako například v příkladu konverze znaků v Twig šabloně.

Grav stránky ukládá do mezipaměti, aby urychlil jejich načítání. K jejich opětovnému vygenerování dochází pouze v případě změny obsahu nebo po vyprázdnění mezipaměti (po vypršení určené doby, po ručním vymazání, nebo vymazání prostřednictvím plánovače úloh). To má za následek, že se načítá stránka z mezipaměti, dokud nenastane některá ze situací, která způsobí její opětovné vygenerování. Existuje proto alternativní – avšak nijak elegantní – řešení, a to vypnout ukládání do mezipaměti na úrovni stránky nastavením položky Použít cache na Vypnuto. Tímto zajistíme, že je při každém načtení stránka opětovně vytvořena znovu. Rychlost vytvoření a zobrazení stránky je závislá jednak na počtu celkových médií stránky, které se musí projít, ale především na počtu těch, které chceme na výstupu, neboť se musí opakovaně generovat jejich náhledy, jako se tomu děje v příkladu výše. Horší variantu, kdy server předává prohlížeči originály obrázků v plné velikosti radši ani nedomýšlet.

A to je vše. Nyní zbývá pouze graficky upravit výstup prostřednictvím stylů, popř. zvolit jiný typ generovaných náhledů (měřítko, oříznuté měřítko), či rozšířit o jiný prvek, např. výstup parametrů Alt a/nebo Title, prohlížeč zvětšenin obrázků (viz odkaz na funkční galerii v úvodu článku), vodoznak apod.