Jezik šablona u programu calibre¶

Calibre jezik šablona je jezik specifičan za calibre koji se koristi širom calibre-a za zadatke kao što su određivanje putanja datoteka, formatiranje vrednosti i izračunavanje vrednosti za kolone koje je odredio korisnik. Primeri:

Odredite strukturu fascikli i imena datoteka prilikom čuvanja datoteka iz calibre biblioteke na disk ili e-čitač.
Definišite pravila za dodavanje ikona i boja na listu knjiga u calibre-u.
Definišite virtuelne kolone koje sadrže podatke iz drugih kolona.
Napredno pretraživanje biblioteke.
Napredna pretraga i zamena metapodataka.

Jezik se zasniva na šablonu, koji određuje koji se metapodaci knjige koriste, kako se obrađuju i kako se rezultat prikazuje.

Osnovni šabloni¶

Osnovni šablon se sastoji od jednog ili više template expressions. template expression se sastoji od teksta i imena u vitičastim zagradama ({}) koji se zamenjuju odgovarajućim metapodacima iz knjige koja se obrađuje. Na primer, podrazumevani šablon u calibre-u koji se koristi za čuvanje knjiga na uređaj ima 4 template expressions:

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

Za knjigu "The Foundation" od "Isaac Asimov" šablon će postati:

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

Kose crte nisu template expressions jer se ne nalaze između {}. Takav tekst ostaje tamo gde se pojavljuje. Na primer, ako je šablon:

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

onda za "The Foundation" šablon proizvodi:

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

template expression može pristupiti svim metapodacima dostupnim u calibre-u, uključujući prilagođene kolone (kolone koje sami kreirate), koristeći lookup name kolone. Da biste pronašli lookup name za column (ponekad se naziva fields), pređite mišem preko zaglavlja kolone u listi knjiga u calibre-u. Lookup imena za prilagođene kolone uvek počinju sa #. Za kolone tipa serije postoji dodatno polje pod nazivom #lookup name_index koje predstavlja indeks serije za tu knjigu u seriji. Na primer, ako imate prilagođenu kolonu serije pod nazivom #myseries, postojaće i kolona pod nazivom #myseries_index. Indeks standardne kolone serije se zove series_index.

Pored standardnih polja zasnovanih na kolonama, takođe možete koristiti:

{formats} - Lista formata dostupnih u calibre biblioteci za knjigu

{identifiers:select(isbn)} - ISBN knjige

Ako metapodaci za polje za datu knjigu nisu definisani, onda se polje u šablonu zamenjuje praznim stringom (''). Na primer, razmotrite sledeći šablon:

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

Ako je Asimovljeva knjiga "Second Foundation" u serijalu "Foundation", onda šablon proizvodi:

Asimov, Isaac/Foundation/Second Foundation 3

Ako serijal nije unet za knjigu, onda šablon proizvodi:

Asimov, Isaac/Second Foundation

Procesor šablona automatski uklanja višestruke kose crte i vodeće ili prateće razmake.

Napredno formatiranje¶

Pored zamene metapodataka, šabloni mogu uslovno uključiti dodatni tekst i kontrolisati kako se zamenjeni podaci formatiraju.

Uslovno uključivanje teksta

Ponekad želite da se tekst pojavi u izlazu samo ako polje nije prazno. Čest slučaj je series i series_index gde želite ili ništa ili dve vrednosti razdvojene crticom. calibre rešava ovaj slučaj koristeći specijalnu template expression sintaksu.

Na primer, koristeći gornji primer Foundation, pretpostavimo da želite da šablon proizvede Foundation - 3 - Second Foundation. Ovaj šablon proizvodi taj izlaz:

{series} - {series_index} - {title}

Međutim, ako knjiga nema serijal, šablon će proizvesti - - the title, što verovatno nije ono što želite. Generalno, ljudi žele da rezultat bude naslov bez suvišnih crtica. Ovo možete postići koristeći sledeću sintaksu šablona:

{field:|prefix_text|suffix_text}

Ovaj template expression kaže da ako field ima vrednost XXXX onda će rezultat biti prefix_textXXXXXsuffix_text. Ako je field prazno (nema vrednost) onda će rezultat biti prazan string (ništa) jer se prefiks i sufiks ignorišu. Prefiks i sufiks mogu sadržati praznine.

Ne koristite podšablone (`{ ... }`) ili funkcije (videti ispod) u prefiksu ili sufiksu.

Koristeći ovu sintaksu, možemo rešiti gornji problem bez serijala sa šablonom:

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

Crtice će biti uključene samo ako knjiga ima indeks serije, što ima samo ako ima seriju. Nastavljajući ponovo primer Foundation, šablon će proizvesti Foundation - 1 - Second Foundation.

Napomene:

Morate uključiti dvotačku nakon lookup name ako koristite prefiks ili sufiks.
Morate koristiti ili nijedan ili oba | karaktera. Korišćenje jednog, kao u {field:| - }, nije dozvoljeno.
U redu je ne navesti tekst ni za prefiks ni za sufiks, kao u {series:|| - }. Šablon {title:||} je isti kao {title}.

Formatiranje

Pretpostavimo da želite da series_index bude formatiran kao tri cifre sa vodećim nulama. Ovo rešava problem:

{series_index:0>3s} - Tri cifre sa vodećim nulama

Za prateće nule, koristite:

{series_index:0<3s} - Tri cifre sa pratećim nulama

Ako koristite indekse serija sa decimalnim vrednostima, npr. 1.1, možda ćete želeti da se decimalne tačke poravnaju. Na primer, možda ćete želeti da se indeksi 1 i 2.5 prikažu kao 01.00 i 02.50 kako bi se pravilno sortirali na uređaju koji vrši leksičko sortiranje. Da biste to uradili, koristite:

{series_index:0>5.2f} - Pet karaktera koji se sastoje od dve cifre sa vodećim nulama, decimalne tačke, a zatim 2 cifre posle decimalne tačke.

Ako želite samo prva dva slova podataka, koristite:

{author_sort:.2} - Samo prva dva slova imena za sortiranje autora

Veći deo formatiranja jezika šablona u calibre-u potiče iz Python-a. Za više detalja o sintaksi ovih naprednih operacija formatiranja pogledajte Python dokumentaciju.

Korišćenje šablona za definisanje prilagođenih kolona¶

