Jazyk šablon v programu Calibre¶

Jazyk šablon calibre je jazyk specifický pro calibre, který se v calibre používá pro úlohy, jako je určování cest k souborům, formátování hodnot a výpočet hodnoty pro uživatelem určené sloupce. Příklady:

Určení struktury složek a názvů souborů při ukládání souborů z knihovny calibre na disk nebo do čtečky e-knih.
Definování pravidel pro přidávání ikon a barev do seznamu knih calibre.
Definování virtuálních sloupců, které obsahují data z jiných sloupců.
Pokročilé hledání v knihovně.
Pokročilé hledání a nahrazování v metadatech.

Jazyk je založen na pojmu šablona, která určuje, která metadata knihy se mají použít, jaké výpočty se s nimi mají provést a jak mají být formátována.

Základní šablony¶

Základní šablona se skládá z jednoho nebo více výrazů šablony. Výraz šablony se skládá z textu a názvů ve složených závorkách ({}), které jsou nahrazeny odpovídajícími metadaty ze zpracovávané knihy. Například výchozí šablona, kterou calibre používá při ukládání knih do zařízení, má čtyři výrazy šablony:

{author_sort}/{title}/{title} - {authors}

Pro knihu „The Foundation“ od autora „Isaac Asimov“ se šablona změní na:

Asimov, Isaac/The Foundation/The Foundation - Isaac Asimov

Lomítka nejsou výrazy šablony, protože nejsou mezi {}. Takový text zůstane tam, kde se vyskytuje. Například pokud je šablona:

{author_sort} Some Important Text {title}/{title} - {authors}

pak pro „The Foundation“ šablona vytvoří:

Asimov, Isaac Some Important Text The Foundation/The Foundation - Isaac Asimov

Výraz šablony může pomocí názvu vyhledávání sloupce přistupovat ke všem metadatům dostupným v calibre, včetně vlastních sloupců (sloupců, které si vytvoříte sami). Název vyhledávání pro sloupec (někdy označovaný jako pole) zjistíte tak, že najedete myší na záhlaví sloupce v seznamu knih calibre. Názvy vyhledávání pro vlastní sloupce vždy začínají znakem #. U sloupců typu série existuje dodatečné pole s názvem #lookup name_index, které představuje pořadí dané knihy v sérii. Pokud máte například vlastní sloupec série s názvem #myseries, bude existovat také sloupec s názvem #myseries_index. Pořadí ve standardním sloupci série se jmenuje series_index.

Kromě standardních polí založených na sloupcích můžete použít také:

{formats} - seznam formátů dostupných pro knihu v knihovně calibre

{identifiers:select(isbn)} - ISBN knihy

Pokud nejsou metadata pole pro danou knihu definována, pole v šabloně se nahradí prázdným řetězcem (''). Zvažte například následující šablonu:

{author_sort}/{series}/{title} {series_index}

Pokud je Asimovova kniha „Second Foundation“ v sérii „Foundation“, šablona vytvoří:

Asimov, Isaac/Foundation/Second Foundation 3

Pokud pro knihu nebyla zadána série, šablona vytvoří:

Asimov, Isaac/Second Foundation

Zpracovatel šablon automaticky odstraní vícenásobná lomítka a počáteční nebo koncové mezery.

Pokročilé formátování¶

Kromě dosazování metadat mohou šablony podmíněně zahrnovat další text a určovat, jak se mají dosazená data formátovat.

Podmíněné zahrnutí textu

Někdy chcete, aby se text ve výstupu objevil jen tehdy, když pole není prázdné. Běžným případem jsou pole series a series_index, u kterých buď nechcete zobrazit nic, nebo chcete zobrazit obě hodnoty oddělené spojovníkem. calibre tento případ řeší pomocí speciální syntaxe výrazu šablony.

Například při použití výše uvedeného příkladu Foundation předpokládejme, že chcete, aby šablona vytvořila Foundation - 3 - Second Foundation. Tento výstup vytvoří následující šablona:

{series} - {series_index} - {title}

Pokud ale kniha nemá žádnou sérii, šablona vytvoří - - název, což pravděpodobně není to, co chcete. Obvykle má být výsledkem název bez nadbytečných spojovníků. Toho můžete dosáhnout pomocí následující syntaxe šablony:

{field:|prefix_text|suffix_text}

Tento výraz šablony říká, že pokud má field hodnotu XXXX, výsledkem bude prefix_textXXXXsuffix_text. Pokud je field prázdné (nemá žádnou hodnotu), výsledkem bude prázdný řetězec (nic), protože předpona a přípona se ignorují. Předpona a přípona mohou obsahovat mezery.

V předponě ani příponě nepoužívejte podšablony (`{ … }`) ani funkce (viz níže).

Pomocí této syntaxe můžeme výše uvedený problém s chybějící sérií vyřešit šablonou:

{series}{series_index:| - | - }{title}

Spojovníky budou zahrnuty jen tehdy, pokud má kniha pořadí v sérii, které má pouze v případě, že patří do série. Pokud budeme pokračovat v příkladu Foundation, šablona vytvoří Foundation - 1 - Second Foundation.

Poznámky:

Pokud používáte předponu nebo příponu, musíte za název vyhledávání vložit dvojtečku.
Musíte použít buď žádný, nebo oba znaky |. Použití jen jednoho, například v {field:| - }, není povoleno.
Je v pořádku pro předponu nebo příponu nezadat žádný text , například v {series:|| - }. Šablona {title:||} je stejná jako {title}.

Formátování

Předpokládejme, že chcete series_index formátovat jako tři číslice s počátečními nulami. To zajistí následující zápis:

{series_index:0>3s} - tři číslice s počátečními nulami

Pro koncové nuly použijte:

{series_index:0<3s} - tři číslice s koncovými nulami

Pokud používáte pořadí v sérii s desetinnými hodnotami, například 1.1, můžete chtít zarovnat desetinné tečky. Například můžete chtít, aby se pořadí 1 a 2.5 zobrazila jako 01.00 a 02.50, aby se správně řadila na zařízení, které používá lexikální řazení. Toho dosáhnete takto:

{series_index:0>5.2f} - pět znaků tvořených dvěma číslicemi s počátečními nulami, desetinnou tečkou a 2 číslicemi za desetinnou tečkou.

Pokud chcete použít pouze první dvě písmena dat, použijte:

{author_sort:.2} - pouze první dvě písmena hodnoty řazení autora

Velká část formátování v jazyce šablon calibre pochází z Pythonu. Další podrobnosti o syntaxi těchto pokročilých formátovacích operací najdete v dokumentaci Pythonu.

Použití šablon k definování vlastních sloupců¶

