Get Adobe Flash player

Definice textových bloků

Definice textových bloků

Katalog na některých místech obsahuje tzv. definovatelné textové bloky, což jsou uživatelsky definovatelné oblasti, ve kterých lze vypisovat data o záznamu. Lze například nadefinovat, aby se v záznamu pod obálkou zobrazoval seznam klíčových slov, poznámka nebo ISBN.

Konkrétně se jedná o následující oblasti:

  • Oblast s dokumentem v seznamu vyhledaných záznamů při kompaktním zobrazení,
  • stejná oblast při plnohodnotném zobrazení,
  • v detailu dokumentu vpravo vedle nadpisu (slouží zejména pro informaci čtenářům, v jakém regálu se daný dokument v knihovně nachází)
  • v detailu dokumentu vpravo vedle obálky,
  • v detailu dokumentu pod obálkou,
  • v detailu autority.

Nastavení těchto oblastí se nachází v ini v sekci OPAC, pod klíči začínajícími DEFINICE_ODSTAVCE. V definici lze nastavovat jakákoliv pole a podpole z daného záznamu, lokalizované texty, nebo i podmíněná pole.

Zápis definice

Univerzální způsob definice textových bloků je pomocí šablonovacího nástroje Apache Velocity. Pomocí něho lze definovat téměř cokoliv, včetně složitějších podmínek, na které již výše zmiňovaný způsob nestačí (vypsání prvních dvou písmen podpole apod.). Kompletní uživatelská dokumentace k nástroji je zde. Pro obecnou představu, jak by měly definice vypadat se stačí podívat na výchozí definice v nastavení.

Pozor, systém již (od 1.1.2016) nepodporuje starý, zakázaný zápis definice (pomocí "stříškové" syntaxe).

V šablonách je předdefinováno několik maker pro snadné vypsání polí a podpolí.

Standardní výpis obsahu pole

Makro "sf" je pomůcka pro vypsání hodnot pole téměř stejně jako u prvního způsobu definice textových bloků. Každé vypsané podpole bude automaticky zobrazovat hint (bublinový popisek) s názvem podpole, nebo, pokud je hodnotou podpole url adresa, automaticky z ní bude vytvořen odkaz.

Syntaxe pro vypsání všech podpolí daného pole (se středníky mezi poli a mezerami mezi podpoli):

#sf( <cislo_pole> )

Syntaxe pro vypsání zadaných podpolí daného pole (se středníky mezi poli a mezerami mezi podpoli):

#sf( <cislo_pole> <seznam_podpoli> )

Syntaxe pro vypsání zadaných podpolí daného pole s daným prefixem, sufixem a oddělovači:

#sf( <cislo_pole> <seznam_podpoli> <prefix> <suffix> <oddelovac_poli> <oddelovac_podpoli> )

, kde:

  • <cislo_pole> je číslo pole, které chceme zobrazit, 
  • <seznam_podpoli> je seznam podpolí, která se mají zobrazit. Je-li prázdný, zobrazí se všechna podpole, 
  • <prefix> je text, který se vloží před celý blok, pokud se alespoň jedno podpole vypíše (výchozí je prázdný), 
  • <suffix> je text, který se vloží za celý blok, pokud se alespoň jedno podpole vypíše (výchozí je prázdný), 
  • <oddelovac_poli> je text, který se vloží mezi každé opakování tohoto pole (výchozí je středník), 
  • <oddelovac_podpoli> je text, který se vloží mezi každá podpole (výchozí je mezera).

Vše, kromě čísla podpole je nutné mít v jednoduchých uvozovkách (např. 'abc'). Pokud chceme u některého parametru použít výchozí hodnotu (například chceme-li všechna podpole, což je výchozí pro parametr <seznam_podpoli>), použijeme prázdný text (jen uvozovky).

Pro vypsání všech podpolí polí 245 (Pole budou oddělena středníky, podpole mezerami):

#sf( 245 )

Pro vypsání podpolí "a" polí 245:

#sf( 245 'a' )

Pro vypsání podpolí "a" a "c" polí 300:

#sf( 300 'ac' )

Pro vypsání podpolí "a" a "c" polí 650 s nadefinovanými oddělovači polí a podpolí:

#sf( 300 'ac' 'Klíčová slova: ' '<br/>' ';' ' ')

Pro vypsání všech podpolí polí 650 s vlastním prefixem:

#sf( 300 '' 'Klíčová slova: ')

Obecně lze říci, že pokud se zbytek parametrů vynechá, použijí se výchozí.

Pro lokalizaci prefixu, suffixu, oddělovače polí nebo podpolí lze lokalizační klíč vložit mezi složené závorky, například pro lokalizování prefixu "Signatura":

#sf( 910 'b' '{detail.signatura}: ')

Výpis čistého obsahu pole

Pokud je potřeba vypsat hodnotu pole bez obalujících html tagů, je možné použít makro "sfRaw". Má úplně stejné parametry jako "sf". Toto makro může být užitečné například pro vytvoření odkazu, kdy v hodnotě podpole je jen druhá část URL adresy a je potřeba pomocí tohoto podpole vytvořit odkaz. Definice by v takovém případě vypadala takto:

#sfRaw(910 'a' '<a href="http://knihovna.cz/' '">Odkaz</a>')

Odkaz se pak vygeneruje následovně:

<a href="http://knihovna.cz/hodnota_podpole">Odkaz</a>

Výpis názvu fondu

K vypsání fondu slouží makro "fond". Následující výraz vypíše název fondu:

#fond()

Výpis lokalizovaného textu

Pro vypsání lokalizovaného textu je připraveno makro "loc", který vyžaduje jediný parametr, kterým je kód lokalizovaného textu. Například:

#loc('detail.signatura')

Výpis URL adresy katalogu

URL adresa katalogu lze vypsat pomocí proměnné $serverUrl. Pro funkčnost je nutné mít správně nakonfigurovanou adres v nastavení OPAC/URL, přesně tato hodnota se totiž do proměnné vkládá. Takto by vypadala syntaxe pro vypsání permanentního odkazu na záznam:

$serverUrl/documents/$record.id

Práce s časem

Pro potřeby vypsání času nebo podmínění datem, je možné využít proměnné calendar. Jedná se o komplikovanější funkci, proto v případě potřeby doporučujeme kontaktovat KpSys. Pro pokročilejší uživatele je možné prostudovat dokumentaci k java objektu Calendar.

Nejpoužívanější funkce proměnné calendar:

Výpis aktuálního roku (např. pro porovnávání s rokem vyplněným v poli záznamu):

$calendar.get(1)

Podmínění fondem

Jakýkoliv blok lze podmínit číslem fondu pomocí $record.fond.id. Takže například pro výpis bloku jen u periodik (fond číslo 3):

#if ($record.fond.id == 3)
<div>tento blok bude vypsán jen u periodik</div>
#end

Pozn.: Pozor na použití dvou rovnítek u porovnání. Pro nerovnost a další operátory viz dokumentace Velocity.

Podmínění hodnotou pole

Stejně, jako lze blok podmínit číslem fondu, lze bloky podmiňovat i hodnotami podpolí. K tomu se používá (stejně, jako u fondu) proměnná $record. Ta obsahuje další struktury polí a podpolí, ke kterým lze přistupovat tečkovou notací. Například pro vrácení obsahu prvního podpole a pole 520:

$record.getSubfield(520, 'a').raw

Tento výraz vrátí čistou (tzn. neupravovanou, proto název raw) hodnotu podpole.

Pro zkušené uživatele: Tato hodnota je typu String, se kterou lze dál pracovat (oříznout několik prvních znaků, změnit vše na velká písmena apod.). Tyto funkce jsou popsány v dokumentaci třídy String.

Pokud tedy budeme chtít vypsat blok jen, když je v prvním podpoli 'a' prvního pole 520 slovo 'abeceda', syntaxe bude vypadat následovně:

#if ($record.getSubfield(520, 'a').raw == 'abeceda')
<span>Tento blok bude vypsán jen u záznamů splňující tuto podmínku</span>
#end

Podmínění existencí pole/podpole lze vytvořit takto:

if ($record.getSubfield(520, 'a'))
<span>Tento blok bude vypsán jen u záznamů obsahujících podpole 520.a</span>
#end

Pokročilá práce s poli