Šabloni se mogu koristiti za prikaz informacija koje nisu u calibre metapodacima, ili za prikaz metapodataka drugačije od normalnog calibre formata. Na primer, možda želite da prikažete ISBN, polje koje calibre ne prikazuje. Ovo možete postići kreiranjem prilagođene kolone sa tipom Column built from other columns (u daljem tekstu composite columns) i obezbeđivanjem šablona za generisanje prikazanog teksta. Kolona će prikazati rezultat evaluacije šablona. Na primer, da biste prikazali ISBN, kreirajte kolonu i unesite {identifiers:select(isbn)} u polje za šablon. Da biste prikazali kolonu koja sadrži vrednosti dve prilagođene kolone za serije, odvojene zarezom, koristite {#series1:||,}{#series2}.

Složene kolone mogu koristiti sve mogućnosti šablona, uključujući formatiranje.

Napomena: Ne možete neposredno menjati podatke prikazane u složenoj koloni. Umesto toga menjate izvorne kolone. Ako pokušate da izmenite složenu kolonu, na primer dvostrukim klikom na nju, calibre će otvoriti šablon za uređivanje, a ne osnovne podatke.

Šabloni i plugboards¶

Plugboards se koriste za promenu metapodataka upisanih u knjige tokom operacija slanja na uređaj (send-to-device) i čuvanja na disk (save-to-disk). Plugboard vam omogućava da navedete šablon koji će obezbediti podatke za upisivanje u metapodatke knjige. Možete koristiti plugboards za izmenu sledećih polja: authors, author_sort, language, publisher, tags, title, title_sort. Ova funkcija pomaže ljudima koji žele da koriste različite metapodatke u knjigama na uređajima kako bi rešili probleme sa sortiranjem ili prikazom.

Kada pravite tablu za metapodatke (plugboard), navodite format i uređaj za koji će se koristiti. Posebna stavka save_to_disk koristi se pri čuvanju formata na disk, umesto pri slanju na uređaj. Zatim birate polja metapodataka koja želite da promenite i unosite šablone koji daju nove vrednosti. Ti šabloni su povezani sa odredišnim poljima, otuda naziv plugboards. U njima možete koristiti i složene kolone.

Plugboards su prilično fleksibilni i mogu biti napisani u Single Function Mode, Template Program Mode, General Program Mode ili Python Template mode.

Kada se plugboard može primeniti (Content server, čuvanje na disk ili slanje na uređaj), calibre pretražuje definisane plugboards kako bi izabrao pravi za dati format i uređaj. Na primer, da bi pronašao odgovarajući plugboard za EPUB knjigu koja se šalje na ANDROID uređaj, calibre pretražuje plugboards koristeći sledeći redosled pretrage:

plugboard sa tačnim podudaranjem formata i uređaja, npr. EPUB i ANDROID
plugboard sa tačnim podudaranjem formata i specijalnim izborom any device, npr. EPUB i any device
plugboard sa specijalnim izborom any format i tačnim podudaranjem uređaja, npr. any format i ANDROID
plugboard sa any format i any device

Polja tags i authors imaju poseban tretman, jer oba ova polja mogu sadržati više od jedne stavke. Knjiga može imati mnogo oznaka i mnogo autora. Kada navedete da jedno od ova dva polja treba da se promeni, rezultat šablona se ispituje da bi se videlo da li tamo ima više od jedne stavke. Za oznake, rezultat se seče gde god calibre pronađe zarez. Na primer, ako šablon proizvede vrednost Thriller, Horror, onda će rezultat biti dve oznake, Thriller i Horror. Ne postoji način da se stavi zarez u sredinu oznake.

Ista stvar se dešava i za autore, ali se koristi drugačiji karakter za sečenje, & (ampersand) umesto zareza. Na primer, ako šablon proizvede vrednost Blogs, Joe&Posts, Susan, onda će knjiga završiti sa dva autora, Blogs, Joe i Posts, Susan. Ako šablon proizvede vrednost Blogs, Joe;Posts, Susan, onda će knjiga imati jednog autora sa prilično čudnim imenom.

Plugboards utiču na metapodatke upisane u knjigu kada se sačuva na disk ili upiše na uređaj. Plugboards ne utiču na metapodatke koje koriste save to disk i send to device za kreiranje imena datoteka. Umesto toga, imena datoteka se konstruišu koristeći šablone unete u odgovarajućem prozoru podešavanja.

Korišćenje funkcija u šablonima - Single Function Mode¶

Pretpostavimo da želite da prikažete vrednost polja velikim slovima kada je to polje obično u formatu naslova. To možete uraditi koristeći template functions. Na primer, da biste prikazali naslov velikim slovima, koristite funkciju uppercase, kao u {title:uppercase()}. Da biste ga prikazali u formatu naslova, koristite {title:titlecase()}.

Funkcije idu u deo za formatiranje šablona, posle : i pre prvog | ili zatvarajuće } ako se ne koristi prefiks/sufiks. Ako imate i format i referencu na funkciju, funkcija dolazi posle drugog :. Funkcije vraćaju vrednost kolone navedene u šablonu, odgovarajuće izmenjenu.

Sintaksa za korišćenje funkcija je jedna od:

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

Imena funkcija moraju uvek biti praćena otvorenim i zatvorenim zagradama. Neke funkcije zahtevaju dodatne vrednosti (argumente), i one idu unutar zagrada. Argumenti su odvojeni zarezima. Literalni zarezi (zarezi kao tekst, a ne separatori argumenata) moraju biti prethodeni obrnutom kosom crtom (\). Poslednji (ili jedini) argument ne može sadržati tekstualnu zatvarajuću zagradu.

Funkcije se procenjuju pre specifikacija formata i prefiksa/sufiksa. Pogledajte dalje dole za primer korišćenja i formata i funkcije.

Važno: Ako imate iskustva u programiranju, imajte na umu da sintaksa u Single Function Mode nije ono što očekujete. Stringovi nisu pod navodnicima i razmaci su značajni. Svi argumenti se smatraju konstantama; nema izraza.

Ne koristite podšablone (`{ ... }`) kao argumente funkcija. Umesto toga, koristite Template Program Mode i General Program Mode.

Napomene o pozivanju funkcija u Single Function Mode:

Kada se funkcije koriste u Single Function Mode, prvi parametar, value, automatski se zamenjuje sadržajem polja navedenog u šablonu. Na primer, kada se obrađuje šablon {title:capitalize()}, sadržaj polja title se prosleđuje kao parametar value funkciji capitalize.
U dokumentaciji funkcije, notacija [something]* znači da se something može ponoviti nula ili više puta. Notacija [something]+ znači da se something ponavlja jedan ili više puta (mora postojati barem jednom).
Neke funkcije koriste regularne izraze. U jeziku šablona podudaranje regularnih izraza ne razlikuje velika i mala slova.

Funkcije su dokumentovane u Referenca funkcija šablona. Dokumentacija vam govori koje argumente funkcije zahtevaju i šta funkcije rade. Na primer, evo dokumentacije funkcije ifempty.

ifempty(value, text_if_empty) -- ako value nije prazno, vraća tu vrednost, u suprotnom vraća text_if_empty.

