Bežné operácie FreeMarker
1. Úvod
FreeMarker je šablónový nástroj napísaný v jazyku Java a udržiavaný nadáciou Apache Foundation. Na vytvorenie mnohých textových formátov, ako sú webové stránky, e-mail alebo súbory XML, môžeme použiť šablónový jazyk FreeMarker, známy tiež ako FTL.
V tomto tutoriáli uvidíme, čo môžeme robiť s balíkom FreeMarker po vybalení, aj keď je potrebné si uvedomiť, že je celkom konfigurovateľný a dokonca sa pekne integruje do Spring.
Začnime!
2. Rýchly prehľad
Na vloženie dynamického obsahu na naše stránky musíme použite syntax, ktorej FreeMarker rozumie:
- ${…} v šablóne bude vo vygenerovanom výstupe nahradená skutočnou hodnotou výrazu vo vnútri zložených zátvoriek - hovoríme tomu interpolácia - pár príkladov je ${1 + 2} a $ {variableName}
- Značky FTL sú ako značky HTML (ale obsahujú # alebo @) a FreeMarker ich napríklad interpretuje
- Komentáre vo FreeMarker začínajú na <#– a končiť s –>
3. Zahrnúť značku
FTL zahrnúť smernica je spôsob, ako môžeme v našej aplikácii dodržiavať princíp DRY. Definujeme opakujúci sa obsah v súbore a znova ho použijeme v rôznych šablónach FreeMarker s jedným zahrnúť značka.
Jedným z takýchto prípadov použitia je, keď chceme zahrnúť časť ponuky do mnohých stránok. Najskôr definujeme časť ponuky vo vnútri súboru - nazvime ju menu.ftl - s nasledujúcim obsahom:
Panel Pridať nový koncový bod
A na našej stránke HTML zahrňme vytvorené menu.ftl:
Stránka informačného panela
A do našich fragmentov môžeme zahrnúť aj FTL, čo je skvelé.
4. Manipulácia s existenciou hodnoty
FTL zváži akékoľvek nulový hodnota ako chýbajúca hodnota. Preto musíme byť obzvlášť opatrní a pridať logiku nulovývnútri našej šablóny.
Môžeme použiť ?? operátor na kontrolu, či existuje atribút alebo vnorená vlastnosť. Výsledok je logický:
$ {attribute ??}
Atribút sme teda otestovali nulový, ale to nie je vždy dosť. Teraz definujme predvolenú hodnotu ako záložnú pre túto chýbajúcu hodnotu. Aby sme to dosiahli, potrebujeme ! operátor umiestnený za názvom premennej:
$ {attribute! 'predvolená hodnota'}
Pomocou okrúhlych zátvoriek môžeme zabaliť veľa vnorených atribútov.
Napríklad na kontrolu, či atribút existuje a či má vnorenú vlastnosť s inou vnorenou vlastnosťou, zabalíme všetko:
$ {(attribute.nestedProperty.nestedProperty) ??}
Napokon, keď dáme všetko dohromady, môžeme ich vložiť medzi statický obsah:
Testuje sa, či existuje vlastnosť študenta: $ {student ??? c}
Používa sa predvolená hodnota pre chýbajúceho študenta: $ {student! 'John Doe'}
Zabaľujú sa vnorené vlastnosti študentov: $ {(student.address.street) ??? c}
A ak študent boli nulový, videli by sme:
Testuje sa, že vlastnosť študenta existuje: nepravda
Používa sa predvolená hodnota pre nezvestného študenta: John Doe
Zabalené vnorené vlastnosti študenta: false
Prosím, všimnite si dodatočné ? c smernica použitá po ??. Urobili sme to preto, aby sme boolovskú hodnotu previedli na ľudsky čitateľný reťazec.
5. Značka If-Else
Ovládacie štruktúry sú obsiahnuté vo FreeMarker a tradičné if-else je pravdepodobne známe:
Kým ináč Ak a inak vetvy sú voliteľné, podmienky sa musia vyriešiť na boolovskú hodnotu.
Na pomoc pri našich hodnoteniach pravdepodobne použijeme jednu z týchto možností:
- x == r skontrolovať je X rovná sa r
- x! = r vrátiť sa pravda iba ak X sa líši od r
- x lt y znamená to X musí byť striktne menšia ako r - môžeme tiež použiť < namiesto lt
- x gt y hodnotí na pravda iba ak X je prísne väčší ako r - môžeme použiť > namiesto gt
- x lte y testy ak X je menšie alebo rovné r - alternatíva k lte je <=
- x gte y testy ak X je väčšie alebo rovné r - alternatíva k gte je> =
- X?? skontrolovať existenciu X
- postupnosť? seqContains (x) potvrdzuje existenciu X vo vnútri sekvencie
Je veľmi dôležité mať na pamäti to FreeMarker považuje> = a> za uzatváracie znaky pre značku FTL. Riešením je zabaliť ich použitie do zátvoriek alebo použitie gte alebo gt namiesto toho.
Zostavte to pre nasledujúcu šablónu:
$ {status.reason}
Chýba stav!
Nakoniec skončíme s výsledným kódom HTML:
404 nenájdené
Chýba stav!
6. Kontajnery čiastkových premenných
Vo FreeMarker máme tri typy kontajnerov pre pod premenné:
- Hashes sú postupnosťou párov kľúč - hodnota - kľúč musí byť vo vnútri hašovania jedinečný a nemáme objednávanie
- Sekvencie sú zoznamy, kde máme index spojený s každou hodnotou - pozoruhodným faktom je, že sub-premenné môžu byť rôznych typov
- Zbierky sú špeciálnym prípadom sekvencií, kde nemôžeme získať prístup k veľkosti alebo načítať hodnoty pomocou indexu - stále ich môžeme iterovať pomocou zoznam tag hoci!
6.1. Iterujúce položky
Môžeme iterovať nad nádobou dvoma základnými spôsobmi. Prvá je miesto, kde iterujeme každú hodnotu a logicky sa deje s každou z nich:
Alebo, keď chceme iterovať a Hash, prístup ku kľúču aj k hodnote:
Druhá forma je výkonnejšia, pretože nám tiež umožňuje definovať logiku, ktorá by sa mala stať v rôznych krokoch iterácie:
The položka predstavuje názov premennej so smyčkami, ale môžeme ju premenovať na to, čo chceme. The inak pobočka je voliteľná.
Pre praktický príklad dobre definujte šablónu, kde uvádzame niektoré stavy:
- $ {status}
Nie sú k dispozícii žiadne stavy
Keď bude náš kontajner, vráti sa nám nasledujúci kód HTML [„200 OK“, „404 sa nenašlo“, „500 interná chyba servera“]:
- 200 OK
- 404 nenájdené
- 500 interná chyba servera
6.2. Manipulácia s položkami
Hash nám umožňuje dve jednoduché funkcie: kľúče - získať iba obsiahnuté kľúče a - hodnoty načítať iba hodnoty.
Sekvencia je zložitejšia; môžeme zoskupiť najužitočnejšie funkcie:
- kus a pripojiť sa aby ste dostali podsekvenciu alebo spojili dve sekvencie
- obrátiť, triediť, a triediť podľa na úpravu poradia prvkov
- najprv a posledný získa prvý, respektíve posledný prvok
- veľkosť predstavuje počet prvkov v poradí
- seqObsahuje, seqIndexOfalebo seqLastIndexOf hľadať prvok
7. Manipulácia s typom
FreeMarker prichádza s obrovskou škálou funkcií (integrovaných) dostupných pre prácu s objektmi. Pozrime sa na niektoré často používané funkcie.
7.1. Manipulácia s reťazcami
- url a urlPath bude URL uniknúť z reťazca, s tou výnimkou urlPath neunikne lomítko /
- jString, jsString, a jsonString použije únikové pravidlá pre Java, Javascript a JSON
- čiapkaPrvý, uncapFirst, veľké písmená, malými písmenami a kapitalizovať sú užitočné na zmenu veľkosti písmen nášho reťazca, čo vyplýva z ich mien
- boolovský, dátum, čas, Dátum Čas a číslo sú funkcie na prevod z reťazca na iné typy
Teraz použijeme niekoľko z týchto funkcií:
$ {'// myurl.com/?search=Hello World'? urlPath}
$ {„Používanie“ v texte '? JsString}
$ {'moja hodnota? upperCase}
$ {'01.01.2019'? Dátum ('rrrr-MM-dd')}
A výstup pre šablónu vyššie bude:
http% 3A // myurl.com /% 3Fsearch% 3DAhoj% 20svet
MOJE HODNOTY
V texte sa používa \ "
12.01.2019
Pri použití dátum sme tiež odovzdali vzor, ktorý sa má použiť na analýzu objektu String. FreeMarker používa lokálny formát, pokiaľ nie je uvedené inak, napríklad v povrázok funkcia dostupná pre dátumové objekty.
7.2. Spracovanie čísla
- okrúhly, poschodie a strop môže pomôcť so zaokrúhľovaním čísel
- abs vráti absolútnu hodnotu čísla
- povrázok prevedie číslo na reťazec. Môžeme tiež odovzdať štyri preddefinované formáty čísel: počítač, mena, čísloalebo percent alebo definujte náš vlastný formát ako [ “0.###” ]
Urobme reťazec niekoľkých matematických operácií:
$ {(7,3? Okrúhle + 3,4? Strop + 0,1234)? Reťazec ('0. ##')}
A ako sa dalo očakávať, výsledná hodnota je 11.12.
7.3. Spracovanie dátumu
- .teraz predstavuje aktuálny dátum a čas
- dátum, čas a Dátum Čas môže vrátiť sekcie dátumu a času objektu dátumu a času
- povrázok prevedie dátum a čas na reťazce - môžeme tiež odovzdať požadovaný formát alebo použiť preddefinovaný formát
Teraz dostaneme aktuálny čas a naformátujeme výstup na reťazec obsahujúci iba hodiny a minúty:
$ {. now? time? string ('HH: mm')}
Výsledný kód HTML bude:
15:39
8. Spracovanie výnimiek
Uvidíme dva spôsoby riešenia výnimiek pre šablónu FreeMarker.
Prvý spôsob je použitie pokus-uzdravenie tagy, ktoré definujú, čo by sme sa mali pokúsiť vykonať, a blok kódu, ktorý by sa mal vykonať v prípade chyby.
Syntax je:
Oboje pokus a zotaviť sa značky sú povinné. V prípade chyby vráti späť pokus o blok a vykoná iba kód v zotaviť sa oddiel.
Pri zohľadnení tejto syntaxe definujme našu šablónu ako:
Príprava na hodnotenie
Atribút je $ {attributeWithPossibleValue ??}
Atribút chýba
Hotovo s hodnotením
Kedy attributeWithPossibleValue chýba, uvidíme:
Príprava na hodnotenie
Atribút chýba
Hotovo s hodnotením
A výstup keď attributeWithPossibleValue existuje:
Príprava na hodnotenie
Atribút je v poriadku
Hotovo s hodnotením
Druhým spôsobom je nakonfigurovať FreeMarker, čo by sa malo stať v prípade výnimiek.
S Spring Boot to ľahko konfigurujeme pomocou súboru vlastností; tu sú niektoré dostupné konfigurácie:
- spring.freemarker.setting.template_exception_handler = rethrow znovu hodí výnimku
- spring.freemarker.setting.template_exception_handler = debug na výstup odošle informácie o sledovaní zásobníka klientovi a potom znova vyvolá výnimku.
- spring.freemarker.setting.template_exception_handler = html_debug odošle informácie o sledovaní zásobníka klientovi, naformátuje ich tak, aby boli zvyčajne dobre čitateľné v prehliadači, a potom znova vyvolá výnimku.
- spring.freemarker.setting.template_exception_handler = ignorovať preskočí zlyhané pokyny a nechá šablónu pokračovať vo vykonávaní.
- spring.freemarker.setting.template_exception_handler = predvolené
9. Metódy volania
Niekedy chceme volať metódy Java z našich šablón FreeMarker. Teraz uvidíme, ako na to.
9.1. Statickí členovia
Aby sme mohli začať pristupovať k statickým členom, mohli by sme buď aktualizovať našu globálnu konfiguráciu FreeMarker, alebo pridať S.taticModels atribút typu na modeli pod názvom atribútu statika:
model.addAttribute ("statika", nový DefaultObjectWrapperBuilder (nová verzia ("2.3.28")) .build (). getStaticModels ());
Prístup k statickým prvkom je priamy.
Najskôr importujeme statické prvky našej triedy pomocou tagu assign, potom rozhodneme o mene a nakoniec o triede Java.
Takto importujeme Matematika triedy v našej šablóne, ukážte hodnotu statickej PI pole a použite statické pow metóda:
Hodnota PI: $ {MathUtils.PI}
2 * 10 je: $ {MathUtils.pow (2, 10)}
Výsledný kód HTML je:
Hodnota PI: 3,142
2 * 10 je: 1 024
9.2. Členovia fazule
Členovia fazule sú veľmi ľahko prístupní: použite bodku (.) a to je všetko!
Pre náš ďalší príklad pridáme a Náhodné namietajte proti nášmu modelu:
model.addAttribute ("random", new Random ());
V našej šablóne FreeMarker vygenerujme náhodné číslo:
Náhodná hodnota: $ {random.nextInt ()}
To spôsobí výstup podobný:
Náhodná hodnota: 1 329 970 768
9.3. Vlastné metódy
Prvým krokom pre pridanie vlastnej metódy je mať triedu, ktorá implementuje FreeMarker's TemplateMethodModelEx rozhranie a definuje našu logiku vo vnútri vykon metóda:
verejná trieda LastCharMethod implementuje TemplateMethodModelEx {verejný objekt exec (zoznam argumentov) hodí TemplateModelException}
Pridáme inštanciu našej novej triedy ako atribút do modelu:
model.addAttribute ("lastChar", nová LastCharMethod ());
Ďalším krokom je použitie našej novej metódy v našej šablóne:
Príklad posledného znaku: $ {lastChar ('mystring')}
Nakoniec je výsledný výstup:
Posledný znakový príklad: g
10. Záver
V tomto článku sme videli, ako používať šablónový modul FreeMarker v našom projekte. Zamerali sme sa na bežné operácie, spôsob manipulácie s rôznymi objektmi a niekoľko pokročilejších tém.
Implementácia všetkých týchto úryvkov je k dispozícii na GitHub.