Velocity - Velocity k?ytt?j?n opas

About

Community

Docs

Tools

Comparisons

Site Translations

Sis?llys

Tietoja t?st? oppaasta

Mik? on Velocity?

Miten voin k?ytt?? Velocity??

Kurakauppa esimerkki

Velocity Template Language (VTL): Johdanto

Hei Velocity Maailma!

Kommentit

Viittaukset

Muuttujat

Ominaisuudet

Metodit

Muodollinen viittausten merkint?

Hiljainen viittausten merkint?

Kirjaimellisesti

Dollari

VTL viittausten suojaaminen

Kirjainkoon muutos

Ohjeet

Set

Tekstivakiot

If-Else ehtolauseet

Relaatio- ja loogiset operaattorit

Foreach silmukat

Include

Parse

Stop

Velocimakrot

VTL ohjeiden suojaaminen

VTL: Muotoilu

Muita ominaisuuksia ja sekalaista

Matematiikka

Vaihteluv?li (Range Operator)

Edistyneet kysymykset: Suojaaminen ja !

Yleist? Velocimakroista

Merkkijonojen yhdist?minen

Palaute

Tietoja t?st? oppaasta

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!

Mik? on Velocity?

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.

Miten voin k?ytt?? Velocity??

Kurakauppa esimerkki
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?.

Velocity Template Language (VTL): Johdanto

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?? arvon muuttujalle. 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".

Hei Velocity Maailma!

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.

Kommentit

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

Viittaukset

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:

aakkoset (a .. z, A .. Z)

numerot (0 .. 9)

viiva ("-")

alaviiva ("_")

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}"/>

Kirjaimellisesti

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
\$email
\\$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.

Kirjainkoon muutos

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.getKayttaja("juha")
## on sama kuin
$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

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?:

Muuttujaviittaus

Tekstivakio

Ominaisuusviittaus

Metodiviittaus

Numeerinen vakio

ArrayList taulukko

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-Else ehtolauseet

If / ElseIf / Else
#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.

Huomaa, ett? nykyisell??n Velocityn numeeriset vertailut on rajoitettu Integer (kokonais-) lukuihin. Kaikki muut arvot tulkitaan ep?tosiksi. Ainoa poikkeus t?h?n on vastaavuus '==', jolloin Velocity vaatii ett? objektit vertailun kummallakin puolella ovat samaa luokkaa.

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.

Silmukat

Foreach silmukat
#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>$velocityCount</td><td>$asiakas.Nimi</td></tr>
#end
</table>
Silmukkalaskurin oletusnimi on $velocityCount ja se m??ritet??n velocity.properties tiedostossa. Oletuksena laskuri alkaa arvosta 1, mutta aloitusarvo voidaan m??ritt?? olemaan joko 1 tai 0 velocity.properties tiedostossa. velocity.properties tiedoston silmukkalaskuriosio n?ytt?? t?lt?:
# Silmukkalaskurin oletusnimi
counter.name = velocityCount

# Silmukkalaskurin aloitusarvo
counter.initial.value = 1

Include

#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

#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

#stop elementin avulla sivupohjan suunnittelija voi pys?ytt?? sivun tulkitsemisen. T?m? on hy?dyllist? sivupohjan virheidenetsinn?n aikana.
#stop

Velocimakrot

#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>
Velocimakron argumentit
Velocimakrot voivat ottaa argumenteiksi mit? tahansa seuraavista VTL elementeist?:

Viittaus : mit? tahansa '$' merkill? alkavaa

Tekstivakio : esimerkiksi "$foo" tai 'hei'

Numerovakio : 1, 2 jne

Numerov?li : [ 1..2] tai [$foo .. $bar]

ObjectArray : [ "a", "b", "c"]

boolean arvo true (tosi)

boolean arvo false (ep?tosi)

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 )
   
Velocimakro ominaisuudet
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_lib.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.context.localscope - Mahdolliset arvot ovat true tai false, oletuksena false. Kun ominaisuuden arvoksi on asetettu tosi, Velocimakroissa #set() ohjeella tehdyt muutokset ovat 'paikallisia' eiv?tk? vaikuta pysyv?sti muuttujien sis?lt??n.

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.
Velocimakro Trivia
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 ohjeiden suojaaminen

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, ei tulostetta tule. 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.

VTL: Muotoilu

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.

Muita ominaisuuksia ja sekalaista

Matematiikka
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 )
Jako-operaation tapauksessa tulos on kokonaisluku. Jakoj??nn?s saadaan k?ytt??n j??nn?soperandilla (%).
#set( $foo = $bar % 5 )
Matemaattisia funktioita k?ytett?ess? Velocityss? vain kokonaisluvut (...-2, -1, 0, 1, 2...) ovat sallittuja; ei-kokonaislukuja k?ytett?ess? asia kirjataan lokiin ja tulokseksi palautetaan tyhj? arvo (null).

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 (Range Operator)
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.
Edistyneet kysymykset: Suojaaminen ja !
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
Yleist? Velocimakroista
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 )
Voinko rekister?id? Velocimakroja #parse() :n kautta?
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?.
Mit? tarkoittaa Velocimakrojen automaattinen uudelleenlataus?
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?.
Merkkijonojen yhdist?minen
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?.

Palaute

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!