Vidite da funkcija zahteva dva argumenta, value i text_if_empty. Međutim, pošto koristimo Single Function Mode, izostavljamo argument value, prosleđujući samo text_if_empty. Na primer, ovaj šablon:

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

prikazuje oznake za knjigu, ako ih ima. Ako nema oznaka, onda prikazuje No tags on this book.

Sledeće funkcije su upotrebljive u Single Function Mode jer je njihov prvi parametar value.

capitalize(value) -- vraća value sa prvim slovom velikim, a ostalim malim.
ceiling(value) -- vraća najmanji ceo broj veći ili jednak value.
cmp(value, y, lt, eq, gt) -- poredi value i y nakon pretvaranja oba u brojeve.
contains(value, pattern, text_if_match, text_if_not_match) -- proverava da li se vrednost poklapa sa regularnim izrazom pattern.
date_arithmetic(value, calc_spec, fmt) -- Izračunava novi datum iz value koristeći calc_spec.
encode_for_url(value, use_plus) -- vraća value kodiran za upotrebu u URL-u kako je navedeno sa use_plus. Vrednost se prvo URL-kodira. Zatim, ako je use_plus 0, razmaci se zamenjuju znakovima '+' (plus). Ako je 1, razmaci se zamenjuju sa %20.
floor(value) -- vraća najveći ceo broj manji ili jednak value.
format_date(value, format_string) -- formatira value, koji mora biti niska datuma, koristeći format_string, vraćajući nisku.
format_duration(value, template, [largest_unit]) -- formatira vrednost, broj sekundi, u niz koji prikazuje nedelje, dane, sate, minute i sekunde. Ako je vrednost float, zaokružuje se na najbliži ceo broj.
format_number(value, template) -- tumači value kao broj i formatira taj broj pomoću Python šablona za formatiranje, kao što su {0:5.2f}, {0:,d} ili ${0:5,.2f}.
fractional_part(value) -- vraća deo vrednosti nakon decimalne tačke.
human_readable(value) -- očekuje da value bude broj i vraća nisku koja predstavlja taj broj u KB, MB, GB, itd.
ifempty(value, text_if_empty) -- ako value nije prazno, vraća tu vrednost, u suprotnom vraća text_if_empty.
language_strings(value, localize) -- vraća nazive jezika za kodove jezika (pogledajte ovde za nazive i kodove) prosleđene u value.
list_contains(value, separator, [ pattern, found_val, ]* not_found_val) -- tumači value kao listu stavki razdvojenih pomoću separator, proveravajući pattern u odnosu na svaku stavku u listi.
list_count(value, separator) -- tumači vrednost kao listu stavki razdvojenih sa separator i vraća broj stavki u listi.
list_count_matching(value, pattern, separator) -- tumači value kao listu stavki razdvojenih sa separator, vraćajući broj stavki u listi koje se poklapaju sa regularnim izrazom pattern.
list_item(value, index, separator) -- tumači value kao listu stavki razdvojenih sa separator, vraćajući stavku na poziciji 'index'.
list_sort(value, direction, separator) -- vraća value sortiranu korišćenjem leksičkog sortiranja koje ne razlikuje velika i mala slova.
lookup(value, [ pattern, key, ]* else_key) -- obrasci će se proveravati u odnosu na value redom.
lowercase(value) -- vraća value malim slovima.
mod(value, y) -- vraća floor ostatka deljenja value / y.
rating_to_stars(value, use_half_stars) -- vraća value kao niz znakova zvezdica (★).
re(value, pattern, replacement) -- vraća value nakon primene regularnog izraza.
re_group(value, pattern [, template_for_group]*) -- vraća string dobijen primenom regularnog izraza pattern na value i zamenom svakog podudaranja
round(value) -- vraća najbliži ceo broj vrednosti value.
select(value, key) -- tumači value kao listu stavki razdvojenih zarezom, gde svaka stavka ima oblik id:id_value (calibre identifier format).
shorten(value, left_chars, middle_text, right_chars) -- vraća skraćenu verziju value
str_in_list(value, separator, [ string, found_val, ]+ not_found_val) -- tumači value kao listu stavki razdvojenih pomoću separator, a zatim upoređuje string sa svakom vrednošću u listi.
subitems(value, start_index, end_index) -- Ova funkcija razbija liste hijerarhijskih stavki nalik oznakama kao što su žanrovi.
sublist(value, start_index, end_index, separator) -- tumači value kao listu stavki razdvojenih sa separator, vraćajući novu listu napravljenu od stavki od start_index do end_index.
substr(value, start, end) -- vraća znakove od start-te do end-te pozicije u value.
swap_around_articles(value, separator) -- vraća value sa članovima pomerenim na kraj, razdvojenim tačkom-zarezom.
swap_around_comma(value) -- s obzirom na value u obliku B, A, vraća A B.
switch(value, [patternN, valueN,]+ else_value) -- za svaki par patternN, valueN, proverava da li se value poklapa sa regularnim izrazom patternN
test(value, text_if_not_empty, text_if_empty) -- vraća text_if_not_empty ako vrednost nije prazna, u suprotnom vraća text_if_empty.
titlecase(value) -- vraća value u formatu naslova.
transliterate(value) -- vraća niz u latiničnom pismu formiran približnim zvukom reči u value.
uppercase(value) -- vraća value velikim slovima.

Korišćenje funkcija i formatiranja u istom šablonu

Pretpostavimo da imate prilagođenu kolonu sa celim brojem #myint koju želite da prikažete sa vodećim nulama, kao u 003. Jedan način da to uradite je da koristite format 0>3s. Međutim, podrazumevano, ako je broj (ceo ili decimalni) jednak nuli, vrednost se prikazuje kao prazan string, tako da će nulte vrednosti proizvesti prazan string, a ne 000. Ako želite da vidite vrednosti 000, onda koristite i format string i funkciju ifempty da promenite praznu vrednost nazad u nulu. Šablon bi bio:

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

Imajte na umu da možete koristiti i prefiks i sufiks. Ako želite da se broj pojavi kao [003] ili [000], onda koristite šablon:

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

General Program Mode¶

General Program Mode (GPM) zamenjuje template expressions programom napisanim u template language. Sintaksa jezika je definisana sledećom gramatikom:

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

Napomene:

top_expression uvek ima vrednost. Vrednost expression_list je vrednost poslednjeg top_expression u listi. Na primer, vrednost liste izraza 1;2;'foobar';3 je 3.
U logičkom kontekstu, svaka neprazna vrednost je True
U logičkom kontekstu, prazna vrednost je False
Stringovi i brojevi se mogu koristiti naizmenično. Na primer, 10 i '10' su ista stvar.
Komentari su linije koje počinju znakom '#', kojima eventualno prethode razmaci ili tabulatori.

Prioritet operatora