Pro pokročilejší práci s poli a podpoli lze využít tzv. Marcuery API. Jedná se o funkce, kterými lze z celého záznamu vybrat jen určitá podpole a následně s nimi dále pracovat (např. vypsat na stránku).

Základním principem je nejdříve výběr požadovaných podpolí záznamu. Například pomocí následujícího zápisu:

$record.query('500.ab, 650.a')

metoda query vždy vrátí skupinu podpolí, která vyhovují zadanému filtru (resp. může vracet i kontrolní pole, neboť ta již nejsou dále dělena na podpole - mají přímo hodnotu. Ale pro zjednodušení můžeme uvažovat jen podpole). Pokud žádné z podpolí zadanému filtru nevyhovuje, vrátí prázdnou skupinu.

Následně je možné skupinu vypsat, například pomocí makra #fg:

#fg($record.query('650.a') 'Věcné téma:' '<br/>')

, kde prvním parametrem je právě skupina podpolí (proto název makra fg - field group) a další parametry jsou stejné, jako u maker #sf, tedy prefix, suffix, oddělovač polí a oddělovač podpolí).

Nebo je možné skupinu dále filtrovat, například můžeme vyfiltrovat všechna podpole 650.a, jejichž hodnota začíná na "PA":

$record.query('650.a').filterStartsWith('PA')

