Webgen 2.1

23. ledna 2014

Po téměr dvou letech spánku k nám pomalu kráčí nová verze „Vašeho oblíbeného generátoru statických webových stránek™“.

A aby vám jeho návštěva nebyla zas tak nepříjemná, přínáší s sebou několik potěšujících novinek. A pár BC breaků, ale ty mu jistě odpustíte.

Volitelný inkrementální režim

Ve výchozím nastavení je aktivní tzv. inkrementální režim. Jde o to, že Webgen generuje pouze soubory, které se změnily od posledního generování. Pokud chceme vygenerovat všechny soubory, můžeme použít parametr --force.

Při inkrementálním režimu jsou ve výstupním adresáři vytvářeny podadresáře, jejichž jméno odpovídá datu a času generování, např. 2012-10-27_15-10-30, a do těchto podadresářů jsou teprve ukládány vygenerované soubory. Tento přístup není vždy vhodný.

Proto verze 2.1 přichází s možností inkrementální režim vypnout. Lze toho docílit buď parametrem --onedir, nebo konfigurační volbou output.onedir:

output:
    onedir: yes

Při vypnutém inkrementálním režimu jsou všechny generované soubory ukládány přímo do výstupního adresáře, zároveň je ignorováno datum posledního generování, takže vždy dojde k vygenerování všech souborů.

Ignorování souborů se @ na začátku

A máme tu první potenciální BC break. Webgen nyní při zpracování ignoruje soubory, jejichž název začíná znakem zavináče @. Pokud nějaké takové soubory máte, budete je muset přejmenovat.

Alternativní syntaxe pro proměnné

Pro práci s proměnnými v Texy můžete nyní použít novou alternativní syntaxi. Pro výpis proměnné do stránky použijte {{$var}}, pro zápis hodnoty proměnné je vám k dispozici {{$var: value}}, příp. {{$var = value}}.

Pročištění výstupního adresáře

Můžete říct Webgenu, aby výstupní adresář před samotným generováním vyčistil. Ve výchozím nastavení je tato volba vypnuta. Zapnout ji můžete v konfiguračním souboru:

output:
    purge: yes

Při tomto nastavení Webgen smaže z výstupního adresáře všechny soubory a složky kromě skrytých (soubory a adresáře začínající tečkou).

Místo hodnoty yes můžete uvést i masku, příp. více masek:

output:
    purge: *.html

output:
    purge:
        - *.html
        - *.php

Opět zůstanou zachovány i všechny skryté soubory a složky.

Kopírování ostatních souborů

Díky nové konfigurační volbě input.copy můžete nechat nakopírovat ostatní soubory (obrázky, styly, javascripty) a složky ze zdrojového adresáře do výstupního adresáře. Při kopírování jsou ignorovány všechny soubory s příponou latte a texy. Funkci zapnete v konfiguračním souboru:

input:
    copy: yes

Můžete uvést i konkrétní masku, pak budou kopírovány všechny soubory a složky, které této masce vyhoví:

input:
    copy: *.css

Případně lze uvést více masek:

input:
    copy:
        - *.css
        - *.js
        - photos

XHTML

XHTML je nyní ve výchozím nastavení vypnuté. Pro jeho zapnutí použijte:

output:
    xhtml: yes

Šablony

V Latte šablonách je nyní dostupná proměnná $webgen, která nabízí pár užitečných metod.

První metodou je getCurrentFile, díky které se dozvíte název právě zpracovávaného souboru.

Řekněme, že zpracováváme soubor ~/webgen/examples/basic/input/articles/article-2.texy, v našem případě je ~/webgen/examples/basic/input zdrojovým adresářem a getCurrentFile nám proto bude vracet zkrácenou cestu articles/article-2.texy.

Poznámka: místo $webgen->getCurrentFile() můžete použít jen $webgen->currentFile, zápisy jsou ekvivalentní.

S currentFile souvisí také další užitečná metoda a tou je isLinkCurrent(). Metoda má jediný parametr a tím je maska, kterou použijeme k porovnání s hodnotou currentFile. Metoda vrací bool hodnotu podle toho jestli currentFile masce odpovídá, či nikoli. Hodí se např. pro zvýraznění aktivní stránky v menu.

A poslední cool metodou je createRelativeLink. Metoda má opět pouze jediný parametr a tím je absolutní cesta k nějakému souboru v rámci zdrojového adresáře. Metoda se pak na základě currentFile pokusí vytvořit ze zadané cesty cestu relativní. A protože příklad vydá za 1000 slov:

Zpracováváme articles/article-2.texy:

zavoláme createRelativeLink('css/style.css')
- metoda nám vrátí ../css/style.css
zavoláme createRelativeLink('articles/article-1.html')
- metoda vrátí article-1.html

Velice se nám tak zjednodušuje práce s odkazy.

PS: isLinkCurrent a createRelativeLink můžete použít i ve formě statických metod ::isPathCurrent(path, mask) a ::makeRelativePath(source, destination)

A to není všechno, teď příjde to nejlepší!

Generování relativních cest

Protože psát $webgen->createRelativeLink('article-2.html') je hrozná pruda, nabízí Webgen pár zkratek.

Zaprvé – v Latte šablonách nyní máme dostupná makra {link}, n:href a n:src, do kterých zapíšeme cestu k požadovanému souboru. Navíc máme nově k dispozici i makro n:image. Jedná se o obdobu makra n:src, navíc se ale pokusí doplnit k elementu i atributy width a height (pokud nalezne ve výstupním adresáři odpovídající obrázek a pokud se ze souboru podaří získat informaci o rozměrech).

<a n:href="articles/article-1.html">Článek č. 1</a>
<img n:src="photos/matrix.jpg">
<img n:image="photos/matrix.jpg">
<p>{link articles/article-1.html}</p>

Výsledek při zpracovávání souboru articles/article-2.texy:

<a href="article-1.html">Článek č. 1</a>
<img src="../photos/matrix.jpg">
<img src="../photos/matrix.jpg" width="73" height="73">
<p>article-1.html</p>

Sexy, že?

Podobně to funguje u Texy, stačí adresu prefixovat pomocí zavináče:

"Článek č. 1":@articles/article-1.html

a funguje to i u obrázků

[* @photos/matrix.png *]

a referencí

[article 1]: @articles/article-1.html

Pozor: metoda createRelativeLink, makra n:href, n:src, n:image a {link} a ani Texy nekontrolují jestli daná cesta (soubor) skutečně existuje! To si musíte pohlídat sami.

Konfigurace na úrovni souboru

Díky novému makru {webgen} můžeme snadno změnit globální konfiguraci pro jednotlivé soubory. Protože ale Webgen moc konfiguračních voleb nemá, lze tímto makrem nyní ovlivnit pouze příponu výstupního souboru. V Latte takto

{webgen ext => php}

a v Texy takto

{{webgen: ext: php}}

případně takto

{{webgen(ext: php)}}

Změna práce s hlavním nadpisem

A poslední BC break dnešního večera. Pokud jste dříve chtěli mít na stránce hlavní nadpis (<h1>) museli jste ho napsat do layoutu(!), přibližně nějak takto:

<h1 n:ifset="#title">{include #title}</h1>

Nevím, proč mi něco tak pitomého před 2 lety připadalo jako dobrý nápad. Tento kód proto z layoutu smažte a hlavní nadpis zapište přímo v konkrétních souborech. Pro Texy soubory se prakticky nic nemění, pro Latte můžete použít něco jako:

<h1 n:block="title">Hlavní nadpis</h1>

a v layoutu pak definujte titulek stránky např. takto

<title>{block #title|striptags|strip}{/block}</title>

A co dál? Verze 3.0

Protože většina dnešních novinek měla být k dispozici až v chystané verzi 3.0, tak tento přehled nebude moc dlouhý, z hlavy mě napadá jen:

verze 3.0 pravděpodobně nebude obsahovat inkrementální režim
místo toho nabídne rozhraní, které umožní použít různé výstupní metody (generované soubory ukládat do složky, ZIP souboru, kamkoli)
možnost mít v projektu více layoutů
rozhraní pro další typy souborů (např. Markdown)
rozhraní pro psaní vlastních rozšíření
aktualizované knihovny

Osobně se nejvíc těším na možnost psaní vlastních rozšíření, díky které bude možné přidat do šablon nové helpery, makra, přidat vlastní Texy handlery apod.

PS. Ke stažení je zatím pouze verze 2.1-RC1. Finální verzi vydám až za několik dní. Nejprve přepíšu na novou verzi všechny své webgen-weby a když nenarazím na žádné problémy, vydám 2.1-final.

Líbí se vám tato stránka?

Podpořit autora