Prioritet operatora (redosled evaluacije) od najvišeg (prvo se evaluira) do najnižeg (poslednje se evaluira) je:

Pozivi funkcija, konstante, izrazi u zagradama, izrazi naredbi, izrazi dodele, reference polja.
Unarni plus (+) i minus (-). Ovi operatori se evaluiraju zdesna nalevo.

Ovi i svi ostali aritmetički operatori vraćaju cele brojeve ako izraz rezultira razlomačkim delom jednakim nuli. Na primer, ako izraz vraća 3.0, menja se u 3.
Množenje (*) i deljenje (/). Ovi operatori su asocijativni i evaluiraju se sleva nadesno. Koristite zagrade ako želite da promenite redosled evaluacije.
Sabiranje (+) i oduzimanje (-). Ovi operatori su asocijativni i evaluiraju se sleva nadesno.
Numerička i string poređenja. Ovi operatori vraćaju '1' ako je poređenje uspešno, inače prazan string (''). Poređenja nisu asocijativna: a < b < c je sintaksna greška.
Spajanje stringova (&). Operator & vraća string formiran spajanjem levog i desnog izraza. Primer: 'aaa' & 'bbb' vraća 'aaabbb'. Operator je asocijativan i izračunava se sleva nadesno.
Unarno logičko ne (!). Ovaj operator vraća '1' ako je izraz netačan (False, izračunava se kao prazan string), inače ''.
Logičko i (&&). Ovaj operator vraća '1' ako su i levi i desni izraz tačni (True), ili prazan string '' ako je bilo koji netačan (False). Asocijativan je, izračunava se sleva nadesno i vrši kratko spajanje (short-circuiting).
Logičko ili (||). Ovaj operator vraća '1' ako je levi ili desni izraz tačan (True), ili '' ako su oba netačna (False). Asocijativan je, izračunava se sleva nadesno i vrši kratko spajanje (short-circuiting). To je inkluzivno ili, koje vraća '1' ako su i levi i desni izraz tačni.

Reference polja

field_reference se izračunava kao vrednost polja metapodataka imenovanog lookup imenom koje sledi nakon $ ili $$. Korišćenje $ je ekvivalentno korišćenju funkcije field. Korišćenje $$ je ekvivalentno korišćenju funkcije raw_field. Primeri:

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

If izrazi

If izrazi prvo procenjuju condition. Ako je condition True (ne-prazna vrednost) onda se procenjuje expression_list u then klauzuli. Ako je False onda se, ako je prisutna, procenjuje expression_list u elif ili else klauzuli. Delovi elif i else su opcioni. Reči if, then, elif, else i fi su rezervisane; ne možete ih koristiti kao imena identifikatora. Možete staviti nove redove i prazan prostor gde god imaju smisla. condition je top_expression a ne expression_list; tačka i zarez nisu dozvoljeni. expression_lists su sekvence top_expressions odvojene tačkom i zarezom. Izraz if vraća rezultat poslednjeg top_expression u procenjenoj expression_list, ili prazan string ako nijedna lista izraza nije procenjena.

Primeri:

* 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)

Primer ugnježdenog if:

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

Kao što je gore rečeno, if proizvodi vrednost. To znači da su svi sledeći primeri ekvivalentni:

* 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

Na primer, ovaj program vraća vrednost kolone series ako knjiga ima serijal, u suprotnom vrednost kolone title:

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

For izrazi

Izraz for iterira kroz listu vrednosti, obrađujući ih jednu po jednu. list_expression se mora proceniti ili kao lookup name polja metapodataka npr. tags ili #genre, ili kao lista vrednosti. range generiše listu brojeva. Ako je rezultat validan lookup name onda se preuzima vrednost polja i koristi se separator naveden za taj tip polja. Ako rezultat nije validan lookup name onda se pretpostavlja da je to lista vrednosti. Pretpostavlja se da je lista odvojena zarezima osim ako nije navedena opciona ključna reč separator, u kom slučaju vrednosti liste moraju biti odvojene rezultatom procene separator_expr. Separator se ne može koristiti ako je lista generisana pomoću range(). Svaka vrednost u listi se dodeljuje navedenoj promenljivoj, a zatim se procenjuje expression_list. Možete koristiti break da iskočite iz petlje, i continue da skočite na početak petlje za sledeću iteraciju.

