File: user-guide_fi.xml

package info (click to toggle)
velocity 1.4-5
links: PTS
area: main
in suites: etch, etch-m68k, lenny
size: 17,900 kB
ctags: 9,916
sloc: java: 24,335; xml: 17,188; sh: 99; lisp: 53; makefile: 16
file content (2328 lines) | stat: -rw-r--r-- 69,056 bytes
<?xml version="1.0" encoding="ISO-8859-1"?>

<document>

 <properties>
  <title>Velocity kyttjn 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="Sisllys">

<ol>
<li><a href="#Tietoja tst oppaasta">Tietoja tst oppaasta</a></li>
<li><a href="#Mik on Velocity?">Mik on Velocity?</a></li>
<li><a href="#Miten voin kytt Velocity?">Miten voin kytt 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="#Vaihteluvli (Range Operator)">Vaihteluvli (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 yhdistminen">Merkkijonojen yhdistminen</a></li>
    </ol>
</li>
<li><a href="#Palaute">Palaute</a></li>
</ol>

</section>

<section name="Tietoja tst oppaasta">

 <p>
    Velocity kyttjn opas on tarkoitettu sivusuunnittelijoille ja
    sisllntuottajille avuksi tutustuttaessa Velocityyn ja sen
    yksinkertaiseen mutta tehokkaaseen skriptikieleen, Velocity
    Template Language:en (VTL). Useat tmn oppaan esimerkeist
    ksittelevt Velocityn kyttmist dynaamisen sislln
    lismiseksi web sivuille, mutta kaikki VTL esimerkit toimivat
    HTML sivujen lisksi yht hyvin mys 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
    mriteltyihin metodeihin. Sivusuunnittelijat voivat tyskennell
    java ohjelmoijien kanssa samanaikaisesti kytten
    Malli-Nkym-Ohjain (Model-View-Controller, MVC)
    suunnittelumallia. MVC mallissa sivusuunnittelijat voivat
    keskitty tysin luomaan hyvin suunniteltua sivustoa, ja
    ohjelmoijat voivat keskitty koodaamaan ykksluokan
    koodia. Velocity erottaa java -koodin web sivuista, tehden
    sivustosta pitkll aikavlill helpommin yllpidettvn 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 kytt web sivujen, SQL:n, PostScriptin ja
    muunlaisten tulosteiden tuottamiseen sivupohjista (template). Sit
    voidaan kytt joko itsenisen tykaluna lhdekoodin ja
    raporttien luomiseen, tai muihin jrjestelmiin 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 kytt Velocity?">
<subsection name="Kurakauppa esimerkki">
   <p>
    Oletetaan ett olet kuraa myyvn onlinekaupan
    sivusuunnittelija. Kutsumme kauppaa "Kurakauppa
    Online":ksi. Kauppa ky hyvin. Asiakkaat tilaavat vaihtelevia
    mri eri kuratyyppej. He psevt tutkimaan tekemin tilauksia
    sek tekemn uusia ostoja kirjautumalla sivullesi kytten
    kyttjtunnustaan ja salasanaansa. Tll hetkell suosittu
    Terracotta -kura on alennusmyynniss. Pieni osa asiakkaistasi
    ostaa snnllisesti Kirkkaanpunaista Kuraa, joka mys on
    alennusmyynniss, mutta pienemmn suosionsa vuoksi yleens
    mainittu sivulla hieman syrjss. Tiedot kustakin asiakkaasta
    talletetaan tietokantaan, joten ern pivn her kysymys;
    Miksip emme kyttisi Velocity kohdentamaan erikoistarjouksia
    kurasta asiakkaille jotka ovat kiinnostuneita juuri tuosta
    kuratyypist?
   </p>

   <p>
    Velocityn avulla verkkosivut on helppo personoida kvijidesi
    mukaan. Kurakauppa Onlinen sivusuunnittelijana haluat tehd sivun
    jonka asiakas nkee kirjauduttuaan jrjestelmn.
   </p>

   <p>
    Tapaat yrityksesi ohjelmoijat ja sovitte, ett muuttuja
    <em>$asiakas</em> pit sislln 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. Tll kertaa keskitymme vain
    nihin kolmeen viittaukseen. Muista, ett sinun ei tarvitse
    huolehtia siit kuinka ohjelmoijat hakevat tarvittavat tiedot
    tietokannasta, sinun tarvitsee tiet vain ett se toimii. Nin
    pset tekemn omaa tytsi ja ohjelmoijat psevt tekemn
    omaansa.
   </p>

   <p>
    Voisit list 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
    jljempn; trke tss on tmn lyhyen skriptin tekem vaikutus
    sivullesi. Kun Kirkkaanpunainen Kura on alennusmyynniss ja sit
    joskus aiemmin ostanut asiakas kirjautuu sisn, asiakas nkee
    ilmoituksen alennuksesta parhaalla mahdollisella paikalla. Jos
    toinen, Terracottakuraa ostanut asiakas kirjautuu jrjestelmn,
    ilmoitus Terracottakuran alennusmyynnist nkyy hnelle
    ensimmisen. Velocity on joustava ja sen kytss vain
    mielikuvituksesi on rajana.
   </p>

   <p>
    VTL hakemistossa on kuvattu Velocityn kaikki elementit jotka
    yhdess antavat kyttsi tehokkaan ja joustavan tykalun jota
    tarvitset luodaksesi web sivuistasi dynaamisen. Pset
    hydyntmn Velocityn voimaa jatkuvasti paremmin sit mukaa kun
    opit kyttmn nit 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
    sislt web sivulle. Dynaamisen sislln kyttminen pitisi
    onnistua nopeasti jopa sellaiselta sivusuunnittelijalta jolla on
    ohjelmointikokemusta vain vhn, tai ei ollenkaan.
 </p>

<p>
     VTL kytt <em>viittauksia</em> dynaamisen aineiston lismiseen
     verkkosivulle. Muuttujat ovat yhdentyyppisi
     viittauksia. Muuttujat voivat viitata johonkin java -koodissa
     mriteltyyn, tai niiden arvo voidaan mritt web -sivulla
     annetun VTL <em>lauseen</em> avulla. Seuraavassa on esimerkki VTL
     lauseesta joka voidaan list HTML -dokumenttiin:
 </p>

<source><![CDATA[
#set( $a = "Velocity" )
]]></source>

 <p>
    Kuten kaikki VTL lauseet (statement), tmkin lause alkaa <em>#</em>
    merkill ja sislt ohjeen (directive): <em>set</em>. Kun verkkosivun
    kyttj hakee sivun Velocity etsii sivupohjastasi kaikki
    <em>#</em> -merkit. Sitten se tulkitsee mitk niist merkitsevt
    VTL lausetta, ja mitk <em>#</em> merkeist ovat osa sivujesi
    normaalia HTML -koodia, eivtk kuulu VTL -koodiin.
 </p>

 <p>
    <em>#</em> merkki seuraa ohje, <em>set</em>. <em>set</em> ohjeen
    jlkeen tulee suluissa ilmaus (expression), -- yhtl joka mritt
    <em>arvon</em> <em>muuttujalle</em>. Muuttuja on ilmaistu
    vasemmalla ja arvo oikealla puolella. Nm on erotettu <em>=</em>
    merkill.
 </p>

 <p>
    Yll olevassa esimerkiss muuttuja on <em>$a</em> ja arvo on
    <em>Velocity</em>. Kaikkien viittausten tapaan tmkin muuttuja
    alkaa <em>$</em> merkill. Arvot ovat aina lainausmerkkien
    sisll; Velocityss muuttujien datatyypeist ei tule
    sekaannuksia, koska vain merkkijonoja (string) voi antaa
    muuttujien arvoksi.
 </p>

 <p>
    Seuraava nyrkkisnt voi auttaa ymmrtmn Velocityn toimintaa:
    <strong>Viittaukset alkavat <em>$</em> merkill ja niit kytetn
    jonkin hakemiseen. Ohjeet alkavat <em>#</em> merkill ja niit
    kytetn jonkin suorittamiseen.</strong>
 </p>

 <p>
     Yll olevassa esimerkiss <em>#set</em> -ohjetta kytetn arvon
     mrittmiseksi muuttujaan. Muuttujaa <em>$a</em> voidaan tmn
     jlkeen kytt sivupohjassa tulostamaan "Velocity".
 </p>

</section>

<section name="Hei Velocity Maailma!">

 <p>
    Kun muuttujalle on mritelty arvo, voidaan siihen viitata miss
    tahansa paikassa HTML dokumenttia. Seuraavassa esimerkiss
    muuttujalle <em>$foo</em> mritelln arvo. Myhemmin 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 tm ei ole
    pakollista. <em>set</em> ohjeeseen palaamme tarkemmin myhemmin.
 </p>

</section>

<section name="Kommentit">

 <p>
    Kommenttien avulla sivulle voidaan list aputekstej jotka eivt
    tule nkymn sivun tulosteessa. Voit kytt kommentteja
    muistuttaaksesi itsesi jostakin tai selittksesi muille mit VTL
    komennot tekevt, tai mihin tahansa muuhun tarkoitukseen. Alla on
    esimerkki kommentin kytst.
 </p>

<source><![CDATA[
## Tm 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[
Tm teksti on kommenttimerkkien ulkopuolella.
Kyttjt nkevt tmn tekstin.

#*
 Monirivinen kommentti alkaa tst. Kyttjt eivt ne tt teksti
 koska Velocityn sivumoottori ei nyt kommenttimerkkien sisll
 olevaa teksti tulosteessaan.
*#

Tm teksti on jlleen kommenttimerkkien ulkopuolella; se on
nkyviss.

]]></source>

 <p>
    Tss on muutamia esimerkkej yksi- ja monirivisten kommenttien
    toiminnan selvittmiseksi:
 </p>

<source><![CDATA[
Tm teksti on nkyviss. ## Tm teksti ei ole.
Tm teksti on nkyviss.
Tm teksti on nkyviss. #* Tm teksti on osa monirivist kommenttia
eik siksi ole nkyviss. Tm teksti ei edelleenkn ole nkyviss
koska se on kommenttimerkkien sisll. *# Tm teksti on
kommenttimerkkien ulkopuolella, joten se on nkyviss.
## Tm teksti ei ole nkyviss.
]]></source>

 <p>
    On olemassa viel kolmaskin kommenttityyppi; VTL kommenttilohko,
    jota voidaan kytt mm. dokumentin tekij- ja versiotietojen
    tallettamiseen
 </p>

<source><![CDATA[
#**
Tm on VTL kommenttilohko. Lohkoa
voidaan kytt 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: kyttvn sivusuunnittelijana sinun, ja
    javapuolta koodaavien ohjelmoijien on sovittava viittausten
    nimist, jotta voit kytt niit sivupohjissasi.
 </p>

 <p>
    Kaikkea viittauksissa olevaa ja niihin mriteltv tietoa
    ksitelln tekstityyppisen. Jos on esimerkiksi mritelty
    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 merkinttapa koostuu ensimmisen olevasta "$"
    merkist, jonka jlkeen 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 listn lause
 </p>

<source><![CDATA[
#set( $foo = "bar" )
]]></source>

 <p>
    Sivun tuloste on sama kaikilla <em>$foo</em> muuttujan
    esiintymiskohdille jotka tulevat tmn lauseen jlkeen.
 </p>

 <p>
 <a name="Ominaisuudet"><strong>Ominaisuudet</strong></a>
 <br/>

    Toinen VTL:n viittaustyyppi ovat ominaisuudet joilla on oma
    tunnusomainen muotonsa. Lyhyt merkinttapa muodostuu ensimmisen
    olevasta <em>$</em> merkist, jonka jlkeen tulee VTL tunniste,
    jota seuraa piste (".") ja toinen VTL tunniste. Seuraavassa on
    esimerkkej toimivista ominaisuusviittauksista:
 </p>

<source><![CDATA[
$asiakas.Osoite
$ostos.Summa
]]></source>

 <p>
    Ksittelemme ensimmisen 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 mys viitata metodiin (ksittelemme
    metodeihin viittaavat viittaukset seuraavassa kappaleessa);
    <em>$asiakas.Osoite</em> saattaa olla lyhennetty muoto
    viittauksesta <em>$asiakas.getOsoite()</em>. Velocity tulkitsee
    sivua haettaessa kumpaa nist vaihtoehdoista tarkoitetaan, ja
    palauttaa vastaavan arvon.
 </p>

 <p>
 <a name="Metodit"><strong>Metodit</strong></a>
 <br/>

    Metodit ovat mritelty java -koodissa ja niiden avulla voidaan
    suorittaa jokin toimenpide; esimerkiksi laskutoimitus tai jonkin
    ptksen tekeminen. Metodit ovat viittauksia jotka muodostuvat
    aloittavasta "$" merkist, jota seuraa VTL tunniste, jonka jlkeen
    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 ensimmist esimerkki -- <em>$asiakas.getOsoite()</em> ja
    <em>$ostos.getSumma()</em> -- nyttvt samanlaisilta kuin
    Ominaisuudet -osiossa aiemmin; <em>$asiakas.Osoite</em> ja
    <em>$ostos.Summa</em>. Jos arvasit ett nill esimerkeill on
    jotakin yhteytt toisiinsa, olit oikeassa!
 </p>

 <p>
    VTL ominaisuuksia voidaan kytt lyhyempin muotoina VTL
    metodeista. Ominaisuudella <em>$asiakas.Osoite</em> on tysin sama
    vaikutus kuin kyttmll metodia
    <em>$asikas.getOsoite()</em>. Yleisesti ottaen ominaisuuksien
    kytt on suositeltavaa silloin kuin se vain on
    mahdollista. Suurin ero ominaisuuksien ja metodien vlill on se,
    ett metodeille voi antaa parametreja.
 </p>

 <p>
    Seuraavien metodien kanssa voidaan kytt lyhytt muotoa:
 </p>

<source><![CDATA[
$aurinko.getPlaneetat()
$mato.getMulta()
$albumi.getValokuva()
]]></source>

 <p>
    Niden metodien voisimme olettaa palauttavan auringolle kuuluvien
    planeettojen nimet, syttvn 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 kytettiin viittauksille lyhytt
    merkinttapaa. Viittauksille on olemassa mys muodollinen
    merkinttapa, jota kytetn seuraavissa esimerkeiss:
 </p>

<source><![CDATA[
${kuraLinko}
${asiakas.Osoite}
${osto.getSumma()}
]]></source>

 <p>
    Voit kytt lyhytt muotoa viittauksiin lhes aina, mutta
    joissain tapauksissa muodollista viittausta tarvitaan virheettmn
    toiminnan turvaamiseksi.
 </p>

 <p>
    Oletetaan ett olet luomassa lausetta jonka sislt riippuu
    muuttujasta. Muuttujaa <em>$pahe</em> kytetn pohjana luotaessa
    muuttujasta riippuvaista sanaa. Tarkoituksena on sallia kyttjn
    valita pohjasana ja tuottaa toinen seuraavista tuloksista: "Juha
    on pyromaani." tai "Juha on kleptomaani.". Tss tapauksessa
    lyhyen viittausmuodon kyttminen ei toimisi. Tutki seuraavaa
    esimerkki:
 </p>

<source><![CDATA[
Juha on $pahemaani.
]]></source>

 <p>
    Velocity olettaa ett tarkoitat muuttujaa <em>$pahemaani</em>,
    vaikka kytettv muuttuja oli <em>$pahe</em>. Koska Velocity ei
    lyd arvoa muuttujalle <em>$pahemaani</em>, se palauttaa
    <em>$pahemaani</em>. Tm ongelma voidaan ratkaista kyttmll
    muodollista viittausta.
 </p>

<source><![CDATA[
Juha on ${pahe}maani.
]]></source>

 <p>
    Nyt Velocity ymmrt ett haluttu viittaus on <em>$pahe</em>, ei
    <em>$pahemaani</em>. Muodollinen viittausten merkint on usein
    hydyllinen 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 mritelty 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 ensimmisen kerran muuttujaviittauksella
    <em>$email</em> ei ole arvoa. Oletuksena Velocity tytt
    lomakkeen tekstill "$email". Haluaisit kuitenkin kenttn
    mieluummin tyhjn arvon. Kyttmll hiljaista viittausten
    merkint voidaan Velocityn normaali toiminta est;
    <em>$email</em> koodin sijaan kytt viittausta
    <em>$!email</em>. Yll oleva koodi nyttisi siis seuraavalta:
 </p>

<source><![CDATA[
<input type="text" name="email" value="$!email"/>
]]></source>

 <p>
    Kun lomake latautuu ensimmisen kerran eik muuttujalla
    <em>$email</em> ole arvoa, tulostetaankin kenttn tyhj teksti
    "$email" tekstin sijaan.
 </p>

 <p>
    Muodollista ja hiljaista muuttujien merkint voidaan kytt mys
    yhdess;
 </p>

<source><![CDATA[
<input type="text" name="email" value="$!{email}"/>
]]></source>

</section>

<section name="Kirjaimellisesti">

  <p>
    VTL kytt erikoismerkkej kuten <em>$</em> ja <em>#</em> omassa
    toiminnassaan, joten niden merkkien kytt sivupohjassa vaatii
    erityist huolellisuutta. Tss kappaleessa ksittelemme
    <em>$</em> merkin suojaamisen (escape).
  </p>

  <p>
    <a name="Dollari"><strong>Dollari</strong></a>
    <br/>

    Seuraavassa lauseessa dollarimerkin kytss ei ole ongelmaa:
    "Ostin markkinoilta skin 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
    ptell tarkoitetaanko dollarinmerkill merkki itsen, vai
    viittausta. Erikoismerkkien <em>suojaaminen</em> on paras keino
    ksitell VTL erikoismerkkej sivupohjissa. Suojaamiseen kytetn
    kenoviivaa ( <em>\</em> ).
  </p>

<source><![CDATA[
#set( $email = "foo" )
$email
]]></source>

  <p>
    Kun Velocity ksittelee <em>$email</em> viittauksen
    sivupohjassasi, se etsii lytyyk sen nimiselle muuttujalle
    arvoa. Tss tapauksessa tuloste tulee olemaan <em>foo</em>, koska
    <em>$email</em> on mritelty. Jos <em>$email</em> muuttujaa ei
    olisi mritelty tulisi tulosteeksi <em>$email</em>.
  </p>

  <p>
    Oletetaan ett <em>$email</em> on mritelty (sill on esimerkiksi
    arvo <em>foo</em>), ja ett haluat muuttujan arvon sijaan tulostaa
    sen nimen <em>$email</em>. Tm saavuttamiseksi on useita keinoja,
    joista helpoin on suojausmerkin kyttminen.
  </p>

<source><![CDATA[
## Seuraava rivi mrittelee muuttujan $email tss 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 nit
     esimerkkej tulosteeseen joka saadaan kun <em>$email</em>
     muuttujaa ei ole mritelty.
  </p>

<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>

  <p>
     tulosteeksi tulee
  </p>

<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>

  <p>
     Huomaa kuinka Velocity ksittelee eri tavalla viittaukset joiden
     arvo on mritelty niist joita ei ole mritelty. 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 mritelty ja
    <em>gibbous</em> tulostetaan muuttujan <em>$foo</em> arvona.
  </p>

  <p>
     Mys VTL ohjeiden suojaaminen on mahdollista; tm kuvataan
     tarkemmin Ohjeet -kappaleessa.
  </p>

</section>

<section name="Kirjainkoon muutos">

    <p>
    Kun nyt olet tutustunut viittauksiin, voit alkaa kyttmn niit
    tehokkaasti omissa sivupohjissasi. Viittaukset Velocityss
    kyttvt hyvkseen joitakin java kielen perusperiaatteita, joiden
    kytt helpottaa sivusuunnittelijoiden tyt. 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>
    Nm esimerkit havainnollistavat viittauksen vaihtoehtoisia
    merkitsemistapoja. Velocity kytt hyvkseen javan introspection
    ja bean -ominaisuuksia objektien sek niiden metodien
    viittausnimi ratkaistaessa. Viittauksia voidaan list lhes
    mihin kohtaan tahansa sivupojassa.
    </p>

    <p>
    Velocity on tehty Sun Microsystemsin mrittelemn Bean
    mrityksen mukaiseksi, ja on tst syyst pieni-iso-eroava
    (ts. pienet ja isot kirjaimet ksitelln eri
    merkkein). Velocityn kehittjt 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 tm ei tuota
    tulosta, seuraavaksi yritetn viittausta
    <code>$getFoo</code>. Samalla tavalla, kun sivupohjassa viitataan
    muuttujaan <code>$bar.Foo</code>, ensin yritetn viittausta
    <em>$getFoo()</em> ja sitten <em>getfoo()</em>.
    </p> 

    <p>
    Huomaa: <em>Viittauksia ilmentymmuuttujiin (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> ilmentymmetodiin (instance method), mutta
    ei luokan Foo julkiseen (public) <code>Name</code>
    ilmentymmuuttujaan).
    </p>

</section>


<section name="Ohjeet">

 <p>
    <em>Ohjeet</em> ovat helppokyttisi skriptielementtej joita
    voidaan kytt web sivun tulosteen manipuloimiseen. Viittausten
    avulla sivupohjien suunnittelijat voivat tuottaa web sivuille
    dynaamista sislt, kun taas ohjeet antavat mahdollisuuden
    mritell sivuston ulkoasun ja sislln.
 </p>

 <a name="Set"><strong>#set</strong></a>
 <p>
    <em>#set</em> ohjetta kytetn arvon mrittmiseksi
    viittaukselle. Arvo voidaan mritt joko muuttujaviittaukselle
    tai ominaisuusviittaukselle. Mritys tehdn suluissa, kuten
    seuraavassa esimerkiss:
 </p>

<source><![CDATA[
#set( $kadellinen = "apina" )
#set( $asiakas.Kayttaytyminen = $kadellinen )
]]></source>

 <p>
    Mrityksen 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 mritetyt
   elementit ovat kytettviss ArrayList -luokan metodien
   avulla. Voisit siis esimerkiksi viitata taulukon ensimmiseen
   elementtiin koodilla $apina.Sano.get(0).
 </p>


 <p>
    Oikeanpuoleinen arvo (RHS) voi olla mys 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 mrityksen oikeanpuoleinen ominaisuus- tai metodiviittaus on
    arvoa <em>null</em>, sit <b>ei</b> anneta vasemman puolen
    arvoksi. Tt keinoa ei voida kytt olemassa olevan viittauksen
    poistamiseen. Tm saattaa olla hmv Velocityn uusille
    kyttjille. Esimerkiksi:
 </p>

<source><![CDATA[
#set( $tulos = $kysely.kriteeri("nimi") )
Ensimmisen 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[
Ensimmisen kyselyn tulos on pete

Toisen kyselyn tulos on pete
]]></source>

 <p>
     Tll on vaara hmt aloittelijoita jotka muodostavat
     <em>#foreach</em> silmukoita joissa yritetn asettaa
     <em>#set</em> ohjeella viittausta ominaisuus- tai
     metodiviittauksella, ja sen jlkeen 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 ksitelln tarkemmin myhemmin tss
     dokumentissa.
 </p>

 <p>
   Yksi ratkaisu ongelmaan olisi asettaa <em>$tulos</em> etukteen
   arvoon <em>false</em> (eptosi). Tmn jlkeen jos kutsu
   <em>$kysely.kriteeri()</em> eponnistuu, 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 kyt <em>#end</em> lausetta.
 </p>

<a name="Tekstivakiot"><strong>Tekstivakiot</strong></a>

 <p>
    <em>#set</em> ohjetta kytettess lainausmerkkeihin (" ")
    suljettu teksti tulkitaan ja tulostetaan kuten seuraavasta
    esimerkist ky 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 sisll
    olevavasta tekstist on oletuksena kytss
    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 sisllytt 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 nhdn onko se tosi,
      joka tapahtuu kahdessa eri tapauksessa: (i) <em>$foo</em> on
      boolean arvo (tosi/eptosi) jolla on tosi -arvo, tai (ii) arvo
      on eri kuin null (eli muuttuja ei ole tyhj). <em>#if</em> ja
      <em>#end</em> lauseiden vliin jv sislt tulostetaan mikli
      testimuuttuja on tosi. Esimerkkitapauksessamme, jos muuttujalla
      <em>$foo</em> on null arvo, tai jos se on boolean eptosi, on
      testimuuttuja eptosi, eik tulostetta tule lainkaan.
    </p>

    <p>
      <em>#if</em> ja <em>#end</em> lauseiden vliss oleva teksti
      tulee tulosteeksi mikli ehto on tosi. Tss tapauksessa jos
      <em>$foo</em> on tosi, tulosteeksi tulee:
      "Velocity!". Toisaalta, mikli <em>$foo</em> on eptosi, on mys
      ehtolause eptosi eik tulostetta tule.
    </p>

    <p>
      <em>#elseif</em> tai <em>#else</em> elementtej voidaan kytt
      <em>#if</em> elementin kanssa. Huomaa, ett Velocityn
      sivumoottori lopettaa ensimmisen 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 itn</strong>
#elseif( $bar == 6 )
    <strong>Mene eteln</strong>
#else
    <strong>Mene lnteen</strong>
#end
]]></source>

    <p>Tss esimerkiss <em>$foo</em> on suurempi kuin 10, joten
    kaksi ensimmist vertailua eivt ole tosia. Seuraavaksi muuttujaa
    <em>$bar</em> verrataan lukuun 6, joka on tosi, joten tulosteeksi
    tulee <strong>Mene eteln</strong>.
    </p>

    <p>
    Huomaa, ett nykyiselln Velocityn numeeriset vertailut on
    rajoitettu Integer (kokonais-) lukuihin. Kaikki muut arvot
    tulkitaan <em>eptosi</em>ksi. Ainoa poikkeus thn 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 kytt vastaavuusoperaattoria muuttujien vlisten
    suhteiden tulkitsemiseen. Seuraavassa on yksinkertainen esimerkki
    vastaavuusoperaattorin kytst.
    </p>

<source><![CDATA[
#set ($foo = "deoksiribonukleiinihappo")
#set ($bar = "ribonukleiinihappo")

#if ($foo == $bar)
  Muuttujat eivt selvstikn ole samanlaiset. Joten...
#else
  Vastaavuusvertaus on eptosi, ja tm teksti tulee tulosteeksi.
#end
]]></source>

    <p>
      Velocity tukee mys loogisia AND ja OR
      operaattoreita. Listietoja lydt dokumentista <a
      href="vtl-reference-guide.html">VTL Reference Guide</a>. Alla on
      esimerkkilause joka kytt loogista AND:i.
    </p>

<source><![CDATA[

## looginen AND

#if( $foo && $bar )
   <strong> Tm JA tuo</strong>
#end

]]></source>

    <p>
      If lause on tosi vain mikli sek <em>$foo</em> ett
      <em>$bar</em> ovat tosia. Jos <em>$foo</em> on eptosi, tulee
      lauseesta eptosi eik <em>$bar</em> muuttujaa tarvitse edes
      testata. Jos <em>$foo</em> on tosi, testataan sen jlkeen
      muuttujan <em>$bar</em> arvo; jos mys <em>$bar</em> on tosi,
      silloin koko ilmaus on tosi ja <strong>Tm JA tuo</strong>
      tulee tulosteeksi. Jos <em>$bar</em> on eptosi, silloin koko
      ilmaus on eptosi 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>Tm 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 eptosi, koko
      lauseke on tosi, ja <strong>Tm TAI tuo</strong> on
      tulosteena. Toisaalta mikli <em>$foo</em> on eptosi, on
      muuttujan <em>$bar</em> arvo testattava. Jos tss tapauksessa
      mys <em>$bar</em> on eptosi, koko ilmauksesta tulee eptosi
      eik tulostetta tule. Jos <em>$bar</em> on tosi, silloin koko
      ilmauksesta tulee tosi, ja tulosteena on <strong>Tm 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 eptosi, eik
    tulostetta tmn vuoksi tule. Mikli <em>$foo</em> on eptosi,
    silloin <em>!$foo</em> on tosi ja <strong>EI tuota</strong> on
    tulosteena. l sekoita tt 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>
    Tm <em>#foreach</em> silmukka ky lpi 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 mys 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 liittyvt objektit,
    voit kytt 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 kyttmiseen. Voit
    kytt 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 mritetn
    velocity.properties tiedostossa. Oletuksena laskuri alkaa arvosta
    1, mutta aloitusarvo voidaan mritt olemaan joko 1 tai 0
    <code>velocity.properties</code>
    tiedostossa. <code>velocity.properties</code> tiedoston
    silmukkalaskuriosio nytt tlt:
    </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 tiedostojrjestelmst tiedoston, jonka sislt
    listn sivun siihen kohtaan jossa <em>#include</em> mritys
    tehtiin. Tiedoston sislt liitetn sellaisenaan eik sit siis
    kytet Velocityn sivumoottorin kautta. Turvallisuussyist
    haettava tiedosto voi sijaita vain TEMPLATE_ROOT vakion
    mrittmn hakemiston alla.
    </p>

<source><![CDATA[
#include( "yksi.txt" )
]]></source>

    <p>
    Tiedosto johon <em>#include</em> ohje viittaa on
    lainausmerkeiss. Jos halutaan sisllytt useampia kuin yksi
    tiedosto, tiedostonimet tulee erotella toisistaan pilkuilla.
    </p>

<source><![CDATA[
#include( "yksi.gif","kaksi.txt","kolme.htm" )
]]></source>

    <p>
    Sisllytettvn tiedoston ei ole pakko viitata nimen perusteella;
    itse asiassa usein on parempi kytt muuttujaa tiedostonimen
    asemesta. Tm on hydyllist esimerkiksi silloin kun sivun
    ulkoasu riippuu sivupyynnn aikana ptettvst
    ehdosta. Seuraavassa on esimerkki jossa kytetn sek
    tiedostonime ett muuttujaa.
    </p>

<source><![CDATA[
#include( "terveiset.txt", $sesonkivarasto )
]]></source>

 </section>

<section name="Parse">

    <p>
    <em>#parse</em> elementin avulla sivusuunnittelija voi sisllytt
    paikallisesta levyjrjestelmst tiedostoja jotka sisltvt 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 lisksi mys muuttujan. Kaikkien sivupohjien
    joihin <em>#parse</em> ohjeella viitataan tulee sijaita
    TEMPLATE_ROOT vakion mrittmn 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 niisskin on <em>#parse</em>
    ohjeita. <code>velocity.properties</code> tiedostossa oleva rivi
    <em>parse_directive.maxdepth</em> mritt sen kuinka monta
    perkkist <em>#parse</em> viittausta voidaan tehd. Mikli
    <em>parse_directive.maxdepth</em> mritys puuttuu, kytetn
    oletusarvoa 10. Rekursiivisuus on sallittu. Jos esimerkiksi
    sivupohja <code>dofoo.vm</code> sislt seuraavat rivit:
    </p>

<source><![CDATA[
Laske alaspin.
#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 alaspin." on nytetty, 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!". Tmn jlkeen 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
    pysytt sivun tulkitsemisen. Tm on hydyllist sivupohjan
    virheidenetsinnn aikana.
    </p>

<source><![CDATA[
#stop
]]></source>
 </section>

<section name="Velocimakrot">

    <p>
    <em>#macro</em> elementin avulla sivupohjan suunnittelija voi
    mritt toistuvasti kytetyn VTL sivupohjan osan. Velocimakrot
    ovat erittin kyttkelpoisia sek monimutkaisissa, ett
    yksinkertaisissa tehtviss. Seuraava Velocimakro toimii
    johdantona Velocimakroihin. Se on luotu kirjoitettavan tekstin
    mrn vhentmiseksi, sek kirjoitusvirheiden mrn
    minimoimiseksi.
    </p>

<source><![CDATA[
#macro( d )
<tr><td></td></tr>
#end
]]></source>

    <p>
    Esimerkiss mriteltiin Velocimakro nimeltn <em>d</em>, ja sit
    voidaan kutsua muiden VTL ohjeiden tapaan:
    </p>

<source><![CDATA[
#d()
]]></source>

    <p>
    Kun tt sivupohjaa haetaan, Velocity korvaa ohjeen <em>#d()</em>
    rivill joka sislt yhden tyhjn solun.
    </p>

    <p>
    Velocimakro voi ottaa kuinka monta parametria tahansa -- tai ei
    yhtn parametria, kuten ensimmisess esimerkissmme -- mutta kun
    Velocimakroa kutsutaan, tulee kutsussa olla tsmlleen yht monta
    parametria kuin makroa mriteltess. Useimmat Velocimakrot ovat
    hieman monimutkaisempia kuin edellinen esimerkki. Seuraavassa on
    Velocimakro joka ottaa kaksi argumenttia; vrin ja listan.
    </p>

<source><![CDATA[
#macro( taulurivit $vari $jokulista )
#foreach( $jotain in $jokulista )
    <tr><td bgcolor=$vari>$jotain</td></tr>
#end
#end
]]></source>

    <p>
    Tss esimerkiss mriteltiin Velocimakro <em>taulurivit</em>
    joka ottaa kaksi parametria. Ensimminen parametri on
    <em>$vari</em> ja toinen <em>$jokulista</em>.
    </p>

    <p>
    Velocimakroon voidaan kirjoittaa mit tahansa koodia jota voidaan
    kytt muuallakin VTL sivupohjassa. <em>taulurivit</em>
    Velocimakro on <em>foreach</em> lause. <em>taulurivit</em>
    Velocimakrossa on kaksi <em>#end</em> lausetta; ensimminen kuuluu
    <em>#foreach</em> lauseelle, jlkimminen ptt Velocimakron
    mrityksen.
    </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>
    tss 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 mritt <em>inline</em>, eli Velocity
    sivupohjassa itsessn, jolloin ko. makro ei ole kytettviss
    muissa sivupohjissa. Velocimakron mrittminen siten ett se on
    kaikkien sivupohjien kytss on hydyllist; samaa makroa ei
    tarvitse mritt erikseen jokaisessa sivupohjassa jossa sit
    tarvitaan, jolloin tymr ja virheiden mahdollisuus
    vhenee. Lisksi makroon tehty muutos vaikuttaa heti kaikkiin
    sivupohjiin joissa se on kytss.
    </p>

    <p>
    Oletetaan ett Velocityss on mriteltyn Velocimakro
    <em>#tablerows($vari $lista)</em>. Tt makroa voitaisiin kytt
    miss tahansa sivupohjassa. Sit voitaisiin kytt useaan kertaan
    ja moneen eri kytttarkoitukseen. Sieniasioita ksittelevss
    sivupohjassa <code>sieni.vm</code>, <em>#tablerows</em>
    Velocimakroa voitaisiin kytt 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 mritelty <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> 
      Numerovli : [ 1..2] tai [$foo .. $bar]
    </li>
    <li> 
      ObjectArray : [ "a", "b", "c"]
    </li>
    <li> 
       boolean arvo true (tosi)
    </li>
    <li> 
       boolean arvo false (eptosi)
    </li>
  </ul>

   <p>
     Kun siirrt viittauksia argumentteina Velocimakroille, huomaa,
     ett viittaukset siirretn 'nimen mukaan' ('by name'). Tm
     tarkoittaa sit, ett viittausten arvo 'haetaan' Velocimakrossa
     itsessn. Tmn ominaisuuden avulla voit siirt viittauksia
     jotka ovat metodikutsuja, ja nin 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 tm ominaisuus saattaa vaikuttaa yllttvlt,
       mutta kun otat huomioon Velocimakrojen alkuperisen
       tarkoituksen -- usein kytettyjen VTL komentojen leikkaa-liimaa
       kopioimisen vhentminen -- ominaisuus on perusteltu. Sen
       avulla voit esimerkiksi siirt Velocimakroon argumenttina
       tilansa muistavia (stateful) objekteja, kuten objektin joka
       generoi vrej perkkisess jrjestyksess taulukon rivien
       vrien mrittmiseksi.
    </p>
   
    <p>
       Jos sinun tarvitsee kiert tm 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 nm arvot on dokumentoitu mys <a
    href="http://jakarta.apache.org/velocity/developer-guide.html">Kehittjn
    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
    etsitn mritellyst sivupohjahakemistosta.
    </p>

    <p>
    <code>velocimacro.permissions.allow.inline</code> - Tm
    ominaisuus ptt voidaanko Velocimakroja mritt tavallisissa
    sivupohjissa. Ominaisuus voi saada arvon true (tosi) tai false
    (eptosi). Oletuksena on tosi, jolloin sivusuunnittelijat voivat
    mritt Velocimakroja suoraan omissa sivupohjissaan.
    </p>

    <p>
    <code>velocimacro.permissions.allow.inline.to.replace.global</code>

    - Tmn ominaisuuden avulla voidaan mritt voivatko
    sivupohjassa mritellyt Velocimakrot korvata yleisesti
    mritellyt, <code>velocimacro.library</code> ominaisuuden kautta
    ladatut Velocimakrot. Ominaisuus voi saada arvon true tai
    false. Oletuksena <code>false</code>, eptosi, jolloin
    sivupohjassa mritellyt Velocimakrot eivt voi korvata
    sivupohjakirjastoista ladattuja makroja.
    </p>

   <p>
    <code>velocimacro.permissions.allow.inline.local.scope</code> -
    Mahdolliset arvot ovat true tai false, oletuksena false. Tm
    ominaisuus ptt ovatko sivupohjassa mritetyt Velocimakrot
    'nkyvi' ainoastaan siin sivupohjassa jossa ne on
    mritelty. Toisin sanoen kun tm ominaisuus on asetettu arvoon
    true (tosi), sivupohja voi mritt inline Velocimakroja jotka
    ovat kytettviss vain sivupohjasta joka ne mritti. Tmn
    ominaisuuden avulla voidaan aikaansaada erikoisia vaikutuksia; jos
    yleisesti mritelty Velocimakro kutsuu toista yleisesti
    mritelty makroa, tmn ominaisuuden avulla sivupohja voi
    mritt oman toteutuksensa jlkimmisest makrosta, jota
    ensimminen makro kutsuu. Sivupohjan paikallista makroa kytetn
    vain kun ensimmist 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' eivtk vaikuta pysyvsti muuttujien sisltn.
    </p>

    <p>
    <code>velocimacro.library.autoreload</code> - Tm ominaisuus
    ohjaa Velocimakrokirjaston automaattista uudelleenlatausta. Kun
    ominaisuus on asetettu arvoon <code>true</code> kutsutun
    Velocimakron koodi tutkitaan mahdollisten muutosten varalta, ja se
    ladataan uudelleen mikli tarpeellista. Nin voit muuttaa ja
    testata Velocimakrokirjastoa ilman ett sinun tarvitsee kynnist
    uudelleen sovellustasi tai sovellusalustaa, aivan kuten voit tehd
    normaalien sivupohjienkin kanssa. Tm asetus toimii vain kun
    resurssilataajien vlimuisti on pois plt (<i>off</i>,
    esim. <code>file.resource.loader.cache = false</code>). Tm
    ominaisuus on tarkoitettu kytettvksi vain sovelluksen
    kehitysvaiheessa, ei tuotantokyttn.
    </p>

    <strong>Velocimakro Trivia</strong>

    <p>
    Nykyiselln Velocimakrot tulee olla mriteltyin ennen kuin
    niit kytetn sivupohjissa. Tm tarkoittaa sit ett #macro()
    mritystesi tulee sijaita ennen rivej joissa kytt Velocimakroja.
    </p>

    <p>
    Tm on trke muistaa jos yritt kytt ohjetta #parse()
    sivupohjaan jossa on inline #macro() ohjeita. Koska #parse()
    suoritetaan ajon aikana, ja parseri ptt ajon aikana onko
    sivupohjassa oleva Velocimakrolta nyttv elementti Velocimakro,
    ei Velocimakrojen #parse():aminen toimi niin kuin
    olettaisi. Ongelma voidaan vltt helposti kyttmll
    <code>velocimacro.library</code> toimintoa jonka avulla Velocity
    lataa Velocimakrosi kynnistyksen 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 sislt>
#include( "a.txt" )

## \#include( "a.txt" ) tulostuu \#include( "a.txt" )
\#include( "a.txt" )

## \\#include ( "a.txt" ) tulostuu \<tiedoston a.txt sislt>
\\#include ( "a.txt" )
]]></source>

  <p>
  Erityst tarkkaavaisuutta tarvitaan tapauksissa joissa suojataan VTL
  ohjeita jotka sisltvt 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 eptosi (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 eptosi, 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>
  Mikli <em>$jazz</em> on tss tapauksessa tosi, tuloste on:
  </p>

<source><![CDATA[
\ Vyacheslav Ganelin
\
]]></source>

  <p>
  Tmn ymmrtmiseksi huomaa, ett <code>#if( arg )</code> rivill
  olevaa rivinvaihtoa (return) ei kopioida tulosteeseen. Tmn vuoksi
  <code>#if()</code> lauseen runko ('Vyacheslav Ganelin') on '\\'
  merkinnst saadun ensimmisen '\' merkin kanssa samalla
  rivill. Jlkimminen '\' merkki on toisella rivill kuin teksti,
  koska tekstin lopussa on rivinvaihto ja jlkimminen '\\'
  merkinnst saatu '\' merkki on ennen <code>#end</code> ohjetta,
  joten merkki kuuluu edelleen <code>#if()</code> lauseen runkoon.
  </p>

  <p>
  Jos <em>$jazz</em> on eptosi, ei tulostetta tule. Huomaa ett
  ongelmia tulee mikli 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 kytss. Liian monta lopetuselementti sivupohjassa
  aiheuttaa virheen sivua luotaessa.
  </p>

 </section>

<section name="VTL: Muotoilu">


    <p>
    Vaikka tss ohjeessa oleva VTL on usein muotoiltu rivivaihdoin ja
    vlilynnein, 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 kodinptk jonka Geir Magnusson
    Jr. lhetti Velocityn kyttjien postituslistalle:
    </p>

<source><![CDATA[
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
]]></source>

    <p>
    Velocity sy ylimriset vlilynnit. Edellinen koodinptk
    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 sisnrakennettuja matemaattisia
    funktioita joita voidaan kytt sivupohjissa <em>#set</em> ohjeen
    kanssa. Seuraavat yhtlt ovat esimerkkej yhteen-, vhennys-,
    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. Jakojnns
    saadaan kyttn jnnsoperandilla (<em>%</em>).
  </p>

<source><![CDATA[
#set( $foo = $bar % 5 )
]]></source>

  <p>
    Matemaattisia funktioita kytettess Velocityss vain
    kokonaisluvut (...-2, -1, 0, 1, 2...) ovat sallittuja;
    ei-kokonaislukuja kytettess asia kirjataan lokiin ja tulokseksi
    palautetaan tyhj arvo (null).
  </p>

  <p>
    Velocityll on sisnrakennettu keino nollalla jakamisen
    ksittelemiseen. 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 nytt tmn sivupohjan, tuloste
    on:
  </p>

<source><![CDATA[
$uhoh
]]></source>

  <p>
    Suunnittelijoiden on otettava huomioon mys, ett <em>#set</em>
    tuottaa merkkijonoja, jotka on muunnettava kokonaisluvuiksi jotta
    niit voidaan kytt vaihteluvli mritettess (range
    operator). Seuraavassa esimerkki tllaisesta 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="Vaihteluvli (Range Operator)">

  <p>
    Vaihteluvli voidaan kytt <em>#set</em> ja <em>#foreach</em>
    lauseiden yhteydess. Vaihteluvli tuottaa kokonaislukuja
    sisltvi 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. Mikli <em>m</em> on pienempi kuin
    <em>n</em> lasketaan vaihteluvlin luvut alaspin. Seuraavassa
    esimerkkej vaihteluvlin kytst:
  </p>

<source><![CDATA[
Ensimminen 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

Neljs esimerkki:
[1..3]
]]></source>

  <p>
    Tuottaa seuraavan tulosteen:
  </p>

<source><![CDATA[
Ensimminen esimerkki:
1 2 3 4 5

Toinen esimerkki:
2 1 0 -1 -2

Kolmas esimerkki:
0 1

Neljs esimerkki:
[1..3]
]]></source>

  <p>
    Huomaa ett vaihteluvlioperaattori tuottaa taulukon vain kun sit
    kytetn <em>#set</em> tai <em>#foreach</em> ohjeiden kanssa,
    kuten neljnnest esimerkist ky selville.
  </p>

  <p>
    Vaihteluvlioperaattori on erityisen kyttkelpoinen kun halutaan
    tehd verkkosivun taulukko standardikokoiseksi, mutta joissain
    tapauksissa taulukon tyttmiseksi ei ole riittvsti dataa.
  </p>

  </subsection>

<subsection name="Edistyneet kysymykset: Suojaaminen ja !">

  <p>
    Kun viittaus hiljennetn <em>!</em> merkill ja <em>!</em> merkki
    edelt suojausmerkki <em>\</em> ksitelln viittaus erityisell
    tavalla. Huomaa erot normaalin suojauksen ja tilanteen jossa
    <em>\</em> edelt <em>!</em> merkki, vlill.
  </p>

<source><![CDATA[
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
]]></source>

  <p>
   Tulosteena on:
  </p>

<source><![CDATA[
$!foo
$!{foo}
$\!foo
$\\!foo
]]></source>

  <p>
   Vertaa tt 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>
Tm osio on Velocimakroaiheinen mini-FAQ. Osio muuttuu ajan myt,
joten uutta tietoa hakevien kannattanee palata sivulle aika ajoin.
</p>

<p>
Huom! : Tss osiossa 'Velocimakro':ihin viitataan usein lyhenteell
'VM'.
</p>

<strong>Voinko kytt 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
kytnnllisesti katsoen ohje.
</p>

<p>
<i>Kuitenkin...</i>, voit kiert rajoituksen. Yksinkertainen ratkaisu
on kytt hyvksi sit ett lainausmerkeiss (") oleva teksti
tulkitaan. Tm ansiosta voit tehd seuraavasti:
</p>

<source><![CDATA[
#set($stuff = "#bold('hello')" )
#center( $stuff )
]]></source>

<p>
Voit mys sst rivin...
</p>

<source><![CDATA[
#center( "#bold( 'hello' )" )
]]></source>

<p>
Huomaa ett jlkimmisess esimerkiss parametri ksitelln VM:n
<i>sisll</i>, ei kutsun tasolla. Toisin sanoen VM:lle annettu
parametri siirretn kokonaisuudessaan ja ksitelln VM:ssa johon se
siirrettiin. Tmn 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() sisll, kytetn muuttujan $bar arvoa joka asetettiin
#outer VM:ssa.
</p>

<p>
Tm on tarkoituksellinen ja tarkkaan vaalittu ominaisuus - parametrit
siirretn '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
vlttmiseksi kutsu metodia VM:n ulkopuolelta ja siirr arvo VM:oon.
</p>

<source><![CDATA[
#set($vari = $bar.rivinVari())
#foo( $vari )
]]></source>


<strong>Voinko rekisterid Velocimakroja #parse() :n kautta?
</strong>

    <p>
    Nykyiselln Velocimakrot tulee olla mriteltyin ennen
    ensimmist kytt. Tm tarkoittaa sit ett #macro()
    mritystesi tulisi tulla ennen kuin kytt Velocimakroja.
    </p>

    <p>
    Tm on trke muistaa jos yritt kytt ohjetta #parse()
    sivupohjaan jossa on inline #macro() ohjeita. Koska #parse()
    suoritetaan ajon aikana, ja parseri ptt ajon aikana onko
    sivupohjassa oleva Velocimakrolta nyttv elementti Velocimakro,
    ei Velocimakrojen #parse():aminen toimi niin kuin
    olettaisi. Ongelma voidaan vltt helposti kyttmll
    <code>velocimacro.library</code> toimintoa jonka avulla Velocity
    lataa Velocimakrosi kynnistyksen yhteydess.
    </p>


<strong>Mit tarkoittaa Velocimakrojen automaattinen
uudelleenlataus?</strong>

  <p>
   On olemassa asetus joka on tarkoitettu kytettvksi jrjestelmn
   <i>kehityksen</i> aikana, ei kytss olevassa jrjestelmss :
  </p>

  <p>
  <code>velocimacro.library.autoreload</code>
  </p>

   <p>
   joka on oletuksena pois kytst (false). Kun ominaisuus on
   asetettu kyttn (true) <em>yhdess</em> asetuksen
   </p>

   <p>
   <code>&lt;type&gt;.resource.loader.cache = false</code>
   </p>

    <p>
    kanssa (jossa &lt;type&gt; on resurssilataajan nimi jota kytt,
    kuten 'file'), silloin Velocity lataa automaattisesti
    Velocitymakroihin tekemsi muutokset silloin kun teet niit, joten
    sinun ei tarvitse kynnist uudelleen sovellusalustaa (tai
    ohjelmaa) tai turvautua johonkin muuhun kikkaan saadaksesi
    muuttuneet Velocitymakrosi kyttn.
    </p>

    <p>
    Yksinkertainen konfiguraatio saattaisi nytt seuraavalta:
    </p>

    <source><![CDATA[
    file.resource.loader.path = templates
    file.resource.loader.cache = false
    velocimacro.library.autoreload = true
    ]]></source>

    <p>
    l kyt nit asetuksia tuotantokytss.
    </p>

</subsection>

<subsection name="Merkkijonojen yhdistminen">

    <p>
    Yleinen kehittjien kysym kysymys on <i>Kuinka yhdistn
    merkkijonoja? Onko olemassa Javan '+' operaattoria vastaavaa
    toimintoa?</i>.
   </p>

   <p>
    Viittausten liittmiseksi yhteen VTL:ssa, sinun tarvitsee vain
    'laittaa ne yhteen'. Konteksti jossa yhdistt viittaukset
    vaikuttaa tuloksiin, joten esimerkit ovat paikallaan.
   </p>

   <p>
    Normaalissa tapauksessa (jolloin sekoitat muuttujat sivupohjan
    muuhun sisltn) :
   </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
     siirrettvksi 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
     kyttmn '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 kytetn, jotta parseri tietisi ett tarkoitat
      viittauksellasi muuttujaa '$size' eik '$sizeTall', jota se
      kyttisi mikli et olisi kyttnyt '{}' merkkej.
    </p>
</subsection>

</section>

<section name="Palaute">

  <p>
    Mikli lydt tst ohjeesta virheit tai haluat antaa ohjetta
    koskevaa palautetta, ole hyv ja lhet shkpostia <a
    href="mailto:velocity-user@jakarta.apache.org">Velocity
    kyttjlistalle</a>.  Kiitos!
  </p>

</section>

</body>
</document>