Velocity käyttäjän opas on tarkoitettu sivusuunnittelijoille ja sisällöntuottajille avuksi tutustuttaessa Velocityyn ja sen yksinkertaiseen mutta tehokkaaseen skriptikieleen, Velocity Template Language:en (VTL). Useat tämän oppaan esimerkeistä käsittelevät Velocityn käyttämistä dynaamisen sisällön lisäämiseksi web sivuille, mutta kaikki VTL esimerkit toimivat HTML sivujen lisäksi yhtä hyvin myös muiden sivujen ja sivupohjien kanssa.
Kiitos että valitsit Velocityn!
Velocity on javapohjainen sivumoottori (template engine). Sen avulla sivusuunnittelijat voivat viitata java -koodissa määriteltyihin metodeihin. Sivusuunnittelijat voivat työskennellä java ohjelmoijien kanssa samanaikaisesti käyttäen Malli-Näkymä-Ohjain (Model-View-Controller, MVC) suunnittelumallia. MVC mallissa sivusuunnittelijat voivat keskittyä täysin luomaan hyvin suunniteltua sivustoa, ja ohjelmoijat voivat keskittyä koodaamaan ykkösluokan koodia. Velocity erottaa java -koodin web sivuista, tehden sivustosta pitkällä aikavälillä helpommin ylläpidettävän ja antamalla varteenotettavan vaihtoehdon JSP:lle (Java Server Pages) ja PHP:lle.
Velocityä voidaan käyttää web sivujen, SQL:n, PostScriptin ja muunlaisten tulosteiden tuottamiseen sivupohjista (template). Sitä voidaan käyttää joko itsenäisenä työkaluna lähdekoodin ja raporttien luomiseen, tai muihin järjestelmiin integroituna komponenttina. Velocity tarjoaa sivupohjaratkaisun Turbine web sovelluskehykselle. Yhdessä Velocity ja Turbine tarjoavat sivupohjaratkaisun jonka avulla web sovelluksia voidaan kehittää todellisen MVC -mallin mukaisesti.
Oletetaan että olet kuraa myyvän onlinekaupan sivusuunnittelija. Kutsumme kauppaa "Kurakauppa Online":ksi. Kauppa käy hyvin. Asiakkaat tilaavat vaihtelevia määriä eri kuratyyppejä. He pääsevät tutkimaan tekemiään tilauksia sekä tekemään uusia ostoja kirjautumalla sivullesi käyttäen käyttäjätunnustaan ja salasanaansa. Tällä hetkellä suosittu Terracotta -kura on alennusmyynnissä. Pieni osa asiakkaistasi ostaa säännöllisesti Kirkkaanpunaista Kuraa, joka myös on alennusmyynnissä, mutta pienemmän suosionsa vuoksi yleensä mainittu sivulla hieman syrjässä. Tiedot kustakin asiakkaasta talletetaan tietokantaan, joten eräänä päivänä herää kysymys; Miksipä emme käyttäisi Velocityä kohdentamaan erikoistarjouksia kurasta asiakkaille jotka ovat kiinnostuneita juuri tuosta kuratyypistä?
Velocityn avulla verkkosivut on helppo personoida kävijöidesi mukaan. Kurakauppa Onlinen sivusuunnittelijana haluat tehdä sivun jonka asiakas näkee kirjauduttuaan järjestelmään.
Tapaat yrityksesi ohjelmoijat ja sovitte, että muuttuja $asiakas pitää sisällään tiedot parhaillaan kirjautuneena olevasta asiakkaasta. Muuttujassa $kuratTarjouksessa ovat tiedot kuratyypeistä jotka ovat parhaillaan erikoistarjouksessa. $tarjous objektissa on metodeja jotka auttavat mainostamisessa. Tällä kertaa keskitymme vain näihin kolmeen viittaukseen. Muista, että sinun ei tarvitse huolehtia siitä kuinka ohjelmoijat hakevat tarvittavat tiedot tietokannasta, sinun tarvitsee tietää vain että se toimii. Näin pääset tekemään omaa työtäsi ja ohjelmoijat pääsevät tekemään omaansa.
Voisit lisätä seuraavat VTL lauseen sivulle:
<HTML>
<BODY>
Hei $asiakas.Nimi!
<table>
#foreach( $kura in $kuratTarjouksessa )
#if ( $asiakas.onOstanut($kura) )
<tr>
<td>
$tarjous.haePromo( $kura )
</td>
</tr>
#end
#end
</table>
foreach lauseen toiminta kuvataan yksityiskohtaisemmin jäljempänä; tärkeää tässä on tämän lyhyen skriptin tekemä vaikutus sivullesi. Kun Kirkkaanpunainen Kura on alennusmyynnissä ja sitä joskus aiemmin ostanut asiakas kirjautuu sisään, asiakas näkee ilmoituksen alennuksesta parhaalla mahdollisella paikalla. Jos toinen, Terracottakuraa ostanut asiakas kirjautuu järjestelmään, ilmoitus Terracottakuran alennusmyynnistä näkyy hänelle ensimmäisenä. Velocity on joustava ja sen käytössä vain mielikuvituksesi on rajana.
VTL hakemistossa on kuvattu Velocityn kaikki elementit jotka yhdessä antavat käyttöösi tehokkaan ja joustavan työkalun jota tarvitset luodaksesi web sivuistasi dynaamisen. Pääset hyödyntämään Velocityn voimaa jatkuvasti paremmin sitä mukaa kun opit käyttämään näitä elementtejä.
Velocityn sivunkuvauskieli (Velocity Template Language, VTL) tarjoaa helpon ja yksinkertaisen keinon liittää dynaamista sisältöä web sivulle. Dynaamisen sisällön käyttäminen pitäisi onnistua nopeasti jopa sellaiselta sivusuunnittelijalta jolla on ohjelmointikokemusta vain vähän, tai ei ollenkaan.
VTL käyttää viittauksia dynaamisen aineiston lisäämiseen verkkosivulle. Muuttujat ovat yhdentyyppisiä viittauksia. Muuttujat voivat viitata johonkin java -koodissa määriteltyyn, tai niiden arvo voidaan määrittää web -sivulla annetun VTL lauseen avulla. Seuraavassa on esimerkki VTL lauseesta joka voidaan lisätä HTML -dokumenttiin:
#set( $a = "Velocity" )
Kuten kaikki VTL lauseet (statement), tämäkin lause alkaa # merkillä ja sisältää ohjeen (directive): set. Kun verkkosivun käyttäjä hakee sivun Velocity etsii sivupohjastasi kaikki # -merkit. Sitten se tulkitsee mitkä niistä merkitsevät VTL lausetta, ja mitkä # merkeistä ovat osa sivujesi normaalia HTML -koodia, eivätkä kuulu VTL -koodiin.
# merkkiä seuraa ohje, set. set ohjeen jälkeen tulee suluissa ilmaus (expression), -- yhtälö joka määrittää arvonmuuttujalle. Muuttuja on ilmaistu vasemmalla ja arvo oikealla puolella. Nämä on erotettu = merkillä.
Yllä olevassa esimerkissä muuttuja on $a ja arvo on Velocity. Kaikkien viittausten tapaan tämäkin muuttuja alkaa $ merkillä. Arvot ovat aina lainausmerkkien sisällä; Velocityssä muuttujien datatyypeistä ei tule sekaannuksia, koska vain merkkijonoja (string) voi antaa muuttujien arvoksi.
Seuraava nyrkkisääntö voi auttaa ymmärtämään Velocityn toimintaa: Viittaukset alkavat $ merkillä ja niitä käytetään jonkin hakemiseen. Ohjeet alkavat # merkillä ja niitä käytetään jonkin suorittamiseen.
Yllä olevassa esimerkissä #set -ohjetta käytetään arvon määrittämiseksi muuttujaan. Muuttujaa $a voidaan tämän jälkeen käyttää sivupohjassa tulostamaan "Velocity".
Kun muuttujalle on määritelty arvo, voidaan siihen viitata missä tahansa paikassa HTML dokumenttia. Seuraavassa esimerkissä muuttujalle $foo määritellään arvo. Myöhemmin muuttujaan viitataan.
<html> <body> #set( $foo = "Velocity" ) Hei $foo Maailma! </body> <html>
Tuloksena on web sivu jossa lukee "Hei Velocity Maailma!".
Jotta VTL lauseet olisivat helpommin luettavissa on suositeltavaa aloittaa jokainen lause uudelta riviltä, vaikkakaan tämä ei ole pakollista. set ohjeeseen palaamme tarkemmin myöhemmin.
Kommenttien avulla sivulle voidaan lisätä aputekstejä jotka eivät tule näkymään sivun tulosteessa. Voit käyttää kommentteja muistuttaaksesi itseäsi jostakin tai selittääksesi muille mitä VTL komennot tekevät, tai mihin tahansa muuhun tarkoitukseen. Alla on esimerkki kommentin käytöstä.
## Tämä on rivin pituinen kommentti.
Yhden rivin pituinen kommentti alkaa ## merkeillä ja loppuu kyseisen rivin lopussa. Jos aiot kirjoittaa usean rivin mittaisen kommentin, ei sinun tarvitse kirjoittaa useita yhden rivin kommentteja. Usean rivin kommentit alkavat #* merkeillä ja loppuvat *# merkkeihin.
Tämä teksti on kommenttimerkkien ulkopuolella. Käyttäjät näkevät tämän tekstin. #* Monirivinen kommentti alkaa tästä. Käyttäjät eivät näe tätä tekstiä koska Velocityn sivumoottori ei näytä kommenttimerkkien sisällä olevaa tekstiä tulosteessaan. *# Tämä teksti on jälleen kommenttimerkkien ulkopuolella; se on näkyvissä.
Tässä on muutamia esimerkkejä yksi- ja monirivisten kommenttien toiminnan selvittämiseksi:
Tämä teksti on näkyvissä. ## Tämä teksti ei ole. Tämä teksti on näkyvissä. Tämä teksti on näkyvissä. #* Tämä teksti on osa monirivistä kommenttia eikä siksi ole näkyvissä. Tämä teksti ei edelleenkään ole näkyvissä koska se on kommenttimerkkien sisällä. *# Tämä teksti on kommenttimerkkien ulkopuolella, joten se on näkyvissä. ## Tämä teksti ei ole näkyvissä.
On olemassa vielä kolmaskin kommenttityyppi; VTL kommenttilohko, jota voidaan käyttää mm. dokumentin tekijä- ja versiotietojen tallettamiseen
#** Tämä on VTL kommenttilohko. Lohkoa voidaan käyttää esimerkiksi dokumentin tekijä- ja versiotietojen tallettamiseen: @author @version 5 *#
VTL:ssä on kolme erityyppistä viittausta: muuttujat, ominaisuudet ja metodit. VTL:ää käyttävänä sivusuunnittelijana sinun, ja javapuolta koodaavien ohjelmoijien on sovittava viittausten nimistä, jotta voit käyttää niitä sivupohjissasi.
Kaikkea viittauksissa olevaa ja niihin määriteltävää tietoa
käsitellään tekstityyppisenä. Jos on esimerkiksi määritelty
objekti $foo (Integer objekti), Velocity kutsuu objektin
.toString() metodia objektin arvon muuntamiseksi
tekstityyppiseksi.
Muuttujat
Muuttujan lyhyt merkintätapa koostuu ensimmäisenä olevasta "$"
merkistä, jonka jälkeen tulee VTL tunniste. VTL
tunnisteen on alettava aakkosnumeerisella merkillä (a..z tai
A..Z). Muuttujan loput merkit ovat rajoitettu seuraaviin:
Seuraavassa muutamia esimerkkejä toimivista muuttujaviittauksista:
$foo $kuraLinko $kura-linko $kura_linko $kuraLinko1
Kun VTL viittaa muuttujaan, kuten $foo, muuttuja voi saada arvonsa joko sivupohjassa olevalta set ohjeelta, tai java -koodista. Jos esimerkiksi javamuuttujalla $foo on arvo bar silloin kun sivupohjaa haetaan, bar korvaa kaikki $foo muuttujan esiintymiskohdat web sivulla. Toisaalta jos sivulle lisätään lause
#set( $foo = "bar" )
Sivun tuloste on sama kaikilla $foo muuttujan esiintymiskohdille jotka tulevat tämän lauseen jälkeen.
Ominaisuudet
Toinen VTL:n viittaustyyppi ovat ominaisuudet joilla on oma
tunnusomainen muotonsa. Lyhyt merkintätapa muodostuu ensimmäisenä
olevasta $ merkistä, jonka jälkeen tulee VTL tunniste,
jota seuraa piste (".") ja toinen VTL tunniste. Seuraavassa on
esimerkkejä toimivista ominaisuusviittauksista:
$asiakas.Osoite $ostos.Summa
Käsittelemme ensimmäisen esimerkin $asiakas.Osoite tarkemmin. Viittauksella voi olla kaksi merkitystä. Se saattaa tarkoittaa; hae asiakas nimisestä hashtable taulukosta arvo joka on liitetty avaimelle Osoite. Toisaalta $asiakas.Osoite voi myös viitata metodiin (käsittelemme metodeihin viittaavat viittaukset seuraavassa kappaleessa); $asiakas.Osoite saattaa olla lyhennetty muoto viittauksesta $asiakas.getOsoite(). Velocity tulkitsee sivua haettaessa kumpaa näistä vaihtoehdoista tarkoitetaan, ja palauttaa vastaavan arvon.
Metodit
Metodit ovat määritelty java -koodissa ja niiden avulla voidaan
suorittaa jokin toimenpide; esimerkiksi laskutoimitus tai jonkin
päätöksen tekeminen. Metodit ovat viittauksia jotka muodostuvat
aloittavasta "$" merkistä, jota seuraa VTL tunniste, jonka jälkeen
tulee VTL Metodirunko. VTL Metodirunko koostuu VTL
tunnisteesta jota seuraa vasen sulkumerkki "(", jota seuraa
valinnainen parametrilista, jota seuraa oikeanpuoleinen
sulkumerkki ")". Seuraavassa on esimerkkejä toimivista
metodiviittauksista:
$asiakas.getOsoite() $ostos.getSumma() $sivu.setOtsake( "Minun kotisivuni" ) $henkilo.setOminaisuudet( ["Outo", "Kummallinen", "Innostunut"] )
Metodirungossa esiintyvä get tarkoittaa "hae" ja set "aseta".
Kaksi ensimmäistä esimerkkiä -- $asiakas.getOsoite() ja $ostos.getSumma() -- näyttävät samanlaisilta kuin Ominaisuudet -osiossa aiemmin; $asiakas.Osoite ja $ostos.Summa. Jos arvasit että näillä esimerkeillä on jotakin yhteyttä toisiinsa, olit oikeassa!
VTL ominaisuuksia voidaan käyttää lyhyempinä muotoina VTL metodeista. Ominaisuudella $asiakas.Osoite on täysin sama vaikutus kuin käyttämällä metodia $asikas.getOsoite(). Yleisesti ottaen ominaisuuksien käyttö on suositeltavaa silloin kuin se vain on mahdollista. Suurin ero ominaisuuksien ja metodien välillä on se, että metodeille voi antaa parametreja.
Seuraavien metodien kanssa voidaan käyttää lyhyttä muotoa:
$aurinko.getPlaneetat() $mato.getMulta() $albumi.getValokuva()
Näiden metodien voisimme olettaa palauttavan auringolle kuuluvien planeettojen nimet, syöttävän matomme, tai hakevan valokuvan albumista. Seuraavissa metodeissa toimii vain pitkä muoto:
$aurinko.getPlaneetat( ["Maa", "Mars", "Neptunus"] ) ## lyhyessä muodossa $sun.Planets ei voida antaa parametreja $sisyphus.pushRock() ## Velocity olettaa että tarkoitan $sisyphus.getRock() $kirja.setOtsake( "Catalonian kotisivu" ) ## Parametrilistaa ei voida antaa
Muodollinen viittausten merkintä
Edellisissä esimerkeissä käytettiin viittauksille lyhyttä
merkintätapaa. Viittauksille on olemassa myös muodollinen
merkintätapa, jota käytetään seuraavissa esimerkeissä:
${kuraLinko}
${asiakas.Osoite}
${osto.getSumma()}
Voit käyttää lyhyttä muotoa viittauksiin lähes aina, mutta joissain tapauksissa muodollista viittausta tarvitaan virheettömän toiminnan turvaamiseksi.
Oletetaan että olet luomassa lausetta jonka sisältö riippuu muuttujasta. Muuttujaa $pahe käytetään pohjana luotaessa muuttujasta riippuvaista sanaa. Tarkoituksena on sallia käyttäjän valita pohjasana ja tuottaa toinen seuraavista tuloksista: "Juha on pyromaani." tai "Juha on kleptomaani.". Tässä tapauksessa lyhyen viittausmuodon käyttäminen ei toimisi. Tutki seuraavaa esimerkkiä:
Juha on $pahemaani.
Velocity olettaa että tarkoitat muuttujaa $pahemaani, vaikka käytettävä muuttuja oli $pahe. Koska Velocity ei löydä arvoa muuttujalle $pahemaani, se palauttaa $pahemaani. Tämä ongelma voidaan ratkaista käyttämällä muodollista viittausta.
Juha on ${pahe}maani.
Nyt Velocity ymmärtää että haluttu viittaus on $pahe, ei $pahemaani. Muodollinen viittausten merkintä on usein hyödyllinen silloin kun viittaukset ovat kiinni muussa tekstissä.
Hiljainen viittausten merkintä
Kun Velocityltä haetaan viittaus jolle ei ole määritelty arvoa,
palauttaa se normaalisti viittauksen tekstinä. Oletetaan
esimerkiksi että seuraavat viittaukset ovat osa VTL sivupohjaa:
<input type="text" name="email" value="$email"/>
Kun lomake latautuu ensimmäisen kerran muuttujaviittauksella $email ei ole arvoa. Oletuksena Velocity täyttää lomakkeen tekstillä "$email". Haluaisit kuitenkin kenttään mieluummin tyhjän arvon. Käyttämällä hiljaista viittausten merkintää voidaan Velocityn normaali toiminta estää; $email koodin sijaan käytät viittausta $!email. Yllä oleva koodi näyttäisi siis seuraavalta:
<input type="text" name="email" value="$!email"/>
Kun lomake latautuu ensimmäisen kerran eikä muuttujalla $email ole arvoa, tulostetaankin kenttään tyhjä teksti "$email" tekstin sijaan.
Muodollista ja hiljaista muuttujien merkintää voidaan käyttää myös yhdessä;
<input type="text" name="email" value="$!{email}"/>
VTL käyttää erikoismerkkejä kuten $ ja # omassa toiminnassaan, joten näiden merkkien käyttö sivupohjassa vaatii erityistä huolellisuutta. Tässä kappaleessa käsittelemme $ merkin suojaamisen (escape).
Dollari
Seuraavassa lauseessa dollarimerkin käytössä ei ole ongelmaa:
"Ostin markkinoilta säkin perunoita hintaan $2.50!". Kuten
mainittu, VTL tunniste alkaa aina aakkosmerkillä, joten merkintää
$2.50 ei ole vaaraa sekoittaa viittaukseksi.
VTL viittausten suojaaminen
Ongelmatilanne saattaa syntyä silloin, kun Velocity ei osaa
päätellä tarkoitetaanko dollarinmerkillä merkkiä itseään, vai
viittausta. Erikoismerkkien suojaaminen on paras keino
käsitellä VTL erikoismerkkejä sivupohjissa. Suojaamiseen käytetään
kenoviivaa ( \ ).
#set( $email = "foo" ) $email
Kun Velocity käsittelee $email viittauksen sivupohjassasi, se etsii löytyykö sen nimiselle muuttujalle arvoa. Tässä tapauksessa tuloste tulee olemaan foo, koska $email on määritelty. Jos $email muuttujaa ei olisi määritelty tulisi tulosteeksi $email.
Oletetaan että $email on määritelty (sillä on esimerkiksi arvo foo), ja että haluat muuttujan arvon sijaan tulostaa sen nimen $email. Tämä saavuttamiseksi on useita keinoja, joista helpoin on suojausmerkin käyttäminen.
## Seuraava rivi määrittelee muuttujan $email tässä sivupohjassa: #set( $email = "foo" ) $email \$email \\$email \\\$email
tulosteeksi tulee
foo $email \foo \\$email
Huomaa $ merkin eteen liitetty \ merkki. Suojausmerkit tulkitaan vasemmalta oikealle, joten \\\$email tulostuu \\$email. Vertaa näitä esimerkkejä tulosteeseen joka saadaan kun $email muuttujaa ei ole määritelty.
$email \$email \\$email \\\$email
tulosteeksi tulee
$email \$email \\$email \\\$email
Huomaa kuinka Velocity käsittelee eri tavalla viittaukset joiden arvo on määritelty niistä joita ei ole määritelty. Seuraavassa on set ohje joka asettaa $foo muuttujalle arvon gibbous.
#set( $foo = "gibbous" ) $kuu = $foo
Tulosteeksi tulee: $kuu = gibbous -- missä $kuu tulostetaan muuttujan nimenä, koska sen arvoa ei ole määritelty ja gibbous tulostetaan muuttujan $foo arvona.
Myös VTL ohjeiden suojaaminen on mahdollista; tämä kuvataan tarkemmin Ohjeet -kappaleessa.
Kun nyt olet tutustunut viittauksiin, voit alkaa käyttämään niitä tehokkaasti omissa sivupohjissasi. Viittaukset Velocityssä käyttävät hyväkseen joitakin java kielen perusperiaatteita, joiden käyttö helpottaa sivusuunnittelijoiden työtä. Esimerkiksi:
$foo
$foo.getBar()
## on sama kuin
$foo.Bar
$data.setKayttaja("juha")
## on sama kuin
#set( $data.Kayttaja = "juha" )
$data.getPyynto().getPalvelinNimi()
## on sama kuin
$data.Pyynto.PalvelinNimi
## on sama kuin
${data.Pyynto.PalvelinNimi}
Nämä esimerkit havainnollistavat viittauksen vaihtoehtoisia merkitsemistapoja. Velocity käyttää hyväkseen javan introspection ja bean -ominaisuuksia objektien sekä niiden metodien viittausnimiä ratkaistaessa. Viittauksia voidaan lisätä lähes mihin kohtaan tahansa sivupojassa.
Velocity on tehty Sun Microsystemsin määrittelemän Bean
määrityksen mukaiseksi, ja on tästä syystä pieni-iso-eroava
(ts. pienet ja isot kirjaimet käsitellään eri
merkkeinä). Velocityn kehittäjät ovat tehneet parhaansa jotta
mahdolliset kirjoitusvirheet voitaisiin korjata
automaattisesti. Kun sivupohjassa viitataan metodiin
getFoo() koodilla $bar.foo, Velocity
kokeilee ensin viittausta $getfoo. Jos tämä ei tuota
tulosta, seuraavaksi yritetään viittausta
$getFoo. Samalla tavalla, kun sivupohjassa viitataan
muuttujaan $bar.Foo, ensin yritetään viittausta
$getFoo() ja sitten getfoo().
Huomaa: Viittauksia ilmentymämuuttujiin (instance variables)
ei ratkaista. Vain viittaukset JavaBeanin mukaisiin
haku/asetus (getter/setter) metodeihin ratkaistaan (toisin sanoen
$foo.Name ratkaistaan Foo -luokan
getName() ilmentymämetodiin (instance method), mutta
ei luokan Foo julkiseen (public) Name
ilmentymämuuttujaan).
Ohjeet ovat helppokäyttöisiä skriptielementtejä joita voidaan käyttää web sivun tulosteen manipuloimiseen. Viittausten avulla sivupohjien suunnittelijat voivat tuottaa web sivuille dynaamista sisältöä, kun taas ohjeet antavat mahdollisuuden määritellä sivuston ulkoasun ja sisällön.
#set#set ohjetta käytetään arvon määrittämiseksi viittaukselle. Arvo voidaan määrittää joko muuttujaviittaukselle tai ominaisuusviittaukselle. Määritys tehdään suluissa, kuten seuraavassa esimerkissä:
#set( $kadellinen = "apina" ) #set( $asiakas.Kayttaytyminen = $kadellinen )
Määrityksen vasemman puolen (left hand side, LHS) tulee olla muuttuja- tai ominaisuusviittaus. Oikea puoli (right hand side, RHS) voi olla jokin seuraavista tyypeistä:
Seuraavassa esimerkit kustakin mainitusta tyypistä:
#set( $apina = $bill ) ## muuttujaviittaus #set( $apina.Ystava = "monica" ) ## tekstivakio #set( $apina.Syytos = $valkoinentalo.vuoto ) ## ominaisuusviittaus #set( $apina.Suunnitelma = $spindoctor.weave($web) ) ## metodiviittaus #set( $apina.Numero = 123 ) ## numeerinen vakio #set( $apina.Sano = ["Ei", $minun, "vikani"] ) ## taulukko
HUOMAA: Viimeisessä esimerkissä [..] operaattorilla määritetyt elementit ovat käytettävissä ArrayList -luokan metodien avulla. Voisit siis esimerkiksi viitata taulukon ensimmäiseen elementtiin koodilla $apina.Sano.get(0).
Oikeanpuoleinen arvo (RHS) voi olla myös yksinkertainen matemaattinen operaatio:
#set( $arvo = $foo + 1 ) #set( $arvo = $bar - 1 ) #set( $arvo = $foo * $bar ) #set( $arvo = $foo / $bar )
Jos määrityksen oikeanpuoleinen ominaisuus- tai metodiviittaus on arvoa null, sitä ei anneta vasemman puolen arvoksi. Tätä keinoa ei voida käyttää olemassa olevan viittauksen poistamiseen. Tämä saattaa olla hämäävää Velocityn uusille käyttäjille. Esimerkiksi:
#set( $tulos = $kysely.kriteeri("nimi") )
Ensimmäisen kyselyn tulos on $tulos
#set( $tulos = $kysely.kriteeri("osoite") )
Toisen kyselyn tulos on $tulos
Jos $kysely.kriteeri("nimi") palauttaa merkkijonon "pete", ja $kysely.kriteeri("osoite") palauttaa arvon null, on esimerkin tuloste seuraava:
Ensimmäisen kyselyn tulos on pete Toisen kyselyn tulos on pete
Tällä on vaara hämätä aloittelijoita jotka muodostavat #foreach silmukoita joissa yritetään asettaa #set ohjeella viittausta ominaisuus- tai metodiviittauksella, ja sen jälkeen testataan tuota viittausta #if ohjeella. Esimerkiksi:
#set( $kriteerit = ["nimi", "osoite"] )
#foreach( $kriteeri in $kriteerit )
#set( $tulos = $kysely.kriteerit($kriteeri) )
#if( $tulos )
Kysely onnistui
#end
#end
Yllä olevassa esimerkissä ei kannata luottaa $tulos muuttujan vertaamiseen kyselyn onnistumisen selville saamiseksi. Kun $tulos on asetettu #set ohjeella (lisatty kontekstiin), sitä ei voida asettaa null:iksi (poistaa kontekstista). #if ja #foreach ohjeet käsitellään tarkemmin myöhemmin tässä dokumentissa.
Yksi ratkaisu ongelmaan olisi asettaa $tulos etukäteen arvoon false (epätosi). Tämän jälkeen jos kutsu $kysely.kriteeri() epäonnistuu, voit tarkastaa arvon.
#set( $kriteerit = ["nimi", "osoite"] )
#foreach( $kriteeri in $kriteeri )
#set( $tulos = false )
#set( $tulos = $kysely.kriteerit($kriteeri) )
#if( $tulos )
Kysely onnistui
#end
#end
Muutamista muista Velocityn ohjeista poiketen, #set ohje ei käytä #end lausetta.
Tekstivakiot#set ohjetta käytettäessä lainausmerkkeihin (" ") suljettu teksti tulkitaan ja tulostetaan kuten seuraavasta esimerkistä käy ilmi:
#set( $hakemistoJuuri = "www" ) #set( $sivupohjaNimi = "index.vm" ) #set( $sivupohja = "$hakemistoJuuri/$sivupohjaNimi" ) $sivupohja
Tulosteeksi tulee
www/index.vm
Jos teksti on suljettu hipsuihin (' '), sitä ei tulkita:
#set( $foo = "bar" ) $foo #set( $blargh = '$foo' ) $blargh
bar $foo
Tulkitsemattoman tekstin tulostaminen hipsumerkkien sisällä
olevavasta tekstistä on oletuksena käytössä
Velocityssä. Oletusarvo voidaan muuttaa vaihtamalla
velocity.properties siten että
stringliterals.interpolate=false.
#if ohjeen avulla voidaan teksti sisällyttää web sivulle sillä ehdolla että if lauseen arvo on tosi. Esimerkiksi:
#if( $foo ) <strong>Velocity!</strong> #end
Muuttuja $foo testataan jotta nähdään onko se tosi, joka tapahtuu kahdessa eri tapauksessa: (i) $foo on boolean arvo (tosi/epätosi) jolla on tosi -arvo, tai (ii) arvo on eri kuin null (eli muuttuja ei ole tyhjä). #if ja #end lauseiden väliin jäävä sisältö tulostetaan mikäli testimuuttuja on tosi. Esimerkkitapauksessamme, jos muuttujalla $foo on null arvo, tai jos se on boolean epätosi, on testimuuttuja epätosi, eikä tulostetta tule lainkaan.
#if ja #end lauseiden välissä oleva teksti tulee tulosteeksi mikäli ehto on tosi. Tässä tapauksessa jos $foo on tosi, tulosteeksi tulee: "Velocity!". Toisaalta, mikäli $foo on epätosi, on myös ehtolause epätosi eikä tulostetta tule.
#elseif tai #else elementtejä voidaan käyttää #if elementin kanssa. Huomaa, että Velocityn sivumoottori lopettaa ensimmäisen tosiarvon saaneen testimuuttujan kohdalla. Oletetaan seuraavassa esimerkissä että muuttujalla $foo on arvo 15 ja muuttujalla $bar on arvo 6.
#if( $foo < 10 )
<strong>Mene pohjoiseen</strong>
#elseif( $foo == 10 )
<strong>Mene itään</strong>
#elseif( $bar == 6 )
<strong>Mene etelään</strong>
#else
<strong>Mene länteen</strong>
#end
Tässä esimerkissä $foo on suurempi kuin 10, joten kaksi ensimmäistä vertailua eivät ole tosia. Seuraavaksi muuttujaa $bar verrataan lukuun 6, joka on tosi, joten tulosteeksi tulee Mene etelään.
Relaatio- ja loogiset operaattorit
Velocity käyttää vastaavuusoperaattoria muuttujien välisten suhteiden tulkitsemiseen. Seuraavassa on yksinkertainen esimerkki vastaavuusoperaattorin käytöstä.
#set ($foo = "deoksiribonukleiinihappo") #set ($bar = "ribonukleiinihappo") #if ($foo == $bar) Muuttujat eivät selvästikään ole samanlaiset. Joten... #else Vastaavuusvertaus on epätosi, ja tämä teksti tulee tulosteeksi. #end
Velocity tukee myös loogisia AND ja OR operaattoreita. Lisätietoja löydät dokumentista VTL Reference Guide. Alla on esimerkkilause joka käyttää loogista AND:iä.
## looginen AND #if( $foo && $bar ) <strong> Tämä JA tuo</strong> #end
If lause on tosi vain mikäli sekä $foo että $bar ovat tosia. Jos $foo on epätosi, tulee lauseesta epätosi eikä $bar muuttujaa tarvitse edes testata. Jos $foo on tosi, testataan sen jälkeen muuttujan $bar arvo; jos myös $bar on tosi, silloin koko ilmaus on tosi ja Tämä JA tuo tulee tulosteeksi. Jos $bar on epätosi, silloin koko ilmaus on epätosi eikä tulostetta tule.
Looginen OR operaattori toimii samaan tapaan, paitsi että vain toisen viittauksen pitää olla tosi jotta koko ilmaus olisi tosi. Katso seuraavaa esimerkkiä.
## looginen OR
#if( $foo || $bar )
<strong>Tämä TAI tuo</strong>
#end
Jos $foo on tosi, ei $bar muuttujaa tarvitse edes testata. Oli $bar sitten tosi tai epätosi, koko lauseke on tosi, ja Tämä TAI tuo on tulosteena. Toisaalta mikäli $foo on epätosi, on muuttujan $bar arvo testattava. Jos tässä tapauksessa myös $bar on epätosi, koko ilmauksesta tulee epätosi eikä tulostetta tule. Jos $bar on tosi, silloin koko ilmauksesta tulee tosi, ja tulosteena on Tämä TAI tuo.
Loogisella EI (NOT) operaattorilla on vain yksi argumentti :
## looginen NOT #if( !$foo ) <strong>EI tuota</strong> #end
Jos $foo on tosi, silloin !$foo on epätosi, eikä tulostetta tämän vuoksi tule. Mikäli $foo on epätosi, silloin !$foo on tosi ja EI tuota on tulosteena. Älä sekoita tätä merkintää hiljaiseen viittaukseen $!foo joka tarkoittaa jotakin aivan muuta.
#foreach mahdollistaa silmukoiden tekemisen. Esimerkiksi:
<ul>
#foreach( $tuote in $kaikkiTuotteet )
<li>$tuote</li>
#end
</ul>
Tämä #foreach silmukka käy läpi yksi kerrallaan kaikki $kaikkiTuotteet listassa olevat tuotteet. Jokaisella kierroksella seuraavan tuotteen arvo kopioidaan $kaikkiTuotteet listasta muuttujaan $tuote.
$kaikkiTuotteet lista on tyyppiä Vector, Hashtable tai Array. $tuote muuttujaan kopioitu arvo on java objekti (Object), joten siihen voidaan myös viitata objektina. Jos esimerkiksi $tuote muuttuja olisi tyyppiä Tuote, sen nimi voitaisiin hakea viittaamalla $tuote.Name metodiin (ts. $Tuote.getName().
Oletetaan että $kaikkiTuotteet on tyyppiä Hashtable. Jos haluat hakea Hashtablen avainarvot sekä niihin liittyvät objektit, voit käyttää seuraavanlaista koodia:
<ul>
#foreach( $avain in $kaikkiTuotteet.keySet() )
<li>Avain: $avain -> Arvo: $kaikkiTuotteet.get($avain)</li>
#end
</ul>
Velocityllä on helppo keino silmukkalaskurin käyttämiseen. Voit käyttää laskuria esimerkiksi seuraavasti:
<table>
#foreach( $asiakas in $asiakasLista )
<tr><td>$foreach.count</td><td>$asiakas.Nimi</td></tr>
#end
</table>
#include elementin avulla sivusuunnittelija voi hakea paikallisesta tiedostojärjestelmästä tiedoston, jonka sisältö lisätään sivun siihen kohtaan jossa #include määritys tehtiin. Tiedoston sisältö liitetään sellaisenaan eikä sitä siis käytetä Velocityn sivumoottorin kautta. Turvallisuussyistä haettava tiedosto voi sijaita vain TEMPLATE_ROOT vakion määrittämän hakemiston alla.
#include( "yksi.txt" )
Tiedosto johon #include ohje viittaa on lainausmerkeissä. Jos halutaan sisällyttää useampia kuin yksi tiedosto, tiedostonimet tulee erotella toisistaan pilkuilla.
#include( "yksi.gif","kaksi.txt","kolme.htm" )
Sisällytettävään tiedoston ei ole pakko viitata nimen perusteella; itse asiassa usein on parempi käyttää muuttujaa tiedostonimen asemesta. Tämä on hyödyllistä esimerkiksi silloin kun sivun ulkoasu riippuu sivupyynnön aikana päätettävästä ehdosta. Seuraavassa on esimerkki jossa käytetään sekä tiedostonimeä että muuttujaa.
#include( "terveiset.txt", $sesonkivarasto )
#parse elementin avulla sivusuunnittelija voi sisällyttää paikallisesta levyjärjestelmästä tiedostoja jotka sisältävät VTL elementtejä. Velocity tulkitsee VTL komennot ja tulostaa tuloksen.
#parse( "mina.vm" )
#include ohjeen tapaan #parse voi ottaa parametrikseen nimen lisäksi myös muuttujan. Kaikkien sivupohjien joihin #parse ohjeella viitataan tulee sijaita TEMPLATE_ROOT vakion määrittämän hakemiston alla. #include ohjeesta poiketen #parse voi ottaa vain yhden argumentin.
VTL sivupohjissa voi olla #parse ohjeita jotka viittaavat
sivupohjiin joissa niissäkin on #parse
ohjeita. velocity.properties tiedostossa oleva rivi
parse_directive.maxdepth määrittää sen kuinka monta
peräkkäistä #parse viittausta voidaan tehdä. Mikäli
parse_directive.maxdepth määritys puuttuu, käytetään
oletusarvoa 10. Rekursiivisuus on sallittu. Jos esimerkiksi
sivupohja dofoo.vm sisältää seuraavat rivit:
Laske alaspäin. #set( $laskuri = 8 ) #parse( "parsefoo.vm" ) Kaikki valmista: dofoo.vm!
Koodi viittaisi sivupohjaan parsefoo.vm, jossa
puolestaan voisi olla seuraavat VTL komennot:
$laskuri
#set( $laskuri = $laskuri - 1 )
#if( $laskuri > 0 )
#parse( "parsefoo.vm" )
#else
Kaikki valmista: parsefoo.vm!
#end
Kun "Laske alaspäin." on näytetty, Velocity lataa ja siirtää
kontrollin sivupohjalle parsefoo.vm, joka laskee alas
luvusta 8. Kun laskuri saavuttaa arvon 0, tulostetaan "Kaikki
valmista: parsefoo.vm!". Tämän jälkeen Velocity palaa sivupohjaan
dofoo.vm ja tulostaa "Kaikki valmista: dofoo.vm!"
tekstin.
#stop elementin avulla sivupohjan suunnittelija voi pysäyttää sivun tulkitsemisen. Tämä on hyödyllistä sivupohjan virheidenetsinnän aikana.
#stop
#macro elementin avulla sivupohjan suunnittelija voi määrittää toistuvasti käytetyn VTL sivupohjan osan. Velocimakrot ovat erittäin käyttökelpoisia sekä monimutkaisissa, että yksinkertaisissa tehtävissä. Seuraava Velocimakro toimii johdantona Velocimakroihin. Se on luotu kirjoitettavan tekstin määrän vähentämiseksi, sekä kirjoitusvirheiden määrän minimoimiseksi.
#macro( d ) <tr><td></td></tr> #end
Esimerkissä määriteltiin Velocimakro nimeltään d, ja sitä voidaan kutsua muiden VTL ohjeiden tapaan:
#d()
Kun tätä sivupohjaa haetaan, Velocity korvaa ohjeen #d() rivillä joka sisältää yhden tyhjän solun.
Velocimakro voi ottaa kuinka monta parametria tahansa -- tai ei yhtään parametria, kuten ensimmäisessä esimerkissämme -- mutta kun Velocimakroa kutsutaan, tulee kutsussa olla täsmälleen yhtä monta parametria kuin makroa määriteltäessä. Useimmat Velocimakrot ovat hieman monimutkaisempia kuin edellinen esimerkki. Seuraavassa on Velocimakro joka ottaa kaksi argumenttia; värin ja listan.
#macro( taulurivit $vari $jokulista )
#foreach( $jotain in $jokulista )
<tr><td bgcolor=$vari>$jotain</td></tr>
#end
#end
Tässä esimerkissä määriteltiin Velocimakro taulurivit joka ottaa kaksi parametria. Ensimmäinen parametri on $vari ja toinen $jokulista.
Velocimakroon voidaan kirjoittaa mitä tahansa koodia jota voidaan käyttää muuallakin VTL sivupohjassa. taulurivit Velocimakro on foreach lause. taulurivit Velocimakrossa on kaksi #end lausetta; ensimmäinen kuuluu #foreach lauseelle, jälkimmäinen päättää Velocimakron määrityksen.
#set( $suuretjarvet = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $vari = "blue" )
<table>
#taulurivit( $vari $suuretjarvet )
</table>
Huomaa että $suuretjarvet on makron parametrin $jokulista arvona. Kun Velocimakroa #taulurivit tässä tapauksessa kutsutaan, on tuloksena seuraavaa:
<table>
<tr><td bgcolor="blue">Superior</td></tr>
<tr><td bgcolor="blue">Michigan</td></tr>
<tr><td bgcolor="blue">Huron</td></tr>
<tr><td bgcolor="blue">Erie</td></tr>
<tr><td bgcolor="blue">Ontario</td></tr>
</table>
Velocimakroja voidaan määrittää inline, eli Velocity sivupohjassa itsessään, jolloin ko. makro ei ole käytettävissä muissa sivupohjissa. Velocimakron määrittäminen siten että se on kaikkien sivupohjien käytössä on hyödyllistä; samaa makroa ei tarvitse määrittää erikseen jokaisessa sivupohjassa jossa sitä tarvitaan, jolloin työmäärä ja virheiden mahdollisuus vähenee. Lisäksi makroon tehty muutos vaikuttaa heti kaikkiin sivupohjiin joissa se on käytössä.
Oletetaan että Velocityssä on määriteltynä Velocimakro
#tablerows($vari $lista). Tätä makroa voitaisiin käyttää
missä tahansa sivupohjassa. Sitä voitaisiin käyttää useaan kertaan
ja moneen eri käyttötarkoitukseen. Sieniasioita käsittelevässä
sivupohjassa sieni.vm, #tablerows
Velocimakroa voitaisiin käyttää listaamaan tyypillisen sienen
osat:
#set( $osat = ["volva","stipe","annulus","gills","pileus"] ) #set( $cellbgcol = "#CC00FF" ) <table> #tablerows( $cellbgcol $osat ) </table>
Kun Velocity luo sivun sivupohjasta sieni.vm, se
etsii Velocimakron #tablerows sivupohjakirjastosta (joka
on määritelty velocity.properties tiedostossa) ja
tuottaa seuraavan tulosteen:
<table>
<tr><td bgcolor="#CC00FF">volva</td></tr>
<tr><td bgcolor="#CC00FF">stipe</td></tr>
<tr><td bgcolor="#CC00FF">annulus</td></tr>
<tr><td bgcolor="#CC00FF">gills</td></tr>
<tr><td bgcolor="#CC00FF">pileus</td></tr>
</table>
Velocimakrot voivat ottaa argumenteiksi mitä tahansa seuraavista VTL elementeistä:
Kun siirrät viittauksia argumentteina Velocimakroille, huomaa, että viittaukset siirretään 'nimen mukaan' ('by name'). Tämä tarkoittaa sitä, että viittausten arvo 'haetaan' Velocimakrossa itsessään. Tämän ominaisuuden avulla voit siirtää viittauksia jotka ovat metodikutsuja, ja näin ko. metodeja kutsutaan Velocimakrossa. Esimerkiksi kun Velocimakroa kutsutaan seuraavasti:
#macro( kutsu $a )
$a $a $a
#end
#kutsu( $foo.bar() )
tuloksena viittauksen $foo metodia bar() kutsutaan 3 kertaa.
Ensi katsomalta tämä ominaisuus saattaa vaikuttaa yllättävältä, mutta kun otat huomioon Velocimakrojen alkuperäisen tarkoituksen -- usein käytettyjen VTL komentojen leikkaa-liimaa kopioimisen vähentäminen -- ominaisuus on perusteltu. Sen avulla voit esimerkiksi siirtää Velocimakroon argumenttina tilansa muistavia (stateful) objekteja, kuten objektin joka generoi värejä peräkkäisessä järjestyksessä taulukon rivien värien määrittämiseksi.
Jos sinun tarvitsee kiertää tämä ominaisuus, voit hakea arvon metodista uudeksi viittaukseksi, ja antaa sen argumentiksi:
#set( $uusiarvo = $foo.bar() )
#kutsu( $uusiarvo )
velocity.properties tiedostossa on useita rivejä
joiden avulla Velocimakrojen toimintaa voidaan muuttaa
joustavasti. Huomaa että nämä arvot on dokumentoitu myös Kehittäjän
oppaassa.
velocimacro.library - Pilkulla eroteltu lista
Velocimakro sivupohjakirjastoja. Oletuksena Velocity etsii yhtä
kirjastoa: VM_global_library.vm. Velocimakro kirjastoja
etsitään määritellystä sivupohjahakemistosta.
velocimacro.permissions.allow.inline - Tämä
ominaisuus päättää voidaanko Velocimakroja määrittää tavallisissa
sivupohjissa. Ominaisuus voi saada arvon true (tosi) tai false
(epätosi). Oletuksena on tosi, jolloin sivusuunnittelijat voivat
määrittää Velocimakroja suoraan omissa sivupohjissaan.
velocimacro.permissions.allow.inline.to.replace.global
- Tämän ominaisuuden avulla voidaan määrittää voivatko
sivupohjassa määritellyt Velocimakrot korvata yleisesti
määritellyt, velocimacro.library ominaisuuden kautta
ladatut Velocimakrot. Ominaisuus voi saada arvon true tai
false. Oletuksena false, epätosi, jolloin
sivupohjassa määritellyt Velocimakrot eivät voi korvata
sivupohjakirjastoista ladattuja makroja.
velocimacro.permissions.allow.inline.local.scope -
Mahdolliset arvot ovat true tai false, oletuksena false. Tämä
ominaisuus päättää ovatko sivupohjassa määritetyt Velocimakrot
'näkyviä' ainoastaan siinä sivupohjassa jossa ne on
määritelty. Toisin sanoen kun tämä ominaisuus on asetettu arvoon
true (tosi), sivupohja voi määrittää inline Velocimakroja jotka
ovat käytettävissä vain sivupohjasta joka ne määritti. Tämän
ominaisuuden avulla voidaan aikaansaada erikoisia vaikutuksia; jos
yleisesti määritelty Velocimakro kutsuu toista yleisesti
määriteltyä makroa, tämän ominaisuuden avulla sivupohja voi
määrittää oman toteutuksensa jälkimmäisestä makrosta, jota
ensimmäinen makro kutsuu. Sivupohjan paikallista makroa käytetään
vain kun ensimmäistä makroa kutsutaan ko. sivupohjasta. Uusi makro
ei vaikuta muihin sivupohjiin.
velocimacro.library.autoreload - Tämä ominaisuus
ohjaa Velocimakrokirjaston automaattista uudelleenlatausta. Kun
ominaisuus on asetettu arvoon true kutsutun
Velocimakron koodi tutkitaan mahdollisten muutosten varalta, ja se
ladataan uudelleen mikäli tarpeellista. Näin voit muuttaa ja
testata Velocimakrokirjastoa ilman että sinun tarvitsee käynnistää
uudelleen sovellustasi tai sovellusalustaa, aivan kuten voit tehdä
normaalien sivupohjienkin kanssa. Tämä asetus toimii vain kun
resurssilataajien välimuisti on pois päältä (off,
esim. file.resource.loader.cache = false). Tämä
ominaisuus on tarkoitettu käytettäväksi vain sovelluksen
kehitysvaiheessa, ei tuotantokäyttöön.
Nykyisellään Velocimakrot tulee olla määriteltyinä ennen kuin niitä käytetään sivupohjissa. Tämä tarkoittaa sitä että #macro() määritystesi tulee sijaita ennen rivejä joissa käytät Velocimakroja.
Tämä on tärkeää muistaa jos yrität käyttää ohjetta #parse()
sivupohjaan jossa on inline #macro() ohjeita. Koska #parse()
suoritetaan ajon aikana, ja parseri päättää ajon aikana onko
sivupohjassa oleva Velocimakrolta näyttävä elementti Velocimakro,
ei Velocimakrojen #parse():aminen toimi niin kuin
olettaisi. Ongelma voidaan välttää helposti käyttämällä
velocimacro.library toimintoa jonka avulla Velocity
lataa Velocimakrosi käynnistyksen yhteydessä.
VTL ohjeet voidaan suojata kenoviivalla ("\") samalla tavalla kuin VTL viittauksetkin.
## #include( "a.txt" ) tulostuu <tiedoston a.txt sisältö> #include( "a.txt" ) ## \#include( "a.txt" ) tulostuu #include( "a.txt" ) \#include( "a.txt" ) ## \\#include ( "a.txt" ) tulostuu \<tiedoston a.txt sisältö> \\#include ( "a.txt" )
Eritystä tarkkaavaisuutta tarvitaan tapauksissa joissa suojataan VTL ohjeita jotka sisältävät useita skriptielementtejä samassa ohjeessa (kuten if-else-end lause). Seuraavassa on tyypillinen VTL if-lause:
#if( $jazz )
Vyacheslav Ganelin
#end
Jos $jazz on tosi (true), tuloste on
Vyacheslav Ganelin
Jos $jazz on epätosi (false), tulostetta ei tule. Skriptielementtien suojaaminen muuttaa tulostetta. Katso seuraavaa esimerkkiä:
\#if( $jazz )
Vyacheslav Ganelin
\#end
Riippumatta siitä onko $jazz tosi vai epätosi, tuloste on aina:
#if($ jazz )
Vyacheslav Ganelin
#end
Itse asiassa koska kaikki skriptielementit on suojattu, $jazz muuttujan totuusarvoa ei edes tutkita. Oletetaan että kenoviiva edeltää skriptielementtejä jotka on suojattu:
\\#if( $jazz ) Vyacheslav Ganelin \\#end
Mikäli $jazz on tässä tapauksessa tosi, tuloste on:
\ Vyacheslav Ganelin \
Tämän ymmärtämiseksi huomaa, että #if( arg ) rivillä
olevaa rivinvaihtoa (return) ei kopioida tulosteeseen. Tämän vuoksi
#if() lauseen runko ('Vyacheslav Ganelin') on '\\'
merkinnästä saadun ensimmäisen '\' merkin kanssa samalla
rivillä. Jälkimmäinen '\' merkki on toisella rivillä kuin teksti,
koska tekstin lopussa on rivinvaihto ja jälkimmäinen '\\'
merkinnästä saatu '\' merkki on ennen #end ohjetta,
joten merkki kuuluu edelleen #if() lauseen runkoon.
Jos $jazz on epätosi, tuloste on:
\
Huomaa että ongelmia tulee mikäli skriptielementtejä ei ole suojattu oikein.
\\\#if( $jazz )
Vyacheslave Ganelin
\\#end
Esimerkissä #if on suojattu, mutta #end elementti on edelleen käytössä. Liian monta lopetuselementtiä sivupohjassa aiheuttaa virheen sivua luotaessa.
Vaikka tässä ohjeessa oleva VTL on usein muotoiltu rivivaihdoin ja välilyönnein, alla oleva VTL
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
$shogun
#end
on yhtä toimiva kuin seuraava kodinpätkä jonka Geir Magnusson Jr. lähetti Velocityn käyttäjien postituslistalle:
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
Velocity syö ylimääräiset välilyönnit. Edellinen koodinpätkä voitaisiin kirjoittaa seuraavasti:
Send me #set( $foo = ["$10 and ","a cake"] ) #foreach( $a in $foo ) $a #end please.
tai
Send me
#set($foo = ["$10 and ","a cake"])
#foreach ($a in $foo )$a
#end please.
Kussakin tapauksessa tulos on sama.
Velocitylla on muutamia sisäänrakennettuja matemaattisia funktioita joita voidaan käyttää sivupohjissa #set ohjeen kanssa. Seuraavat yhtälöt ovat esimerkkejä yhteen-, vähennys-, kerto- sekä jakolaskuista.
#set( $foo = $bar + 3 ) #set( $foo = $bar - 4 ) #set( $foo = $bar * 6 ) #set( $foo = $bar / 2 )
Kun kaksi kokonaislukua jaetaan keskenään, tuloksena on kokonaisluku, jonka arvo on jakolaskun kokonaisosa. Jakojäännös voidaan laskea modulo-operaattorilla (%).
#set( $foo = $bar % 5 )
Velocityllä on sisäänrakennettu keino nollalla jakamisen käsittelemiseen. Seuraavassa esimerkissä:
#set( $foo = 5 ) #set( $bar = $foo - 5 ) #set( $uhoh = $foo / $bar ) $uhoh
Viittaukseen $uhoh asetetaan tulos operaatiosta viisi jaettuna nollalla. Kun Velocity näyttää tämän sivupohjan, tuloste on:
$uhoh
Suunnittelijoiden on otettava huomioon myös, että #set tuottaa merkkijonoja, jotka on muunnettava kokonaisluvuiksi jotta niitä voidaan käyttää vaihteluväliä määritettäessä (range operator). Seuraavassa esimerkki tällaisesta muunnoksesta:
#set($a = "7") #set($b = $int.valueOf($a) + 10) $b
Tuloksena on 17.
Vaihteluväliä voidaan käyttää #set ja #foreach lauseiden yhteydessä. Vaihteluväli tuottaa kokonaislukuja sisältäviä oliotaulukoita seuraavalla tavalla:
[n..m]
Sekä n että m pitää olla tai niiden tulee tuottaa kokonaislukuja. Mikäli m on pienempi kuin n lasketaan vaihteluvälin luvut alaspäin. Seuraavassa esimerkkejä vaihteluvälin käytöstä:
Ensimmäinen esimerkki: #foreach( $foo in [1..5] ) $foo #end Toinen esimerkki: #foreach( $bar in [2..-2] ) $bar #end Kolmas esimerkki: #set( $arr = [0..1] ) #foreach( $i in $arr ) $i #end Neljäs esimerkki: [1..3]
Tuottaa seuraavan tulosteen:
Ensimmäinen esimerkki: 1 2 3 4 5 Toinen esimerkki: 2 1 0 -1 -2 Kolmas esimerkki: 0 1 Neljäs esimerkki: [1..3]
Huomaa että vaihteluvälioperaattori tuottaa taulukon vain kun sitä käytetään #set tai #foreach ohjeiden kanssa, kuten neljännestä esimerkistä käy selville.
Vaihteluvälioperaattori on erityisen käyttökelpoinen kun halutaan tehdä verkkosivun taulukko standardikokoiseksi, mutta joissain tapauksissa taulukon täyttämiseksi ei ole riittävästi dataa.
Kun viittaus hiljennetään ! merkillä ja ! merkkiä edeltää suojausmerkki \ käsitellään viittaus erityisellä tavalla. Huomaa erot normaalin suojauksen ja tilanteen jossa \ edeltää ! merkkiä, välillä.
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
Tulosteena on:
$!foo
$!{foo}
$\!foo
$\\!foo
Vertaa tätä normaaliin suojaukseen, jossa \ on $ merkin edellä:
\$foo
\$!foo
\$!{foo}
\\$!{foo}
Tulosteena on:
$foo
$!foo
$!{foo}
\bar
Tämä osio on Velocimakroaiheinen mini-FAQ. Osio muuttuu ajan myötä, joten uutta tietoa hakevien kannattanee palata sivulle aika ajoin.
Huom! : Tässä osiossa 'Velocimakro':ihin viitataan usein lyhenteellä 'VM'.
Voinko käyttää ohjetta tai toista VM:a argumenttina VM:oon?
Esimerkki : #center( #bold("hello") )
Et. Ohje ei ole sallittu argumentti ohjeelle, ja VM on käytännöllisesti katsoen ohje.
Kuitenkin..., voit kiertää rajoituksen. Yksinkertainen ratkaisu on käyttää hyväksi sitä että lainausmerkeissä (") oleva teksti tulkitaan. Tämä ansiosta voit tehdä seuraavasti:
#set($stuff = "#bold('hello')" )
#center( $stuff )
Voit myös säästää rivin...
#center( "#bold( 'hello' )" )
Huomaa että jälkimmäisessä esimerkissä parametri käsitellään VM:n sisällä, ei kutsun tasolla. Toisin sanoen VM:lle annettu parametri siirretään kokonaisuudessaan ja käsitellään VM:ssa johon se siirrettiin. Tämän ansiosta voit tehdä esimerkiksi seuraavaa:
#macro( inner $foo ) inner : $foo #end #macro( outer $foo ) #set($bar = "outerlala") outer : $foo #end #set($bar = 'calltimelala') #outer( "#inner($bar)" )
Tulosteeksi tulee
Outer : inner : outerlala
koska parametrin "#inner($bar)" tulkitseminen tapahtuu lauseen #outer() sisällä, käytetään muuttujan $bar arvoa joka asetettiin #outer VM:ssa.
Tämä on tarkoituksellinen ja tarkkaan vaalittu ominaisuus - parametrit siirretään 'nimen mukaan' ('by name') VM:oon, jotta voit siirtää VM:oon tilansa muistavia (stateful) viittauksia kuten
#macro( foo $vari ) <tr bgcolor=$vari><td>Hei</td></tr> <tr bgcolor=$vari><td>Siellä</td></tr> #end #foo( $bar.rivinVari() )
jossa rivinVari() metodia kutsutaan toistuvasti, ei vain kerran. Sen välttämiseksi kutsu metodia VM:n ulkopuolelta ja siirrä arvo VM:oon.
#set($vari = $bar.rivinVari()) #foo( $vari )
Nykyisellään Velocimakrot tulee olla määriteltyinä ennen ensimmäistä käyttöä. Tämä tarkoittaa sitä että #macro() määritystesi tulisi tulla ennen kuin käytät Velocimakroja.
Tämä on tärkeää muistaa jos yrität käyttää ohjetta #parse()
sivupohjaan jossa on inline #macro() ohjeita. Koska #parse()
suoritetaan ajon aikana, ja parseri päättää ajon aikana onko
sivupohjassa oleva Velocimakrolta näyttävä elementti Velocimakro,
ei Velocimakrojen #parse():aminen toimi niin kuin
olettaisi. Ongelma voidaan välttää helposti käyttämällä
velocimacro.library toimintoa jonka avulla Velocity
lataa Velocimakrosi käynnistyksen yhteydessä.
On olemassa asetus joka on tarkoitettu käytettäväksi järjestelmän kehityksen aikana, ei käytössä olevassa järjestelmässä :
velocimacro.library.autoreload
joka on oletuksena pois käytöstä (false). Kun ominaisuus on asetettu käyttöön (true) yhdessä asetuksen
<type>.resource.loader.cache = false
kanssa (jossa <type> on resurssilataajan nimi jota käytät, kuten 'file'), silloin Velocity lataa automaattisesti Velocitymakroihin tekemäsi muutokset silloin kun teet niitä, joten sinun ei tarvitse käynnistää uudelleen sovellusalustaa (tai ohjelmaa) tai turvautua johonkin muuhun kikkaan saadaksesi muuttuneet Velocitymakrosi käyttöön.
Yksinkertainen konfiguraatio saattaisi näyttää seuraavalta:
file.resource.loader.path = templates
file.resource.loader.cache = false
velocimacro.library.autoreload = true
Älä käytä näitä asetuksia tuotantokäytössä.
Yleinen kehittäjien kysymä kysymys on Kuinka yhdistän merkkijonoja? Onko olemassa Javan '+' operaattoria vastaavaa toimintoa?.
Viittausten liittämiseksi yhteen VTL:ssa, sinun tarvitsee vain 'laittaa ne yhteen'. Konteksti jossa yhdistät viittaukset vaikuttaa tuloksiin, joten esimerkit ovat paikallaan.
Normaalissa tapauksessa (jolloin sekoitat muuttujat sivupohjan muuhun sisältöön) :
#set( $koko = "Big" )
#set( $nimi = "Ben" )
Kello on $iso$nimi.
tulosteena on 'Kello on BigBen'. Hieman mielenkiintoisemmassa tapauksessa, kuten silloin kun haluat liittää merkkijonot siirrettäväksi parametrina metodille, tai asettaaksesi uuden viittauksen, tee seuraavasti:
#set( $koko = "Big" )
#set( $nimi = "Ben" )
#set($kello = "$koko$nimi" )
Kello on $kello.
Josta tulee sama tuloste. Viimeisenä esimerkkinä, kun haluat sekoittaa 'staattisia' merkkijonoja viittauksiin, saatat joutua käyttämään 'muodollista viittausten merkintää' :
#set( $koko = "Big" )
#set( $nimi = "Ben" )
#set($kello = "${koko}Tall$nimi" )
Kello on $kello.
Nyt tuloste on 'Kello on BigTallBen'. Muodollista viittausten merkintää käytetään, jotta parseri tietäisi että tarkoitat viittauksellasi muuttujaa '$size' eikä '$sizeTall', jota se käyttäisi mikäli et olisi käyttänyt '{}' merkkejä.
Mikäli löydät tästä ohjeesta virheitä tai haluat antaa ohjetta koskevaa palautetta, ole hyvä ja lähetä sähköpostia Velocity käyttäjälistalle. Kiitos!