Primer: Ovaj šablon uklanja prvo hijerarhijsko ime za svaku vrednost u Genre (#genre), konstruišući listu sa novim imenima:

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

Ako je originalni Genre History.Military, Science Fiction.Alternate History, ReadMe onda šablon vraća Military, Alternate History, ReadMe. Možete koristiti ovaj šablon u calibre-ovom Edit metadata in bulk → Search & replace sa Search for postavljenim na template da biste uklonili prvi nivo hijerarhije i dodelili rezultujuću vrednost Genre-u.

Napomena: poslednja linija u šablonu, new_tags, nije strogo neophodna u ovom slučaju jer for vraća vrednost poslednjeg top_expression u listi izraza. Vrednost dodele je vrednost njenog izraza, tako da je vrednost for iskaza ono što je dodeljeno new_tags.

with izrazi

with izraz:

menja trenutnu knjigu u knjigu sa calibre book id (ceo broj) proizvedenim evaluacijom top_expression.
pokreće expression_list.
zatim vraća trenutnu knjigu na ono što je bila.

with izraz vraća rezultat poslednjeg top_expression u evaluiranoj expression_list, ili prazan string ako nijedna lista izraza nije evaluirana.

Na primer, ovaj šablon vraća listu naslova svake knjige izabrane u GUI-ju:

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

Return stmt

Vraća vrednost expression. Ako se izvršava u funkciji, onda vraća vrednost izraza pozivaocu. Ako se izvršava u najspoljnijem kontekstu (šablonu), onda postavlja vrednost šablona na vrednost izraza i izlazi iz šablona.

Function definition

Ako imate ponovljeni kod u šablonu, onda taj kod možete staviti u lokalnu funkciju. Ključna reč def započinje definiciju. Sledi ime funkcije, lista argumenata, a zatim kod u funkciji. Definicija funkcije se završava ključnom reči fed.

Argumenti su pozicioni. Kada se funkcija pozove, prosleđeni argumenti se uparuju sleva nadesno sa definisanim parametrima, pri čemu se vrednost argumenta dodeljuje parametru. Greška je proslediti više argumenata nego što ima definisanih parametara. Parametri mogu imati podrazumevane vrednosti, kao što je a = 25. Ako argument nije prosleđen za taj parametar, onda se koristi podrazumevana vrednost, inače se parametar postavlja na prazan string.

Naredba return se može koristiti u lokalnoj funkciji.

Funkcija mora biti definisana pre nego što se može koristiti.

Primer: Ovaj šablon izračunava približno trajanje u godinama, mesecima i danima iz broja dana. Funkcija to_plural() formatira izračunate vrednosti. Imajte na umu da primer takođe koristi operator &:

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')

Relacioni operatori

Relacioni operatori vraćaju '1' ako je poređenje tačno, inače prazan string ('').

Postoje dva oblika relacionih operatora: poređenja stringova i numerička poređenja.

Poređenja stringova vrše poređenje stringova bez obzira na velika i mala slova koristeći leksički redosled. Podržani operatori za poređenje stringova su ==, !=, <, <=, >, >=, in, inlist i inlist_field. Za operatore in, inlist i inlist_field, rezultat levog izraza se tumači kao obrazac regularnog izraza. Oni su tačni ako se vrednost levog regularnog izraza podudara sa vrednošću desnog izraza. Regularni izrazi ne razlikuju velika i mala slova.

Operator inlist je tačan ako se levi regularni izraz podudara sa bilo kojom od stavki u desnoj listi gde su stavke u listi odvojene zarezima. Operator inlist_field je tačan ako se levi regularni izraz podudara sa bilo kojom od stavki u polju (koloni) imenovanom desnim izrazom, koristeći separator definisan za to polje. Napomena: operator inlist_field zahteva da se desni izraz proceni kao ime polja, dok operator inlist zahteva da se desni izraz proceni kao string koji sadrži listu odvojenu zarezima. Zbog ove razlike, inlist_field je znatno brži od inlist jer se ne vrše konverzije stringova niti konstrukcije listi.

Numerički operatori poređenja su ==#, !=#, <#, <=#, >#, >=#. Levi i desni izrazi moraju se proceniti kao numeričke vrednosti sa dva izuzetka: i string vrednost "None" (nedefinisano polje) i prazan string se procenjuju kao vrednost nula.

Primeri:

program: field('series') == 'foo' vraća '1' ako je serija knjige foo, inače ''.

program: 'f.o' in field('series') vraća '1' ako se serija knjige podudara sa regularnim izrazom f.o (npr. foo, Off Onyx, itd.), inače ''.

program: 'science' inlist $#genre vraća '1' ako se bilo koja od vrednosti preuzetih iz žanrova knjige podudara sa regularnim izrazom science, npr. Science, History of Science, Science Fiction itd., inače ''.

program: '^science$' inlist $#genre vraća '1' ako se bilo koji od žanrova knjige tačno podudara sa regularnim izrazom ^science$, npr. Science, inače ''. Žanrovi History of Science i Science Fiction se ne podudaraju.

program: 'asimov' inlist $authors vraća '1' ako se bilo koji autor podudara sa regularnim izrazom asimov, npr. Asimov, Isaac ili Isaac Asimov, inače ''.

program: 'asimov' inlist_field 'authors' vraća '1' ako se bilo koji autor podudara sa regularnim izrazom asimov, npr. Asimov, Isaac ili Isaac Asimov, inače ''.

program: 'asimov$' inlist_field 'authors' vraća '1' ako se bilo koji autor podudara sa regularnim izrazom asimov$, npr. Isaac Asimov, inače ''. Ne podudara se sa Asimov, Isaac zbog sidra $ u regularnom izrazu.

program: if field('series') != 'foo' then 'bar' else 'mumble' fi vraća 'bar' ako serija knjige nije foo. Inače vraća 'mumble'.

program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi vraća 'yes' ako je serija foo ili 1632, inače 'no'.

program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi vraća 'yes' ako je serija foo ili 1632, inače 'no'.

program: if 11 > 2 then 'yes' else 'no' fi vraća 'no' jer operator > vrši leksičko poređenje.

program: if 11 ># 2 then 'yes' else 'no' fi vraća 'yes' jer operator ># vrši numeričko poređenje.

Funkcije u General Program Mode

Pogledajte Referenca funkcija šablona za listu funkcija ugrađenih u jezik šablona.

Napomene:

Za razliku od Single Function Mode, u General Program Mode morate navesti prvi parametar value.
Svi parametri su expression_lists (pogledajte gramatiku iznad).

Složeniji programi u izrazima šablona - Template Program Mode¶

Template Program Mode (TPM) je mešavina General Program Mode i Single Function Mode. TPM se razlikuje od Single Function Mode po tome što dozvoljava pisanje izraza šablona koji se odnose na druga polja metapodataka, koriste ugnježdene funkcije, menjaju promenljive i vrše aritmetiku. Razlikuje se od General Program Mode po tome što je šablon sadržan između znakova { i } i ne počinje rečju program:. Programski deo šablona je lista izraza General Program Mode.

Primer: pretpostavimo da želite šablon koji prikazuje seriju za knjigu ako je ima, inače prikazuje vrednost prilagođenog polja #genre. Ovo ne možete uraditi u Single Function Mode jer ne možete referencirati drugo polje metapodataka unutar izraza šablona. U TPM to možete, kao što pokazuje sledeći izraz:

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

Primer pokazuje nekoliko stvari:

TPM se koristi ako izraz počinje sa :' i završava se sa '}. Sve ostalo se pretpostavlja da je u Single Function Mode.

Ako šablon sadrži prefiks i sufiks, izraz se završava sa '| gde je | graničnik za prefiks. Primer:
```
{series:'ifempty($, $#genre)'|prefix | suffix}
```
Funkcijama moraju biti dati svi njihovi argumenti. Na primer, standardnim ugrađenim funkcijama mora biti dat početni parametar value.
Promenljiva $ se može koristiti kao argument value i predstavlja vrednost polja imenovanog u šablonu, u ovom slučaju series.
prazan prostor se ignoriše i može se koristiti bilo gde unutar izraza.
konstantni stringovi su zatvoreni u odgovarajuće navodnike, bilo ' ili ".

U TPM, korišćenje karaktera { i } u string literalima može dovesti do grešaka ili neočekivanih rezultata jer zbunjuju procesor šablona. On pokušava da ih tretira kao granice izraza šablona, a ne kao karaktere. U nekim, ali ne svim slučajevima, možete zameniti { sa [[ i } sa ]]. Savet: ako vaš program sadrži karaktere { i }, onda bi trebalo da koristite General Program Mode.

Python Template Mode¶

Python Template Mode (PTM) vam omogućava da pišete šablone koristeći izvorni Python i calibre API. API baze podataka će biti od najveće koristi; dalja diskusija je van opsega ovog priručnika. PTM šabloni su brži i mogu obavljati komplikovanije operacije, ali morate znati kako da pišete kod u Python-u koristeći calibre API.

PTM šablon počinje sa:

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'

Možete dodati gornji tekst u vaš šablon koristeći kontekstni meni, kojem se obično pristupa desnim klikom. Komentari nisu značajni i mogu se ukloniti. Morate koristiti python uvlačenje.