Šablony lze použít k zobrazení informací, které nejsou v metadatech calibre, nebo k zobrazení metadat jinak než v běžném formátu calibre. Můžete například chtít zobrazit ISBN, což je pole, které calibre nezobrazuje. Toho dosáhnete vytvořením vlastního sloupce typu Sloupec sestavený z jiných sloupců (dále jen složené sloupce) a zadáním šablony, která vygeneruje zobrazovaný text. Sloupec zobrazí výsledek vyhodnocení šablony. Chcete-li například zobrazit ISBN, vytvořte sloupec a do pole šablony zadejte {identifiers:select(isbn)}. Chcete-li zobrazit sloupec obsahující hodnoty dvou vlastních sloupců série oddělené čárkou, použijte {#series1:||,}{#series2}.

Složené sloupce mohou používat libovolnou možnost šablony, včetně formátování.

Poznámka: Data zobrazená ve složeném sloupci nemůžete upravovat. Místo toho upravujete zdrojové sloupce. Pokud upravíte složený sloupec, například dvojitým kliknutím, calibre otevře k úpravám šablonu, ne podkladová data.

Šablony a zásuvné panely¶

Zásuvné panely se používají ke změně metadat zapisovaných do knih během operací odeslání do zařízení a uložení na disk. Zásuvný panel umožňuje zadat šablonu, která poskytne data zapisovaná do metadat knihy. Pomocí zásuvných panelů můžete upravit následující pole: authors, author_sort, language, publisher, tags, title, title_sort. Tato funkce pomáhá lidem, kteří chtějí v knihách na zařízeních používat jiná metadata kvůli řešení problémů s řazením nebo zobrazením.

Při vytváření zásuvného panelu určíte formát a zařízení, pro které se má zásuvný panel použít. K dispozici je speciální zařízení save_to_disk, které se používá při ukládání formátů (na rozdíl od jejich odesílání do zařízení). Jakmile zvolíte formát a zařízení, vyberete pole metadat, která se mají změnit, a zadáte šablony, které dodají nové hodnoty. Tyto šablony jsou připojeny ke svým cílovým polím, odtud název zásuvné panely. V těchto šablonách samozřejmě můžete používat složené sloupce.

Zásuvné panely jsou poměrně flexibilní a lze je psát v režimu jedné funkce, režimu programu šablony, obecném režimu programu nebo režimu pythonové šablony.

Když může být zásuvný panel použit (Server s obsahem, uložení na disk nebo odeslání do zařízení), calibre prohledá definované zásuvné panely a vybere správný pro daný formát a zařízení. Například při hledání vhodného zásuvného panelu pro knihu EPUB odesílanou do zařízení ANDROID calibre prohledá zásuvné panely v následujícím pořadí:

zásuvný panel s přesnou shodou formátu a zařízení, např. EPUB a ANDROID
zásuvný panel s přesnou shodou formátu a speciální volbou any device, např. EPUB a any device
zásuvný panel se speciální volbou any format a přesnou shodou zařízení, např. any format a ANDROID
zásuvný panel s any format a any device

Pole tags a authors mají speciální zpracování, protože obě tato pole mohou obsahovat více než jednu položku. Kniha může mít mnoho štítků a mnoho autorů. Když určíte, že se má jedno z těchto dvou polí změnit, výsledek šablony se zkontroluje, zda obsahuje více než jednu položku. U štítků se výsledek rozdělí všude, kde calibre najde čárku. Pokud například šablona vytvoří hodnotu Thriller, Horror, výsledkem budou dva štítky, Thriller a Horror. Čárku doprostřed štítku nelze vložit.

Totéž se děje u autorů, ale pro rozdělení se místo čárky používá jiný znak, & (ampersand). Pokud například šablona vytvoří hodnotu Blogs, Joe&Posts, Susan, kniha bude mít nakonec dva autory, Blogs, Joe a Posts, Susan. Pokud šablona vytvoří hodnotu Blogs, Joe;Posts, Susan, bude mít kniha jednoho autora s poměrně zvláštním jménem.

Zásuvné panely ovlivňují metadata zapisovaná do knihy při jejím uložení na disk nebo zápisu do zařízení. Zásuvné panely neovlivňují metadata, která save to disk a send to device používají k vytváření názvů souborů. Názvy souborů se místo toho sestavují pomocí šablon zadaných v příslušném okně předvoleb.

Použití funkcí v šablonách - Režim jedné funkce¶

Předpokládejme, že chcete zobrazit hodnotu pole velkými písmeny, zatímco běžně je toto pole ve formátu velkých počátečních písmen. To můžete udělat pomocí funkcí šablony. Chcete-li například zobrazit název velkými písmeny, použijte funkci uppercase jako v {title:uppercase()}. Chcete-li jej zobrazit s velkými počátečními písmeny, použijte {title:titlecase()}.

Funkce patří do formátovací části šablony, za : a před první | nebo před uzavírací }, pokud se nepoužívá předpona/přípona. Pokud máte současně formát i odkaz na funkci, funkce následuje za druhou :. Funkce vracejí hodnotu sloupce určeného ve vhodně upravené šabloně.

Syntaxe použití funkcí je jedna z následujících:

{lookup_name:function(arguments)}
{lookup_name:format:function(arguments)}
{lookup_name:function(arguments)|prefix|suffix}
{lookup_name:format:function(arguments)|prefix|suffix}

Za názvy funkcí musí vždy následovat otevírací a uzavírací závorka. Některé funkce vyžadují další hodnoty (argumenty) a ty se zapisují do závorek. Argumenty jsou oddělené čárkami. Doslovným čárkám (čárkám jako textu, ne jako oddělovačům argumentů) musí předcházet zpětné lomítko (\). Poslední (nebo jediný) argument nesmí obsahovat uzavírací závorku zadanou jako text.

Funkce se vyhodnocují před specifikacemi formátu a předponou/příponou. Níže najdete příklad použití formátu i funkce současně.

Důležité: Pokud máte zkušenosti s programováním, všimněte si, že syntaxe v režimu jedné funkce není taková, jakou byste očekávali. Řetězce se neuzavírají do uvozovek a mezery jsou významné. Všechny argumenty se považují za konstanty; neexistují zde žádné výrazy.

Nepoužívejte podšablony (`{ … }`) jako argumenty funkcí. Místo toho použijte režim programu šablony a obecný režim programu.

Poznámky k volání funkcí v režimu jedné funkce:

Při použití funkcí v režimu jedné funkce se první parametr, value, automaticky nahradí obsahem pole určeného v šabloně. Například při zpracování šablony {title:capitalize()} se obsah pole title předá funkci capitalize jako parametr value.
V dokumentaci funkcí zápis [something]* znamená, že something se může opakovat nula nebo vícekrát. Zápis [something]+ znamená, že se something opakuje jednou nebo vícekrát (musí existovat alespoň jednou).
Některé funkce využívají regulární výrazy. V jazyce šablon se při porovnávání regulárních výrazů nerozlišují velká a malá písmena.

Funkce jsou zdokumentovány v Referenční příručka funkcí šablon. Dokumentace uvádí, jaké argumenty funkce vyžadují a co funkce dělají. Například zde je dokumentace funkce ifempty.

ifempty(value, text_if_empty) – pokud value není prázdné, vrátí toto value, jinak vrátí text_if_empty.

Vidíte, že funkce vyžaduje dva argumenty, value a text_if_empty. Protože ale používáme režim jedné funkce, argument value vynecháme a předáme pouze text_if_empty. Například tato šablona:

{tags:ifempty(No tags on this book)}

zobrazí štítky knihy, pokud nějaké má. Pokud nemá žádné štítky, zobrazí No tags on this book.

Následující funkce lze použít v režimu jedné funkce, protože jejich prvním parametrem je value.

