Moje odkazy
Obsah článku:
vydáno: 8. 1. 2012 17:32, aktualizováno: 18. 7. 2020 13:32
Zase jsem po večerech a ve chvílích volna udělal trochu práce na svém generátoru webových stránek. Takže tady je souhrn novinek. Pokud nevíte, o co jde, přečtěte si nejdřív úvod: XML Web generátor. Nejzajímavější jsou na něm tzv. makra, která umožňují vkládat do generovaných stránek různé věci pomocí jednoduchých značek (podobné jako XHTML značky, akorát se nachází ve vlastním jmenném prostoru).
Zatím vyšly tři verze programu – první dvě jsem označil až zpětně:
Často potřebujeme na stránky vložit nějaké ukázky kódu – konfigurace nebo programy, skripty atd. Pro lepší čitelnost je dobré zvýraznit syntaxi – to uměla už předchozí verze.
U větších ukázek je ale nepraktické kopírovat kód přímo do stránky.
Inspiroval jsem se XHTML značkou <img src="obrázek.jpeg" alt="…"/>
pro vkládání obrázků a přidal podobnou funkcionalitu do makra, které se stará o zvýrazňování zdrojáků:
<m:pre jazyk="bash" src="matrixový-spořič.sh" odkaz="ano"/>
Načte obsah souboru matrixový-spořič.sh
a vypíše se zvýrazněnou syntaxí:
Atribut odkaz
je volitelný a pokud je nastaven na ano
,
generátor pod ukázku přidá i odkaz na stažení původního souboru se zdrojovým kódem.
Generátor umožňuje do stránek vkládat různé diagramy – to šlo už ve verzi 0.2. Ukázka úplně jednoduchého diagramu:
…který jsme vložili pomocí tohoto makra:
<m:diagram orientace="vodorovně">
A -> B;
B -> C;
</m:diagram>
Zadání složitějších diagramů je šikovnější nepsat přímo do stránky,
ale mít ho uložené v souboru,
na který se pouze odkážeme atributem src
– to je novinka verze 0.3:
<m:diagram src="kočka-a-pes-oop.dot" nadpis="Třídy"/>
Výše uvedený kód nám vloží do stránky diagram tříd:
Pro vkládání tabulek můžeme použít standardní XHTML značky, kde lze nastavit úplně cokoli a vytvořit libovolně složitou tabulku.
<table>
<thead>…hlavička tabulky…</thead>
<tbody>
<tr><td>…</td><td>…</td></tr>
<tr><td>…</td><td>…</td></tr>
<tr><td>…</td><td>…</td></tr>
…
</tbody>
</table>
Pro jednoduché tabulky se nám ale může hodit následující makro. Např. ceník krmení ptáků vložíme takto:
<m:tabulka>
Velikost ptáka Cena za jedno krmení
malý 250
střední 500
velký 1000
</m:tabulka>
Což nám vygeneruje (živá ukázka, zdroj):
Sloupečky vytvoříme jednoduše odsazením pomocí
tabulátoru
případně si můžeme atributem oddělovač
určit jiný oddělovač (třeba středník).
A když máme data v CSV souboru,
nemusíme je ani kopírovat do stránky – název souboru prostě zadáme do atributu src
(živá ukázka):
<m:tabulka src="telefonní-seznam.csv"/>
Uvnitř jednoduchých tabulek nelze zatím používat žádné formátování nebo makra – v buňkách může být jen prostý text. Ale není to nic nemožného, vlastně už jsem jednou podobný úkol řešil, takže snad v nějaké příští verzi na to přijde řada.
Při tvorbě stránek často chceme odladit vzhled/rozvržení, ještě než máme všechen obsah. Proto se používá nějaký vycpávkový text (většinou Lorem Ipsum), který nemusíme vymýšlet a prostě ho jen plácneme na stránku, aby tam něco bylo.
Takový text si můžeme zkopírovat z webu lorem.lipsum.com a ručně vložit do stránky. Nebo taky můžeme použít makro a do stránky vložíme pouze:
<m:vycpávka odstavců="3"/>
A prázdné místo na stránce nám rázem zaplní tři krásné odstavce Lorem Ipsum textu. XSLT šablona se postará o stažení těchto odstavců ze Sítě a vložení do stránky.
Akorát ve verzi 0.3 používejte prosím toto makro opatrně, protože text se stahuje při každém generování vždy znovu. V některé z dalších verzí by to mělo fungovat tak, že se text stáhne jen jednou, uloží do zvláštního XML souboru a z něj bude brát při každém dalším generování stránek.
Kromě formátování textu pomocí XHTML značek a našich skvělých maker můžeme části stránek psát v i alternativní syntaxi – tzv. wiki syntaxi (podobná se totiž používá na Wikipedii). Pro některé jednoduché věci to může být použitelné a celkem fajn – např. pomocí následujícího kódu vložíme nečíslovaný seznam a tučné písmo:
<m:wiki>
- první odrážka
- druhá **tenhle text bude tučně**
- třetí
</m:wiki>
Generátor je připravený na použití různých syntaxí resp. procesorů wiki syntaxe
– lze je určit atributem syntaxe
elementu wiki
.
Zatím je ale jediným podporovaným procesorem
Markdown.
Docela zajímavá by mohla být podpora Texy!,
ale dokud nebude snadný způsob, jak ho nainstalovat
(tzn. balíček pro Debian nebo Fedoru),
nechce se mi s tím dělat.
Odkazy samozřejmě můžeme vkládat pomocí klasické XHTML značky, jak jsme zvyklí:
<a href="http://example.com/">nějaká stránka</a>
<a href="mailto:anonym@example.com">nějaký e-mail</a>
Ale jsou tu i makra, která nám ušetří práci při vkládání určitých typů odkazů
– zadáme jen konkrétní parametr a nemusíme psát celé URL.
Typ těchto odkazů se určuje pomocí XML atributu typ
.
Interní odkazy – zadáme
jen
název souboru bez přípony
a makro se postará o správné zakódování (důležité, když název obsahuje diakritiku nebo mezery)
a doplnění přípony (ta se může měnit podle nastavení v build.xml
).
<m:a href="služby">Služby</m:a>
Zdroj se jmenuje služby.xml
a vygenerovaná stránka služby.xhtml
nebo taky služby.html
(podle nastavení)
a v odkazu je potřeba zakódovat URL jako:
slu%C5%BEby.xhtml
– díky makru tohle nemusíme řešit a zadáme jen název souboru, jak ho vidíme třeba v Dolphinu (správce souborů).
Odkazy na Trac generátoru – pro uživatele nejsou moc zajímavé, ale hodí se k dokumentaci systému:
<m:a href="8" typ="trac">odkaz na úkol</m:a>
<m:a href="využití" typ="trac">odkaz na wiki stránku</m:a>
Vygeneruje následující XHTML odkazy:
https://trac.frantovo.cz/xml-web-generator/ticket/8 https://trac.frantovo.cz/xml-web-generator/wiki/vyu%C5%BEit%C3%AD
Odkazy na Wikipedii – opět nemusíme zadávat URL,
ale stačí název stránky.
Ve výchozím stavu makro odkazuje na českou verzi encyklopedie
– a pomocí atributu jazyk
můžeme určit libovolnou jinou:
<m:a href="Linus Torvalds" typ="wiki">Linus Torvalds</m:a>
<m:a href="Richard Stallman" typ="wiki" jazyk="en">Richard Stallman</m:a>
Odkazy na Javadoc – dokumentaci k Javě.
Do href
se píše název třídy a volitelně můžeme uvést verzi Javy
(výchozí je 7 resp. aktuální verze).
<m:a href="javax.xml.parsers.SAXParserFactory" typ="javadoc">SAXParserFactory</m:a>
<m:a href="java.lang.String" typ="javadoc" verze="5">String</m:a>
Odkazy na vyhledávání Seznamem nebo Googlem. Zadává se jen hledaný výraz a typ hledače:
<m:a href="nejlepší GNU/Linuxová distribuce" typ="seznam">Nejlepší distribuce</m:a>
<m:a href="GNU/Linux a tučňák Tux" typ="google">GNU/Linux a tučňák Tux</m:a>
A v neposlední řadě je možno odkazovat na internetové standardy RFC:
<m:a href="1855" typ="rfc">Netiketa</m:a>
Výhoda je mj. v tom, že kdyby se něco změnilo, stačí upravit makro a nemusíme předělávat odkazy na všech stránkách. (živá ukázka, zdroj)
Dopracoval jsem se také k tomu, že program z jedné XSLT šablony generuje jinou XSLT šablonu a tu následně spouští. Takže se dá říct, že program upravuje sám sebe :-) Chová se ale deterministicky a řídí se jen vstupem, který mu zadal uživatel. Takže se o nějaké umělé inteligenci mluvit nedá. Zatím…
Rozdělil jsem původní šablonu stránka.xsl
na menší části:
všechna makra jsou v samostatných souborech v adresáři šablona/makra
.
Přestože ani dřív to nebyl špagetový kód
(XSLT je v tomhle super, šablony jsou přehledné – samostatné kousky kódu aplikované na elementy vyhovující masce),
teď je to ještě lepší.
Např. ve verzovacím systému bude vidět, co se měnilo už jen podle názvu souboru.
A taky si vlastní makra mohou snadno psát uživatelé sami
– uživatelská makra se ukládají opět do
samostatných souborů,
tentokrát ale ve složce vstup/makra
.
A všechny tyhle malé soubory – systémová i uživatelská makra – se vezmou a použijí při generování stránek
(nová makra není potřeba nikde registrovat, prostě jen vytvoříte nový soubor).
Taky jsem vyčlenil zvlášť pár funkcí (do stránka-společné.xsl
),
takže stránka.xsl
je teď už jen kostra výsledné XHTML stránky
→ bude v ní probíhat minimum změn
a uživatel si ji může snadno
přizpůsobit,
aniž by riskoval moc konfliktů
a slučování při aktualizacích na vyšší verze.
Tento program je svobodný software vydaný pod licencí GNU GPL, takže ho můžete svobodně používat, upravovat a šířit. Pokud máte nápad na nějaké šikovné makro, napište mi, co by mělo dělat, nebo ideálně pošlete rovnou XSLT šablonu :-)
Témata: [softwarové inženýrství] [XML] [www]
Tento článek zatím nikdo nekomentoval