Objekat konteksta podržava str(context) koji vraća string sadržaja konteksta, i context.attributes koji vraća listu imena atributa u kontekstu.

Atribut context.funcs omogućava pozivanje ugrađenih i korisničkih funkcija šablona, kao i sačuvanih GPM/Python šablona, tako da ih možete izvršavati direktno u vašem kodu. Funkcije se preuzimaju koristeći njihova imena. Ako je ime u konfliktu sa Python ključnom rečju, dodajte donju crtu na kraj imena. Primeri:

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

Evo primera PTM šablona koji proizvodi listu svih autora za seriju. Lista je sačuvana u Column built from other columns, behaves like tags. Prikazuje se u Book details i ima označeno on separate lines (u Preferences → Look & feel → Book details). Ta opcija zahteva da lista bude odvojena zarezima. Da bi se zadovoljio taj zahtev, šablon pretvara zareze u imenima autora u tačka-zareze, a zatim gradi listu autora odvojenu zarezima. Autori se zatim sortiraju, zbog čega šablon koristi 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))

Izlaz u Book details izgleda ovako:

Šabloni i URL-ovi¶

Možete koristiti šablone za konstruisanje URL-ova. Ovde su opisana dva slučaja:

Prilagođena kolona Book details URL-ovi za pretragu
calibre URL šema

Prilagođena kolona book details URL-ovi za pretragu

Kada kreirate prilagođenu kolonu, možete obezbediti URL koji će se koristiti u Book details pomoću šablona. Na primer, ako imate prilagođenu kolonu za Translators, možete definisati URL koji će vas odvesti na sajt za prevodioce. URL-ovi za pretragu detalja o knjizi mogu se obezbediti za tipove kolona Text, Enumerated, Series i Column built from other column.

Kada se klikne na stavku sa search template u Book details, šablon se procenjuje. Obezbeđeni su mu normalni metapodaci knjige. Takođe su mu obezbeđena tri dodatna polja:

item_value: vrednost kliknute stavke.
item_value_quoted: vrednost kliknute stavke, URL-kodirana. Specijalni karakteri su izbegnuti kako bi bili validni u URL-ovima, a razmaci su zamenjeni znakovima '+' (plus).
item_value_no_plus: vrednost kliknute stavke, URL-kodirana. Specijalni karakteri su izbegnuti kako bi bili validni u URL-ovima, a razmaci su zamenjeni sa %20, a ne plusom.

Postoji nekoliko načina za konstruisanje URL-a. Sledeći koriste Wikipediju kao primer.

Najjednostavniji je osnovni šablon:

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

U nekim slučajevima možda ćete želeti da uradite više obrade. Postoje četiri funkcije šablona koje možete koristiti, u zavisnosti od složenosti obrade.

make_url(path, [query_name, query_value]+) -- ova funkcija je najlakši način za konstruisanje URL-a upita. Koristi path, veb lokaciju i stranicu koju želite da pretražite, i parove query_name, query_value od kojih se upit gradi. Uopšteno, query_value mora biti URL-kodiran. Sa ovom funkcijom on je uvek kodiran, a razmaci se uvek zamenjuju znakovima '+'.
make_url_extended(...) -- ova funkcija je slična make_url(), ali vam daje veću kontrolu nad komponentama URL-a. Komponente URL-a su

šema:://autoritet/putanja?niz upita.

Pogledajte Uniform Resource Locator na Wikipediji za više detalja.

Funkcija ima dve varijante:
```
make_url_extended(scheme, authority, path, [query_name, query_value]+)
```
i
```
make_url_extended(scheme, authority, path, query_string)
```
query_string([query_name, query_value, how_to_encode]+)-- vraća niz URL upita konstruisan od trijada query_name, query_value, how_to_encode. Niz upita je niz stavki gde svaka stavka izgleda kao query_name=query_value, gde je query_value URL-kodiran prema instrukcijama. Stavke upita su razdvojene znakovima '&' (ampersand).
encode_for_url(value, use_plus) -- vraća value kodiran za upotrebu u URL-u kako je navedeno sa use_plus. Vrednost se prvo URL-kodira. Zatim, ako je use_plus 0, razmaci se zamenjuju znakovima '+' (plus). Ako je 1, razmaci se zamenjuju sa %20.

