Velocity

About

Community

Docs

Tools

Comparisons

Site Translations
Sisällys
  1. Tietoja tästä oppaasta
  2. Mikä on Velocity?
  3. Miten voin käyttää Velocityä?
    1. Kurakauppa esimerkki
  4. Velocity Template Language (VTL): Johdanto
  5. Hei Velocity Maailma!
  6. Kommentit
  7. Viittaukset
    1. Muuttujat
    2. Ominaisuudet
    3. Metodit
  8. Muodollinen viittausten merkintä
  9. Hiljainen viittausten merkintä
  10. Kirjaimellisesti
    1. Dollari
    2. VTL viittausten suojaaminen
  11. Kirjainkoon muutos
  12. Ohjeet
    1. Set
    2. Tekstivakiot
    3. If-Else ehtolauseet
      1. Relaatio- ja loogiset operaattorit
    4. Foreach silmukat
    5. Include
    6. Parse
    7. Stop
    8. Velocimakrot
  13. VTL ohjeiden suojaaminen
  14. VTL: Muotoilu
  15. Muita ominaisuuksia ja sekalaista
    1. Matematiikka
    2. Vaihteluväli (Range Operator)
    3. Edistyneet kysymykset: Suojaaminen ja !
    4. Yleistä Velocimakroista
    5. Merkkijonojen yhdistäminen
  16. 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
\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.


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_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.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!


Copyright © 1999-2004, The Apache Software Foundation