Tento filtr vrátí opět skupinu podpolí. Takže je možné buď úplně stejným způsobem (makrem #fg) skupinu vypsat:

#fg($record.query('650.a').filterStartsWith('PA') 'Věcná témata začínající na PA:' '<br/>')

nebo lépe - skupinu uložíme do proměnné $grPA a až následně vypíšeme:

#set($grPA = $record.query('650.a').filterStartsWith('PA'))
#fg($grPA 'Věcná témata začínající na PA:' '<br/>')

, nebo ji dále filtrovat. Například podpole, která obsahují slovo "bio": 

#fg($grPA.filterContains('bio') 'Věcná témata začínající na PA a obsahující bio:' '<br/>')

Popis Marcuery

Zápis filtru polí v $record.query(...) má následující strukturu:

<vycet_cisel_poli>#<vycet_opakovani_poli>.<vycet_kodu_podpoli>#<vycet_opakovani_podpoli>, 

, kde ani jedna z částí není povinná. Pokud chceme například všechna opakování polí, nemusíme vypisovat ani znak '#'. Například, pokud chceme vypsat všechna první podpolí "a" všech opakování polí 650:

$record.query('650.a#0')

Pozn.: opakování polí a podpolí jsou číslována od 0. Tedy první výskyt pole 650 je 650#0, druhý 650#1 atd.

Stejně tak, pokud chceme všechna podpole pole 650, není třeba uvádět ani tečku:

$record.query('650')

Místo jednoho konkrétního pole, opakování polí nebo podpolí je možné definovat i celé výčty, stačí je vložit mezi hranaté závorky. Například, chceme-li všechna podpole prvních a druhých opakování polí 600 a 650:

$record.query('[600,650]#[0,1]')

Výjímkou zápisu výčtu je jen výčet kódů podpolí, ta v nemusejí ani být závorce a ani oddělená čárkami. Chceme-li například jen první výskyty podpolí abc všech polí 650, zápis bude následující:

$record.query('650.abc#0')

Posledním důležitým bodem je, že je možné do jednoho dotazu vložit více zápisů (maximálně však 4) oddělených čárkami (za čárkami mohou být pro větší přehlednost mezery):

$record.query('600.a, 650.a, [245,250].ab, [500,510]#0.a#[0]')

Tím dostaneme všechna podpole a všech polí 600 a 650, všechna podpole ab polí 245 a 250 a první opakování podpole a prvních opakování polí 500 a 510.

Opět zdůrazňuji, že z každého dotazu dostaneme skupinu podpolí, kterou buď můžeme vypsat, nebo dále filtrovat.

Vlastnosti a metody (funkce) skupiny podpolí

Každá skupina (i jedno nebo žádné podpole představuje skupinu) obsahuje několik vlastností:

  • any (nebo isAny()) vrátí, zda skupina obsahuje alespoň jeden prvek
  • contains(infix) vrátí, zda alespoň jedno z podpolí obsahuje daný infix. $group.contains('abc')
  • containsField(cislo_pole) vrátí true/false, zda skupina obsahuje alespoň jedno dané pole. $group.containsField(245)
  • filterContains(infix) vrátí novou vyfiltrovanou skupinu obsahující jen podpole obsahující daný infix. $group.filterContains('ab')
  • filterStartsWith(prefix) viz filterContains, jen musí být prefix na začátcích.
  • get(index) vrátí jedno z polí ve skupině. $group.get(2) vrátí 3. podpole.
  • first (nebo getFirst()) vrátí první pole ve skupině. $group.first
  • raw (nebo getRaw()) vrátí hodnotu. Pokud je ve skupině více podpolí, vrátí všechny hodnoty oddělené čárkami. Pokud skupina obsahuje jen jedno pole, vrátí jeho hodnotu.
  • size (nebo getSize()) je počet podpolí ve skupině. $group.size
  • empty (nebo isEmpty()) vrátí, zda je skupina prázdná (opak hasLength())
  • startsWith(prefix) vrátí, zda alespoň jedno z podpolí začíná na daný prefix. $group.startsWith('abc')

Příklad

#fg($record.query('245.abc') 'Název:' '<br/>')
#foreach($gr610 in $record.query('610'))
    #fg($gr610)
#end
#set($gr7280 = $record.query('[72,80].2'))
#fg($gr7280.filterContains('MRF') 'VydáníMRF: ' '<br/>')
#fg($gr7280.filterContains('BSP') 'VydáníBSP: ' '<br/>')
Počet autorit věcné téma: $record.query('650.a#0').size

Vlastní formáty emailů a tiskových výstupů

V systému je zabudován vždy jeden výchozí formáty odesílaných emailů a tiskových výstupů. Lze ale definovat formáty (šablony) vlastní a v tom případě se pak uživateli automaticky zobrazí nabídka s výběrem požadovaného formátu.

Šablony se zapisují do textových souborů s příponou .vtl a jejich syntaxe je stejná jako u definice textových bloků. Každá šablona se zapisuje do samostatného souboru.

Definice pro emaily a tisky mohou být stejné (například totožná definice tisku a emailu může být pro seznam oblíbených), jen je třeba v emailu definici uzavřít do tagů <html> a <body>. To proto, že tělo emailu je samostatná HTML stránka, kdežto tisky se zobrazují přímo v katalogu a definice do HTML stránky automaticky vkládá.

Pro definici formátu emailu s informacemi o dokumentu je nutné vytvořit soubor ve složce custom/<path>/html, s názvem začínajícím na document-mail.

Například pro nějaký stručný formát by se soubor mohl jmenovat document-mail.simple.vtl. Aby se v nabídce s výběrem formátu zobrazil text s vypovídajícím popisem formátu, je možné nadefinovat lokalizační hlášku, která bude představovat název formátu. Pro šablonu document-mail.simple.vtl by byl kód lokalizační hlášky "templates.document-mail.simple" a český text by mohl být například "Jednoduchý formát".

Obsah souboru document-mail.simple.vtl by mohl vypadat například následovně:

<html>
    <body>
        <b>$record.name</b><br/>
        $!record.subTitle<br/>
        Autor: #sf(260)<br/>
        Odkaz na záznam: ${serverUrl}/documents/${record.id}
    </body>
</html>

Definice formátu emailu se seznamem oblíbených dokumentů je podobná, nicméně jedná se o soubor dokumentů, nikoliv jen jeden. Proto je v definici cyklus, který jednotlivé záznamy prochází a postupně vypisuje. Navíc, protože systém uvnitř cyklu nemůže vědět, jaký dokument se právě vypisuje, je nutné místo makra #sf používat upravené makro #sfSep, který přijímá navíc na začátku parametr se záznamem. Pro fond pak analogicky místo #fond() makro #fondSep($record).

Pro nadefinování vlastních formátů je nutné, aby názvy souborů začínaly prefixem "favourites-mail.".

Například pro nadefinování nějakého stručného formátu výpisu oblíbených bude vytvořen soubor favourites-mail.simple.vtl, jehož obsah by mohl být následující:

<html>
    <body>
        <b>Oblíbené dokumenty $!readerName</b> ($favourites.size() záznamů)<br/>
        <ul>
        #foreach( $record in $favourites.list )
            <li>
                Název dokumentu: <b>$record.name</b><br/>
                Podtitul: $!record.subTitle<br/>
                Autor: #sfSep($record 260)<br/>
Fond: #fondSep($record)<br/> Odkaz na záznam: ${serverUrl}/documents/${record.id} </li> #end </ul> </body> </html>

Pozn: Všimněte si upraveného makra #sfSep($record 260) místo #sf(260). Jinak je uvnitř cyklu foreach definice stejná jako u formátu emailu se záznamem.

V následujícím seznamu jsou shrnuty názvy souborů jednotlivých šablon:

  • document-mail.*.vtl - email s detailem záznamu (předmět je definován v lokalizaci mail.informaceODokumentuX)
  • favourites-mail.*.vtl - email se seznamem oblíbených (předmět v mail.oblibeneMailSubject)
  • favourites-print.*.vtl - tisk seznamu oblíbených
  • document-citation.vtl - šablona pro citace
  • loan-ready-mail.vtl - šablona pro odeslání mailu s připravenou výpůjčkou
  • user-registration-success-mail.vtl - šablona pro mail po úspěšné registraci čtenáře (předmět v registrace.full.MailSubject)

, kde * značí upřesnění typu šablony, tedy napřiklad "favourites-mail.simple.vtl".

Importování skriptu do skriptu

Pro odstranění duplicity skriptů, tzn. aby nebyl ve více souborech stejný bloku skriptu, je možné využít import skriptu, což je vlastně vložení jednoho skriptu do jiného. Například, pokud máme skript pro generování těla emailu se záznamem (document-mail.simple.vtl, viz výše) se používá stejný blok, jako u generování emailu s oblíbenými (favourites-mail.simple.vtl). Pro odstranění duplicity je tedy možné vložit část s 

Název dokumentu: <b>$record.name</b><br/>
Podtitul: $!record.subTitle<br/>
Autor: #sfSep($record 260)<br/>
Fond: #fondSep($record)<br/>
Odkaz na záznam: ${serverUrl}/documents/${record.id}

Do jiného souboru, například document.vtl a v původních souborech místo tohoto bloku daný skript (soubor) naimportovat, například:

<html>
    <body>
        <b>Oblíbené dokumenty $!readerName</b> ($favourites.size() záznamů)<br/>
        <ul>
        #foreach( $record in $favourites.list )
            <li>
                #parse("document.vtl")
            </li>
        #end
        </ul>
    </body>
</html>

Import se provádí makrem #parse s názvem importovaného souboru v parametru. Makro lze zavolat i ve skriptech v ini, čímž lze obejít limit pro maximální počet znaků v hodnotě ini.

Zmenšování a komprese obrázků

Systém umožňuje s využitím velocity vytvářet například i galerie obrázků, jejichž url adresy jsou uvedeny v některých polích záznamu. Obrázky však mohou být velmi rozměrné a tedy i velké ve smyslu množství dat, které se musejí oři zobrazení stránky načíst (podotýkám, že při nastavení velikosti obrázku přes width a height elementů img, se změní jen rozměry, nikoliv obrazová data). Proto systém podporuje funkci automatického zmenšování obrázku na serveru, kde se zmenší i obrazová data.

Využití této funkce spočívá v úpravě elementu img z:

<img src="/$urlAdresaObrazku" width="200" />

na

<img src="#resize($urlAdresaObrazku 200 0)" width="200" />

Makro #resize změní url adresu obrázku tak, že se obrázek načte skrze server, který ho zmenší a teprve pak pošle prohlížeči. Vzhledem k "delší" cestě obrázku do prohlížeče je tak vhodné toto používat pouze u obrázků větších, než cca 200kB. Neboli, funkce slouží spíše jako generátor náhledů obrázků.

Úprava tedy znamená pouze obalení původní adresy makrem #resize. Jeho první parametr je právě url adresa k obrázku a další dva jsou požadovaná šířka a výška. Jestliže se u některého rozměru ponechá 0, rozměr se automaticky dopočítá podle proporcí originálního obrázku.