Na primer, pretpostavimo da imate prilagođenu kolonu Translators (#translators) gde su imena Last name, First name. Možda ćete morati da konvertujete ime u First name Last name prilikom kreiranja URL-a. Možete koristiti funkciju make_url da to uradite:

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

Ako pretpostavimo da je ime prevodioca Boy-Żeleński, Tadeusz, onda gornji šablon proizvodi vezu:

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

Imajte na umu da je ime osobe sada prvo, razmak je sada plus, a neengleski znakovi u prezimenu su URL-kodirani.

Funkcije make_url_extended, query_string i encode_for_url mogu biti korisne u zavisnosti od dodatne složenosti obrade.

The calibre URL scheme

Calibre podržava nekoliko različitih URL-ova za navigaciju vašim calibre bibliotekama. Ovaj odeljak pokazuje kako koristiti šablone za konstruisanje nekih od URL-ova. Pogledajte URL šema calibre:// za detalje o dostupnim URL-ovima.

Prebacite se na određenu biblioteku. Sintaksa ovog URL-a je:
```
calibre://switch-library/Library_Name
```
Library_Name mora biti zamenjeno imenom calibre biblioteke koju želite da otvorite. Ime biblioteke je prikazano u naslovnoj traci prozora. To je jednostavno ime, a ne putanja datoteke do biblioteke. Morate ga napisati onako kako je prikazano u naslovnoj traci, uključujući velika i mala slova. Znak _ (donja crta) označava trenutnu biblioteku. Ako ime sadrži razmake ili specijalne znakove, onda mora biti heksadecimalno kodirano pomoću funkcije to_hex, kao u sledećem primeru:
```
program: strcat('calibre://switch-library/_hex_-', to_hex(current_library_name()))
```
Šablon generiše URL:
```
calibre://switch-library/_hex_-4c6962726172792e746573745f736d616c6c
```
Možete zameniti funkciju current_library_name() sa stvarnim imenom biblioteke, kao u:
```
program: strcat('calibre://switch-library/_hex_-', to_hex('Library.test_small'))
```
Veze za prikaz knjiga. Ove veze biraju knjigu u calibre biblioteci. Sintaksa za ovaj URL je:
```
calibre://show-book/Library_Name/book_id
```
book id je numerički calibre id za knjigu, dostupan šablonima kao $id. Kao i gore, ime biblioteke možda treba da bude heksadecimalno kodirano. Evo primera:
```
program: strcat('calibre://show-book/_hex_-', to_hex(current_library_name()), '/', $id)
```
To proizvodi URL:
```
calibre://show-book/_hex_-4c6962726172792e746573745f736d616c6c/1353
```
Pretraga knjiga. Ove veze pretražuju knjige u navedenoj calibre biblioteci. Sintaksa za ovaj URL je:
```
calibre://search/Library_Name?q=query
calibre://search/Library_Name?eq=hex_encoded_query
```
gde je query bilo koji važeći calibre izraz za pretragu. Morate heksadecimalno kodirati svaki upit koji sadrži razmake ili specijalne karaktere, što generalno znači sve njih. Na primer, calibre izraz za pretragu za hijerarhijsku oznaku koja počinje sa 'AA' je tags:"=.AA". Ovaj šablon konstruiše URL za pretragu za taj izraz:
```
program: strcat('calibre://search/_hex_-', to_hex(current_library_name()), '?eq=', to_hex('tags:"=.AA"'))
```
Rezultujući URL je:
```
calibre://search/_hex_-4c6962726172792e746573745f736d616c6c?eq=746167733a223d2e414122
```
Evo primera istog URL-a izgrađenog pomoću funkcije :ref:ff_make_url_extended umesto strcat:
```
program: make_url_extended('calibre', '', 'search/_hex_-' & to_hex(current_library_name()),
                           'eq', to_hex('tags:"=.AA"'))
```

Otvorite prozor sa detaljima o knjizi za knjigu u nekoj biblioteci. Sintaksa za ovaj URL je:

calibre://book-details/Library_Name/book_id

Primer šablona je:

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

koji proizvodi URL:

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

Otvorite beleške povezane sa autorom/serijom/itd. Sintaksa URL-a 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 ime za pretragu polja. Ako je polje prilagođena kolona, zamenite znak # donjom crtom (_). Item_Id je interni numerički ID vrednosti u polju. Ne postoji funkcija šablona koja vraća Item_Id, tako da će šabloni obično koristiti drugi oblik, Hex_Encoded_Item_Name. Evo primera šablona koji otvara belešku za osobu Boy-Żeleński, Tadeusz u polju #authtest:
```
program: strcat('calibre://show-note/_hex_-', to_hex(current_library_name()),
                '/_authtest/hex_', to_hex('Boy-Żeleński, Tadeusz'))
```
koji proizvodi URL:
```
calibre://show-note/_hex_-4c6962726172792e746573745f736d616c6c/_authtest/hex_426f792dc5bb656c65c584736b692c205461646575737a
```

Sačuvani šabloni¶

I General Program Mode i Python Template Mode podržavaju čuvanje šablona i pozivanje tih šablona iz drugog šablona, slično pozivanju sačuvanih funkcija. Šablone čuvate koristeći Preferences → Advanced → Template functions. Više informacija je navedeno u tom dijalogu. Šablon pozivate na isti način kao što pozivate funkciju, prosleđujući pozicione argumente ako želite. Argument može biti bilo koji izraz. Primeri pozivanja šablona, pod pretpostavkom da se sačuvani šablon zove foo:

foo() -- poziva šablon bez prosleđivanja argumenata.
foo(a, b) poziva šablon prosleđujući vrednosti dve promenljive a i b.
foo(if field('series') then field('series_index') else 0 fi) -- ako knjiga ima series onda prosledi series_index, inače prosledi vrednost 0.

U GPM-u preuzimate argumente prosleđene u pozivu sačuvanom šablonu koristeći funkciju arguments. Ona istovremeno deklariše i inicijalizuje lokalne promenljive, efektivno parametre. Promenljive su pozicione; dobijaju vrednost parametra datog u pozivu na istoj poziciji. Ako odgovarajući parametar nije obezbeđen u pozivu, onda arguments dodeljuje toj promenljivoj obezbeđenu podrazumevanu vrednost. Ako nema podrazumevane vrednosti, onda se promenljiva postavlja na prazan string. Na primer, sledeća funkcija arguments deklariše 2 promenljive, key, alternate:

arguments(key, alternate='series')

Primeri, ponovo pretpostavljajući da je sačuvani šablon nazvan foo:

foo('#myseries') -- argumentu key je dodeljena vrednost 'myseries' a argumentu alternate je dodeljena podrazumevana vrednost 'series'.
foo('series', '#genre') promenljivoj key je dodeljena vrednost 'series' a promenljivoj alternate je dodeljena vrednost '#genre'.
foo() -- promenljivoj key je dodeljen prazan string a promenljivoj alternate je dodeljena vrednost 'series'.

U PTM-u argumenti se prosleđuju u parametru arguments, koji je lista stringova. Ne postoji način da se odrede podrazumevane vrednosti. Morate proveriti dužinu liste arguments da biste bili sigurni da je broj argumenata onakav kakav očekujete.

Jednostavan način za testiranje sačuvanih šablona je korišćenje dijaloga Template tester. Za lakši pristup dodelite mu prečicu na tastaturi u Preferences → Advanced → Keyboard shortcuts → Template tester. Davanje prečice dijalogu Stored templates pomoći će u bržem prebacivanju između testera i uređivanja izvornog koda sačuvanog šablona.

Pružanje dodatnih informacija šablonima¶

Programer može izabrati da prosledi dodatne informacije procesoru šablona, kao što su metapodaci knjige specifični za aplikaciju ili informacije o tome šta se od procesora traži da uradi. Šablon može pristupiti ovim informacijama i koristiti ih tokom evaluacije.

Programer: kako proslediti dodatne informacije

Dodatne informacije su Python rečnik koji sadrži parove variable_name: variable_value gde vrednosti moraju biti stringovi. Šablon može pristupiti rečniku, kreirajući lokalne promenljive šablona sa imenom variable_name koje sadrže vrednost variable_value. Korisnik ne može promeniti ime, pa je najbolje koristiti imena koja se neće sudarati sa drugim lokalnim promenljivama šablona, na primer dodavanjem donje crte ispred imena.

Ovaj rečnik se prosleđuje procesoru šablona (formatter) koristeći imenovani parametar global_vars=your_dict. Puni potpis metode je:

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

Pisac šablona: kako pristupiti dodatnim informacijama

Pristupate dodatnim informacijama (rečniku globals) u šablonu koristeći funkciju šablona:

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

gde je id bilo koje legalno ime promenljive. Ova funkcija proverava da li dodatne informacije koje je pružio programer sadrže to ime. Ako sadrže, funkcija dodeljuje pruženu vrednost lokalnoj promenljivoj šablona sa tim imenom. Ako ime nije u dodatnim informacijama i ako je obezbeđen expression, expression se evaluira i rezultat se dodeljuje lokalnoj promenljivoj. Ako nije obezbeđena ni vrednost ni izraz, funkcija dodeljuje prazan string ('') lokalnoj promenljivoj.

Šablon može postaviti vrednost u globals rečniku koristeći funkciju šablona:

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

Ova funkcija postavlja par ključ:vrednost u globals rečniku kao id:value gde je value vrednost lokalne promenljive šablona id. Ako ta lokalna promenljiva ne postoji, onda se value postavlja na rezultat evaluacije expression.

Napomene o razlici između režima¶

Tri programska režima, Single Function Mode (SFM), Template Program Mode (TPM) i General Program Mode (GPM), rade različito. SFM je zamišljen da bude 'jednostavan' pa sakriva mnogo delova programskog jezika.

Razlike:

U SFM-u vrednost kolone se uvek prosleđuje kao 'nevidljivi' prvi argument funkciji uključenoj u šablon.
SFM ne podržava razliku između promenljivih i stringova; sve vrednosti su stringovi.
Sledeći SFM šablon vraća ili ime serije ili string "no series":
```
{series:ifempty(no series)}
```
Ekvivalentni šablon u TPM je
```
{series:'ifempty($, 'no series')'}
```
Ekvivalentni šablon u GPM je:
```
program: ifempty(field('series'), 'no series')
```
Prvi argument za ifempty je vrednost polja series. Drugi argument je string no series. U SFM-u se prvi argument, vrednost polja, automatski prosleđuje (nevidljivi argument).
Nekoliko funkcija šablona, na primer booksize() i current_library_name(), ne uzimaju argumente. Zbog 'nevidljivog argumenta' ne možete koristiti ove funkcije u SFM-u.
Ugnježđene funkcije, gde funkcija poziva drugu funkciju da izračuna argument, ne mogu se koristiti u SFM-u. Na primer, ovaj šablon, namenjen da vrati prvih 5 karaktera vrednosti serije velikim slovima, neće raditi u SFM-u:
```
{series:uppercase(substr(0,5))}
```

TPM i GPM podržavaju ugnježđene funkcije. Gornji šablon u TPM bi bio:

{series:'uppercase(substr($, 0,5))'}

U GPM bi to bilo:

program: uppercase(substr(field('series'), 0,5))

Kao što je navedeno u gornjem odeljku Template Program Mode, korišćenje karaktera { i } u TPM string literalima može dovesti do grešaka ili neočekivanih rezultata jer zbunjuju procesor šablona. On pokušava da ih tretira kao granice šablona, a ne kao karaktere. U nekim, ali ne svim slučajevima, možete zameniti { sa [[ i } sa ]]. Generalno, ako vaš program sadrži karaktere { i }, onda bi trebalo da koristite General Program Mode.

Korisnički definisane Python funkcije šablona¶

Možete dodati sopstvene Python funkcije u procesor šablona. Takve funkcije se mogu koristiti u bilo kom od tri režima programiranja šablona. Funkcije se dodaju odlaskom na Preferences → Advanced → Template functions. Uputstva su prikazana u tom dijalogu. Imajte na umu da možete koristiti Python Templates za sličnu svrhu. Pošto je pozivanje korisnički definisanih funkcija brže od pozivanja Python šablona, korisnički definisane funkcije mogu biti efikasnije u zavisnosti od složenosti onoga što funkcija ili šablon radi.

Posebne napomene za korišćenje šablona u različitim kontekstima¶

U GUI-ju (Columns made from other columns i Template searches):

GPM šabloni rade kao i ranije.
Python šabloni imaju pun pristup calibre bazi podataka.

U pravilima ikona:

šabloni pravila ikona nemaju podatke o knjizi, tako da funkcije zasnovane na poljima kao što su format_date_field, list_count_field i check_yes_no neće raditi.

U Content server:

Šabloni imaju pristup novom API-ju, ali ne i starom API-ju (LibraryDatabase).
Zbog gore navedenog, sledeće funkcije formatera nisu garantovane da rade u GPM šablonima (kompozitne kolone, pravila za ikone, itd.) i treba ih izbegavati ako koristite content server:

Posebne napomene za šablone za čuvanje/slanje¶

Posebna obrada se primenjuje kada se šablon koristi u Save to disk ili Send to device šablonu. Vrednosti polja se čiste, zamenjujući karaktere koji su posebni za sisteme datoteka donjim crtama, uključujući kose crte. To znači da se tekst polja ne može koristiti za kreiranje fascikli. Međutim, kose crte se ne menjaju u prefiks ili sufiks stringovima, tako da će kose crte u ovim stringovima prouzrokovati kreiranje fascikli. Zbog toga možete kreirati strukturu fascikli promenljive dubine.

Na primer, pretpostavimo da želimo strukturu fascikli series/series_index - title, sa upozorenjem da ako serija ne postoji, onda naslov treba da bude u gornjoj fascikli. Šablon za ovo je:

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

Kosa crta i crtica se pojavljuju samo ako serija nije prazna.

Funkcija pretrage nam omogućava još složeniju obradu. Na primer, pretpostavimo da ako knjiga ima seriju, onda želimo strukturu fascikli series/series index - title.fmt. Ako knjiga nema seriju onda želimo strukturu fascikli genre/author_sort/title.fmt. Ako knjiga nema žanr onda želimo da koristimo 'Unknown'. Želimo dve potpuno različite putanje, u zavisnosti od vrednosti serije.

Da bismo to postigli, mi:

Kreiramo kompozitno polje (dajemo mu ime za pretragu #aa) koje sadrži {series}/{series_index} - {title}. Ako serija nije prazna, onda će ovaj šablon proizvesti series/series_index - title.
Kreiramo kompozitno polje (dajemo mu ime za pretragu #bb) koje sadrži {#genre:ifempty(Unknown)}/{author_sort}/{title}. Ovaj šablon proizvodi genre/author_sort/title, gde se prazan žanr zamenjuje sa Unknown.
Postavite šablon za čuvanje na {series:lookup(.,#aa,#bb)}. Ovaj šablon bira kompozitno polje #aa ako serija nije prazna i kompozitno polje #bb ako je serija prazna. Zbog toga imamo dve potpuno različite putanje za čuvanje, u zavisnosti od toga da li je series prazno ili ne.

Saveti¶

Koristite Template Tester za testiranje šablona. Dodajte tester u kontekstni meni za knjige u biblioteci i/ili mu dodelite prečicu na tastaturi.
Šabloni mogu koristiti druge šablone referenciranjem kompozitnih kolona izgrađenih sa željenim šablonom. Alternativno, možete koristiti Stored Templates.
U plugboard-u, možete postaviti polje na prazno (ili šta god je ekvivalentno praznom) korišćenjem specijalnog šablona {}. Ovaj šablon će se uvek evaluirati u prazan string.
Tehnika opisana iznad za prikazivanje brojeva čak i ako imaju nultu vrednost radi sa standardnim poljem series_index.

Referenca funkcija šablona¶

Reference for all built-in template language functions