capitalize(value) – vrátí value s prvním písmenem velkým a zbytkem malými písmeny.
ceiling(value) – vrátí nejmenší celé číslo větší nebo rovné value.
cmp(value, y, lt, eq, gt) – porovná value a y po převodu obou hodnot na čísla.
contains(value, pattern, text_if_match, text_if_not_match) – zkontroluje, zda hodnota odpovídá regulárnímu výrazu pattern.
date_arithmetic(value, calc_spec, fmt) – vypočítá nové datum z value pomocí calc_spec.
encode_for_url(value, use_plus) – vrátí value zakódované pro použití v URL podle use_plus. Hodnota se nejdřív zakóduje pro URL. Potom, pokud je use_plus 0, jsou mezery nahrazeny znaménky '+' (plus). Pokud je 1, jsou mezery nahrazeny hodnotou %20.
floor(value) – vrátí největší celé číslo menší nebo rovné value.
format_date(value, format_string) – formátuje value, což musí být řetězec s datem, pomocí format_string a vrátí řetězec.
format_duration(value, template, [largest_unit]) – naformátuje hodnotu představující počet sekund jako řetězec zobrazující týdny, dny, hodiny, minuty a sekundy. Pokud je hodnota typu float, zaokrouhlí se na nejbližší celé číslo.
format_number(value, template) – interpretuje value jako číslo a toto číslo formátuje pomocí pythonové formátovací šablony, například {0:5.2f}, {0:,d} nebo ${0:5,.2f}.
fractional_part(value) – vrátí část hodnoty za desetinnou tečkou.
human_readable(value) – očekává, že value je číslo, a vrátí řetězec představující toto číslo v KB, MB, GB atd.
ifempty(value, text_if_empty) – pokud value není prázdné, vrátí toto value, jinak vrátí text_if_empty.
language_strings(value, localize) – vrátí názvy jazyků pro kódy jazyků (názvy a kódy najdete zde) předané v value.
list_contains(value, separator, [ pattern, found_val, ]* not_found_val) – interpretuje value jako seznam položek oddělených pomocí separator a porovnává pattern s každou položkou v seznamu.
list_count(value, separator) – interpretuje hodnotu jako seznam položek oddělených pomocí separator a vrátí počet položek v seznamu.
list_count_matching(value, pattern, separator) – interpretuje value jako seznam položek oddělených pomocí separator a vrátí počet položek v seznamu, které odpovídají regulárnímu výrazu pattern.
list_item(value, index, separator) – interpretuje value jako seznam položek oddělených pomocí separator a vrátí položku na pozici index.
list_sort(value, direction, separator) – vrátí value seřazené pomocí lexikálního řazení bez rozlišení velikosti písmen.
lookup(value, [ pattern, key, ]* else_key) – vzory se postupně zkontrolují proti value.
lowercase(value) – vrátí value malými písmeny.
mod(value, y) – vrátí floor zbytku po dělení value / y.
rating_to_stars(value, use_half_stars) – vrátí value jako řetězec tvořený znaky hvězdiček (★).
re(value, pattern, replacement) – vrátí value po použití regulárního výrazu.
re_group(value, pattern [, template_for_group]*) – vrátí řetězec vytvořený použitím regulárního výrazu pattern na value a nahrazením každého odpovídajícího výskytu
round(value) – vrátí celé číslo nejbližší hodnotě value.
select(value, key) – interpretuje value jako čárkami oddělený seznam položek, kde každá položka má tvar id:id_value (formát identifier v calibre).
shorten(value, left_chars, middle_text, right_chars) – vrátí zkrácenou verzi value
str_in_list(value, separator, [ string, found_val, ]+ not_found_val) – interpretuje value jako seznam položek oddělených pomocí separator a potom porovná string s každou hodnotou v seznamu.
subitems(value, start_index, end_index) – Tato funkce rozkládá seznamy hierarchických položek podobných štítkům, například žánrů.
sublist(value, start_index, end_index, separator) – interpretuje value jako seznam položek oddělených pomocí separator a vrátí nový seznam vytvořený z položek od start_index do end_index.
substr(value, start, end) – vrátí znaky value od start po end.
swap_around_articles(value, separator) – vrátí value s členy přesunutými na konec a oddělenými středníkem.
swap_around_comma(value) – při zadané hodnotě ve tvaru B, A vrátí A B.
switch(value, [patternN, valueN,]+ else_value) – pro každou dvojici patternN, valueN zkontroluje, zda value odpovídá regulárnímu výrazu patternN
test(value, text_if_not_empty, text_if_empty) – vrátí text_if_not_empty, pokud hodnota není prázdná, jinak vrátí text_if_empty.
titlecase(value) – vrátí value s velkými počátečními písmeny.
transliterate(value) – vrátí řetězec v latince vytvořený přibližným zvukovým přepisem slov v value.
uppercase(value) – vrátí value velkými písmeny.

Použití funkcí a formátování ve stejné šabloně

Předpokládejme, že máte celočíselný vlastní sloupec #myint, který chcete zobrazit s počátečními nulami, například jako 003. Jedním způsobem je použít formát 0>3s. Ve výchozím nastavení se však číslo (celé číslo nebo číslo s plovoucí desetinnou čárkou) rovné nule zobrazí jako prázdný řetězec, takže nulové hodnoty vytvoří prázdný řetězec, ne 000. Pokud chcete vidět hodnoty 000, použijte formátovací řetězec i funkci ifempty a změňte prázdnou hodnotu zpět na nulu. Šablona by byla:

{#myint:0>3s:ifempty(0)}

Všimněte si, že můžete použít také předponu a příponu. Pokud chcete, aby se číslo zobrazilo jako [003] nebo [000], použijte šablonu:

{#myint:0>3s:ifempty(0)|[|]}

Obecný režim programu¶

Obecný režim programu (GPM) nahrazuje výrazy šablony programem napsaným v jazyce šablon. Syntaxe jazyka je definována následující gramatikou:

program         ::= 'program:' expression_list
expression_list ::= top_expression [ ';' top_expression ]*
top_expression  ::= or_expression
or_expression   ::= and_expression [ '||' and_expression ]*
and_expression  ::= not_expression [ '&&' not_expression ]*
not_expression  ::= [ '!' not_expression ]* | concatenate_expr
concatenate_expr::= compare_expr [ '&' compare_expr ]*
compare_expr    ::= add_sub_expr [ compare_op add_sub_expr ]
compare_op      ::= '==' | '!=' | '>=' | '>' | '<=' | '<' |
                    'in' | 'inlist' | 'inlist_field' |
                    '==#' | '!=#' | '>=#' | '>#' | '<=#' | '<#'
add_sub_expr    ::= times_div_expr [ add_sub_op times_div_expr ]*
add_sub_op      ::= '+' | '-'
times_div_expr  ::= unary_op_expr [ times_div_op unary_op_expr ]*
times_div_op    ::= '*' | '/'
unary_op_expr   ::= [ add_sub_op unary_op_expr ]* | expression
expression      ::= identifier | constant | function | assignment | field_reference |
                    if_expr | for_expr | break_expr | continue_expr | return_stmt
                    '(' expression_list ')' | function_def
field_reference ::= '$' [ '$' ] [ '#' ] identifier
identifier      ::= id_start [ id_rest ]*
id_start        ::= letter | underscore
id_rest         ::= id_start | digit
constant        ::= " string " | ' string ' | number
function        ::= identifier '(' expression_list [ ',' expression_list ]* ')'
function_def    ::= 'def' identifier '(' top_expression [ ',' top_expression ]* ')' ':'
                    expression_list 'fed'
assignment      ::= identifier '=' top_expression
if_expr         ::= 'if' condition 'then' expression_list
                    [ elif_expr ] [ 'else' expression_list ] 'fi'
condition       ::= top_expression
elif_expr       ::= 'elif' condition 'then' expression_list elif_expr | ''
for_expr        ::= for_list | for_range
for_list        ::= 'for' identifier 'in' list_expr
                    [ 'separator' separator_expr ] ':' expression_list 'rof'
for_range       ::= 'for' identifier 'in' range_expr ':' expression_list 'rof'
range_expr      ::= 'range' '(' [ start_expr ',' ] stop_expr
                    [ ',' step_expr [ ',' limit_expr ] ] ')'
with_expr       ::= 'with' top_expression ':' expression_list 'htiw'
list_expr       ::= top_expression
break_expr      ::= 'break'
continue_expr   ::= 'continue'
return_stmt     ::= 'return' top_expression
separator_expr  ::= top_expression
start_expr      ::= top_expression
stop_expr       ::= top_expression
step_expr       ::= top_expression
limit_expr      ::= top_expression

Poznámky:

top_expression má vždy hodnotu. Hodnota expression_list je hodnota posledního top_expression v seznamu. Například hodnota seznamu výrazů 1;2;'foobar';3 je 3.
V logickém kontextu je každá neprázdná hodnota True
V logickém kontextu je prázdná hodnota False
Řetězce a čísla lze používat zaměnitelně. Například 10 a '10' jsou totéž.
Komentáře jsou řádky začínající znakem „#“, kterému mohou předcházet mezery nebo tabulátory.

Priorita operátorů

Priorita operátorů (pořadí vyhodnocení) od nejvyšší (vyhodnocuje se jako první) po nejnižší (vyhodnocuje se jako poslední) je:

Volání funkcí, konstanty, výrazy v závorkách, výrazy příkazů, přiřazovací výrazy, odkazy na pole.
Unární plus (+) a minus (-). Tyto operátory se vyhodnocují zprava doleva.

Tyto i všechny ostatní aritmetické operátory vracejí celá čísla, pokud výsledkem výrazu je desetinná část rovná nule. Pokud například výraz vrátí 3.0, změní se na 3.
Násobení (*) a dělení (/). Tyto operátory jsou asociativní a vyhodnocují se zleva doprava. Pokud chcete změnit pořadí vyhodnocení, použijte závorky.
Sčítání (+) a odčítání (-). Tyto operátory jsou asociativní a vyhodnocují se zleva doprava.
Číselná a řetězcová porovnání. Tyto operátory vracejí '1', pokud je porovnání úspěšné, jinak prázdný řetězec (''). Porovnání nejsou asociativní: a < b < c je syntaktická chyba.
Zřetězení řetězců (&). Operátor & vrací řetězec vytvořený zřetězením levého a pravého výrazu. Příklad: 'aaa' & 'bbb' vrátí 'aaabbb'. Operátor je asociativní a vyhodnocuje se zleva doprava.
Unární logické ne (!). Tento operátor vrací '1', pokud je výraz False (vyhodnotí se jako prázdný řetězec), jinak vrací ''.
Logické a (&&). Tento operátor vrací ‚1‘, pokud jsou levý i pravý výraz True, nebo prázdný řetězec '', pokud je kterýkoli z nich False. Je asociativní, vyhodnocuje se zleva doprava a používá zkratové vyhodnocování.
Logické nebo (||). Tento operátor vrací '1', pokud je levý nebo pravý výraz True, nebo '', pokud jsou oba False. Je asociativní, vyhodnocuje se zleva doprava a používá zkratové vyhodnocování. Je to inkluzivní nebo, které vrací '1', pokud jsou levý i pravý výraz True.

Odkazy na pole

field_reference se vyhodnotí jako hodnota pole metadat určeného názvem vyhledávání, který následuje za $ nebo $$. Použití $ je ekvivalentní použití funkce field. Použití $$ je ekvivalentní použití funkce raw_field. Příklady:

* $authors ==> field('authors')
* $#genre ==> field('#genre')
* $$pubdate ==> raw_field('pubdate')
* $$#my_int ==> raw_field('#my_int')

Výrazy if

Výrazy if nejprve vyhodnotí condition. Pokud je condition True (neprázdná hodnota), vyhodnotí se expression_list ve větvi then. Pokud je False, vyhodnotí se, pokud existuje, expression_list ve větvi elif nebo else. Části elif a else jsou volitelné. Slova if, then, elif, else a fi jsou rezervovaná; nemůžete je použít jako názvy identifikátorů. Nové řádky a bílé znaky můžete vložit všude, kde dávají smysl. condition je top_expression, ne expression_list; středníky nejsou povoleny. expression_lists jsou sekvence top_expressions oddělené středníky. Výraz if vrátí výsledek posledního top_expression ve vyhodnoceném expression_list nebo prázdný řetězec, pokud nebyl vyhodnocen žádný seznam výrazů.

Příklady:

* program: if field('series') then 'yes' else 'no' fi
* program:
      if field('series') then
          a = 'yes';
          b = 'no'
      else
          a = 'no';
          b = 'yes'
      fi;
      strcat(a, '-', b)

Příklad vnořeného if:

program:
  if field('series') then
    if check_yes_no(field('#mybool'), '', '', '1') then
      'yes'
    else
      'no'
    fi
  else
    'no series'
  fi

Jak bylo uvedeno výše, if produkuje hodnotu. To znamená, že všechny následující zápisy jsou ekvivalentní:

* program: if field('series') then 'foo' else 'bar' fi
* program: if field('series') then a = 'foo' else a = 'bar' fi; a
* program: a = if field('series') then 'foo' else 'bar' fi; a

Například tento program vrátí hodnotu sloupce series, pokud má kniha sérii, jinak hodnotu sloupce title:

program: field(if field('series') then 'series' else 'title' fi)

Výrazy for

Výraz for iteruje přes seznam hodnot a zpracovává je po jedné. list_expression se musí vyhodnotit buď jako název vyhledávání pole metadat, např. tags nebo #genre, nebo jako seznam hodnot. range generuje seznam čísel. Pokud je výsledkem platný název vyhledávání, načte se hodnota pole a použije se oddělovač určený pro tento typ pole. Pokud výsledkem není platný název vyhledávání, předpokládá se, že jde o seznam hodnot. Předpokládá se, že seznam je oddělen čárkami, pokud není zadáno volitelné klíčové slovo separator; v takovém případě musí být hodnoty seznamu odděleny výsledkem vyhodnocení separator_expr. Oddělovač nelze použít, pokud seznam generuje range(). Každá hodnota v seznamu se přiřadí zadané proměnné a potom se vyhodnotí expression_list. Pomocí break můžete vyskočit ze smyčky a pomocí continue přejít na začátek smyčky pro další iteraci.

Příklad: Tato šablona odebere z každé hodnoty pole Žánr (#genre) první úroveň hierarchického názvu a vytvoří seznam s novými názvy:

program:
  new_tags = '';
  for i in '#genre':
    j = re(i, '^.*?\.(.*)$', '\1');
    new_tags = list_union(new_tags, j, ',')
  rof;
  new_tags

Pokud je původní Žánr History.Military, Science Fiction.Alternate History, ReadMe, šablona vrátí Military, Alternate History, ReadMe. Tuto šablonu můžete v calibre použít v Upravit metadata hromadně → Hledat a nahradit s položkou Hledat nastavenou na template k odstranění první úrovně hierarchie a přiřazení výsledné hodnoty do pole Žánr.

Poznámka: poslední řádek v šabloně, new_tags, není v tomto případě nezbytně nutný, protože for vrací hodnotu posledního výrazu top_expression v seznamu výrazů. Hodnotou přiřazení je hodnota jeho výrazu, takže hodnota příkazu for je to, co bylo přiřazeno do new_tags.

Výrazy with

Výraz with:

změní aktuální knihu na knihu s ID knihy v calibre (celé číslo) získaným vyhodnocením top_expression.
provede expression_list.
potom znovu nastaví jako aktuální původní knihu.

Výraz with vrátí výsledek posledního top_expression ve vyhodnoceném expression_list nebo prázdný řetězec, pokud nebyl vyhodnocen žádný seznam výrazů.

Například tato šablona vrátí seznam názvů všech knih vybraných v GUI:

program:
  res = '';
  ids = selected_books();
  for id in ids:
      with id:
          res = (if res then res & ', ' fi) & $title
      htiw
  rof;
  res

Příkaz return

Vrátí hodnotu výrazu expression. Pokud se provede ve funkci, vrátí hodnotu výrazu volajícímu. Pokud se provede v nejvnějším kontextu (v šabloně), nastaví hodnotu šablony na hodnotu výrazu a šablonu ukončí.

Definice funkce

Pokud máte v šabloně opakovaný kód, můžete tento kód vložit do lokální funkce. Klíčové slovo def zahajuje definici. Za ním následuje název funkce, seznam argumentů a potom kód funkce. Definice funkce končí klíčovým slovem fed.

Argumenty jsou poziční. Při volání funkce se dodané argumenty párují zleva doprava s definovanými parametry a hodnota argumentu se přiřadí parametru. Zadání většího počtu argumentů, než je definovaných parametrů, je chyba. Parametry mohou mít výchozí hodnoty, například a = 25. Pokud pro daný parametr není argument zadán, použije se výchozí hodnota; pokud žádná výchozí hodnota není, parametr se nastaví na prázdný řetězec.

Příkaz return lze použít v lokální funkci.

Funkce musí být definována předtím, než ji lze použít.

Příklad: Tato šablona vypočítá z počtu dnů přibližnou dobu trvání v letech, měsících a dnech. Funkce to_plural() formátuje vypočtené hodnoty. Všimněte si, že příklad používá také operátor &:

program:
      days = 2112;
      years = floor(days/360);
      months = floor(mod(days, 360)/30);
      days = days - ((years*360) + (months * 30));

      def to_plural(v, str):
              if v == 0 then return '' fi;
              return v & ' ' & (if v == 1 then str else str & 's' fi) & ' '
      fed;

      to_plural(years, 'year') & to_plural(months, 'month') & to_plural(days,'day')

Relační operátory

Relační operátory vracejí '1', pokud je porovnání pravdivé, jinak vracejí prázdný řetězec ('').

Existují dvě formy relačních operátorů: řetězcová porovnání a číselná porovnání.

Řetězcová porovnání porovnávají řetězce v lexikálním pořadí bez rozlišení velikosti písmen. Podporované operátory řetězcového porovnání jsou ==, !=, <, <=, >, >=, in, inlist a inlist_field. U operátorů in, inlist a inlist_field se výsledek levého výrazu interpretuje jako vzor regulárního výrazu. Tyto operátory jsou pravdivé, pokud regulární výraz z levé strany odpovídá hodnotě pravého výrazu. Regulární výrazy nerozlišují velikost písmen.

Operátor inlist je pravdivý, pokud regulární výraz na levé straně odpovídá kterékoli položce v seznamu na pravé straně, kde jsou položky seznamu odděleny čárkami. Operátor inlist_field je pravdivý, pokud regulární výraz na levé straně odpovídá kterékoli položce v poli (sloupci) pojmenovaném pravým výrazem, přičemž se použije oddělovač definovaný pro dané pole. Poznámka: operátor inlist_field vyžaduje, aby se pravý výraz vyhodnotil na název pole, zatímco operátor inlist vyžaduje, aby se pravý výraz vyhodnotil na řetězec obsahující seznam oddělený čárkami. Kvůli tomuto rozdílu je inlist_field podstatně rychlejší než inlist, protože se neprovádějí žádné převody na řetězce ani vytváření seznamů.

Operátory číselného porovnání jsou ==#, !=#, <#, <=#, ># a >=#. Levý a pravý výraz se musí vyhodnotit na číselné hodnoty se dvěma výjimkami: řetězcová hodnota „None“ (nedefinované pole) i prázdný řetězec se vyhodnotí na hodnotu nula.

Příklady:

program: field('series') == 'foo' vrátí '1', pokud je série knihy foo, jinak ''.

program: 'f.o' in field('series') vrátí '1', pokud série knihy odpovídá regulárnímu výrazu f.o (např. foo, Off Onyx atd.), jinak ''.

program: 'science' inlist $#genre vrátí '1', pokud některá z hodnot získaných ze žánrů knihy odpovídá regulárnímu výrazu science, např. Science, History of Science, Science Fiction atd., jinak ''.

program: '^science$' inlist $#genre vrátí '1', pokud některý ze žánrů knihy přesně odpovídá regulárnímu výrazu ^science$, např. Science, jinak ''. Žánry History of Science a Science Fiction neodpovídají.

program: 'asimov' inlist $authors vrátí '1', pokud některý autor odpovídá regulárnímu výrazu asimov, např. Asimov, Isaac nebo Isaac Asimov, jinak ''.

program: 'asimov' inlist_field 'authors' vrátí '1', pokud některý autor odpovídá regulárnímu výrazu asimov, např. Asimov, Isaac nebo Isaac Asimov, jinak ''.

program: 'asimov$' inlist_field 'authors' vrátí '1', pokud některý autor odpovídá regulárnímu výrazu asimov$, např. Isaac Asimov, jinak ''. Hodnota Asimov, Isaac neodpovídá kvůli kotvě $ v regulárním výrazu.

program: if field('series') != 'foo' then 'bar' else 'mumble' fi vrátí 'bar', pokud série knihy není foo. Jinak vrátí 'mumble'.

program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi vrátí 'yes', pokud je série buď foo, nebo 1632, jinak 'no'.

program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi vrátí 'yes', pokud je série buď foo, nebo 1632, jinak 'no'.

program: if 11 > 2 then 'yes' else 'no' fi vrátí 'no', protože operátor > provádí lexikální porovnání.

program: if 11 ># 2 then 'yes' else 'no' fi vrátí 'yes', protože operátor ># provádí číselné porovnání.

Funkce v obecném režimu programu

Seznam funkcí zabudovaných do jazyka šablon najdete v sekci Referenční příručka funkcí šablon.

Poznámky:

Na rozdíl od režimu jedné funkce musíte v obecném režimu programu zadat první parametr value.
Všechny parametry jsou seznamy výrazů (expression_lists; viz gramatika výše).

Složitější programy ve výrazech šablony - Režim programu šablony¶

Režim programu šablony (TPM) je kombinací obecného režimu programu a režimu jedné funkce. TPM se od režimu jedné funkce liší tím, že umožňuje psát výrazy šablony, které odkazují na jiná pole metadat, používají vnořené funkce, mění proměnné a provádějí aritmetiku. Od obecného režimu programu se liší tím, že šablona je uzavřena mezi znaky { a } a nezačíná slovem program:. Programová část šablony je seznam výrazů obecného režimu programu.

Příklad: předpokládejme, že chcete, aby šablona zobrazila sérii knihy, pokud ji kniha má, jinak aby zobrazila hodnotu vlastního pole #genre. V režimu jedné funkce to nemůžete udělat, protože ve výrazu šablony nelze odkazovat na jiné pole metadat. V TPM to možné je, jak ukazuje následující výraz:

{series:'ifempty($, $#genre)'}

Příklad ukazuje několik věcí:

TPM se použije, pokud výraz začíná :' a končí '}. U všeho ostatního se předpokládá, že jde o režim jedné funkce.

Pokud šablona obsahuje předponu a příponu, výraz končí '|, kde | je oddělovač předpony. Příklad:
```
{series:'ifempty($, $#genre)'|prefix | suffix}
```
Funkcím musí být předány všechny jejich argumenty. Například standardním vestavěným funkcím musí být předán první parametr value.
Proměnnou $ lze použít jako argument value a představuje hodnotu pole pojmenovaného v šabloně, v tomto případě series.
bílé znaky jsou ignorovány a lze je použít kdekoli uvnitř výrazu.
konstantní řetězce se uzavírají do párových uvozovek, buď ', nebo ".

V TPM může použití znaků { a } v řetězcových literálech vést k chybám nebo neočekávaným výsledkům, protože matou zpracovatele šablon. Ten se je pokouší vykládat jako hranice výrazů šablony, ne jako samotné znaky. V některých případech, ale ne ve všech, můžete { nahradit [[ a } nahradit ]]. Doporučení: pokud váš program obsahuje znaky { a }, měli byste použít obecný režim programu.

Režim pythonové šablony¶

Režim pythonové šablony (PTM) umožňuje psát šablony pomocí nativního Pythonu a API calibre. Nejvíce se uplatní databázové API; další výklad je mimo rozsah této příručky. Šablony PTM jsou rychlejší a zvládnou složitější operace, ale musíte umět psát kód v Pythonu s využitím API calibre.

Šablona PTM začíná takto:

python:
def evaluate(book, context):
    # book is a calibre metadata object
    # context is an instance of calibre.utils.formatter.PythonTemplateContext,
    # which currently contains the following attributes:
    # db: a calibre legacy database object.
    # globals: the template global variable dictionary.
    # arguments: is a list of arguments if the template is called by a GPM template, otherwise None.
    # funcs: used to call Built-in/User functions and Stored GPM/Python templates.
    # Example: context.funcs.list_re_group()

    # your Python code goes here
    return 'a string'

Výše uvedený text můžete do šablony přidat pomocí místní nabídky, která se obvykle otevře kliknutím pravým tlačítkem myši. Komentáře nejsou pro funkci šablony podstatné a lze je odstranit. Musíte používat odsazení podle pravidel Pythonu.

Objekt context podporuje volání str(context), které vrací řetězec s obsahem objektu context, a vlastnost context.attributes, která vrací seznam názvů atributů v objektu context.

Atribut context.funcs umožňuje volat vestavěné a uživatelské funkce šablon a uložené šablony GPM/Python, takže je můžete spouštět přímo ve svém kódu. Funkce se získávají podle svého názvu. Pokud je název v konfliktu s klíčovým slovem Pythonu, přidejte na konec názvu podtržítko. Příklady:

context.funcs.list_re_group()
context.funcs.assert_()

Zde je příklad šablony PTM, která vytvoří seznam všech autorů pro danou sérii. Seznam je uložen ve sloupci Sloupec sestavený z jiných sloupců, chová se jako štítky. Tento sloupec se zobrazuje v Podrobnosti o knize a má zaškrtnutou volbu na oddělených řádcích (v Předvolby → Vzhled a chování → Podrobnosti o knize). Tato volba vyžaduje, aby byl seznam oddělený čárkami. Aby šablona tento požadavek splnila, převádí čárky ve jménech autorů na středníky a potom vytvoří seznam autorů oddělený čárkami. Autoři se potom seřadí, proto šablona používá author_sort.

python:
def evaluate(book, context):
    if book.series is None:
        return ''
    db = context.db.new_api
    ans = set()
    # Get the list of books in the series
    ids = db.search(f'series:"={book.series}"', '')
    if ids:
        # Get all the author_sort values for the books in the series
        author_sorts = (v for v in db.all_field_for('author_sort', ids).values())
        # Add the names to the result set, removing duplicates
        for aus in author_sorts:
            ans.update(v.strip() for v in aus.split('&'))
    # Make a sorted comma-separated string from the result set
    return ', '.join(v.replace(',', ';') for v in sorted(ans))

Výstup v Podrobnosti o knize vypadá takto:

Šablony a URL¶

Šablony můžete použít k sestavování adres URL. Zde jsou popsány dva případy:

Vyhledávací URL vlastního sloupce v Podrobnosti o knize
Schéma URL calibre

Vyhledávací URL vlastního sloupce v Podrobnostech o knize

Při vytváření vlastního sloupce můžete pomocí šablony zadat adresu URL, která se použije v Podrobnosti o knize. Pokud máte například vlastní sloupec Překladatelé, můžete definovat adresu URL, která otevře web pro překladatele. Vyhledávací URL v Podrobnostech o knize lze zadat pro typy sloupců Text, Text s pevnou sadou povolených hodnot, Série a Sloupec sestavený z jiných sloupců.

Když v Podrobnosti o knize kliknete na položku s vyhledávací šablonou, šablona se vyhodnotí. Šabloně se předají běžná metadata knihy a také tři další pole:

item_value: hodnota položky, na kterou bylo kliknuto.
item_value_quoted: hodnota položky, na kterou bylo kliknuto, zakódovaná pro URL. Speciální znaky jsou zakódovány tak, aby byly v URL platné, a mezery jsou nahrazeny znaky '+' (znaménko plus).
item_value_no_plus: hodnota položky, na kterou bylo kliknuto, zakódovaná pro URL. Speciální znaky jsou zakódovány tak, aby byly v URL platné, a mezery jsou nahrazeny hodnotou %20, nikoli znaménkem plus.

URL lze sestavit několika způsoby. Následující příklady používají Wikipedii.

Nejjednodušší je základní šablona:

https://en.wikipedia.org/w/index.php?search={item_value_encoded}

V některých případech můžete chtít provést další zpracování. Podle složitosti zpracování můžete použít čtyři funkce šablon.

make_url(path, [query_name, query_value]+) – tato funkce je nejsnazší způsob, jak sestavit URL s dotazem. Používá path, web a stránku, na které se chcete dotazovat, a dvojice query_name, query_value, ze kterých se dotaz sestaví. Obecně musí být query_value zakódováno pro URL. U této funkce je zakódováno vždy a mezery jsou vždy nahrazeny znaménky '+'.
make_url_extended(...) – tato funkce se podobá funkci make_url(), ale dává vám větší kontrolu nad komponentami URL. Komponenty URL jsou

schéma:://autorita/cesta?řetězec dotazu.

Další podrobnosti najdete na Wikipedii v článku Uniform Resource Locator.

Funkce má dvě varianty:
```
make_url_extended(scheme, authority, path, [query_name, query_value]+)
```
a
```
make_url_extended(scheme, authority, path, query_string)
```
query_string([query_name, query_value, how_to_encode]+)– vrátí řetězec dotazu URL sestavený z trojic query_name, query_value, how_to_encode. Řetězec dotazu je řada položek, kde každá položka vypadá jako query_name=query_value a query_value je podle pokynů zakódováno pro URL. Položky dotazu jsou odděleny znaky '&' (ampersand).
encode_for_url(value, use_plus) – vrátí value zakódované pro použití v URL podle use_plus. Hodnota se nejdřív zakóduje pro URL. Potom, pokud je use_plus 0, jsou mezery nahrazeny znaménky '+' (plus). Pokud je 1, jsou mezery nahrazeny hodnotou %20.

Předpokládejme například, že máte vlastní sloupec Překladatelé (#translators), ve kterém jsou jména ve tvaru Příjmení, jméno. Při vytváření URL možná budete potřebovat převést jméno do tvaru Jméno Příjmení. K tomu můžete použít funkci make_url:

program: make_url('https://en.wikipedia.org/w/index.php', 'search', swap_around_comma($item_value))

Pokud předpokládáme, že jméno překladatele je Boy-Żeleński, Tadeusz, pak výše uvedená šablona vytvoří odkaz:

https://en.wikipedia.org/w/index.php?search=Tadeusz+Boy-%C5%BBele%C5%84ski

Všimněte si, že křestní jméno osoby je nyní na prvním místě, mezera je nyní znaménkem plus a znaky mimo angličtinu v příjmení jsou zakódované pro URL.

Funkce make_url_extended, query_string a encode_for_url mohou být užitečné podle toho, jak složité další zpracování potřebujete.

Schéma URL calibre

Calibre podporuje několik různých adres URL pro navigaci v knihovnách calibre. Tato část ukazuje, jak pomocí šablon sestavit některé z těchto adres URL. Podrobnosti o dostupných adresách URL najdete v calibre:// URL schéma.

Přepnutí na konkrétní knihovnu. Syntaxe této URL je:
```
calibre://switch-library/Library_Name
```
Library_Name je třeba nahradit názvem knihovny calibre, kterou chcete otevřít. Název knihovny je zobrazen v záhlaví okna. Jde o jednoduchý název, nikoli o cestu ke knihovně. Musíte ho zapsat tak, jak je zobrazen v záhlaví okna, včetně velikosti písmen. Znak _ (podtržítko) označuje aktuální knihovnu. Pokud název obsahuje mezery nebo speciální znaky, musí být hexadecimálně zakódován pomocí funkce to_hex, jako v následujícím příkladu:
```
program: strcat('calibre://switch-library/_hex_-', to_hex(current_library_name()))
```
Šablona vygeneruje URL:
```
calibre://switch-library/_hex_-4c6962726172792e746573745f736d616c6c
```
Funkci current_library_name() můžete nahradit skutečným názvem knihovny, například:
```
program: strcat('calibre://switch-library/_hex_-', to_hex('Library.test_small'))
```
Odkazy pro zobrazení knih. Tyto odkazy vyberou knihu v knihovně calibre. Syntaxe této URL je:
```
calibre://show-book/Library_Name/book_id
```
book id je číselné ID knihy v calibre, dostupné šablonám jako $id. Stejně jako výše může být nutné název knihovny hexadecimálně zakódovat. Zde je příklad:
```
program: strcat('calibre://show-book/_hex_-', to_hex(current_library_name()), '/', $id)
```
Vytvoří URL:
```
calibre://show-book/_hex_-4c6962726172792e746573745f736d616c6c/1353
```
Vyhledávání knih. Tyto odkazy vyhledají knihy v zadané knihovně calibre. Syntaxe této URL je:
```
calibre://search/Library_Name?q=query
calibre://search/Library_Name?eq=hex_encoded_query
```
kde query je libovolný platný vyhledávací výraz calibre. Každý dotaz obsahující mezery nebo speciální znaky musíte hexadecimálně zakódovat, což obecně znamená všechny dotazy. Například vyhledávací výraz calibre pro hledání hierarchického štítku začínajícího na ‚AA‘ je tags:"=.AA". Tato šablona sestaví vyhledávací URL pro tento výraz:
```
program: strcat('calibre://search/_hex_-', to_hex(current_library_name()), '?eq=', to_hex('tags:"=.AA"'))
```
Výsledná URL je:
```
calibre://search/_hex_-4c6962726172792e746573745f736d616c6c?eq=746167733a223d2e414122
```
Zde je příklad stejné URL sestavené pomocí funkce make_url_extended místo strcat:
```
program: make_url_extended('calibre', '', 'search/_hex_-' & to_hex(current_library_name()),
                           'eq', to_hex('tags:"=.AA"'))
```

Otevření okna Podrobnosti o knize pro knihu v některé knihovně. Syntaxe této URL je:

calibre://book-details/Library_Name/book_id

Ukázková šablona je:

program: strcat('calibre://book-details/_hex_-', to_hex(current_library_name()), '/', $id)

která vytvoří URL:

calibre://book-details/_hex_-4c6962726172792e746573745f736d616c6c/1353

Otevření poznámek přidružených k autorovi, sérii atd. Syntaxe URL je:
```
calibre://book-details/Library_Name/Field_Name/id_Item_Id
calibre://book-details/Library_Name/Field_Name/hex_Hex_Encoded_Item_Name
```
Field_Name je název vyhledávání daného pole. Pokud je pole vlastním sloupcem, nahraďte znak # podtržítkem (_). Item_Id je interní číselné ID hodnoty v poli. Neexistuje funkce šablony, která by vracela Item_Id, takže šablony obvykle použijí druhou podobu, Hex_Encoded_Item_Name. Zde je ukázková šablona, která otevře poznámku pro osobu Boy-Żeleński, Tadeusz v poli #authtest:
```
program: strcat('calibre://show-note/_hex_-', to_hex(current_library_name()),
                '/_authtest/hex_', to_hex('Boy-Żeleński, Tadeusz'))
```
která vytvoří URL:
```
calibre://show-note/_hex_-4c6962726172792e746573745f736d616c6c/_authtest/hex_426f792dc5bb656c65c584736b692c205461646575737a
```

Uložené šablony¶

Jak obecný režim programu, tak režim pythonové šablony podporují ukládání šablon a volání těchto šablon z jiné šablony, podobně jako při volání uložených funkcí. Šablony ukládáte pomocí Předvolby → Rozšířené → Funkce šablony. Další informace jsou uvedeny v tomto dialogu. Šablonu voláte stejně jako funkci a podle potřeby jí předáváte poziční argumenty. Argumentem může být libovolný výraz. Příklady volání šablony za předpokladu, že uložená šablona se jmenuje foo:

foo() – zavolá šablonu bez předání argumentů.
foo(a, b) zavolá šablonu a předá jí hodnoty dvou proměnných a a b.
foo(if field('series') then field('series_index') else 0 fi) – pokud má kniha hodnotu v poli series, předá se series_index, jinak se předá hodnota 0.

V GPM načtete argumenty předané při volání uložené šablony pomocí funkce arguments. Ta zároveň deklaruje a inicializuje lokální proměnné, fakticky tedy parametry. Proměnné jsou poziční; získají hodnotu argumentu zadaného ve volání na stejné pozici. Pokud odpovídající argument ve volání zadán není, funkce arguments přiřadí této proměnné zadanou výchozí hodnotu. Pokud výchozí hodnota neexistuje, proměnná se nastaví na prázdný řetězec. Například následující funkce arguments deklaruje dvě proměnné, key a alternate:

arguments(key, alternate='series')

Příklady, opět za předpokladu, že uložená šablona se jmenuje foo:

foo('#myseries') – proměnné key se přiřadí hodnota '#myseries' a proměnné alternate výchozí hodnota 'series'.
foo('series', '#genre') proměnné key se přiřadí hodnota 'series' a proměnné alternate hodnota '#genre'.
foo() – proměnné key se přiřadí prázdný řetězec a proměnné alternate hodnota 'series'.

V PTM se argumenty předávají v atributu arguments, což je seznam řetězců. Výchozí hodnoty nelze nijak zadat. Musíte zkontrolovat délku seznamu arguments, abyste měli jistotu, že počet argumentů odpovídá tomu, co očekáváte.

Uložené šablony lze snadno testovat pomocí dialogu Testovač šablon. Pro snadný přístup mu přiřaďte klávesovou zkratku v Předvolby → Rozšířené → Klávesové zkratky → Testovač šablon. Přiřazení zkratky dialogu Uložené šablony vám pomůže rychleji přepínat mezi testovačem a úpravami zdrojového kódu uložené šablony.

Předávání dodatečných informací šablonám¶

Vývojář může zpracovateli šablon předat dodatečné informace, například metadata knih specifická pro aplikaci nebo informace o tom, co je po zpracovateli požadováno. Šablona k těmto informacím může přistupovat a použít je během vyhodnocování.

Vývojář: jak předat dodatečné informace

Dodatečné informace jsou slovník Pythonu obsahující dvojice variable_name: variable_value, kde hodnoty musí být řetězce. Šablona může ke slovníku přistupovat tak, že vytvoří lokální proměnné šablony s názvem variable_name obsahující hodnotu variable_value. Uživatel název nemůže změnit, proto je nejlepší použít názvy, které nebudou kolidovat s jinými lokálními proměnnými šablony, například přidáním podtržítka na začátek názvu.

Tento slovník se předává zpracovateli šablon (formatter) pomocí pojmenovaného parametru global_vars=your_dict. Úplná signatura metody je:

def safe_format(self, fmt, kwargs, error_value, book,
                column_name=None, template_cache=None,
                strip_results=True, template_functions=None,
                global_vars={})

Autor šablony: jak přistupovat k dodatečným informacím

K dodatečným informacím (slovníku globals) v šabloně přistupujete pomocí funkce šablony:

globals(id[=expression] [, id[=expression]]*)

kde id je libovolný platný název proměnné. Tato funkce zkontroluje, zda dodatečné informace poskytnuté vývojářem obsahují daný název. Pokud ano, funkce přiřadí poskytnutou hodnotu lokální proměnné šablony s tímto názvem. Pokud název v dodatečných informacích není a je zadán expression, vyhodnotí se expression a výsledek se přiřadí lokální proměnné. Pokud není zadána ani hodnota, ani výraz, funkce přiřadí lokální proměnné prázdný řetězec ('').

Šablona může nastavit hodnotu ve slovníku globals pomocí funkce šablony:

set_globals(id[=expression] [, id[=expression]]*)

Tato funkce nastaví ve slovníku globals dvojici klíč:hodnota id:value, kde value je hodnota lokální proměnné šablony id. Pokud tato lokální proměnná neexistuje, nastaví se value na výsledek vyhodnocení expression.

Poznámky k rozdílům mezi režimy¶

Tři režimy programu, režim jedné funkce (SFM), režim programu šablony (TPM) a obecný režim programu (GPM), fungují odlišně. SFM má být „jednoduchý“, proto skrývá mnoho částí programovacího jazyka.

Rozdíly:

V SFM se hodnota sloupce vždy předává jako „neviditelný“ první argument funkci obsažené v šabloně.
SFM nerozlišuje mezi proměnnými a řetězci; všechny hodnoty jsou řetězce.
Následující šablona SFM vrátí buď název série, nebo řetězec „no series“:
```
{series:ifempty(no series)}
```
Ekvivalentní šablona v TPM je
```
{series:'ifempty($, 'no series')'}
```
V GPM by to vypadalo takto:
```
program: ifempty(field('series'), 'no series')
```
První argument funkce ifempty je hodnota pole series. Druhý argument je řetězec no series. V SFM se první argument, hodnota pole, předává automaticky (neviditelný argument).
Několik funkcí šablony, například booksize() a current_library_name(), nepřijímá žádné argumenty. Kvůli „neviditelnému argumentu“ tyto funkce nelze v SFM použít.
Vnořené funkce, kdy funkce volá jinou funkci pro výpočet argumentu, nelze v SFM použít. Například tato šablona, která má vrátit prvních 5 znaků hodnoty série převedených na velká písmena, nebude v SFM fungovat:
```
{series:uppercase(substr(0,5))}
```
TPM a GPM podporují vnořené funkce. Výše uvedená šablona v TPM by vypadala takto:
```
{series:'uppercase(substr($, 0,5))'}
```
V GPM by to vypadalo takto:
```
program: uppercase(substr(field('series'), 0,5))
```
Jak je uvedeno výše v části režim programu šablony, použití znaků { a } v řetězcových literálech TPM může vést k chybám nebo neočekávaným výsledkům, protože matou zpracovatele šablon. Ten se je pokouší zpracovat jako hranice šablony, ne jako znaky. V některých případech, ale ne ve všech, můžete { nahradit [[ a } nahradit ]]. Obecně platí, že pokud váš program obsahuje znaky { a }, měli byste použít obecný režim programu.

Uživatelsky definované pythonové funkce šablon¶

Do zpracovatele šablon můžete přidat vlastní pythonové funkce. Takové funkce lze použít v kterémkoliv ze tří programovacích režimů šablon. Funkce se přidávají v Předvolby → Rozšířené → Funkce šablony. Pokyny jsou uvedeny v tomto dialogu. Všimněte si, že k podobnému účelu můžete použít také pythonové šablony. Protože volání uživatelsky definovaných funkcí je rychlejší než volání pythonové šablony, mohou být uživatelsky definované funkce efektivnější v závislosti na složitosti toho, co funkce nebo šablona dělá.

Speciální poznámky k používání šablon v různých kontextech¶

V GUI (Sloupce sestavené z jiných sloupců a Vyhledávání pomocí šablon):

Šablony GPM fungují stejně jako dříve.
Pythonové šablony mají plný přístup k databázi calibre.

V pravidlech ikon:

Šablony pravidel ikon nemají k dispozici data knihy, takže funkce založené na polích, jako jsou format_date_field, list_count_field a check_yes_no, nebudou fungovat.

V Serveru s obsahem:

Šablony mají přístup k novému API, ale ne ke starému API (LibraryDatabase).
Z výše uvedeného důvodu není zaručeno, že následující funkce formatteru budou fungovat v šablonách GPM (složené sloupce, pravidla ikon atd.), a pokud používáte server s obsahem, měli byste se jim vyhnout:

Speciální poznámky k šablonám pro uložení/odeslání¶

Při použití šablony jako šablony pro Uložit na disk nebo Odeslat do zařízení se použije speciální zpracování. Hodnoty polí se vyčistí tak, že znaky se speciálním významem pro systémy souborů, včetně lomítek, se nahradí podtržítky. To znamená, že text pole nelze použít k vytváření složek. Lomítka se však nemění v řetězcích předpony nebo přípony, takže lomítka v těchto řetězcích způsobí vytvoření složek. Díky tomu můžete vytvořit strukturu složek s proměnlivou hloubkou.

Předpokládejme například, že chceme strukturu složek series/series_index - title, s tím omezením, že pokud série neexistuje, má být název knihy v nejvyšší složce. Šablona pro tento účel je:

{series:||/}{series_index:|| - }{title}

Lomítko a spojovník se zobrazí pouze v případě, že pole series není prázdné.

Funkce lookup umožňuje ještě propracovanější zpracování. Předpokládejme například, že pokud má kniha sérii, chceme strukturu složek series/series index - title.fmt. Pokud kniha sérii nemá, chceme strukturu složek genre/author_sort/title.fmt. Pokud kniha nemá žánr, chceme použít hodnotu ‚Unknown‘. Chceme dvě zcela odlišné cesty v závislosti na hodnotě pole series.

Abychom toho dosáhli, provedeme toto:

Vytvořte složené pole (dejte mu název vyhledávání #aa) obsahující {series}/{series_index} - {title}. Pokud série není prázdná, tato šablona vytvoří series/series_index - title.
Vytvořte složené pole (dejte mu název vyhledávání #bb) obsahující {#genre:ifempty(Unknown)}/{author_sort}/{title}. Tato šablona vytvoří genre/author_sort/title, kde se prázdný žánr nahradí hodnotou Unknown.
Nastavte šablonu pro uložení na {series:lookup(.,#aa,#bb)}. Tato šablona vybere složené pole #aa, pokud pole series není prázdné, a složené pole #bb, pokud je pole series prázdné. Máme tedy dvě zcela odlišné cesty pro uložení podle toho, zda je pole series prázdné.

Rady¶

K testování šablon použijte Testovač šablon. Přidejte testovač do místní nabídky knih v knihovně nebo mu přiřaďte klávesovou zkratku, případně obojí.
Šablony mohou používat jiné šablony prostřednictvím odkazů na složené sloupce sestavené požadovanou šablonou. Případně můžete použít uložené šablony.
V zásuvném panelu můžete pole nastavit na prázdnou hodnotu (nebo na ekvivalent prázdné hodnoty) pomocí speciální šablony {}. Tato šablona se vždy vyhodnotí jako prázdný řetězec.
Výše popsaná technika pro zobrazení čísel i tehdy, když mají nulovou hodnotu, funguje se standardním polem series_index.

Referenční příručka funkcí šablon¶

Reference for all built-in template language functions