You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ge...@apache.org on 2002/03/25 17:13:45 UTC
cvs commit: jakarta-velocity/xdocs user-guide.xml user-guide_fi.xml
geirm 02/03/25 08:13:45
Modified: docs user-guide.html user-guide_fi.html
xdocs user-guide.xml user-guide_fi.xml
Log:
fix posted by Mikael Gueck (bug 6901). Thx
Revision Changes Path
1.70 +1 -1 jakarta-velocity/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide.html,v
retrieving revision 1.69
retrieving revision 1.70
diff -u -r1.69 -r1.70
--- user-guide.html 15 Mar 2002 00:07:45 -0000 1.69
+++ user-guide.html 25 Mar 2002 16:13:44 -0000 1.70
@@ -1191,8 +1191,8 @@
<td bgcolor="#ffffff"><pre>
foo
$email
+\foo
\$email
-\\$email
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
1.3 +1 -1 jakarta-velocity/docs/user-guide_fi.html
Index: user-guide_fi.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/user-guide_fi.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- user-guide_fi.html 23 Mar 2002 14:41:49 -0000 1.2
+++ user-guide_fi.html 25 Mar 2002 16:13:45 -0000 1.3
@@ -1220,7 +1220,7 @@
<td bgcolor="#ffffff"><pre>
foo
$email
-\$email
+\foo
\\$email
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
1.63 +1 -1 jakarta-velocity/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide.xml,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -r1.62 -r1.63
--- user-guide.xml 15 Mar 2002 00:07:46 -0000 1.62
+++ user-guide.xml 25 Mar 2002 16:13:45 -0000 1.63
@@ -675,8 +675,8 @@
<source><![CDATA[
foo
$email
+\foo
\$email
-\\$email
]]></source>
<p>
1.3 +1 -1 jakarta-velocity/xdocs/user-guide_fi.xml
Index: user-guide_fi.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/user-guide_fi.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- user-guide_fi.xml 23 Mar 2002 14:41:49 -0000 1.2
+++ user-guide_fi.xml 25 Mar 2002 16:13:45 -0000 1.3
@@ -1 +1 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Velocity k�ytt�j�n opas</title>
<author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
<author email="jcastura@kw.igs.net">John Castura</author>
<author email="juha@dwebs.com">Juha Kilpi</author>
</properties>
<body>
<section name="Sis�llys">
<ol>
<li><a href="#Tietoja t�st� oppaasta">Tietoja t�st� oppaasta</a></li>
<li><a href="#Mik� on Velocity?">Mik� on Velocity?</a></li>
<li><a href="#Miten voin k�ytt�� Velocity�?">Miten voin k�ytt�� Velocity�?</a>
<ol>
<li><a href="#Kurakauppa esimerkki">Kurakauppa esimerkki</a></li>
</ol>
</li>
<li><a href="#Velocity Template Language (VTL): Johdanto">Velocity
Template Language (VTL): Johdanto</a></li>
<li><a href="#Hei Velocity Maailma!">Hei Velocity Maailma!</a></li>
<li><a href="#Kommentit">Kommentit</a></li>
<li><a href="#Viittaukset">Viittaukset</a>
<ol>
<li><a href="#Muuttujat">Muuttujat</a></li>
<li><a href="#Ominaisuudet">Ominaisuudet</a></li>
<li><a href="#Metodit">Metodit</a></li>
</ol>
</li>
<li><a href="#Muodollinen merkint�">Muodollinen viittausten merkint�</a></li>
<li><a href="#Hiljainen viittausten merkint�">Hiljainen viittausten merkint�</a></li>
<li><a href="#Kirjaimellisesti">Kirjaimellisesti</a>
<ol>
<li><a href="#Dollari">Dollari</a></li>
<li><a href="#VTL viittausten suojaaminen">VTL viittausten suojaaminen</a></li>
</ol>
</li>
<li><a href="#Kirjainkoon muutos">Kirjainkoon muutos</a></li>
<li><a href="#Ohjeet">Ohjeet</a>
<ol>
<li><a href="#Set">Set</a></li>
<li><a href="#Tekstivakiot">Tekstivakiot</a></li>
<li><a href="#If-Else ehtolauseet">If-Else ehtolauseet</a>
<ol>
<li><a href="#Relaatio- ja loogiset operaattorit">Relaatio- ja loogiset
operaattorit</a></li>
</ol>
</li>
<li><a href="#Silmukat">Foreach silmukat</a></li>
<li><a href="#Include">Include</a></li>
<li><a href="#Parse">Parse</a></li>
<li><a href="#Stop">Stop</a></li>
<li><a href="#Velocimakrot">Velocimakrot</a></li>
</ol>
</li>
<li><a href="#VTL ohjeiden suojaaminen">VTL ohjeiden suojaaminen</a></li>
<li><a href="#VTL: Muotoilu">VTL: Muotoilu</a></li>
<li><a href="#Muita ominaisuuksia ja sekalaista">Muita ominaisuuksia ja sekalaista</a>
<ol>
<li><a href="#Matematiikka">Matematiikka</a></li>
<li><a href="#Vaihteluv�li (Range Operator)">Vaihteluv�li (Range Operator)</a></li>
<li><a href="#Edistyneet kysymykset: Suojaaminen ja
!">Edistyneet kysymykset: Suojaaminen ja !</a></li>
<li><a href="#Yleist� Velocimakroista">Yleist� Velocimakroista</a></li>
<li><a href="#Merkkijonojen yhdist�minen">Merkkijonojen yhdist�minen</a></li>
</ol>
</li>
<li><a href="#Palaute">Palaute</a></li>
</ol>
</section>
<section name="Tietoja t�st� oppaasta">
<p>
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.
</p>
<p>
Kiitos ett� valitsit Velocityn!
</p>
</section>
<section name="Mik� on Velocity?">
<p>
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 <a
href="http://java.sun.com/products/jsp/">JSP</a>:lle (Java Server
Pages) ja <a href="http://www.php.net/">PHP</a>:lle.
</p>
<p>
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 <a
href="http://java.apache.org/turbine/">Turbine</a> web
sovelluskehykselle. Yhdess� Velocity ja Turbine tarjoavat
sivupohjaratkaisun jonka avulla web sovelluksia voidaan kehitt��
todellisen MVC -mallin mukaisesti.
</p>
</section>
<section name="Miten voin k�ytt�� Velocity�?">
<subsection name="Kurakauppa esimerkki">
<p>
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�?
</p>
<p>
Velocityn avulla verkkosivut on helppo personoida k�vij�idesi
mukaan. Kurakauppa Onlinen sivusuunnittelijana haluat tehd� sivun
jonka asiakas n�kee kirjauduttuaan j�rjestelm��n.
</p>
<p>
Tapaat yrityksesi ohjelmoijat ja sovitte, ett� muuttuja
<em>$asiakas</em> pit�� sis�ll��n tiedot parhaillaan kirjautuneena
olevasta asiakkaasta. Muuttujassa <em>$kuratTarjouksessa</em> ovat
tiedot kuratyypeist� jotka ovat parhaillaan
erikoistarjouksessa. <em>$tarjous</em> 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.
</p>
<p>
Voisit lis�t� seuraavat VTL lauseen sivulle:
</p>
<source><![CDATA[
<HTML>
<BODY>
Hei $asiakas.Nimi!
<table>
#foreach( $kura in $kuratTarjouksessa )
#if ( $asiakas.onOstanut($kura) )
<tr>
<td>
$tarjous.haePromo( $kura )
</td>
</tr>
#end
#end
</table>
]]></source>
<p>
<em>foreach</em> 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.
</p>
<p>
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�.
</p>
</subsection>
</section>
<section name="Velocity Template Language (VTL): Johdanto">
<p>
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.
</p>
<p>
VTL k�ytt�� <em>viittauksia</em> 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 <em>lauseen</em> avulla. Seuraavassa on esimerkki VTL
lauseesta joka voidaan lis�t� HTML -dokumenttiin:
</p>
<source><![CDATA[
#set( $a = "Velocity" )
]]></source>
<p>
Kuten kaikki VTL lauseet (statement), t�m�kin lause alkaa <em>#</em>
merkill� ja sis�lt�� ohjeen (directive): <em>set</em>. Kun verkkosivun
k�ytt�j� hakee sivun Velocity etsii sivupohjastasi kaikki
<em>#</em> -merkit. Sitten se tulkitsee mitk� niist� merkitsev�t
VTL lausetta, ja mitk� <em>#</em> merkeist� ovat osa sivujesi
normaalia HTML -koodia, eiv�tk� kuulu VTL -koodiin.
</p>
<p>
<em>#</em> merkki� seuraa ohje, <em>set</em>. <em>set</em> ohjeen
j�lkeen tulee suluissa ilmaus (expression), -- yht�l� joka m��ritt��
<em>arvon</em> <em>muuttujalle</em>. Muuttuja on ilmaistu
vasemmalla ja arvo oikealla puolella. N�m� on erotettu <em>=</em>
merkill�.
</p>
<p>
Yll� olevassa esimerkiss� muuttuja on <em>$a</em> ja arvo on
<em>Velocity</em>. Kaikkien viittausten tapaan t�m�kin muuttuja
alkaa <em>$</em> merkill�. Arvot ovat aina lainausmerkkien
sis�ll�; Velocityss� muuttujien datatyypeist� ei tule
sekaannuksia, koska vain merkkijonoja (string) voi antaa
muuttujien arvoksi.
</p>
<p>
Seuraava nyrkkis��nt� voi auttaa ymm�rt�m��n Velocityn toimintaa:
<strong>Viittaukset alkavat <em>$</em> merkill� ja niit� k�ytet��n
jonkin hakemiseen. Ohjeet alkavat <em>#</em> merkill� ja niit�
k�ytet��n jonkin suorittamiseen.</strong>
</p>
<p>
Yll� olevassa esimerkiss� <em>#set</em> -ohjetta k�ytet��n arvon
m��ritt�miseksi muuttujaan. Muuttujaa <em>$a</em> voidaan t�m�n
j�lkeen k�ytt�� sivupohjassa tulostamaan "Velocity".
</p>
</section>
<section name="Hei Velocity Maailma!">
<p>
Kun muuttujalle on m��ritelty arvo, voidaan siihen viitata miss�
tahansa paikassa HTML dokumenttia. Seuraavassa esimerkiss�
muuttujalle <em>$foo</em> m��ritell��n arvo. My�hemmin muuttujaan
viitataan.
</p>
<source><![CDATA[
<html>
<body>
#set( $foo = "Velocity" )
Hei $foo Maailma!
</body>
<html>
]]></source>
<p>
Tuloksena on web sivu jossa lukee "Hei Velocity Maailma!".
</p>
<p>
Jotta VTL lauseet olisivat helpommin luettavissa on suositeltavaa
aloittaa jokainen lause uudelta rivilt�, vaikkakaan t�m� ei ole
pakollista. <em>set</em> ohjeeseen palaamme tarkemmin my�hemmin.
</p>
</section>
<section name="Kommentit">
<p>
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�.
</p>
<source><![CDATA[
## T�m� on rivin pituinen kommentti.
]]></source>
<p>
Yhden rivin pituinen kommentti alkaa <em>##</em> 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 <em>#*</em>
merkeill� ja loppuvat <em>*#</em> merkkeihin.
</p>
<source><![CDATA[
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�.
]]></source>
<p>
T�ss� on muutamia esimerkkej� yksi- ja monirivisten kommenttien
toiminnan selvitt�miseksi:
</p>
<source><![CDATA[
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�.
]]></source>
<p>
On olemassa viel� kolmaskin kommenttityyppi; VTL kommenttilohko,
jota voidaan k�ytt�� mm. dokumentin tekij�- ja versiotietojen
tallettamiseen
</p>
<source><![CDATA[
#**
T�m� on VTL kommenttilohko. Lohkoa
voidaan k�ytt�� esimerkiksi dokumentin
tekij�- ja versiotietojen
tallettamiseen:
@author
@version 5
*#
]]></source>
</section>
<section name="Viittaukset">
<p>
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.
</p>
<p>
Kaikkea viittauksissa olevaa ja niihin m��ritelt�v�� tietoa
k�sitell��n tekstityyppisen�. Jos on esimerkiksi m��ritelty
objekti <em>$foo</em> (Integer objekti), Velocity kutsuu objektin
<code>.toString()</code> metodia objektin arvon muuntamiseksi
tekstityyppiseksi.
</p>
<p>
<a name="Muuttujat"><strong>Muuttujat</strong></a>
<br/>
Muuttujan lyhyt merkint�tapa koostuu ensimm�isen� olevasta "$"
merkist�, jonka j�lkeen tulee VTL <em>tunniste</em>. VTL
tunnisteen on alettava aakkosnumeerisella merkill� (a..z tai
A..Z). Muuttujan loput merkit ovat rajoitettu seuraaviin:
</p>
<p>
<ul>
<li>aakkoset (a .. z, A .. Z)</li>
<li>numerot (0 .. 9)</li>
<li>viiva ("-")</li>
<li>alaviiva ("_")</li>
</ul>
</p>
<p>
Seuraavassa muutamia esimerkkej� toimivista muuttujaviittauksista:
</p>
<source><![CDATA[
$foo
$kuraLinko
$kura-linko
$kura_linko
$kuraLinko1
]]></source>
<p>
Kun VTL viittaa muuttujaan, kuten <em>$foo</em>, muuttuja voi
saada arvonsa joko sivupohjassa olevalta <em>set</em> ohjeelta,
tai java -koodista. Jos esimerkiksi javamuuttujalla <em>$foo</em>
on arvo <em>bar</em> silloin kun sivupohjaa haetaan, <em>bar</em>
korvaa kaikki <em>$foo</em> muuttujan esiintymiskohdat web
sivulla. Toisaalta jos sivulle lis�t��n lause
</p>
<source><![CDATA[
#set( $foo = "bar" )
]]></source>
<p>
Sivun tuloste on sama kaikilla <em>$foo</em> muuttujan
esiintymiskohdille jotka tulevat t�m�n lauseen j�lkeen.
</p>
<p>
<a name="Ominaisuudet"><strong>Ominaisuudet</strong></a>
<br/>
Toinen VTL:n viittaustyyppi ovat ominaisuudet joilla on oma
tunnusomainen muotonsa. Lyhyt merkint�tapa muodostuu ensimm�isen�
olevasta <em>$</em> merkist�, jonka j�lkeen tulee VTL tunniste,
jota seuraa piste (".") ja toinen VTL tunniste. Seuraavassa on
esimerkkej� toimivista ominaisuusviittauksista:
</p>
<source><![CDATA[
$asiakas.Osoite
$ostos.Summa
]]></source>
<p>
K�sittelemme ensimm�isen esimerkin <em>$asiakas.Osoite</em>
tarkemmin. Viittauksella voi olla kaksi merkityst�. Se saattaa
tarkoittaa; hae <em>asiakas</em> nimisest� hashtable taulukosta
arvo joka on liitetty avaimelle <em>Osoite</em>. Toisaalta
<em>$asiakas.Osoite</em> voi my�s viitata metodiin (k�sittelemme
metodeihin viittaavat viittaukset seuraavassa kappaleessa);
<em>$asiakas.Osoite</em> saattaa olla lyhennetty muoto
viittauksesta <em>$asiakas.getOsoite()</em>. Velocity tulkitsee
sivua haettaessa kumpaa n�ist� vaihtoehdoista tarkoitetaan, ja
palauttaa vastaavan arvon.
</p>
<p>
<a name="Metodit"><strong>Metodit</strong></a>
<br/>
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 <em>Metodirunko</em>. VTL Metodirunko koostuu VTL
tunnisteesta jota seuraa vasen sulkumerkki "(", jota seuraa
valinnainen parametrilista, jota seuraa oikeanpuoleinen
sulkumerkki ")". Seuraavassa on esimerkkej� toimivista
metodiviittauksista:
</p>
<source><![CDATA[
$asiakas.getOsoite()
$ostos.getSumma()
$sivu.setOtsake( "Minun kotisivuni" )
$henkilo.setOminaisuudet( ["Outo", "Kummallinen", "Innostunut"] )
]]></source>
<p>
Metodirungossa esiintyv� get tarkoittaa "hae" ja set "aseta".
</p>
<p>
Kaksi ensimm�ist� esimerkki� -- <em>$asiakas.getOsoite()</em> ja
<em>$ostos.getSumma()</em> -- n�ytt�v�t samanlaisilta kuin
Ominaisuudet -osiossa aiemmin; <em>$asiakas.Osoite</em> ja
<em>$ostos.Summa</em>. Jos arvasit ett� n�ill� esimerkeill� on
jotakin yhteytt� toisiinsa, olit oikeassa!
</p>
<p>
VTL ominaisuuksia voidaan k�ytt�� lyhyempin� muotoina VTL
metodeista. Ominaisuudella <em>$asiakas.Osoite</em> on t�ysin sama
vaikutus kuin k�ytt�m�ll� metodia
<em>$asikas.getOsoite()</em>. 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.
</p>
<p>
Seuraavien metodien kanssa voidaan k�ytt�� lyhytt� muotoa:
</p>
<source><![CDATA[
$aurinko.getPlaneetat()
$mato.getMulta()
$albumi.getValokuva()
]]></source>
<p>
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:
</p>
<source><![CDATA[
$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
]]></source>
<p>
<a name="Muodollinen viittausten merkint�"><strong>Muodollinen viittausten merkint�</strong></a>
<br/>
Edellisiss� esimerkeiss� k�ytettiin viittauksille lyhytt�
merkint�tapaa. Viittauksille on olemassa my�s muodollinen
merkint�tapa, jota k�ytet��n seuraavissa esimerkeiss�:
</p>
<source><![CDATA[
${kuraLinko}
${asiakas.Osoite}
${osto.getSumma()}
]]></source>
<p>
Voit k�ytt�� lyhytt� muotoa viittauksiin l�hes aina, mutta
joissain tapauksissa muodollista viittausta tarvitaan virheett�m�n
toiminnan turvaamiseksi.
</p>
<p>
Oletetaan ett� olet luomassa lausetta jonka sis�lt� riippuu
muuttujasta. Muuttujaa <em>$pahe</em> 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�:
</p>
<source><![CDATA[
Juha on $pahemaani.
]]></source>
<p>
Velocity olettaa ett� tarkoitat muuttujaa <em>$pahemaani</em>,
vaikka k�ytett�v� muuttuja oli <em>$pahe</em>. Koska Velocity ei
l�yd� arvoa muuttujalle <em>$pahemaani</em>, se palauttaa
<em>$pahemaani</em>. T�m� ongelma voidaan ratkaista k�ytt�m�ll�
muodollista viittausta.
</p>
<source><![CDATA[
Juha on ${pahe}maani.
]]></source>
<p>
Nyt Velocity ymm�rt�� ett� haluttu viittaus on <em>$pahe</em>, ei
<em>$pahemaani</em>. Muodollinen viittausten merkint� on usein
hy�dyllinen silloin kun viittaukset ovat kiinni muussa tekstiss�.
</p>
<p>
<a name="Hiljainen viittausten merkint�"><strong>Hiljainen viittausten merkint�</strong></a>
<br/>
Kun Velocitylt� haetaan viittaus jolle ei ole m��ritelty arvoa,
palauttaa se normaalisti viittauksen tekstin�. Oletetaan
esimerkiksi ett� seuraavat viittaukset ovat osa VTL sivupohjaa:
</p>
<source><![CDATA[
<input type="text" name="email" value="$email"/>
]]></source>
<p>
Kun lomake latautuu ensimm�isen kerran muuttujaviittauksella
<em>$email</em> 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��;
<em>$email</em> koodin sijaan k�yt�t viittausta
<em>$!email</em>. Yll� oleva koodi n�ytt�isi siis seuraavalta:
</p>
<source><![CDATA[
<input type="text" name="email" value="$!email"/>
]]></source>
<p>
Kun lomake latautuu ensimm�isen kerran eik� muuttujalla
<em>$email</em> ole arvoa, tulostetaankin kentt��n tyhj� teksti
"$email" tekstin sijaan.
</p>
<p>
Muodollista ja hiljaista muuttujien merkint�� voidaan k�ytt�� my�s
yhdess�;
</p>
<source><![CDATA[
<input type="text" name="email" value="$!{email}"/>
]]></source>
</section>
<section name="Kirjaimellisesti">
<p>
VTL k�ytt�� erikoismerkkej� kuten <em>$</em> ja <em>#</em> omassa
toiminnassaan, joten n�iden merkkien k�ytt� sivupohjassa vaatii
erityist� huolellisuutta. T�ss� kappaleessa k�sittelemme
<em>$</em> merkin suojaamisen (escape).
</p>
<p>
<a name="Dollari"><strong>Dollari</strong></a>
<br/>
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.
</p>
<p>
<a name="VTL viittausten suojaaminen"><strong>VTL viittausten suojaaminen</strong></a>
<br/>
Ongelmatilanne saattaa synty� silloin, kun Velocity ei osaa
p��tell� tarkoitetaanko dollarinmerkill� merkki� itse��n, vai
viittausta. Erikoismerkkien <em>suojaaminen</em> on paras keino
k�sitell� VTL erikoismerkkej� sivupohjissa. Suojaamiseen k�ytet��n
kenoviivaa ( <em>\</em> ).
</p>
<source><![CDATA[
#set( $email = "foo" )
$email
]]></source>
<p>
Kun Velocity k�sittelee <em>$email</em> viittauksen
sivupohjassasi, se etsii l�ytyyk� sen nimiselle muuttujalle
arvoa. T�ss� tapauksessa tuloste tulee olemaan <em>foo</em>, koska
<em>$email</em> on m��ritelty. Jos <em>$email</em> muuttujaa ei
olisi m��ritelty tulisi tulosteeksi <em>$email</em>.
</p>
<p>
Oletetaan ett� <em>$email</em> on m��ritelty (sill� on esimerkiksi
arvo <em>foo</em>), ja ett� haluat muuttujan arvon sijaan tulostaa
sen nimen <em>$email</em>. T�m� saavuttamiseksi on useita keinoja,
joista helpoin on suojausmerkin k�ytt�minen.
</p>
<source><![CDATA[
## Seuraava rivi m��rittelee muuttujan $email t�ss� sivupohjassa:
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
]]></source>
<p>
tulosteeksi tulee
</p>
<source><![CDATA[
foo
$email
\$email
\\$email
]]></source>
<p>
Huomaa <em>$</em> merkin eteen liitetty <em>\</em>
merkki. Suojausmerkit tulkitaan vasemmalta oikealle, joten
<em>\\\$email</em> tulostuu <em>\\$email</em>. Vertaa n�it�
esimerkkej� tulosteeseen joka saadaan kun <em>$email</em>
muuttujaa ei ole m��ritelty.
</p>
<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>
<p>
tulosteeksi tulee
</p>
<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>
<p>
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 <em>$foo</em> muuttujalle arvon
<em>gibbous</em>.
</p>
<source><![CDATA[
#set( $foo = "gibbous" )
$kuu = $foo
]]></source>
<p>
Tulosteeksi tulee: <em>$kuu = gibbous</em> -- miss� <em>$kuu</em>
tulostetaan muuttujan nimen�, koska sen arvoa ei ole m��ritelty ja
<em>gibbous</em> tulostetaan muuttujan <em>$foo</em> arvona.
</p>
<p>
My�s VTL ohjeiden suojaaminen on mahdollista; t�m� kuvataan
tarkemmin Ohjeet -kappaleessa.
</p>
</section>
<section name="Kirjainkoon muutos">
<p>
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:
</p>
<source><![CDATA[
$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}
]]></source>
<p>
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.
</p>
<p>
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
<em>getFoo()</em> koodilla <code>$bar.foo</code>, Velocity
kokeilee ensin viittausta <code>$getfoo</code>. Jos t�m� ei tuota
tulosta, seuraavaksi yritet��n viittausta
<code>$getFoo</code>. Samalla tavalla, kun sivupohjassa viitataan
muuttujaan <code>$bar.Foo</code>, ensin yritet��n viittausta
<em>$getFoo()</em> ja sitten <em>getfoo()</em>.
</p>
<p>
Huomaa: <em>Viittauksia ilmentym�muuttujiin (instance variables)
ei ratkaista.</em> Vain viittaukset JavaBeanin mukaisiin
haku/asetus (getter/setter) metodeihin ratkaistaan (toisin sanoen
<code>$foo.Name</code> ratkaistaan Foo -luokan
<code>getName()</code> ilmentym�metodiin (instance method), mutta
ei luokan Foo julkiseen (public) <code>Name</code>
ilmentym�muuttujaan).
</p>
</section>
<section name="Ohjeet">
<p>
<em>Ohjeet</em> 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.
</p>
<a name="Set"><strong>#set</strong></a>
<p>
<em>#set</em> 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�:
</p>
<source><![CDATA[
#set( $kadellinen = "apina" )
#set( $asiakas.Kayttaytyminen = $kadellinen )
]]></source>
<p>
M��rityksen vasemman puolen (left hand side, LHS) tulee olla
muuttuja- tai ominaisuusviittaus. Oikea puoli (right hand side,
RHS) voi olla jokin seuraavista tyypeist�:
</p>
<p>
<ul>
<li>Muuttujaviittaus</li>
<li>Tekstivakio</li>
<li>Ominaisuusviittaus</li>
<li>Metodiviittaus</li>
<li>Numeerinen vakio</li>
<li>ArrayList taulukko</li>
</ul>
</p>
<p>
Seuraavassa esimerkit kustakin mainitusta tyypist�:
</p>
<source><![CDATA[
#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
]]></source>
<p>
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).
</p>
<p>
Oikeanpuoleinen arvo (RHS) voi olla my�s yksinkertainen
matemaattinen operaatio:
</p>
<source><![CDATA[
#set( $arvo = $foo + 1 )
#set( $arvo = $bar - 1 )
#set( $arvo = $foo * $bar )
#set( $arvo = $foo / $bar )
]]></source>
<p>
Jos m��rityksen oikeanpuoleinen ominaisuus- tai metodiviittaus on
arvoa <em>null</em>, sit� <b>ei</b> 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:
</p>
<source><![CDATA[
#set( $tulos = $kysely.kriteeri("nimi") )
Ensimm�isen kyselyn tulos on $tulos
#set( $tulos = $kysely.kriteeri("osoite") )
Toisen kyselyn tulos on $tulos
]]></source>
<p>
Jos <em>$kysely.kriteeri("nimi")</em> palauttaa merkkijonon
"pete", ja <em>$kysely.kriteeri("osoite")</em> palauttaa arvon
<em>null</em>, on esimerkin tuloste seuraava:
</p>
<source><![CDATA[
Ensimm�isen kyselyn tulos on pete
Toisen kyselyn tulos on pete
]]></source>
<p>
T�ll� on vaara h�m�t� aloittelijoita jotka muodostavat
<em>#foreach</em> silmukoita joissa yritet��n asettaa
<em>#set</em> ohjeella viittausta ominaisuus- tai
metodiviittauksella, ja sen j�lkeen testataan tuota viittausta
<em>#if</em> ohjeella. Esimerkiksi:
</p>
<source><![CDATA[
#set( $kriteerit = ["nimi", "osoite"] )
#foreach( $kriteeri in $kriteerit )
#set( $tulos = $kysely.kriteerit($kriteeri) )
#if( $tulos )
Kysely onnistui
#end
#end
]]></source>
<p>
Yll� olevassa esimerkiss� ei kannata luottaa <em>$tulos</em>
muuttujan vertaamiseen kyselyn onnistumisen selville
saamiseksi. Kun <em>$tulos</em> on asetettu <em>#set</em>
ohjeella (lisatty kontekstiin), sit� ei voida asettaa
<em>null</em>:iksi (poistaa kontekstista). <em>#if</em> ja
<em>#foreach</em> ohjeet k�sitell��n tarkemmin my�hemmin t�ss�
dokumentissa.
</p>
<p>
Yksi ratkaisu ongelmaan olisi asettaa <em>$tulos</em> etuk�teen
arvoon <em>false</em> (ep�tosi). T�m�n j�lkeen jos kutsu
<em>$kysely.kriteeri()</em> ep�onnistuu, voit tarkastaa arvon.
</p>
<source><![CDATA[
#set( $kriteerit = ["nimi", "osoite"] )
#foreach( $kriteeri in $kriteeri )
#set( $tulos = false )
#set( $tulos = $kysely.kriteerit($kriteeri) )
#if( $tulos )
Kysely onnistui
#end
#end
]]></source>
<p>
Muutamista muista Velocityn ohjeista poiketen, <em>#set</em> ohje
ei k�yt� <em>#end</em> lausetta.
</p>
<a name="Tekstivakiot"><strong>Tekstivakiot</strong></a>
<p>
<em>#set</em> ohjetta k�ytett�ess� lainausmerkkeihin (" ")
suljettu teksti tulkitaan ja tulostetaan kuten seuraavasta
esimerkist� k�y ilmi:
</p>
<source><![CDATA[
#set( $hakemistoJuuri = "www" )
#set( $sivupohjaNimi = "index.vm" )
#set( $sivupohja = "$hakemistoJuuri/$sivupohjaNimi" )
$sivupohja
]]></source>
<p>
Tulosteeksi tulee
</p>
<source><![CDATA[
www/index.vm
]]></source>
<p>
Jos teksti on suljettu hipsuihin (' '), sit� ei tulkita:
</p>
<source><![CDATA[
#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh
]]></source>
Tulosteeksi tulee:
<source><![CDATA[
bar
$foo
]]></source>
<p>
Tulkitsemattoman tekstin tulostaminen hipsumerkkien sis�ll�
olevavasta tekstist� on oletuksena k�yt�ss�
Velocityss�. Oletusarvo voidaan muuttaa vaihtamalla
<code>velocity.properties</code> siten ett�
<code>stringliterals.interpolate=false</code>.
</p>
</section>
<section name="If-Else ehtolauseet">
<strong>If / ElseIf / Else</strong>
<p>
<em>#if</em> ohjeen avulla voidaan teksti sis�llytt�� web
sivulle sill� ehdolla ett� if lauseen arvo on
tosi. Esimerkiksi:
</p>
<source><![CDATA[
#if( $foo )
<strong>Velocity!</strong>
#end
]]></source>
<p>
Muuttuja <em>$foo</em> testataan jotta n�hd��n onko se tosi,
joka tapahtuu kahdessa eri tapauksessa: (i) <em>$foo</em> on
boolean arvo (tosi/ep�tosi) jolla on tosi -arvo, tai (ii) arvo
on eri kuin null (eli muuttuja ei ole tyhj�). <em>#if</em> ja
<em>#end</em> lauseiden v�liin j��v� sis�lt� tulostetaan mik�li
testimuuttuja on tosi. Esimerkkitapauksessamme, jos muuttujalla
<em>$foo</em> on null arvo, tai jos se on boolean ep�tosi, on
testimuuttuja ep�tosi, eik� tulostetta tule lainkaan.
</p>
<p>
<em>#if</em> ja <em>#end</em> lauseiden v�liss� oleva teksti
tulee tulosteeksi mik�li ehto on tosi. T�ss� tapauksessa jos
<em>$foo</em> on tosi, tulosteeksi tulee:
"Velocity!". Toisaalta, mik�li <em>$foo</em> on ep�tosi, on my�s
ehtolause ep�tosi eik� tulostetta tule.
</p>
<p>
<em>#elseif</em> tai <em>#else</em> elementtej� voidaan k�ytt��
<em>#if</em> elementin kanssa. Huomaa, ett� Velocityn
sivumoottori lopettaa ensimm�isen tosiarvon saaneen
testimuuttujan kohdalla. Oletetaan seuraavassa esimerkiss� ett�
muuttujalla <em>$foo</em> on arvo 15 ja muuttujalla
<em>$bar</em> on arvo 6.
</p>
<source><![CDATA[
#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
]]></source>
<p>T�ss� esimerkiss� <em>$foo</em> on suurempi kuin 10, joten
kaksi ensimm�ist� vertailua eiv�t ole tosia. Seuraavaksi muuttujaa
<em>$bar</em> verrataan lukuun 6, joka on tosi, joten tulosteeksi
tulee <strong>Mene etel��n</strong>.
</p>
<p>
Huomaa, ett� nykyisell��n Velocityn numeeriset vertailut on
rajoitettu Integer (kokonais-) lukuihin. Kaikki muut arvot
tulkitaan <em>ep�tosi</em>ksi. Ainoa poikkeus t�h�n on vastaavuus
'==', jolloin Velocity vaatii ett� objektit vertailun kummallakin
puolella ovat <em>samaa</em> luokkaa.
</p>
<p>
<a name="Relaatio- ja loogiset operaattorit"><strong>Relaatio- ja
loogiset operaattorit</strong></a>
</p>
<p>
Velocity k�ytt�� vastaavuusoperaattoria muuttujien v�listen
suhteiden tulkitsemiseen. Seuraavassa on yksinkertainen esimerkki
vastaavuusoperaattorin k�yt�st�.
</p>
<source><![CDATA[
#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
]]></source>
<p>
Velocity tukee my�s loogisia AND ja OR
operaattoreita. Lis�tietoja l�yd�t dokumentista <a
href="vtl-reference-guide.html">VTL Reference Guide</a>. Alla on
esimerkkilause joka k�ytt�� loogista AND:i�.
</p>
<source><![CDATA[
## looginen AND
#if( $foo && $bar )
<strong> T�m� JA tuo</strong>
#end
]]></source>
<p>
If lause on tosi vain mik�li sek� <em>$foo</em> ett�
<em>$bar</em> ovat tosia. Jos <em>$foo</em> on ep�tosi, tulee
lauseesta ep�tosi eik� <em>$bar</em> muuttujaa tarvitse edes
testata. Jos <em>$foo</em> on tosi, testataan sen j�lkeen
muuttujan <em>$bar</em> arvo; jos my�s <em>$bar</em> on tosi,
silloin koko ilmaus on tosi ja <strong>T�m� JA tuo</strong>
tulee tulosteeksi. Jos <em>$bar</em> on ep�tosi, silloin koko
ilmaus on ep�tosi eik� tulostetta tule.
</p>
<p>
Looginen OR operaattori toimii samaan tapaan, paitsi ett� vain
toisen viittauksen pit�� olla tosi jotta koko ilmaus olisi
tosi. Katso seuraavaa esimerkki�.
</p>
<source><![CDATA[
## looginen OR
#if( $foo || $bar )
<strong>T�m� TAI tuo</strong>
#end
]]></source>
<p>
Jos <em>$foo</em> on tosi, ei <em>$bar</em> muuttujaa tarvitse
edes testata. Oli <em>$bar</em> sitten tosi tai ep�tosi, koko
lauseke on tosi, ja <strong>T�m� TAI tuo</strong> on
tulosteena. Toisaalta mik�li <em>$foo</em> on ep�tosi, on
muuttujan <em>$bar</em> arvo testattava. Jos t�ss� tapauksessa
my�s <em>$bar</em> on ep�tosi, koko ilmauksesta tulee ep�tosi
eik� tulostetta tule. Jos <em>$bar</em> on tosi, silloin koko
ilmauksesta tulee tosi, ja tulosteena on <strong>T�m� TAI
tuo</strong>.
</p>
<p>
Loogisella EI (NOT) operaattorilla on vain yksi argumentti :
</p>
<source><![CDATA[
## looginen NOT
#if( !$foo )
<strong>EI tuota</strong>
#end
]]></source>
<p>
Jos <em>$foo</em> on tosi, silloin <em>!$foo</em> on ep�tosi, eik�
tulostetta t�m�n vuoksi tule. Mik�li <em>$foo</em> on ep�tosi,
silloin <em>!$foo</em> on tosi ja <strong>EI tuota</strong> on
tulosteena. �l� sekoita t�t� merkint�� <em>hiljaiseen viittaukseen
$!foo</em> joka tarkoittaa jotakin aivan muuta.
</p>
</section>
<section name="Silmukat">
<strong>Foreach silmukat</strong>
<p>
<em>#foreach</em> mahdollistaa silmukoiden tekemisen. Esimerkiksi:
</p>
<source><![CDATA[
<ul>
#foreach( $tuote in $kaikkiTuotteet )
<li>$tuote</li>
#end
</ul>
]]></source>
<p>
T�m� <em>#foreach</em> silmukka k�y l�pi yksi kerrallaan kaikki
<em>$kaikkiTuotteet</em> listassa olevat tuotteet. Jokaisella
kierroksella seuraavan tuotteen arvo kopioidaan
<em>$kaikkiTuotteet</em> listasta muuttujaan <em>$tuote</em>.
</p>
<p>
<em>$kaikkiTuotteet</em> lista on tyyppi� Vector, Hashtable tai
Array. <em>$tuote</em> muuttujaan kopioitu arvo on java objekti
(Object), joten siihen voidaan my�s viitata objektina. Jos
esimerkiksi <em>$tuote</em> muuttuja olisi tyyppi� Tuote, sen nimi
voitaisiin hakea viittaamalla <em>$tuote.Name</em> metodiin
(ts. <em>$Tuote.getName()</em>.
</p>
<p>
Oletetaan ett� <em>$kaikkiTuotteet</em> on tyyppi� Hashtable. Jos
haluat hakea Hashtablen avainarvot sek� niihin liittyv�t objektit,
voit k�ytt�� seuraavanlaista koodia:
</p>
<source><![CDATA[
<ul>
#foreach( $avain in $kaikkiTuotteet.keySet() )
<li>Avain: $avain -> Arvo: $kaikkiTuotteet.get($avain)</li>
#end
</ul>
]]></source>
<p>
Velocityll� on helppo keino silmukkalaskurin k�ytt�miseen. Voit
k�ytt�� laskuria esimerkiksi seuraavasti:
</p>
<source><![CDATA[
<table>
#foreach( $asiakas in $asiakasLista )
<tr><td>$velocityCount</td><td>$asiakas.Nimi</td></tr>
#end
</table>
]]></source>
<p>
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
<code>velocity.properties</code>
tiedostossa. <code>velocity.properties</code> tiedoston
silmukkalaskuriosio n�ytt�� t�lt�:
</p>
<source><![CDATA[
# Silmukkalaskurin oletusnimi
counter.name = velocityCount
# Silmukkalaskurin aloitusarvo
counter.initial.value = 1
]]></source>
</section>
<section name="Include">
<p>
<em>#include</em> elementin avulla sivusuunnittelija voi hakea
paikallisesta tiedostoj�rjestelm�st� tiedoston, jonka sis�lt�
lis�t��n sivun siihen kohtaan jossa <em>#include</em> 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.
</p>
<source><![CDATA[
#include( "yksi.txt" )
]]></source>
<p>
Tiedosto johon <em>#include</em> ohje viittaa on
lainausmerkeiss�. Jos halutaan sis�llytt�� useampia kuin yksi
tiedosto, tiedostonimet tulee erotella toisistaan pilkuilla.
</p>
<source><![CDATA[
#include( "yksi.gif","kaksi.txt","kolme.htm" )
]]></source>
<p>
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.
</p>
<source><![CDATA[
#include( "terveiset.txt", $sesonkivarasto )
]]></source>
</section>
<section name="Parse">
<p>
<em>#parse</em> 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.
</p>
<source><![CDATA[
#parse( "mina.vm" )
]]></source>
<p>
<em>#include</em> ohjeen tapaan <em>#parse</em> voi ottaa
parametrikseen nimen lis�ksi my�s muuttujan. Kaikkien sivupohjien
joihin <em>#parse</em> ohjeella viitataan tulee sijaita
TEMPLATE_ROOT vakion m��ritt�m�n hakemiston
alla. <em>#include</em> ohjeesta poiketen <em>#parse</em> voi
ottaa vain yhden argumentin.
</p>
<p>
VTL sivupohjissa voi olla <em>#parse</em> ohjeita jotka viittaavat
sivupohjiin joissa niiss�kin on <em>#parse</em>
ohjeita. <code>velocity.properties</code> tiedostossa oleva rivi
<em>parse_directive.maxdepth</em> m��ritt�� sen kuinka monta
per�kk�ist� <em>#parse</em> viittausta voidaan tehd�. Mik�li
<em>parse_directive.maxdepth</em> m��ritys puuttuu, k�ytet��n
oletusarvoa 10. Rekursiivisuus on sallittu. Jos esimerkiksi
sivupohja <code>dofoo.vm</code> sis�lt�� seuraavat rivit:
</p>
<source><![CDATA[
Laske alasp�in.
#set( $laskuri = 8 )
#parse( "parsefoo.vm" )
Kaikki valmista: dofoo.vm!
]]></source>
<p>
Koodi viittaisi sivupohjaan <code>parsefoo.vm</code>, jossa
puolestaan voisi olla seuraavat VTL komennot:
</p>
<source><![CDATA[
$laskuri
#set( $laskuri = $laskuri - 1 )
#if( $laskuri > 0 )
#parse( "parsefoo.vm" )
#else
Kaikki valmista: parsefoo.vm!
#end
]]></source>
<p>
Kun "Laske alasp�in." on n�ytetty, Velocity lataa ja siirt��
kontrollin sivupohjalle <code>parsefoo.vm</code>, joka laskee alas
luvusta 8. Kun laskuri saavuttaa arvon 0, tulostetaan "Kaikki
valmista: parsefoo.vm!". T�m�n j�lkeen Velocity palaa sivupohjaan
<code>dofoo.vm</code> ja tulostaa "Kaikki valmista: dofoo.vm!"
tekstin.
</p>
</section>
<section name="Stop">
<p>
<em>#stop</em> elementin avulla sivupohjan suunnittelija voi
pys�ytt�� sivun tulkitsemisen. T�m� on hy�dyllist� sivupohjan
virheidenetsinn�n aikana.
</p>
<source><![CDATA[
#stop
]]></source>
</section>
<section name="Velocimakrot">
<p>
<em>#macro</em> 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.
</p>
<source><![CDATA[
#macro( d )
<tr><td></td></tr>
#end
]]></source>
<p>
Esimerkiss� m��riteltiin Velocimakro nimelt��n <em>d</em>, ja sit�
voidaan kutsua muiden VTL ohjeiden tapaan:
</p>
<source><![CDATA[
#d()
]]></source>
<p>
Kun t�t� sivupohjaa haetaan, Velocity korvaa ohjeen <em>#d()</em>
rivill� joka sis�lt�� yhden tyhj�n solun.
</p>
<p>
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.
</p>
<source><![CDATA[
#macro( taulurivit $vari $jokulista )
#foreach( $jotain in $jokulista )
<tr><td bgcolor=$vari>$jotain</td></tr>
#end
#end
]]></source>
<p>
T�ss� esimerkiss� m��riteltiin Velocimakro <em>taulurivit</em>
joka ottaa kaksi parametria. Ensimm�inen parametri on
<em>$vari</em> ja toinen <em>$jokulista</em>.
</p>
<p>
Velocimakroon voidaan kirjoittaa mit� tahansa koodia jota voidaan
k�ytt�� muuallakin VTL sivupohjassa. <em>taulurivit</em>
Velocimakro on <em>foreach</em> lause. <em>taulurivit</em>
Velocimakrossa on kaksi <em>#end</em> lausetta; ensimm�inen kuuluu
<em>#foreach</em> lauseelle, j�lkimm�inen p��tt�� Velocimakron
m��rityksen.
</p>
<source><![CDATA[
#set( $suuretjarvet = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $vari = "blue" )
<table>
#taulurivit( $vari $suuretjarvet )
</table>
]]></source>
<p>
Huomaa ett� <em>$suuretjarvet</em> on makron parametrin
<em>$jokulista</em> arvona. Kun Velocimakroa <em>#taulurivit</em>
t�ss� tapauksessa kutsutaan, on tuloksena seuraavaa:
</p>
<source><![CDATA[
<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>
]]></source>
<p>
Velocimakroja voidaan m��ritt�� <em>inline</em>, 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�.
</p>
<p>
Oletetaan ett� Velocityss� on m��riteltyn� Velocimakro
<em>#tablerows($vari $lista)</em>. 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 <code>sieni.vm</code>, <em>#tablerows</em>
Velocimakroa voitaisiin k�ytt�� listaamaan tyypillisen sienen
osat:
</p>
<source><![CDATA[
#set( $osat = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $osat )
</table>
]]></source>
<p>
Kun Velocity luo sivun sivupohjasta <code>sieni.vm</code>, se
etsii Velocimakron <em>#tablerows</em> sivupohjakirjastosta (joka
on m��ritelty <code>velocity.properties</code> tiedostossa) ja
tuottaa seuraavan tulosteen:
</p>
<source><![CDATA[
<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>
]]></source>
<strong>Velocimakron argumentit</strong>
<p>
Velocimakrot voivat ottaa argumenteiksi mit� tahansa seuraavista
VTL elementeist�:
</p>
<ul>
<li>
Viittaus : mit� tahansa '$' merkill� alkavaa
</li>
<li>
Tekstivakio : esimerkiksi "$foo" tai 'hei'
</li>
<li>
Numerovakio : 1, 2 jne
</li>
<li>
Numerov�li : [ 1..2] tai [$foo .. $bar]
</li>
<li>
ObjectArray : [ "a", "b", "c"]
</li>
<li>
boolean arvo true (tosi)
</li>
<li>
boolean arvo false (ep�tosi)
</li>
</ul>
<p>
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:
</p>
<source><![CDATA[
#macro( kutsu $a )
$a $a $a
#end
#kutsu( $foo.bar() )
]]></source>
<p>
tuloksena viittauksen $foo metodia bar() kutsutaan 3 kertaa.
</p>
<p>
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.
</p>
<p>
Jos sinun tarvitsee kiert�� t�m� ominaisuus, voit hakea arvon
metodista uudeksi viittaukseksi, ja antaa sen argumentiksi:
</p>
<source><![CDATA[
#set( $uusiarvo = $foo.bar() )
#kutsu( $uusiarvo )
]]></source>
<strong>Velocimakro ominaisuudet</strong>
<p>
<code>velocity.properties</code> tiedostossa on useita rivej�
joiden avulla Velocimakrojen toimintaa voidaan muuttaa
joustavasti. Huomaa ett� n�m� arvot on dokumentoitu my�s <a
href="http://jakarta.apache.org/velocity/developer-guide.html">Kehitt�j�n
oppaassa</a>.
</p>
<p>
<code>velocimacro.library</code> - Pilkulla eroteltu lista
Velocimakro sivupohjakirjastoja. Oletuksena Velocity etsii yht�
kirjastoa: <em>VM_global_library.vm</em>. Velocimakro kirjastoja
etsit��n m��ritellyst� sivupohjahakemistosta.
</p>
<p>
<code>velocimacro.permissions.allow.inline</code> - 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.
</p>
<p>
<code>velocimacro.permissions.allow.inline.to.replace.global</code>
- T�m�n ominaisuuden avulla voidaan m��ritt�� voivatko
sivupohjassa m��ritellyt Velocimakrot korvata yleisesti
m��ritellyt, <code>velocimacro.library</code> ominaisuuden kautta
ladatut Velocimakrot. Ominaisuus voi saada arvon true tai
false. Oletuksena <code>false</code>, ep�tosi, jolloin
sivupohjassa m��ritellyt Velocimakrot eiv�t voi korvata
sivupohjakirjastoista ladattuja makroja.
</p>
<p>
<code>velocimacro.permissions.allow.inline.local.scope</code> -
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.
</p>
<p>
<code>velocimacro.context.localscope</code> - 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.
</p>
<p>
<code>velocimacro.library.autoreload</code> - T�m� ominaisuus
ohjaa Velocimakrokirjaston automaattista uudelleenlatausta. Kun
ominaisuus on asetettu arvoon <code>true</code> 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� (<i>off</i>,
esim. <code>file.resource.loader.cache = false</code>). T�m�
ominaisuus on tarkoitettu k�ytett�v�ksi vain sovelluksen
kehitysvaiheessa, ei tuotantok�ytt��n.
</p>
<strong>Velocimakro Trivia</strong>
<p>
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.
</p>
<p>
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�
<code>velocimacro.library</code> toimintoa jonka avulla Velocity
lataa Velocimakrosi k�ynnistyksen yhteydess�.
</p>
</section>
<section name="VTL ohjeiden suojaaminen">
<p>
VTL ohjeet voidaan suojata kenoviivalla ("\") samalla tavalla kuin
VTL viittauksetkin.
</p>
<source><![CDATA[
## #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" )
]]></source>
<p>
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:
</p>
<source><![CDATA[
#if( $jazz )
Vyacheslav Ganelin
#end
]]></source>
<p>
Jos <em>$jazz</em> on tosi (true), tuloste on
</p>
<source><![CDATA[
Vyacheslav Ganelin
]]></source>
<p>
Jos <em>$jazz</em> on ep�tosi (false), tulostetta ei
tule. Skriptielementtien suojaaminen muuttaa tulostetta. Katso
seuraavaa esimerkki�:
</p>
<source><![CDATA[
\#if( $jazz )
Vyacheslav Ganelin
\#end
]]></source>
<p>
Riippumatta siit� onko <em>$jazz</em> tosi vai ep�tosi, tuloste on
aina:
</p>
<source><![CDATA[
#if($ jazz )
Vyacheslav Ganelin
#end
]]></source>
<p>
Itse asiassa koska kaikki skriptielementit on suojattu,
<em>$jazz</em> muuttujan totuusarvoa ei edes tutkita. Oletetaan ett�
kenoviiva edelt�� skriptielementtej� jotka on suojattu:
</p>
<source><![CDATA[
\\#if( $jazz )
Vyacheslav Ganelin
\\#end
]]></source>
<p>
Mik�li <em>$jazz</em> on t�ss� tapauksessa tosi, tuloste on:
</p>
<source><![CDATA[
\ Vyacheslav Ganelin
\
]]></source>
<p>
T�m�n ymm�rt�miseksi huomaa, ett� <code>#if( arg )</code> rivill�
olevaa rivinvaihtoa (return) ei kopioida tulosteeseen. T�m�n vuoksi
<code>#if()</code> 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 <code>#end</code> ohjetta,
joten merkki kuuluu edelleen <code>#if()</code> lauseen runkoon.
</p>
<p>
Jos <em>$jazz</em> on ep�tosi, ei tulostetta tule. Huomaa ett�
ongelmia tulee mik�li skriptielementtej� ei ole suojattu oikein.
</p>
<source><![CDATA[
\\\#if( $jazz )
Vyacheslave Ganelin
\\#end
]]></source>
<p>
Esimerkiss� <em>#if</em> on suojattu, mutta <em>#end</em> elementti
on edelleen k�yt�ss�. Liian monta lopetuselementti� sivupohjassa
aiheuttaa virheen sivua luotaessa.
</p>
</section>
<section name="VTL: Muotoilu">
<p>
Vaikka t�ss� ohjeessa oleva VTL on usein muotoiltu rivivaihdoin ja
v�lily�nnein, alla oleva VTL
</p>
<source><![CDATA[
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
$shogun
#end
]]></source>
<p>
on yht� toimiva kuin seuraava kodinp�tk� jonka Geir Magnusson
Jr. l�hetti Velocityn k�ytt�jien postituslistalle:
</p>
<source><![CDATA[
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
]]></source>
<p>
Velocity sy� ylim��r�iset v�lily�nnit. Edellinen koodinp�tk�
voitaisiin kirjoittaa seuraavasti:
</p>
<source><![CDATA[
Send me
#set( $foo = ["$10 and ","a cake"] )
#foreach( $a in $foo )
$a
#end
please.
]]></source>
<p>
tai
</p>
<source><![CDATA[
Send me
#set($foo = ["$10 and ","a cake"])
#foreach ($a in $foo )$a
#end please.
]]></source>
<p>
Kussakin tapauksessa tulos on sama.
</p>
</section>
<section name="Muita ominaisuuksia ja sekalaista">
<subsection name="Matematiikka">
<p>
Velocitylla on muutamia sis��nrakennettuja matemaattisia
funktioita joita voidaan k�ytt�� sivupohjissa <em>#set</em> ohjeen
kanssa. Seuraavat yht�l�t ovat esimerkkej� yhteen-, v�hennys-,
kerto- sek� jakolaskuista.
</p>
<source><![CDATA[
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
]]></source>
<p>
Jako-operaation tapauksessa tulos on kokonaisluku. Jakoj��nn�s
saadaan k�ytt��n j��nn�soperandilla (<em>%</em>).
</p>
<source><![CDATA[
#set( $foo = $bar % 5 )
]]></source>
<p>
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).
</p>
<p>
Velocityll� on sis��nrakennettu keino nollalla jakamisen
k�sittelemiseen. Seuraavassa esimerkiss�:
</p>
<source><![CDATA[
#set( $foo = 5 )
#set( $bar = $foo - 5 )
#set( $uhoh = $foo / $bar )
$uhoh
]]></source>
<p>
Viittaukseen <em>$uhoh</em> asetetaan tulos operaatiosta viisi
jaettuna nollalla. Kun Velocity n�ytt�� t�m�n sivupohjan, tuloste
on:
</p>
<source><![CDATA[
$uhoh
]]></source>
<p>
Suunnittelijoiden on otettava huomioon my�s, ett� <em>#set</em>
tuottaa merkkijonoja, jotka on muunnettava kokonaisluvuiksi jotta
niit� voidaan k�ytt�� vaihteluv�li� m��ritett�ess� (range
operator). Seuraavassa esimerkki t�llaisesta muunnoksesta:
</p>
<source><![CDATA[
#set($a = "7")
#set($b = $int.valueOf($a) + 10)
$b
]]></source>
<p>
Tuloksena on <em>17</em>.
</p>
</subsection>
<subsection name="Vaihteluv�li (Range Operator)">
<p>
Vaihteluv�li� voidaan k�ytt�� <em>#set</em> ja <em>#foreach</em>
lauseiden yhteydess�. Vaihteluv�li tuottaa kokonaislukuja
sis�lt�vi� oliotaulukoita seuraavalla tavalla:
</p>
<source><![CDATA[
[n..m]
]]></source>
<p>
Sek� <em>n</em> ett� <em>m</em> pit�� olla tai niiden tulee
tuottaa kokonaislukuja. Mik�li <em>m</em> on pienempi kuin
<em>n</em> lasketaan vaihteluv�lin luvut alasp�in. Seuraavassa
esimerkkej� vaihteluv�lin k�yt�st�:
</p>
<source><![CDATA[
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]
]]></source>
<p>
Tuottaa seuraavan tulosteen:
</p>
<source><![CDATA[
Ensimm�inen esimerkki:
1 2 3 4 5
Toinen esimerkki:
2 1 0 -1 -2
Kolmas esimerkki:
0 1
Nelj�s esimerkki:
[1..3]
]]></source>
<p>
Huomaa ett� vaihteluv�lioperaattori tuottaa taulukon vain kun sit�
k�ytet��n <em>#set</em> tai <em>#foreach</em> ohjeiden kanssa,
kuten nelj�nnest� esimerkist� k�y selville.
</p>
<p>
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.
</p>
</subsection>
<subsection name="Edistyneet kysymykset: Suojaaminen ja !">
<p>
Kun viittaus hiljennet��n <em>!</em> merkill� ja <em>!</em> merkki�
edelt�� suojausmerkki <em>\</em> k�sitell��n viittaus erityisell�
tavalla. Huomaa erot normaalin suojauksen ja tilanteen jossa
<em>\</em> edelt�� <em>!</em> merkki�, v�lill�.
</p>
<source><![CDATA[
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
]]></source>
<p>
Tulosteena on:
</p>
<source><![CDATA[
$!foo
$!{foo}
$\!foo
$\\!foo
]]></source>
<p>
Vertaa t�t� normaaliin suojaukseen, jossa <em>\</em> on <em>$</em>
merkin edell�:
</p>
<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\\$!{foo}
]]></source>
<p>
Tulosteena on:
</p>
<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\bar
]]></source>
</subsection>
<subsection name="Yleist� Velocimakroista">
<p>
T�m� osio on Velocimakroaiheinen mini-FAQ. Osio muuttuu ajan my�t�,
joten uutta tietoa hakevien kannattanee palata sivulle aika ajoin.
</p>
<p>
Huom! : T�ss� osiossa 'Velocimakro':ihin viitataan usein lyhenteell�
'VM'.
</p>
<strong>Voinko k�ytt�� ohjetta tai toista VM:a argumenttina
VM:oon?</strong>
<p>
Esimerkki : <code>#center( #bold("hello") )</code>
</p>
<p>
Et. Ohje ei ole sallittu argumentti ohjeelle, ja VM on
k�yt�nn�llisesti katsoen ohje.
</p>
<p>
<i>Kuitenkin...</i>, voit kiert�� rajoituksen. Yksinkertainen ratkaisu
on k�ytt�� hyv�ksi sit� ett� lainausmerkeiss� (") oleva teksti
tulkitaan. T�m� ansiosta voit tehd� seuraavasti:
</p>
<source><![CDATA[
#set($stuff = "#bold('hello')" )
#center( $stuff )
]]></source>
<p>
Voit my�s s��st�� rivin...
</p>
<source><![CDATA[
#center( "#bold( 'hello' )" )
]]></source>
<p>
Huomaa ett� j�lkimm�isess� esimerkiss� parametri k�sitell��n VM:n
<i>sis�ll�</i>, 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:
</p>
<source><![CDATA[
#macro( inner $foo )
inner : $foo
#end
#macro( outer $foo )
#set($bar = "outerlala")
outer : $foo
#end
#set($bar = 'calltimelala')
#outer( "#inner($bar)" )
]]></source>
<p>
Tulosteeksi tulee
</p>
<source><![CDATA[
Outer : inner : outerlala
]]></source>
<p>
koska parametrin "#inner($bar)" tulkitseminen tapahtuu lauseen
#outer() sis�ll�, k�ytet��n muuttujan $bar arvoa joka asetettiin
#outer VM:ssa.
</p>
<p>
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
</p>
<source><![CDATA[
#macro( foo $vari )
<tr bgcolor=$vari><td>Hei</td></tr>
<tr bgcolor=$vari><td>Siell�</td></tr>
#end
#foo( $bar.rivinVari() )
]]></source>
<p>
jossa rivinVari() metodia kutsutaan toistuvasti, ei vain kerran. Sen
v�ltt�miseksi kutsu metodia VM:n ulkopuolelta ja siirr� arvo VM:oon.
</p>
<source><![CDATA[
#set($vari = $bar.rivinVari())
#foo( $vari )
]]></source>
<strong>Voinko rekister�id� Velocimakroja #parse() :n kautta?
</strong>
<p>
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.
</p>
<p>
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�
<code>velocimacro.library</code> toimintoa jonka avulla Velocity
lataa Velocimakrosi k�ynnistyksen yhteydess�.
</p>
<strong>Mit� tarkoittaa Velocimakrojen automaattinen
uudelleenlataus?</strong>
<p>
On olemassa asetus joka on tarkoitettu k�ytett�v�ksi j�rjestelm�n
<i>kehityksen</i> aikana, ei k�yt�ss� olevassa j�rjestelm�ss� :
</p>
<p>
<code>velocimacro.library.autoreload</code>
</p>
<p>
joka on oletuksena pois k�yt�st� (false). Kun ominaisuus on
asetettu k�ytt��n (true) <em>yhdess�</em> asetuksen
</p>
<p>
<code><type>.resource.loader.cache = false</code>
</p>
<p>
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.
</p>
<p>
Yksinkertainen konfiguraatio saattaisi n�ytt�� seuraavalta:
</p>
<source><![CDATA[
file.resource.loader.path = templates
file.resource.loader.cache = false
velocimacro.library.autoreload = true
]]></source>
<p>
�l� k�yt� n�it� asetuksia tuotantok�yt�ss�.
</p>
</subsection>
<subsection name="Merkkijonojen yhdist�minen">
<p>
Yleinen kehitt�jien kysym� kysymys on <i>Kuinka yhdist�n
merkkijonoja? Onko olemassa Javan '+' operaattoria vastaavaa
toimintoa?</i>.
</p>
<p>
Viittausten liitt�miseksi yhteen VTL:ssa, sinun tarvitsee vain
'laittaa ne yhteen'. Konteksti jossa yhdist�t viittaukset
vaikuttaa tuloksiin, joten esimerkit ovat paikallaan.
</p>
<p>
Normaalissa tapauksessa (jolloin sekoitat muuttujat sivupohjan
muuhun sis�lt��n) :
</p>
<source><![CDATA[
#set( $koko = "Big" )
#set( $nimi = "Ben" )
Kello on $iso$nimi.
]]></source>
<p>
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:
</p>
<source><![CDATA[
#set( $koko = "Big" )
#set( $nimi = "Ben" )
#set($kello = "$koko$nimi" )
Kello on $kello.
]]></source>
<p>
Josta tulee sama tuloste. Viimeisen� esimerkkin�, kun haluat
sekoittaa 'staattisia' merkkijonoja viittauksiin, saatat joutua
k�ytt�m��n 'muodollista viittausten merkint��' :
</p>
<source><![CDATA[
#set( $koko = "Big" )
#set( $nimi = "Ben" )
#set($kello = "${koko}Tall$nimi" )
Kello on $kello.
]]></source>
<p>
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�.
</p>
</subsection>
</section>
<section name="Palaute">
<p>
Mik�li l�yd�t t�st� ohjeesta virheit� tai haluat antaa ohjetta
koskevaa palautetta, ole hyv� ja l�het� s�hk�postia <a
href="mailto:velocity-user@jakarta.apache.org">Velocity
k�ytt�j�listalle</a>. Kiitos!
</p>
</section>
</body>
</document>
\ No newline at end of file
+<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Velocity k�ytt�j�n opas</title>
<author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
<author email="jcastura@kw.igs.net">John Castura</author>
<author email="juha@dwebs.com">Juha Kilpi</author>
</properties>
<body>
<section name="Sis�llys">
<ol>
<li><a href="#Tietoja t�st� oppaasta">Tietoja t�st� oppaasta</a></li>
<li><a href="#Mik� on Velocity?">Mik� on Velocity?</a></li>
<li><a href="#Miten voin k�ytt�� Velocity�?">Miten voin k�ytt�� Velocity�?</a>
<ol>
<li><a href="#Kurakauppa esimerkki">Kurakauppa esimerkki</a></li>
</ol>
</li>
<li><a href="#Velocity Template Language (VTL): Johdanto">Velocity
Template Language (VTL): Johdanto</a></li>
<li><a href="#Hei Velocity Maailma!">Hei Velocity Maailma!</a></li>
<li><a href="#Kommentit">Kommentit</a></li>
<li><a href="#Viittaukset">Viittaukset</a>
<ol>
<li><a href="#Muuttujat">Muuttujat</a></li>
<li><a href="#Ominaisuudet">Ominaisuudet</a></li>
<li><a href="#Metodit">Metodit</a></li>
</ol>
</li>
<li><a href="#Muodollinen merkint�">Muodollinen viittausten merkint�</a></li>
<li><a href="#Hiljainen viittausten merkint�">Hiljainen viittausten merkint�</a></li>
<li><a href="#Kirjaimellisesti">Kirjaimellisesti</a>
<ol>
<li><a href="#Dollari">Dollari</a></li>
<li><a href="#VTL viittausten suojaaminen">VTL viittausten suojaaminen</a></li>
</ol>
</li>
<li><a href="#Kirjainkoon muutos">Kirjainkoon muutos</a></li>
<li><a href="#Ohjeet">Ohjeet</a>
<ol>
<li><a href="#Set">Set</a></li>
<li><a href="#Tekstivakiot">Tekstivakiot</a></li>
<li><a href="#If-Else ehtolauseet">If-Else ehtolauseet</a>
<ol>
<li><a href="#Relaatio- ja loogiset operaattorit">Relaatio- ja loogiset
operaattorit</a></li>
</ol>
</li>
<li><a href="#Silmukat">Foreach silmukat</a></li>
<li><a href="#Include">Include</a></li>
<li><a href="#Parse">Parse</a></li>
<li><a href="#Stop">Stop</a></li>
<li><a href="#Velocimakrot">Velocimakrot</a></li>
</ol>
</li>
<li><a href="#VTL ohjeiden suojaaminen">VTL ohjeiden suojaaminen</a></li>
<li><a href="#VTL: Muotoilu">VTL: Muotoilu</a></li>
<li><a href="#Muita ominaisuuksia ja sekalaista">Muita ominaisuuksia ja sekalaista</a>
<ol>
<li><a href="#Matematiikka">Matematiikka</a></li>
<li><a href="#Vaihteluv�li (Range Operator)">Vaihteluv�li (Range Operator)</a></li>
<li><a href="#Edistyneet kysymykset: Suojaaminen ja
!">Edistyneet kysymykset: Suojaaminen ja !</a></li>
<li><a href="#Yleist� Velocimakroista">Yleist� Velocimakroista</a></li>
<li><a href="#Merkkijonojen yhdist�minen">Merkkijonojen yhdist�minen</a></li>
</ol>
</li>
<li><a href="#Palaute">Palaute</a></li>
</ol>
</section>
<section name="Tietoja t�st� oppaasta">
<p>
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.
</p>
<p>
Kiitos ett� valitsit Velocityn!
</p>
</section>
<section name="Mik� on Velocity?">
<p>
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 <a
href="http://java.sun.com/products/jsp/">JSP</a>:lle (Java Server
Pages) ja <a href="http://www.php.net/">PHP</a>:lle.
</p>
<p>
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 <a
href="http://java.apache.org/turbine/">Turbine</a> web
sovelluskehykselle. Yhdess� Velocity ja Turbine tarjoavat
sivupohjaratkaisun jonka avulla web sovelluksia voidaan kehitt��
todellisen MVC -mallin mukaisesti.
</p>
</section>
<section name="Miten voin k�ytt�� Velocity�?">
<subsection name="Kurakauppa esimerkki">
<p>
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�?
</p>
<p>
Velocityn avulla verkkosivut on helppo personoida k�vij�idesi
mukaan. Kurakauppa Onlinen sivusuunnittelijana haluat tehd� sivun
jonka asiakas n�kee kirjauduttuaan j�rjestelm��n.
</p>
<p>
Tapaat yrityksesi ohjelmoijat ja sovitte, ett� muuttuja
<em>$asiakas</em> pit�� sis�ll��n tiedot parhaillaan kirjautuneena
olevasta asiakkaasta. Muuttujassa <em>$kuratTarjouksessa</em> ovat
tiedot kuratyypeist� jotka ovat parhaillaan
erikoistarjouksessa. <em>$tarjous</em> 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.
</p>
<p>
Voisit lis�t� seuraavat VTL lauseen sivulle:
</p>
<source><![CDATA[
<HTML>
<BODY>
Hei $asiakas.Nimi!
<table>
#foreach( $kura in $kuratTarjouksessa )
#if ( $asiakas.onOstanut($kura) )
<tr>
<td>
$tarjous.haePromo( $kura )
</td>
</tr>
#end
#end
</table>
]]></source>
<p>
<em>foreach</em> 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.
</p>
<p>
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�.
</p>
</subsection>
</section>
<section name="Velocity Template Language (VTL): Johdanto">
<p>
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.
</p>
<p>
VTL k�ytt�� <em>viittauksia</em> 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 <em>lauseen</em> avulla. Seuraavassa on esimerkki VTL
lauseesta joka voidaan lis�t� HTML -dokumenttiin:
</p>
<source><![CDATA[
#set( $a = "Velocity" )
]]></source>
<p>
Kuten kaikki VTL lauseet (statement), t�m�kin lause alkaa <em>#</em>
merkill� ja sis�lt�� ohjeen (directive): <em>set</em>. Kun verkkosivun
k�ytt�j� hakee sivun Velocity etsii sivupohjastasi kaikki
<em>#</em> -merkit. Sitten se tulkitsee mitk� niist� merkitsev�t
VTL lausetta, ja mitk� <em>#</em> merkeist� ovat osa sivujesi
normaalia HTML -koodia, eiv�tk� kuulu VTL -koodiin.
</p>
<p>
<em>#</em> merkki� seuraa ohje, <em>set</em>. <em>set</em> ohjeen
j�lkeen tulee suluissa ilmaus (expression), -- yht�l� joka m��ritt��
<em>arvon</em> <em>muuttujalle</em>. Muuttuja on ilmaistu
vasemmalla ja arvo oikealla puolella. N�m� on erotettu <em>=</em>
merkill�.
</p>
<p>
Yll� olevassa esimerkiss� muuttuja on <em>$a</em> ja arvo on
<em>Velocity</em>. Kaikkien viittausten tapaan t�m�kin muuttuja
alkaa <em>$</em> merkill�. Arvot ovat aina lainausmerkkien
sis�ll�; Velocityss� muuttujien datatyypeist� ei tule
sekaannuksia, koska vain merkkijonoja (string) voi antaa
muuttujien arvoksi.
</p>
<p>
Seuraava nyrkkis��nt� voi auttaa ymm�rt�m��n Velocityn toimintaa:
<strong>Viittaukset alkavat <em>$</em> merkill� ja niit� k�ytet��n
jonkin hakemiseen. Ohjeet alkavat <em>#</em> merkill� ja niit�
k�ytet��n jonkin suorittamiseen.</strong>
</p>
<p>
Yll� olevassa esimerkiss� <em>#set</em> -ohjetta k�ytet��n arvon
m��ritt�miseksi muuttujaan. Muuttujaa <em>$a</em> voidaan t�m�n
j�lkeen k�ytt�� sivupohjassa tulostamaan "Velocity".
</p>
</section>
<section name="Hei Velocity Maailma!">
<p>
Kun muuttujalle on m��ritelty arvo, voidaan siihen viitata miss�
tahansa paikassa HTML dokumenttia. Seuraavassa esimerkiss�
muuttujalle <em>$foo</em> m��ritell��n arvo. My�hemmin muuttujaan
viitataan.
</p>
<source><![CDATA[
<html>
<body>
#set( $foo = "Velocity" )
Hei $foo Maailma!
</body>
<html>
]]></source>
<p>
Tuloksena on web sivu jossa lukee "Hei Velocity Maailma!".
</p>
<p>
Jotta VTL lauseet olisivat helpommin luettavissa on suositeltavaa
aloittaa jokainen lause uudelta rivilt�, vaikkakaan t�m� ei ole
pakollista. <em>set</em> ohjeeseen palaamme tarkemmin my�hemmin.
</p>
</section>
<section name="Kommentit">
<p>
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�.
</p>
<source><![CDATA[
## T�m� on rivin pituinen kommentti.
]]></source>
<p>
Yhden rivin pituinen kommentti alkaa <em>##</em> 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 <em>#*</em>
merkeill� ja loppuvat <em>*#</em> merkkeihin.
</p>
<source><![CDATA[
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�.
]]></source>
<p>
T�ss� on muutamia esimerkkej� yksi- ja monirivisten kommenttien
toiminnan selvitt�miseksi:
</p>
<source><![CDATA[
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�.
]]></source>
<p>
On olemassa viel� kolmaskin kommenttityyppi; VTL kommenttilohko,
jota voidaan k�ytt�� mm. dokumentin tekij�- ja versiotietojen
tallettamiseen
</p>
<source><![CDATA[
#**
T�m� on VTL kommenttilohko. Lohkoa
voidaan k�ytt�� esimerkiksi dokumentin
tekij�- ja versiotietojen
tallettamiseen:
@author
@version 5
*#
]]></source>
</section>
<section name="Viittaukset">
<p>
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.
</p>
<p>
Kaikkea viittauksissa olevaa ja niihin m��ritelt�v�� tietoa
k�sitell��n tekstityyppisen�. Jos on esimerkiksi m��ritelty
objekti <em>$foo</em> (Integer objekti), Velocity kutsuu objektin
<code>.toString()</code> metodia objektin arvon muuntamiseksi
tekstityyppiseksi.
</p>
<p>
<a name="Muuttujat"><strong>Muuttujat</strong></a>
<br/>
Muuttujan lyhyt merkint�tapa koostuu ensimm�isen� olevasta "$"
merkist�, jonka j�lkeen tulee VTL <em>tunniste</em>. VTL
tunnisteen on alettava aakkosnumeerisella merkill� (a..z tai
A..Z). Muuttujan loput merkit ovat rajoitettu seuraaviin:
</p>
<p>
<ul>
<li>aakkoset (a .. z, A .. Z)</li>
<li>numerot (0 .. 9)</li>
<li>viiva ("-")</li>
<li>alaviiva ("_")</li>
</ul>
</p>
<p>
Seuraavassa muutamia esimerkkej� toimivista muuttujaviittauksista:
</p>
<source><![CDATA[
$foo
$kuraLinko
$kura-linko
$kura_linko
$kuraLinko1
]]></source>
<p>
Kun VTL viittaa muuttujaan, kuten <em>$foo</em>, muuttuja voi
saada arvonsa joko sivupohjassa olevalta <em>set</em> ohjeelta,
tai java -koodista. Jos esimerkiksi javamuuttujalla <em>$foo</em>
on arvo <em>bar</em> silloin kun sivupohjaa haetaan, <em>bar</em>
korvaa kaikki <em>$foo</em> muuttujan esiintymiskohdat web
sivulla. Toisaalta jos sivulle lis�t��n lause
</p>
<source><![CDATA[
#set( $foo = "bar" )
]]></source>
<p>
Sivun tuloste on sama kaikilla <em>$foo</em> muuttujan
esiintymiskohdille jotka tulevat t�m�n lauseen j�lkeen.
</p>
<p>
<a name="Ominaisuudet"><strong>Ominaisuudet</strong></a>
<br/>
Toinen VTL:n viittaustyyppi ovat ominaisuudet joilla on oma
tunnusomainen muotonsa. Lyhyt merkint�tapa muodostuu ensimm�isen�
olevasta <em>$</em> merkist�, jonka j�lkeen tulee VTL tunniste,
jota seuraa piste (".") ja toinen VTL tunniste. Seuraavassa on
esimerkkej� toimivista ominaisuusviittauksista:
</p>
<source><![CDATA[
$asiakas.Osoite
$ostos.Summa
]]></source>
<p>
K�sittelemme ensimm�isen esimerkin <em>$asiakas.Osoite</em>
tarkemmin. Viittauksella voi olla kaksi merkityst�. Se saattaa
tarkoittaa; hae <em>asiakas</em> nimisest� hashtable taulukosta
arvo joka on liitetty avaimelle <em>Osoite</em>. Toisaalta
<em>$asiakas.Osoite</em> voi my�s viitata metodiin (k�sittelemme
metodeihin viittaavat viittaukset seuraavassa kappaleessa);
<em>$asiakas.Osoite</em> saattaa olla lyhennetty muoto
viittauksesta <em>$asiakas.getOsoite()</em>. Velocity tulkitsee
sivua haettaessa kumpaa n�ist� vaihtoehdoista tarkoitetaan, ja
palauttaa vastaavan arvon.
</p>
<p>
<a name="Metodit"><strong>Metodit</strong></a>
<br/>
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 <em>Metodirunko</em>. VTL Metodirunko koostuu VTL
tunnisteesta jota seuraa vasen sulkumerkki "(", jota seuraa
valinnainen parametrilista, jota seuraa oikeanpuoleinen
sulkumerkki ")". Seuraavassa on esimerkkej� toimivista
metodiviittauksista:
</p>
<source><![CDATA[
$asiakas.getOsoite()
$ostos.getSumma()
$sivu.setOtsake( "Minun kotisivuni" )
$henkilo.setOminaisuudet( ["Outo", "Kummallinen", "Innostunut"] )
]]></source>
<p>
Metodirungossa esiintyv� get tarkoittaa "hae" ja set "aseta".
</p>
<p>
Kaksi ensimm�ist� esimerkki� -- <em>$asiakas.getOsoite()</em> ja
<em>$ostos.getSumma()</em> -- n�ytt�v�t samanlaisilta kuin
Ominaisuudet -osiossa aiemmin; <em>$asiakas.Osoite</em> ja
<em>$ostos.Summa</em>. Jos arvasit ett� n�ill� esimerkeill� on
jotakin yhteytt� toisiinsa, olit oikeassa!
</p>
<p>
VTL ominaisuuksia voidaan k�ytt�� lyhyempin� muotoina VTL
metodeista. Ominaisuudella <em>$asiakas.Osoite</em> on t�ysin sama
vaikutus kuin k�ytt�m�ll� metodia
<em>$asikas.getOsoite()</em>. 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.
</p>
<p>
Seuraavien metodien kanssa voidaan k�ytt�� lyhytt� muotoa:
</p>
<source><![CDATA[
$aurinko.getPlaneetat()
$mato.getMulta()
$albumi.getValokuva()
]]></source>
<p>
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:
</p>
<source><![CDATA[
$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
]]></source>
<p>
<a name="Muodollinen viittausten merkint�"><strong>Muodollinen viittausten merkint�</strong></a>
<br/>
Edellisiss� esimerkeiss� k�ytettiin viittauksille lyhytt�
merkint�tapaa. Viittauksille on olemassa my�s muodollinen
merkint�tapa, jota k�ytet��n seuraavissa esimerkeiss�:
</p>
<source><![CDATA[
${kuraLinko}
${asiakas.Osoite}
${osto.getSumma()}
]]></source>
<p>
Voit k�ytt�� lyhytt� muotoa viittauksiin l�hes aina, mutta
joissain tapauksissa muodollista viittausta tarvitaan virheett�m�n
toiminnan turvaamiseksi.
</p>
<p>
Oletetaan ett� olet luomassa lausetta jonka sis�lt� riippuu
muuttujasta. Muuttujaa <em>$pahe</em> 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�:
</p>
<source><![CDATA[
Juha on $pahemaani.
]]></source>
<p>
Velocity olettaa ett� tarkoitat muuttujaa <em>$pahemaani</em>,
vaikka k�ytett�v� muuttuja oli <em>$pahe</em>. Koska Velocity ei
l�yd� arvoa muuttujalle <em>$pahemaani</em>, se palauttaa
<em>$pahemaani</em>. T�m� ongelma voidaan ratkaista k�ytt�m�ll�
muodollista viittausta.
</p>
<source><![CDATA[
Juha on ${pahe}maani.
]]></source>
<p>
Nyt Velocity ymm�rt�� ett� haluttu viittaus on <em>$pahe</em>, ei
<em>$pahemaani</em>. Muodollinen viittausten merkint� on usein
hy�dyllinen silloin kun viittaukset ovat kiinni muussa tekstiss�.
</p>
<p>
<a name="Hiljainen viittausten merkint�"><strong>Hiljainen viittausten merkint�</strong></a>
<br/>
Kun Velocitylt� haetaan viittaus jolle ei ole m��ritelty arvoa,
palauttaa se normaalisti viittauksen tekstin�. Oletetaan
esimerkiksi ett� seuraavat viittaukset ovat osa VTL sivupohjaa:
</p>
<source><![CDATA[
<input type="text" name="email" value="$email"/>
]]></source>
<p>
Kun lomake latautuu ensimm�isen kerran muuttujaviittauksella
<em>$email</em> 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��;
<em>$email</em> koodin sijaan k�yt�t viittausta
<em>$!email</em>. Yll� oleva koodi n�ytt�isi siis seuraavalta:
</p>
<source><![CDATA[
<input type="text" name="email" value="$!email"/>
]]></source>
<p>
Kun lomake latautuu ensimm�isen kerran eik� muuttujalla
<em>$email</em> ole arvoa, tulostetaankin kentt��n tyhj� teksti
"$email" tekstin sijaan.
</p>
<p>
Muodollista ja hiljaista muuttujien merkint�� voidaan k�ytt�� my�s
yhdess�;
</p>
<source><![CDATA[
<input type="text" name="email" value="$!{email}"/>
]]></source>
</section>
<section name="Kirjaimellisesti">
<p>
VTL k�ytt�� erikoismerkkej� kuten <em>$</em> ja <em>#</em> omassa
toiminnassaan, joten n�iden merkkien k�ytt� sivupohjassa vaatii
erityist� huolellisuutta. T�ss� kappaleessa k�sittelemme
<em>$</em> merkin suojaamisen (escape).
</p>
<p>
<a name="Dollari"><strong>Dollari</strong></a>
<br/>
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.
</p>
<p>
<a name="VTL viittausten suojaaminen"><strong>VTL viittausten suojaaminen</strong></a>
<br/>
Ongelmatilanne saattaa synty� silloin, kun Velocity ei osaa
p��tell� tarkoitetaanko dollarinmerkill� merkki� itse��n, vai
viittausta. Erikoismerkkien <em>suojaaminen</em> on paras keino
k�sitell� VTL erikoismerkkej� sivupohjissa. Suojaamiseen k�ytet��n
kenoviivaa ( <em>\</em> ).
</p>
<source><![CDATA[
#set( $email = "foo" )
$email
]]></source>
<p>
Kun Velocity k�sittelee <em>$email</em> viittauksen
sivupohjassasi, se etsii l�ytyyk� sen nimiselle muuttujalle
arvoa. T�ss� tapauksessa tuloste tulee olemaan <em>foo</em>, koska
<em>$email</em> on m��ritelty. Jos <em>$email</em> muuttujaa ei
olisi m��ritelty tulisi tulosteeksi <em>$email</em>.
</p>
<p>
Oletetaan ett� <em>$email</em> on m��ritelty (sill� on esimerkiksi
arvo <em>foo</em>), ja ett� haluat muuttujan arvon sijaan tulostaa
sen nimen <em>$email</em>. T�m� saavuttamiseksi on useita keinoja,
joista helpoin on suojausmerkin k�ytt�minen.
</p>
<source><![CDATA[
## Seuraava rivi m��rittelee muuttujan $email t�ss� sivupohjassa:
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
]]></source>
<p>
tulosteeksi tulee
</p>
<source><![CDATA[
foo
$email
\foo
\\$email
]]></source>
<p>
Huomaa <em>$</em> merkin eteen liitetty <em>\</em>
merkki. Suojausmerkit tulkitaan vasemmalta oikealle, joten
<em>\\\$email</em> tulostuu <em>\\$email</em>. Vertaa n�it�
esimerkkej� tulosteeseen joka saadaan kun <em>$email</em>
muuttujaa ei ole m��ritelty.
</p>
<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>
<p>
tulosteeksi tulee
</p>
<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>
<p>
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 <em>$foo</em> muuttujalle arvon
<em>gibbous</em>.
</p>
<source><![CDATA[
#set( $foo = "gibbous" )
$kuu = $foo
]]></source>
<p>
Tulosteeksi tulee: <em>$kuu = gibbous</em> -- miss� <em>$kuu</em>
tulostetaan muuttujan nimen�, koska sen arvoa ei ole m��ritelty ja
<em>gibbous</em> tulostetaan muuttujan <em>$foo</em> arvona.
</p>
<p>
My�s VTL ohjeiden suojaaminen on mahdollista; t�m� kuvataan
tarkemmin Ohjeet -kappaleessa.
</p>
</section>
<section name="Kirjainkoon muutos">
<p>
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:
</p>
<source><![CDATA[
$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}
]]></source>
<p>
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.
</p>
<p>
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
<em>getFoo()</em> koodilla <code>$bar.foo</code>, Velocity
kokeilee ensin viittausta <code>$getfoo</code>. Jos t�m� ei tuota
tulosta, seuraavaksi yritet��n viittausta
<code>$getFoo</code>. Samalla tavalla, kun sivupohjassa viitataan
muuttujaan <code>$bar.Foo</code>, ensin yritet��n viittausta
<em>$getFoo()</em> ja sitten <em>getfoo()</em>.
</p>
<p>
Huomaa: <em>Viittauksia ilmentym�muuttujiin (instance variables)
ei ratkaista.</em> Vain viittaukset JavaBeanin mukaisiin
haku/asetus (getter/setter) metodeihin ratkaistaan (toisin sanoen
<code>$foo.Name</code> ratkaistaan Foo -luokan
<code>getName()</code> ilmentym�metodiin (instance method), mutta
ei luokan Foo julkiseen (public) <code>Name</code>
ilmentym�muuttujaan).
</p>
</section>
<section name="Ohjeet">
<p>
<em>Ohjeet</em> 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.
</p>
<a name="Set"><strong>#set</strong></a>
<p>
<em>#set</em> 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�:
</p>
<source><![CDATA[
#set( $kadellinen = "apina" )
#set( $asiakas.Kayttaytyminen = $kadellinen )
]]></source>
<p>
M��rityksen vasemman puolen (left hand side, LHS) tulee olla
muuttuja- tai ominaisuusviittaus. Oikea puoli (right hand side,
RHS) voi olla jokin seuraavista tyypeist�:
</p>
<p>
<ul>
<li>Muuttujaviittaus</li>
<li>Tekstivakio</li>
<li>Ominaisuusviittaus</li>
<li>Metodiviittaus</li>
<li>Numeerinen vakio</li>
<li>ArrayList taulukko</li>
</ul>
</p>
<p>
Seuraavassa esimerkit kustakin mainitusta tyypist�:
</p>
<source><![CDATA[
#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
]]></source>
<p>
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).
</p>
<p>
Oikeanpuoleinen arvo (RHS) voi olla my�s yksinkertainen
matemaattinen operaatio:
</p>
<source><![CDATA[
#set( $arvo = $foo + 1 )
#set( $arvo = $bar - 1 )
#set( $arvo = $foo * $bar )
#set( $arvo = $foo / $bar )
]]></source>
<p>
Jos m��rityksen oikeanpuoleinen ominaisuus- tai metodiviittaus on
arvoa <em>null</em>, sit� <b>ei</b> 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:
</p>
<source><![CDATA[
#set( $tulos = $kysely.kriteeri("nimi") )
Ensimm�isen kyselyn tulos on $tulos
#set( $tulos = $kysely.kriteeri("osoite") )
Toisen kyselyn tulos on $tulos
]]></source>
<p>
Jos <em>$kysely.kriteeri("nimi")</em> palauttaa merkkijonon
"pete", ja <em>$kysely.kriteeri("osoite")</em> palauttaa arvon
<em>null</em>, on esimerkin tuloste seuraava:
</p>
<source><![CDATA[
Ensimm�isen kyselyn tulos on pete
Toisen kyselyn tulos on pete
]]></source>
<p>
T�ll� on vaara h�m�t� aloittelijoita jotka muodostavat
<em>#foreach</em> silmukoita joissa yritet��n asettaa
<em>#set</em> ohjeella viittausta ominaisuus- tai
metodiviittauksella, ja sen j�lkeen testataan tuota viittausta
<em>#if</em> ohjeella. Esimerkiksi:
</p>
<source><![CDATA[
#set( $kriteerit = ["nimi", "osoite"] )
#foreach( $kriteeri in $kriteerit )
#set( $tulos = $kysely.kriteerit($kriteeri) )
#if( $tulos )
Kysely onnistui
#end
#end
]]></source>
<p>
Yll� olevassa esimerkiss� ei kannata luottaa <em>$tulos</em>
muuttujan vertaamiseen kyselyn onnistumisen selville
saamiseksi. Kun <em>$tulos</em> on asetettu <em>#set</em>
ohjeella (lisatty kontekstiin), sit� ei voida asettaa
<em>null</em>:iksi (poistaa kontekstista). <em>#if</em> ja
<em>#foreach</em> ohjeet k�sitell��n tarkemmin my�hemmin t�ss�
dokumentissa.
</p>
<p>
Yksi ratkaisu ongelmaan olisi asettaa <em>$tulos</em> etuk�teen
arvoon <em>false</em> (ep�tosi). T�m�n j�lkeen jos kutsu
<em>$kysely.kriteeri()</em> ep�onnistuu, voit tarkastaa arvon.
</p>
<source><![CDATA[
#set( $kriteerit = ["nimi", "osoite"] )
#foreach( $kriteeri in $kriteeri )
#set( $tulos = false )
#set( $tulos = $kysely.kriteerit($kriteeri) )
#if( $tulos )
Kysely onnistui
#end
#end
]]></source>
<p>
Muutamista muista Velocityn ohjeista poiketen, <em>#set</em> ohje
ei k�yt� <em>#end</em> lausetta.
</p>
<a name="Tekstivakiot"><strong>Tekstivakiot</strong></a>
<p>
<em>#set</em> ohjetta k�ytett�ess� lainausmerkkeihin (" ")
suljettu teksti tulkitaan ja tulostetaan kuten seuraavasta
esimerkist� k�y ilmi:
</p>
<source><![CDATA[
#set( $hakemistoJuuri = "www" )
#set( $sivupohjaNimi = "index.vm" )
#set( $sivupohja = "$hakemistoJuuri/$sivupohjaNimi" )
$sivupohja
]]></source>
<p>
Tulosteeksi tulee
</p>
<source><![CDATA[
www/index.vm
]]></source>
<p>
Jos teksti on suljettu hipsuihin (' '), sit� ei tulkita:
</p>
<source><![CDATA[
#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh
]]></source>
Tulosteeksi tulee:
<source><![CDATA[
bar
$foo
]]></source>
<p>
Tulkitsemattoman tekstin tulostaminen hipsumerkkien sis�ll�
olevavasta tekstist� on oletuksena k�yt�ss�
Velocityss�. Oletusarvo voidaan muuttaa vaihtamalla
<code>velocity.properties</code> siten ett�
<code>stringliterals.interpolate=false</code>.
</p>
</section>
<section name="If-Else ehtolauseet">
<strong>If / ElseIf / Else</strong>
<p>
<em>#if</em> ohjeen avulla voidaan teksti sis�llytt�� web
sivulle sill� ehdolla ett� if lauseen arvo on
tosi. Esimerkiksi:
</p>
<source><![CDATA[
#if( $foo )
<strong>Velocity!</strong>
#end
]]></source>
<p>
Muuttuja <em>$foo</em> testataan jotta n�hd��n onko se tosi,
joka tapahtuu kahdessa eri tapauksessa: (i) <em>$foo</em> on
boolean arvo (tosi/ep�tosi) jolla on tosi -arvo, tai (ii) arvo
on eri kuin null (eli muuttuja ei ole tyhj�). <em>#if</em> ja
<em>#end</em> lauseiden v�liin j��v� sis�lt� tulostetaan mik�li
testimuuttuja on tosi. Esimerkkitapauksessamme, jos muuttujalla
<em>$foo</em> on null arvo, tai jos se on boolean ep�tosi, on
testimuuttuja ep�tosi, eik� tulostetta tule lainkaan.
</p>
<p>
<em>#if</em> ja <em>#end</em> lauseiden v�liss� oleva teksti
tulee tulosteeksi mik�li ehto on tosi. T�ss� tapauksessa jos
<em>$foo</em> on tosi, tulosteeksi tulee:
"Velocity!". Toisaalta, mik�li <em>$foo</em> on ep�tosi, on my�s
ehtolause ep�tosi eik� tulostetta tule.
</p>
<p>
<em>#elseif</em> tai <em>#else</em> elementtej� voidaan k�ytt��
<em>#if</em> elementin kanssa. Huomaa, ett� Velocityn
sivumoottori lopettaa ensimm�isen tosiarvon saaneen
testimuuttujan kohdalla. Oletetaan seuraavassa esimerkiss� ett�
muuttujalla <em>$foo</em> on arvo 15 ja muuttujalla
<em>$bar</em> on arvo 6.
</p>
<source><![CDATA[
#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
]]></source>
<p>T�ss� esimerkiss� <em>$foo</em> on suurempi kuin 10, joten
kaksi ensimm�ist� vertailua eiv�t ole tosia. Seuraavaksi muuttujaa
<em>$bar</em> verrataan lukuun 6, joka on tosi, joten tulosteeksi
tulee <strong>Mene etel��n</strong>.
</p>
<p>
Huomaa, ett� nykyisell��n Velocityn numeeriset vertailut on
rajoitettu Integer (kokonais-) lukuihin. Kaikki muut arvot
tulkitaan <em>ep�tosi</em>ksi. Ainoa poikkeus t�h�n on vastaavuus
'==', jolloin Velocity vaatii ett� objektit vertailun kummallakin
puolella ovat <em>samaa</em> luokkaa.
</p>
<p>
<a name="Relaatio- ja loogiset operaattorit"><strong>Relaatio- ja
loogiset operaattorit</strong></a>
</p>
<p>
Velocity k�ytt�� vastaavuusoperaattoria muuttujien v�listen
suhteiden tulkitsemiseen. Seuraavassa on yksinkertainen esimerkki
vastaavuusoperaattorin k�yt�st�.
</p>
<source><![CDATA[
#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
]]></source>
<p>
Velocity tukee my�s loogisia AND ja OR
operaattoreita. Lis�tietoja l�yd�t dokumentista <a
href="vtl-reference-guide.html">VTL Reference Guide</a>. Alla on
esimerkkilause joka k�ytt�� loogista AND:i�.
</p>
<source><![CDATA[
## looginen AND
#if( $foo && $bar )
<strong> T�m� JA tuo</strong>
#end
]]></source>
<p>
If lause on tosi vain mik�li sek� <em>$foo</em> ett�
<em>$bar</em> ovat tosia. Jos <em>$foo</em> on ep�tosi, tulee
lauseesta ep�tosi eik� <em>$bar</em> muuttujaa tarvitse edes
testata. Jos <em>$foo</em> on tosi, testataan sen j�lkeen
muuttujan <em>$bar</em> arvo; jos my�s <em>$bar</em> on tosi,
silloin koko ilmaus on tosi ja <strong>T�m� JA tuo</strong>
tulee tulosteeksi. Jos <em>$bar</em> on ep�tosi, silloin koko
ilmaus on ep�tosi eik� tulostetta tule.
</p>
<p>
Looginen OR operaattori toimii samaan tapaan, paitsi ett� vain
toisen viittauksen pit�� olla tosi jotta koko ilmaus olisi
tosi. Katso seuraavaa esimerkki�.
</p>
<source><![CDATA[
## looginen OR
#if( $foo || $bar )
<strong>T�m� TAI tuo</strong>
#end
]]></source>
<p>
Jos <em>$foo</em> on tosi, ei <em>$bar</em> muuttujaa tarvitse
edes testata. Oli <em>$bar</em> sitten tosi tai ep�tosi, koko
lauseke on tosi, ja <strong>T�m� TAI tuo</strong> on
tulosteena. Toisaalta mik�li <em>$foo</em> on ep�tosi, on
muuttujan <em>$bar</em> arvo testattava. Jos t�ss� tapauksessa
my�s <em>$bar</em> on ep�tosi, koko ilmauksesta tulee ep�tosi
eik� tulostetta tule. Jos <em>$bar</em> on tosi, silloin koko
ilmauksesta tulee tosi, ja tulosteena on <strong>T�m� TAI
tuo</strong>.
</p>
<p>
Loogisella EI (NOT) operaattorilla on vain yksi argumentti :
</p>
<source><![CDATA[
## looginen NOT
#if( !$foo )
<strong>EI tuota</strong>
#end
]]></source>
<p>
Jos <em>$foo</em> on tosi, silloin <em>!$foo</em> on ep�tosi, eik�
tulostetta t�m�n vuoksi tule. Mik�li <em>$foo</em> on ep�tosi,
silloin <em>!$foo</em> on tosi ja <strong>EI tuota</strong> on
tulosteena. �l� sekoita t�t� merkint�� <em>hiljaiseen viittaukseen
$!foo</em> joka tarkoittaa jotakin aivan muuta.
</p>
</section>
<section name="Silmukat">
<strong>Foreach silmukat</strong>
<p>
<em>#foreach</em> mahdollistaa silmukoiden tekemisen. Esimerkiksi:
</p>
<source><![CDATA[
<ul>
#foreach( $tuote in $kaikkiTuotteet )
<li>$tuote</li>
#end
</ul>
]]></source>
<p>
T�m� <em>#foreach</em> silmukka k�y l�pi yksi kerrallaan kaikki
<em>$kaikkiTuotteet</em> listassa olevat tuotteet. Jokaisella
kierroksella seuraavan tuotteen arvo kopioidaan
<em>$kaikkiTuotteet</em> listasta muuttujaan <em>$tuote</em>.
</p>
<p>
<em>$kaikkiTuotteet</em> lista on tyyppi� Vector, Hashtable tai
Array. <em>$tuote</em> muuttujaan kopioitu arvo on java objekti
(Object), joten siihen voidaan my�s viitata objektina. Jos
esimerkiksi <em>$tuote</em> muuttuja olisi tyyppi� Tuote, sen nimi
voitaisiin hakea viittaamalla <em>$tuote.Name</em> metodiin
(ts. <em>$Tuote.getName()</em>.
</p>
<p>
Oletetaan ett� <em>$kaikkiTuotteet</em> on tyyppi� Hashtable. Jos
haluat hakea Hashtablen avainarvot sek� niihin liittyv�t objektit,
voit k�ytt�� seuraavanlaista koodia:
</p>
<source><![CDATA[
<ul>
#foreach( $avain in $kaikkiTuotteet.keySet() )
<li>Avain: $avain -> Arvo: $kaikkiTuotteet.get($avain)</li>
#end
</ul>
]]></source>
<p>
Velocityll� on helppo keino silmukkalaskurin k�ytt�miseen. Voit
k�ytt�� laskuria esimerkiksi seuraavasti:
</p>
<source><![CDATA[
<table>
#foreach( $asiakas in $asiakasLista )
<tr><td>$velocityCount</td><td>$asiakas.Nimi</td></tr>
#end
</table>
]]></source>
<p>
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
<code>velocity.properties</code>
tiedostossa. <code>velocity.properties</code> tiedoston
silmukkalaskuriosio n�ytt�� t�lt�:
</p>
<source><![CDATA[
# Silmukkalaskurin oletusnimi
counter.name = velocityCount
# Silmukkalaskurin aloitusarvo
counter.initial.value = 1
]]></source>
</section>
<section name="Include">
<p>
<em>#include</em> elementin avulla sivusuunnittelija voi hakea
paikallisesta tiedostoj�rjestelm�st� tiedoston, jonka sis�lt�
lis�t��n sivun siihen kohtaan jossa <em>#include</em> 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.
</p>
<source><![CDATA[
#include( "yksi.txt" )
]]></source>
<p>
Tiedosto johon <em>#include</em> ohje viittaa on
lainausmerkeiss�. Jos halutaan sis�llytt�� useampia kuin yksi
tiedosto, tiedostonimet tulee erotella toisistaan pilkuilla.
</p>
<source><![CDATA[
#include( "yksi.gif","kaksi.txt","kolme.htm" )
]]></source>
<p>
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.
</p>
<source><![CDATA[
#include( "terveiset.txt", $sesonkivarasto )
]]></source>
</section>
<section name="Parse">
<p>
<em>#parse</em> 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.
</p>
<source><![CDATA[
#parse( "mina.vm" )
]]></source>
<p>
<em>#include</em> ohjeen tapaan <em>#parse</em> voi ottaa
parametrikseen nimen lis�ksi my�s muuttujan. Kaikkien sivupohjien
joihin <em>#parse</em> ohjeella viitataan tulee sijaita
TEMPLATE_ROOT vakion m��ritt�m�n hakemiston
alla. <em>#include</em> ohjeesta poiketen <em>#parse</em> voi
ottaa vain yhden argumentin.
</p>
<p>
VTL sivupohjissa voi olla <em>#parse</em> ohjeita jotka viittaavat
sivupohjiin joissa niiss�kin on <em>#parse</em>
ohjeita. <code>velocity.properties</code> tiedostossa oleva rivi
<em>parse_directive.maxdepth</em> m��ritt�� sen kuinka monta
per�kk�ist� <em>#parse</em> viittausta voidaan tehd�. Mik�li
<em>parse_directive.maxdepth</em> m��ritys puuttuu, k�ytet��n
oletusarvoa 10. Rekursiivisuus on sallittu. Jos esimerkiksi
sivupohja <code>dofoo.vm</code> sis�lt�� seuraavat rivit:
</p>
<source><![CDATA[
Laske alasp�in.
#set( $laskuri = 8 )
#parse( "parsefoo.vm" )
Kaikki valmista: dofoo.vm!
]]></source>
<p>
Koodi viittaisi sivupohjaan <code>parsefoo.vm</code>, jossa
puolestaan voisi olla seuraavat VTL komennot:
</p>
<source><![CDATA[
$laskuri
#set( $laskuri = $laskuri - 1 )
#if( $laskuri > 0 )
#parse( "parsefoo.vm" )
#else
Kaikki valmista: parsefoo.vm!
#end
]]></source>
<p>
Kun "Laske alasp�in." on n�ytetty, Velocity lataa ja siirt��
kontrollin sivupohjalle <code>parsefoo.vm</code>, joka laskee alas
luvusta 8. Kun laskuri saavuttaa arvon 0, tulostetaan "Kaikki
valmista: parsefoo.vm!". T�m�n j�lkeen Velocity palaa sivupohjaan
<code>dofoo.vm</code> ja tulostaa "Kaikki valmista: dofoo.vm!"
tekstin.
</p>
</section>
<section name="Stop">
<p>
<em>#stop</em> elementin avulla sivupohjan suunnittelija voi
pys�ytt�� sivun tulkitsemisen. T�m� on hy�dyllist� sivupohjan
virheidenetsinn�n aikana.
</p>
<source><![CDATA[
#stop
]]></source>
</section>
<section name="Velocimakrot">
<p>
<em>#macro</em> 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.
</p>
<source><![CDATA[
#macro( d )
<tr><td></td></tr>
#end
]]></source>
<p>
Esimerkiss� m��riteltiin Velocimakro nimelt��n <em>d</em>, ja sit�
voidaan kutsua muiden VTL ohjeiden tapaan:
</p>
<source><![CDATA[
#d()
]]></source>
<p>
Kun t�t� sivupohjaa haetaan, Velocity korvaa ohjeen <em>#d()</em>
rivill� joka sis�lt�� yhden tyhj�n solun.
</p>
<p>
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.
</p>
<source><![CDATA[
#macro( taulurivit $vari $jokulista )
#foreach( $jotain in $jokulista )
<tr><td bgcolor=$vari>$jotain</td></tr>
#end
#end
]]></source>
<p>
T�ss� esimerkiss� m��riteltiin Velocimakro <em>taulurivit</em>
joka ottaa kaksi parametria. Ensimm�inen parametri on
<em>$vari</em> ja toinen <em>$jokulista</em>.
</p>
<p>
Velocimakroon voidaan kirjoittaa mit� tahansa koodia jota voidaan
k�ytt�� muuallakin VTL sivupohjassa. <em>taulurivit</em>
Velocimakro on <em>foreach</em> lause. <em>taulurivit</em>
Velocimakrossa on kaksi <em>#end</em> lausetta; ensimm�inen kuuluu
<em>#foreach</em> lauseelle, j�lkimm�inen p��tt�� Velocimakron
m��rityksen.
</p>
<source><![CDATA[
#set( $suuretjarvet = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $vari = "blue" )
<table>
#taulurivit( $vari $suuretjarvet )
</table>
]]></source>
<p>
Huomaa ett� <em>$suuretjarvet</em> on makron parametrin
<em>$jokulista</em> arvona. Kun Velocimakroa <em>#taulurivit</em>
t�ss� tapauksessa kutsutaan, on tuloksena seuraavaa:
</p>
<source><![CDATA[
<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>
]]></source>
<p>
Velocimakroja voidaan m��ritt�� <em>inline</em>, 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�.
</p>
<p>
Oletetaan ett� Velocityss� on m��riteltyn� Velocimakro
<em>#tablerows($vari $lista)</em>. 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 <code>sieni.vm</code>, <em>#tablerows</em>
Velocimakroa voitaisiin k�ytt�� listaamaan tyypillisen sienen
osat:
</p>
<source><![CDATA[
#set( $osat = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $osat )
</table>
]]></source>
<p>
Kun Velocity luo sivun sivupohjasta <code>sieni.vm</code>, se
etsii Velocimakron <em>#tablerows</em> sivupohjakirjastosta (joka
on m��ritelty <code>velocity.properties</code> tiedostossa) ja
tuottaa seuraavan tulosteen:
</p>
<source><![CDATA[
<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>
]]></source>
<strong>Velocimakron argumentit</strong>
<p>
Velocimakrot voivat ottaa argumenteiksi mit� tahansa seuraavista
VTL elementeist�:
</p>
<ul>
<li>
Viittaus : mit� tahansa '$' merkill� alkavaa
</li>
<li>
Tekstivakio : esimerkiksi "$foo" tai 'hei'
</li>
<li>
Numerovakio : 1, 2 jne
</li>
<li>
Numerov�li : [ 1..2] tai [$foo .. $bar]
</li>
<li>
ObjectArray : [ "a", "b", "c"]
</li>
<li>
boolean arvo true (tosi)
</li>
<li>
boolean arvo false (ep�tosi)
</li>
</ul>
<p>
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:
</p>
<source><![CDATA[
#macro( kutsu $a )
$a $a $a
#end
#kutsu( $foo.bar() )
]]></source>
<p>
tuloksena viittauksen $foo metodia bar() kutsutaan 3 kertaa.
</p>
<p>
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.
</p>
<p>
Jos sinun tarvitsee kiert�� t�m� ominaisuus, voit hakea arvon
metodista uudeksi viittaukseksi, ja antaa sen argumentiksi:
</p>
<source><![CDATA[
#set( $uusiarvo = $foo.bar() )
#kutsu( $uusiarvo )
]]></source>
<strong>Velocimakro ominaisuudet</strong>
<p>
<code>velocity.properties</code> tiedostossa on useita rivej�
joiden avulla Velocimakrojen toimintaa voidaan muuttaa
joustavasti. Huomaa ett� n�m� arvot on dokumentoitu my�s <a
href="http://jakarta.apache.org/velocity/developer-guide.html">Kehitt�j�n
oppaassa</a>.
</p>
<p>
<code>velocimacro.library</code> - Pilkulla eroteltu lista
Velocimakro sivupohjakirjastoja. Oletuksena Velocity etsii yht�
kirjastoa: <em>VM_global_library.vm</em>. Velocimakro kirjastoja
etsit��n m��ritellyst� sivupohjahakemistosta.
</p>
<p>
<code>velocimacro.permissions.allow.inline</code> - 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.
</p>
<p>
<code>velocimacro.permissions.allow.inline.to.replace.global</code>
- T�m�n ominaisuuden avulla voidaan m��ritt�� voivatko
sivupohjassa m��ritellyt Velocimakrot korvata yleisesti
m��ritellyt, <code>velocimacro.library</code> ominaisuuden kautta
ladatut Velocimakrot. Ominaisuus voi saada arvon true tai
false. Oletuksena <code>false</code>, ep�tosi, jolloin
sivupohjassa m��ritellyt Velocimakrot eiv�t voi korvata
sivupohjakirjastoista ladattuja makroja.
</p>
<p>
<code>velocimacro.permissions.allow.inline.local.scope</code> -
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.
</p>
<p>
<code>velocimacro.context.localscope</code> - 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.
</p>
<p>
<code>velocimacro.library.autoreload</code> - T�m� ominaisuus
ohjaa Velocimakrokirjaston automaattista uudelleenlatausta. Kun
ominaisuus on asetettu arvoon <code>true</code> 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� (<i>off</i>,
esim. <code>file.resource.loader.cache = false</code>). T�m�
ominaisuus on tarkoitettu k�ytett�v�ksi vain sovelluksen
kehitysvaiheessa, ei tuotantok�ytt��n.
</p>
<strong>Velocimakro Trivia</strong>
<p>
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.
</p>
<p>
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�
<code>velocimacro.library</code> toimintoa jonka avulla Velocity
lataa Velocimakrosi k�ynnistyksen yhteydess�.
</p>
</section>
<section name="VTL ohjeiden suojaaminen">
<p>
VTL ohjeet voidaan suojata kenoviivalla ("\") samalla tavalla kuin
VTL viittauksetkin.
</p>
<source><![CDATA[
## #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" )
]]></source>
<p>
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:
</p>
<source><![CDATA[
#if( $jazz )
Vyacheslav Ganelin
#end
]]></source>
<p>
Jos <em>$jazz</em> on tosi (true), tuloste on
</p>
<source><![CDATA[
Vyacheslav Ganelin
]]></source>
<p>
Jos <em>$jazz</em> on ep�tosi (false), tulostetta ei
tule. Skriptielementtien suojaaminen muuttaa tulostetta. Katso
seuraavaa esimerkki�:
</p>
<source><![CDATA[
\#if( $jazz )
Vyacheslav Ganelin
\#end
]]></source>
<p>
Riippumatta siit� onko <em>$jazz</em> tosi vai ep�tosi, tuloste on
aina:
</p>
<source><![CDATA[
#if($ jazz )
Vyacheslav Ganelin
#end
]]></source>
<p>
Itse asiassa koska kaikki skriptielementit on suojattu,
<em>$jazz</em> muuttujan totuusarvoa ei edes tutkita. Oletetaan ett�
kenoviiva edelt�� skriptielementtej� jotka on suojattu:
</p>
<source><![CDATA[
\\#if( $jazz )
Vyacheslav Ganelin
\\#end
]]></source>
<p>
Mik�li <em>$jazz</em> on t�ss� tapauksessa tosi, tuloste on:
</p>
<source><![CDATA[
\ Vyacheslav Ganelin
\
]]></source>
<p>
T�m�n ymm�rt�miseksi huomaa, ett� <code>#if( arg )</code> rivill�
olevaa rivinvaihtoa (return) ei kopioida tulosteeseen. T�m�n vuoksi
<code>#if()</code> 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 <code>#end</code> ohjetta,
joten merkki kuuluu edelleen <code>#if()</code> lauseen runkoon.
</p>
<p>
Jos <em>$jazz</em> on ep�tosi, ei tulostetta tule. Huomaa ett�
ongelmia tulee mik�li skriptielementtej� ei ole suojattu oikein.
</p>
<source><![CDATA[
\\\#if( $jazz )
Vyacheslave Ganelin
\\#end
]]></source>
<p>
Esimerkiss� <em>#if</em> on suojattu, mutta <em>#end</em> elementti
on edelleen k�yt�ss�. Liian monta lopetuselementti� sivupohjassa
aiheuttaa virheen sivua luotaessa.
</p>
</section>
<section name="VTL: Muotoilu">
<p>
Vaikka t�ss� ohjeessa oleva VTL on usein muotoiltu rivivaihdoin ja
v�lily�nnein, alla oleva VTL
</p>
<source><![CDATA[
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
$shogun
#end
]]></source>
<p>
on yht� toimiva kuin seuraava kodinp�tk� jonka Geir Magnusson
Jr. l�hetti Velocityn k�ytt�jien postituslistalle:
</p>
<source><![CDATA[
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
]]></source>
<p>
Velocity sy� ylim��r�iset v�lily�nnit. Edellinen koodinp�tk�
voitaisiin kirjoittaa seuraavasti:
</p>
<source><![CDATA[
Send me
#set( $foo = ["$10 and ","a cake"] )
#foreach( $a in $foo )
$a
#end
please.
]]></source>
<p>
tai
</p>
<source><![CDATA[
Send me
#set($foo = ["$10 and ","a cake"])
#foreach ($a in $foo )$a
#end please.
]]></source>
<p>
Kussakin tapauksessa tulos on sama.
</p>
</section>
<section name="Muita ominaisuuksia ja sekalaista">
<subsection name="Matematiikka">
<p>
Velocitylla on muutamia sis��nrakennettuja matemaattisia
funktioita joita voidaan k�ytt�� sivupohjissa <em>#set</em> ohjeen
kanssa. Seuraavat yht�l�t ovat esimerkkej� yhteen-, v�hennys-,
kerto- sek� jakolaskuista.
</p>
<source><![CDATA[
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
]]></source>
<p>
Jako-operaation tapauksessa tulos on kokonaisluku. Jakoj��nn�s
saadaan k�ytt��n j��nn�soperandilla (<em>%</em>).
</p>
<source><![CDATA[
#set( $foo = $bar % 5 )
]]></source>
<p>
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).
</p>
<p>
Velocityll� on sis��nrakennettu keino nollalla jakamisen
k�sittelemiseen. Seuraavassa esimerkiss�:
</p>
<source><![CDATA[
#set( $foo = 5 )
#set( $bar = $foo - 5 )
#set( $uhoh = $foo / $bar )
$uhoh
]]></source>
<p>
Viittaukseen <em>$uhoh</em> asetetaan tulos operaatiosta viisi
jaettuna nollalla. Kun Velocity n�ytt�� t�m�n sivupohjan, tuloste
on:
</p>
<source><![CDATA[
$uhoh
]]></source>
<p>
Suunnittelijoiden on otettava huomioon my�s, ett� <em>#set</em>
tuottaa merkkijonoja, jotka on muunnettava kokonaisluvuiksi jotta
niit� voidaan k�ytt�� vaihteluv�li� m��ritett�ess� (range
operator). Seuraavassa esimerkki t�llaisesta muunnoksesta:
</p>
<source><![CDATA[
#set($a = "7")
#set($b = $int.valueOf($a) + 10)
$b
]]></source>
<p>
Tuloksena on <em>17</em>.
</p>
</subsection>
<subsection name="Vaihteluv�li (Range Operator)">
<p>
Vaihteluv�li� voidaan k�ytt�� <em>#set</em> ja <em>#foreach</em>
lauseiden yhteydess�. Vaihteluv�li tuottaa kokonaislukuja
sis�lt�vi� oliotaulukoita seuraavalla tavalla:
</p>
<source><![CDATA[
[n..m]
]]></source>
<p>
Sek� <em>n</em> ett� <em>m</em> pit�� olla tai niiden tulee
tuottaa kokonaislukuja. Mik�li <em>m</em> on pienempi kuin
<em>n</em> lasketaan vaihteluv�lin luvut alasp�in. Seuraavassa
esimerkkej� vaihteluv�lin k�yt�st�:
</p>
<source><![CDATA[
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]
]]></source>
<p>
Tuottaa seuraavan tulosteen:
</p>
<source><![CDATA[
Ensimm�inen esimerkki:
1 2 3 4 5
Toinen esimerkki:
2 1 0 -1 -2
Kolmas esimerkki:
0 1
Nelj�s esimerkki:
[1..3]
]]></source>
<p>
Huomaa ett� vaihteluv�lioperaattori tuottaa taulukon vain kun sit�
k�ytet��n <em>#set</em> tai <em>#foreach</em> ohjeiden kanssa,
kuten nelj�nnest� esimerkist� k�y selville.
</p>
<p>
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.
</p>
</subsection>
<subsection name="Edistyneet kysymykset: Suojaaminen ja !">
<p>
Kun viittaus hiljennet��n <em>!</em> merkill� ja <em>!</em> merkki�
edelt�� suojausmerkki <em>\</em> k�sitell��n viittaus erityisell�
tavalla. Huomaa erot normaalin suojauksen ja tilanteen jossa
<em>\</em> edelt�� <em>!</em> merkki�, v�lill�.
</p>
<source><![CDATA[
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
]]></source>
<p>
Tulosteena on:
</p>
<source><![CDATA[
$!foo
$!{foo}
$\!foo
$\\!foo
]]></source>
<p>
Vertaa t�t� normaaliin suojaukseen, jossa <em>\</em> on <em>$</em>
merkin edell�:
</p>
<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\\$!{foo}
]]></source>
<p>
Tulosteena on:
</p>
<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\bar
]]></source>
</subsection>
<subsection name="Yleist� Velocimakroista">
<p>
T�m� osio on Velocimakroaiheinen mini-FAQ. Osio muuttuu ajan my�t�,
joten uutta tietoa hakevien kannattanee palata sivulle aika ajoin.
</p>
<p>
Huom! : T�ss� osiossa 'Velocimakro':ihin viitataan usein lyhenteell�
'VM'.
</p>
<strong>Voinko k�ytt�� ohjetta tai toista VM:a argumenttina
VM:oon?</strong>
<p>
Esimerkki : <code>#center( #bold("hello") )</code>
</p>
<p>
Et. Ohje ei ole sallittu argumentti ohjeelle, ja VM on
k�yt�nn�llisesti katsoen ohje.
</p>
<p>
<i>Kuitenkin...</i>, voit kiert�� rajoituksen. Yksinkertainen ratkaisu
on k�ytt�� hyv�ksi sit� ett� lainausmerkeiss� (") oleva teksti
tulkitaan. T�m� ansiosta voit tehd� seuraavasti:
</p>
<source><![CDATA[
#set($stuff = "#bold('hello')" )
#center( $stuff )
]]></source>
<p>
Voit my�s s��st�� rivin...
</p>
<source><![CDATA[
#center( "#bold( 'hello' )" )
]]></source>
<p>
Huomaa ett� j�lkimm�isess� esimerkiss� parametri k�sitell��n VM:n
<i>sis�ll�</i>, 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:
</p>
<source><![CDATA[
#macro( inner $foo )
inner : $foo
#end
#macro( outer $foo )
#set($bar = "outerlala")
outer : $foo
#end
#set($bar = 'calltimelala')
#outer( "#inner($bar)" )
]]></source>
<p>
Tulosteeksi tulee
</p>
<source><![CDATA[
Outer : inner : outerlala
]]></source>
<p>
koska parametrin "#inner($bar)" tulkitseminen tapahtuu lauseen
#outer() sis�ll�, k�ytet��n muuttujan $bar arvoa joka asetettiin
#outer VM:ssa.
</p>
<p>
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
</p>
<source><![CDATA[
#macro( foo $vari )
<tr bgcolor=$vari><td>Hei</td></tr>
<tr bgcolor=$vari><td>Siell�</td></tr>
#end
#foo( $bar.rivinVari() )
]]></source>
<p>
jossa rivinVari() metodia kutsutaan toistuvasti, ei vain kerran. Sen
v�ltt�miseksi kutsu metodia VM:n ulkopuolelta ja siirr� arvo VM:oon.
</p>
<source><![CDATA[
#set($vari = $bar.rivinVari())
#foo( $vari )
]]></source>
<strong>Voinko rekister�id� Velocimakroja #parse() :n kautta?
</strong>
<p>
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.
</p>
<p>
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�
<code>velocimacro.library</code> toimintoa jonka avulla Velocity
lataa Velocimakrosi k�ynnistyksen yhteydess�.
</p>
<strong>Mit� tarkoittaa Velocimakrojen automaattinen
uudelleenlataus?</strong>
<p>
On olemassa asetus joka on tarkoitettu k�ytett�v�ksi j�rjestelm�n
<i>kehityksen</i> aikana, ei k�yt�ss� olevassa j�rjestelm�ss� :
</p>
<p>
<code>velocimacro.library.autoreload</code>
</p>
<p>
joka on oletuksena pois k�yt�st� (false). Kun ominaisuus on
asetettu k�ytt��n (true) <em>yhdess�</em> asetuksen
</p>
<p>
<code><type>.resource.loader.cache = false</code>
</p>
<p>
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.
</p>
<p>
Yksinkertainen konfiguraatio saattaisi n�ytt�� seuraavalta:
</p>
<source><![CDATA[
file.resource.loader.path = templates
file.resource.loader.cache = false
velocimacro.library.autoreload = true
]]></source>
<p>
�l� k�yt� n�it� asetuksia tuotantok�yt�ss�.
</p>
</subsection>
<subsection name="Merkkijonojen yhdist�minen">
<p>
Yleinen kehitt�jien kysym� kysymys on <i>Kuinka yhdist�n
merkkijonoja? Onko olemassa Javan '+' operaattoria vastaavaa
toimintoa?</i>.
</p>
<p>
Viittausten liitt�miseksi yhteen VTL:ssa, sinun tarvitsee vain
'laittaa ne yhteen'. Konteksti jossa yhdist�t viittaukset
vaikuttaa tuloksiin, joten esimerkit ovat paikallaan.
</p>
<p>
Normaalissa tapauksessa (jolloin sekoitat muuttujat sivupohjan
muuhun sis�lt��n) :
</p>
<source><![CDATA[
#set( $koko = "Big" )
#set( $nimi = "Ben" )
Kello on $iso$nimi.
]]></source>
<p>
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:
</p>
<source><![CDATA[
#set( $koko = "Big" )
#set( $nimi = "Ben" )
#set($kello = "$koko$nimi" )
Kello on $kello.
]]></source>
<p>
Josta tulee sama tuloste. Viimeisen� esimerkkin�, kun haluat
sekoittaa 'staattisia' merkkijonoja viittauksiin, saatat joutua
k�ytt�m��n 'muodollista viittausten merkint��' :
</p>
<source><![CDATA[
#set( $koko = "Big" )
#set( $nimi = "Ben" )
#set($kello = "${koko}Tall$nimi" )
Kello on $kello.
]]></source>
<p>
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�.
</p>
</subsection>
</section>
<section name="Palaute">
<p>
Mik�li l�yd�t t�st� ohjeesta virheit� tai haluat antaa ohjetta
koskevaa palautetta, ole hyv� ja l�het� s�hk�postia <a
href="mailto:velocity-user@jakarta.apache.org">Velocity
k�ytt�j�listalle</a>. Kiitos!
</p>
</section>
</body>
</document>
\ No newline at end of file
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>