<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html>
  <head>
    <title>Apache Velocity - 
  Velocity käyttäjän opas</title>
    <style type="text/css" media="all">
      @import url("../css/maven-base.css");
      @import url("../css/maven-theme.css");
      @import url("../css/site.css");
    </style>
    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
    <link rel="alternate" href="http://feeds.feedburner.com/ApacheVelocitySiteNews" type="application/rss+xml" title="Apache Velocity - 
  Velocity käyttäjän opas News" />
          <meta name="author" content="
  Velocity Documentation Team" />
          <meta name="author" content="
  John Castura" />
          <meta name="author" content="
  Juha Kilpi" />
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
      </head>
  <body class="composite">
    <div id="banner">
                  <a href="../../../" id="bannerLeft">
    
                                            <img src="../images/velocity_project_wide.png" alt="" />
    
            </a>
                          <span id="bannerRight">
    
                                            <img src="../images/velocity-logo.png" alt="" />
    
            </span>
            <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="breadcrumbs">
          
  
            <div class="xleft">
          
          <a href="http://www.apache.org/">Apache</a>
              &gt;
      
          <a href="../../../../">Velocity</a>
              &gt;
      
          <a href="../">Velocity Engine</a>
                </div>
            <div class="xright">      <a href="../../../devel/index.html">Engine</a>
          |
          <a href="../../../../tools/devel/index.html">Tools</a>
          |
          <a href="../../../../dvsl/devel/index.html">DVSL</a>
          
  
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="leftColumn">
      <div id="navcolumn">
           
  
                   <h5>Velocity</h5>
        <ul>
              
    <li class="none">
              <a href="../index.html">General</a>
        </li>
              
    <li class="none">
              <a href="../overview.html">Overview</a>
        </li>
              
    <li class="none">
              <a href="../getting-started.html">Getting Started</a>
        </li>
              
    <li class="none">
              <a href="../webapps.html">Web Applications</a>
        </li>
              
    <li class="none">
              <a href="../../../../download.cgi">Download</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/VelocityFAQ">FAQ (Wiki)</a>
        </li>
          </ul>
          <h5>Docs</h5>
        <ul>
              
    <li class="none">
              <a href="../user-guide.html">User Guide</a>
        </li>
              
    <li class="none">
              <a href="../developer-guide.html">Developer Guide</a>
        </li>
              
    <li class="none">
              <a href="../vtl-reference-guide.html">VTL Reference</a>
        </li>
              
    <li class="none">
              <a href="../anakia.html">Anakia: XML->doc tool</a>
        </li>
              
    <li class="none">
              <a href="../texen.html">Texen: text generation</a>
        </li>
          </ul>
          <h5>Developers</h5>
        <ul>
              
    <li class="none">
              <a href="../license.html">License</a>
        </li>
              
    <li class="none">
              <a href="../apidocs/index.html">Javadoc</a>
        </li>
              
    <li class="none">
              <a href="../changes-report.html">Changes in 1.5</a>
        </li>
              
    <li class="none">
              <a href="../jira-report.html">Resolved Issues in 1.5</a>
        </li>
              
    <li class="none">
              <a href="../jar-dependencies.html">Dependencies</a>
        </li>
              
    <li class="none">
              <a href="http://svn.apache.org/viewvc/velocity/engine/branches/Velocity_1.5_BRANCH/">Source Code Repository</a>
        </li>
              
    <li class="none">
              <a href="../build.html">Building from Source</a>
        </li>
          </ul>
          <h5>Community</h5>
        <ul>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/">Wiki</a>
        </li>
              
    <li class="none">
              <a href="../../../../news.html">Recent News</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/PoweredByVelocity">Powered By Velocity</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/VelocityEditors">IDE/Editor Plugins</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/PublishedArticlesAndBooks">Articles and Books</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/GetInvolved">Get Involved</a>
        </li>
              
    <li class="none">
              <a href="../../../../contact.html">Mailing Lists</a>
        </li>
          </ul>
          <h5>Velocity Development</h5>
        <ul>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/RoadMap">Road Map</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/CodeStandards">Coding Standards</a>
        </li>
              
    <li class="none">
              <a href="http://wiki.apache.org/velocity/DocumentationGuidelines">Documentation Guidelines</a>
        </li>
              
    <li class="none">
              <a href="https://issues.apache.org/jira/browse/VELOCITY">Issues</a>
        </li>
              
    <li class="none">
              <a href="../../../../who-we-are.html">Who we are</a>
        </li>
          </ul>
          <h5>Translations</h5>
        <ul>
              
    <li class="none">
              <a href="http://www.jajakarta.org/velocity/">Site (Japanese)</a>
        </li>
              
    <li class="none">
              <strong>User's Guide (Finnish)</strong>
        </li>
              
    <li class="none">
              <a href="../translations/user-guide_fr.html">User's Guide (French)</a>
        </li>
              
    <li class="none">
              <a href="../translations/user-guide_es.html">User's Guide (Spanish)</a>
        </li>
          </ul>
          <h5>Project Documentation</h5>
        <ul>
              
                
        <li class="collapsed">
              <a href="../project-info.html">Project Information</a>
              </li>
              
                
        <li class="collapsed">
              <a href="../project-reports.html">Project Reports</a>
              </li>
          </ul>
                                             
                        
                        <a class="poweredBy" href="../../../../" title="Apache Velocity" ><img class="poweredBy" alt="Apache Velocity" src="../images/pbv90x30.png" /></a>
                                
                        
                        <a class="poweredBy" href="../../../../rss/news.rss" title="Velocity News Feed" ><img class="poweredBy" alt="Velocity News Feed" src="../images/feed-icon-24x24.jpg" /></a>
                    

        </div>
    </div>
    <div id="bodyColumn">
      <div id="contentBox">
        

<a name="sisällys"></a><div class="section"><h2>Sisällys</h2>

<ol type="1">
<li><a href="#Tietojatästäoppaasta">Tietoja tästä oppaasta</a></li>
<li><a href="#MikäonVelocity?">Mikä on Velocity?</a></li>
<li><a href="#MitenvoinkäyttääVelocityä?">Miten voin käyttää Velocityä?</a>
    <ol type="1">
        <li><a href="#Kurakauppaesimerkki">Kurakauppa esimerkki</a></li>
    </ol>
</li>
<li><a href="#VelocityTemplateLanguage(VTL):Johdanto">Velocity
Template Language (VTL): Johdanto</a></li>
<li><a href="#HeiVelocityMaailma!">Hei Velocity Maailma!</a></li>
<li><a href="#Kommentit">Kommentit</a></li>
<li><a href="#Viittaukset">Viittaukset</a>
    <ol type="1">
        <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="#Muodollinenmerkintä">Muodollinen viittausten merkintä</a></li>
<li><a href="#Hiljainenviittaustenmerkintä">Hiljainen viittausten merkintä</a></li>
<li><a href="#Kirjaimellisesti">Kirjaimellisesti</a>
    <ol type="1">
        <li><a href="#Dollari">Dollari</a></li>
        <li><a href="#VTLviittaustensuojaaminen">VTL viittausten suojaaminen</a></li>
    </ol>
</li>
<li><a href="#Kirjainkoonmuutos">Kirjainkoon muutos</a></li>
<li><a href="#Ohjeet">Ohjeet</a>
    <ol type="1">
        <li><a href="#Set">Set</a></li>
        <li><a href="#Tekstivakiot">Tekstivakiot</a></li>
        <li><a href="#If-Elseehtolauseet">If-Else ehtolauseet</a>
            <ol type="1">
                <li><a href="#Relaatio-jaloogisetoperaattorit">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="#VTLohjeidensuojaaminen">VTL ohjeiden suojaaminen</a></li>
<li><a href="#VTL:Muotoilu">VTL: Muotoilu</a></li>
<li><a href="#Muitaominaisuuksiajasekalaista">Muita ominaisuuksia ja sekalaista</a>
    <ol type="1">
        <li><a href="#Matematiikka">Matematiikka</a></li>
        <li><a href="#Vaihteluväli(RangeOperator)">Vaihteluväli (Range Operator)</a></li>
        <li><a href="#Edistyneetkysymykset:Suojaaminenja!">Edistyneet kysymykset: Suojaaminen ja !</a></li>
        <li><a href="#YleistäVelocimakroista">Yleistä Velocimakroista</a></li>
        <li><a href="#Merkkijonojenyhdistäminen">Merkkijonojen yhdistäminen</a></li>
    </ol>
</li>
<li><a href="#Palaute">Palaute</a></li>
</ol>

</div>

<a name="tietoja_tästä_oppaasta"></a><div class="section"><h2>Tietoja tästä oppaasta</h2>

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

</div>

<a name="mikä_on_velocity"></a><div class="section"><h2>Mikä on Velocity?</h2>

 <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/" class="externalLink">JSP</a>:lle (Java Server
    Pages) ja <a href="http://www.php.net/" class="externalLink">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/" class="externalLink">Turbine</a> web
    sovelluskehykselle. Yhdessä Velocity ja Turbine tarjoavat
    sivupohjaratkaisun jonka avulla web sovelluksia voidaan kehittää
    todellisen MVC -mallin mukaisesti.
 </p>

</div>

<a name="miten_voin_käyttää_velocityä"></a><div class="section"><h2>Miten voin käyttää Velocityä?</h2>
<a name="kurakauppa_esimerkki"></a><div class="section"><h3>Kurakauppa esimerkki</h3>
   <p>
    Oletetaan että olet kuraa myyvän onlinekaupan
    sivusuunnittelija. Kutsumme kauppaa &quot;Kurakauppa
    Online&quot;: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>

<div class="source"><pre>
&lt;HTML&gt;
&lt;BODY&gt;
Hei $asiakas.Nimi!
&lt;table&gt;
#foreach( $kura in $kuratTarjouksessa )
   #if ( $asiakas.onOstanut($kura) )
      &lt;tr&gt;
        &lt;td&gt;
          $tarjous.haePromo( $kura )
        &lt;/td&gt;
      &lt;/tr&gt;
   #end
#end
&lt;/table&gt;
</pre></div>

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

 </div>

</div>

<a name="velocity_template_language_vtl:_johdanto"></a><div class="section"><h2>Velocity Template Language (VTL): Johdanto</h2>

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

<div class="source"><pre>
#set( $a = &quot;Velocity&quot; )
</pre></div>

 <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 &quot;Velocity&quot;.
 </p>

</div>

<a name="hei_velocity_maailma"></a><div class="section"><h2>Hei Velocity Maailma!</h2>

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

<div class="source"><pre>
&lt;html&gt;
&lt;body&gt;
#set( $foo = &quot;Velocity&quot; )
Hei $foo Maailma!
&lt;/body&gt;
&lt;html&gt;
</pre></div>

 <p>
    Tuloksena on web sivu jossa lukee &quot;Hei Velocity Maailma!&quot;.
 </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>

</div>

<a name="kommentit"></a><div class="section"><h2>Kommentit</h2>

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

<div class="source"><pre>
## Tämä on rivin pituinen kommentti.
</pre></div>

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

<div class="source"><pre>
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ä.

</pre></div>

 <p>
    Tässä on muutamia esimerkkejä yksi- ja monirivisten kommenttien
    toiminnan selvittämiseksi:
 </p>

<div class="source"><pre>
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ä.
</pre></div>

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

<div class="source"><pre>
#**
Tämä on VTL kommenttilohko. Lohkoa
voidaan käyttää esimerkiksi dokumentin
tekijä- ja versiotietojen
tallettamiseen:
@author
@version 5
*#
</pre></div>

</div>

<a name="viittaukset"></a><div class="section"><h2>Viittaukset</h2>

 <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></br>

    Muuttujan lyhyt merkintätapa koostuu ensimmäisenä olevasta &quot;$&quot;
    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 (&quot;-&quot;)</li>
     <li>alaviiva (&quot;_&quot;)</li>
   </ul>
 </p>

 <p>
    Seuraavassa muutamia esimerkkejä toimivista muuttujaviittauksista:
 </p>

<div class="source"><pre>
$foo
$kuraLinko
$kura-linko
$kura_linko
$kuraLinko1
</pre></div>

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

<div class="source"><pre>
#set( $foo = &quot;bar&quot; )
</pre></div>

 <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></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 (&quot;.&quot;) ja toinen VTL tunniste. Seuraavassa on
    esimerkkejä toimivista ominaisuusviittauksista:
 </p>

<div class="source"><pre>
$asiakas.Osoite
$ostos.Summa
</pre></div>

 <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></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 &quot;$&quot; merkistä, jota seuraa VTL tunniste, jonka jälkeen
    tulee VTL <em>Metodirunko</em>. VTL Metodirunko koostuu VTL
    tunnisteesta jota seuraa vasen sulkumerkki &quot;(&quot;, jota seuraa
    valinnainen parametrilista, jota seuraa oikeanpuoleinen
    sulkumerkki &quot;)&quot;. Seuraavassa on esimerkkejä toimivista
    metodiviittauksista:
 </p>

<div class="source"><pre>
$asiakas.getOsoite()
$ostos.getSumma()
$sivu.setOtsake( &quot;Minun kotisivuni&quot; )
$henkilo.setOminaisuudet( [&quot;Outo&quot;, &quot;Kummallinen&quot;, &quot;Innostunut&quot;] )
</pre></div>

 <p>
    Metodirungossa esiintyvä get tarkoittaa &quot;hae&quot; ja set &quot;aseta&quot;.
 </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>

<div class="source"><pre>
$aurinko.getPlaneetat()
$mato.getMulta()
$albumi.getValokuva()
</pre></div>

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

<div class="source"><pre>
$aurinko.getPlaneetat( [&quot;Maa&quot;, &quot;Mars&quot;, &quot;Neptunus&quot;] )
## lyhyessä muodossa $sun.Planets ei voida antaa parametreja

$sisyphus.pushRock()
## Velocity olettaa että tarkoitan $sisyphus.getRock()

$kirja.setOtsake( &quot;Catalonian kotisivu&quot; )
## Parametrilistaa ei voida antaa
</pre></div>

 <p>
    <a name="muodollinen_viittausten_merkintä"><strong>Muodollinen viittausten merkintä</strong></a>
    <br></br>

    Edellisissä esimerkeissä käytettiin viittauksille lyhyttä
    merkintätapaa. Viittauksille on olemassa myös muodollinen
    merkintätapa, jota käytetään seuraavissa esimerkeissä:
 </p>

<div class="source"><pre>
${kuraLinko}
${asiakas.Osoite}
${osto.getSumma()}
</pre></div>

 <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: &quot;Juha
    on pyromaani.&quot; tai &quot;Juha on kleptomaani.&quot;. Tässä tapauksessa
    lyhyen viittausmuodon käyttäminen ei toimisi. Tutki seuraavaa
    esimerkkiä:
 </p>

<div class="source"><pre>
Juha on $pahemaani.
</pre></div>

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

<div class="source"><pre>
Juha on ${pahe}maani.
</pre></div>

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

<div class="source"><pre>
&lt;input type=&quot;text&quot; name=&quot;email&quot; value=&quot;$email&quot;/&gt;
</pre></div>

 <p>
    Kun lomake latautuu ensimmäisen kerran muuttujaviittauksella
    <em>$email</em> ei ole arvoa. Oletuksena Velocity täyttää
    lomakkeen tekstillä &quot;$email&quot;. 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>

<div class="source"><pre>
&lt;input type=&quot;text&quot; name=&quot;email&quot; value=&quot;$!email&quot;/&gt;
</pre></div>

 <p>
    Kun lomake latautuu ensimmäisen kerran eikä muuttujalla
    <em>$email</em> ole arvoa, tulostetaankin kenttään tyhjä teksti
    &quot;$email&quot; tekstin sijaan.
 </p>

 <p>
    Muodollista ja hiljaista muuttujien merkintää voidaan käyttää myös
    yhdessä;
 </p>

<div class="source"><pre>
&lt;input type=&quot;text&quot; name=&quot;email&quot; value=&quot;$!{email}&quot;/&gt;
</pre></div>

</div>

<a name="kirjaimellisesti"></a><div class="section"><h2>Kirjaimellisesti</h2>

  <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></br>

    Seuraavassa lauseessa dollarimerkin käytössä ei ole ongelmaa:
    &quot;Ostin markkinoilta säkin perunoita hintaan $2.50!&quot;. Kuten
    mainittu, VTL tunniste alkaa aina aakkosmerkillä, joten merkintää
    $2.50 ei ole vaaraa sekoittaa viittaukseksi.
  </p>

  <p>
    <a name="vtlviittaustensuojaaminen"><strong>VTL viittausten suojaaminen</strong></a>
    <br></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>

<div class="source"><pre>
#set( $email = &quot;foo&quot; )
$email
</pre></div>

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

<div class="source"><pre>
## Seuraava rivi määrittelee muuttujan $email tässä sivupohjassa:
#set( $email = &quot;foo&quot; )
$email
\$email
\\$email
\\\$email
</pre></div>

  <p>
     tulosteeksi tulee
  </p>

<div class="source"><pre>
foo
$email
\foo
\\$email
</pre></div>

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

<div class="source"><pre>
$email
\$email
\\$email
\\\$email
</pre></div>

  <p>
     tulosteeksi tulee
  </p>

<div class="source"><pre>
$email
\$email
\\$email
\\\$email
</pre></div>

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

<div class="source"><pre>
#set( $foo = &quot;gibbous&quot; )
$kuu = $foo
</pre></div>

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

</div>

<a name="kirjainkoon_muutos"></a><div class="section"><h2>Kirjainkoon muutos</h2>

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

<div class="source"><pre>
$foo

$foo.getBar()
## on sama kuin
$foo.Bar

$data.setKayttaja(&quot;juha&quot;)
## on sama kuin
#set( $data.Kayttaja = &quot;juha&quot; )

$data.getPyynto().getPalvelinNimi()
## on sama kuin
$data.Pyynto.PalvelinNimi
## on sama kuin
${data.Pyynto.PalvelinNimi}
</pre></div>

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

</div>


<a name="ohjeet"></a><div class="section"><h2>Ohjeet</h2>

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

<div class="source"><pre>
#set( $kadellinen = &quot;apina&quot; )
#set( $asiakas.Kayttaytyminen = $kadellinen )
</pre></div>

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

<div class="source"><pre>
#set( $apina = $bill ) ## muuttujaviittaus
#set( $apina.Ystava = &quot;monica&quot; ) ## tekstivakio
#set( $apina.Syytos = $valkoinentalo.vuoto ) ## ominaisuusviittaus
#set( $apina.Suunnitelma = $spindoctor.weave($web) ) ## metodiviittaus
#set( $apina.Numero = 123 ) ## numeerinen vakio
#set( $apina.Sano = [&quot;Ei&quot;, $minun, &quot;vikani&quot;] ) ## taulukko
</pre></div>

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

<div class="source"><pre>
#set( $arvo = $foo + 1 )
#set( $arvo = $bar - 1 )
#set( $arvo = $foo * $bar )
#set( $arvo = $foo / $bar )
</pre></div>

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

<div class="source"><pre>
#set( $tulos = $kysely.kriteeri(&quot;nimi&quot;) )
Ensimmäisen kyselyn tulos on $tulos

#set( $tulos = $kysely.kriteeri(&quot;osoite&quot;) )
Toisen kyselyn tulos on $tulos
</pre></div>

  <p>
     Jos <em>$kysely.kriteeri(&quot;nimi&quot;)</em> palauttaa merkkijonon
     &quot;pete&quot;, ja <em>$kysely.kriteeri(&quot;osoite&quot;)</em> palauttaa arvon
     <em>null</em>, on esimerkin tuloste seuraava:
 </p>

<div class="source"><pre>
Ensimmäisen kyselyn tulos on pete

Toisen kyselyn tulos on pete
</pre></div>

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

<div class="source"><pre>

#set( $kriteerit = [&quot;nimi&quot;, &quot;osoite&quot;] )

#foreach( $kriteeri in $kriteerit )

    #set( $tulos = $kysely.kriteerit($kriteeri) )

    #if( $tulos )
        Kysely onnistui
    #end

#end
</pre></div>

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


<div class="source"><pre>

#set( $kriteerit = [&quot;nimi&quot;, &quot;osoite&quot;] )

#foreach( $kriteeri in $kriteeri )

    #set( $tulos = false )
    #set( $tulos = $kysely.kriteerit($kriteeri) )

    #if( $tulos )
        Kysely onnistui
    #end

#end
</pre></div>

 <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 (&quot; &quot;)
    suljettu teksti tulkitaan ja tulostetaan kuten seuraavasta
    esimerkistä käy ilmi:
 </p>

<div class="source"><pre>
#set( $hakemistoJuuri = &quot;www&quot; )
#set( $sivupohjaNimi = &quot;index.vm&quot; )
#set( $sivupohja = &quot;$hakemistoJuuri/$sivupohjaNimi&quot; )
$sivupohja
</pre></div>

 <p>
  Tulosteeksi tulee
 </p>

<div class="source"><pre>
www/index.vm
</pre></div>

 <p>
    Jos teksti on suljettu hipsuihin (' '), sitä ei tulkita:
 </p>

<div class="source"><pre>
#set( $foo = &quot;bar&quot; )
$foo
#set( $blargh = '$foo' )
$blargh
</pre></div>

  Tulosteeksi tulee:

<div class="source"><pre>
  bar
  $foo
</pre></div>

 <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>
</div>


<a name="if-else_ehtolauseet"></a><div class="section"><h2>If-Else ehtolauseet</h2>

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

<div class="source"><pre>
#if( $foo )
   &lt;strong&gt;Velocity!&lt;/strong&gt;
#end
</pre></div>

    <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:
      &quot;Velocity!&quot;. 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>

<div class="source"><pre>
#if( $foo &lt; 10 )
    &lt;strong&gt;Mene pohjoiseen&lt;/strong&gt;
#elseif( $foo == 10 )
    &lt;strong&gt;Mene itään&lt;/strong&gt;
#elseif( $bar == 6 )
    &lt;strong&gt;Mene etelään&lt;/strong&gt;
#else
    &lt;strong&gt;Mene länteen&lt;/strong&gt;
#end
</pre></div>

    <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>
    <a name="relaatio-jaloogisetoperaattorit"><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>

<div class="source"><pre>
#set ($foo = &quot;deoksiribonukleiinihappo&quot;)
#set ($bar = &quot;ribonukleiinihappo&quot;)

#if ($foo == $bar)
  Muuttujat eivät selvästikään ole samanlaiset. Joten...
#else
  Vastaavuusvertaus on epätosi, ja tämä teksti tulee tulosteeksi.
#end
</pre></div>

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

<div class="source"><pre>

## looginen AND

#if( $foo &amp;&amp; $bar )
   &lt;strong&gt; Tämä JA tuo&lt;/strong&gt;
#end

</pre></div>

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

<div class="source"><pre>

## looginen OR

#if( $foo || $bar )
    &lt;strong&gt;Tämä TAI tuo&lt;/strong&gt;
#end
</pre></div>

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

<div class="source"><pre>

## looginen NOT

#if( !$foo )
  &lt;strong&gt;EI tuota&lt;/strong&gt;
#end

</pre></div>

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


 </div>

<a name="silmukat"></a><div class="section"><h2>Silmukat</h2>

   <strong>Foreach silmukat</strong>

    <p>
      <em>#foreach</em> mahdollistaa silmukoiden tekemisen. Esimerkiksi:
    </p>

<div class="source"><pre>
&lt;ul&gt;
#foreach( $tuote in $kaikkiTuotteet )
    &lt;li&gt;$tuote&lt;/li&gt;
#end
&lt;/ul&gt;
</pre></div>

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

<div class="source"><pre>
&lt;ul&gt;
#foreach( $avain in $kaikkiTuotteet.keySet() )
    &lt;li&gt;Avain: $avain -&gt; Arvo: $kaikkiTuotteet.get($avain)&lt;/li&gt;
#end
&lt;/ul&gt;
</pre></div>

    <p>
    Velocityllä on helppo keino silmukkalaskurin käyttämiseen. Voit
    käyttää laskuria esimerkiksi seuraavasti:
    </p>

<div class="source"><pre>
&lt;table&gt;
#foreach( $asiakas in $asiakasLista )
    &lt;tr&gt;&lt;td&gt;$velocityCount&lt;/td&gt;&lt;td&gt;$asiakas.Nimi&lt;/td&gt;&lt;/tr&gt;
#end
&lt;/table&gt;
</pre></div>

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

<div class="source"><pre>
# Silmukkalaskurin oletusnimi
counter.name = velocityCount

# Silmukkalaskurin aloitusarvo
counter.initial.value = 1
</pre></div>

 </div>

<a name="include"></a><div class="section"><h2>Include</h2>

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

<div class="source"><pre>
#include( &quot;yksi.txt&quot; )
</pre></div>

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

<div class="source"><pre>
#include( &quot;yksi.gif&quot;,&quot;kaksi.txt&quot;,&quot;kolme.htm&quot; )
</pre></div>

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

<div class="source"><pre>
#include( &quot;terveiset.txt&quot;, $sesonkivarasto )
</pre></div>

 </div>

<a name="parse"></a><div class="section"><h2>Parse</h2>

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

<div class="source"><pre>
#parse( &quot;mina.vm&quot; )
</pre></div>

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

<div class="source"><pre>
Laske alaspäin.
#set( $laskuri = 8 )
#parse( &quot;parsefoo.vm&quot; )
Kaikki valmista: dofoo.vm!
</pre></div>

    <p>
    Koodi viittaisi sivupohjaan <code>parsefoo.vm</code>, jossa
    puolestaan voisi olla seuraavat VTL komennot:
    </p>

<div class="source"><pre>
$laskuri
#set( $laskuri = $laskuri - 1 )
#if( $laskuri &gt; 0 )
    #parse( &quot;parsefoo.vm&quot; )
#else
    Kaikki valmista: parsefoo.vm!
#end
</pre></div>

    <p>
    Kun &quot;Laske alaspäin.&quot; on näytetty, Velocity lataa ja siirtää
    kontrollin sivupohjalle <code>parsefoo.vm</code>, joka laskee alas
    luvusta 8. Kun laskuri saavuttaa arvon 0, tulostetaan &quot;Kaikki
    valmista: parsefoo.vm!&quot;. Tämän jälkeen Velocity palaa sivupohjaan
    <code>dofoo.vm</code> ja tulostaa &quot;Kaikki valmista: dofoo.vm!&quot;
    tekstin.
    </p>

 </div>


<a name="stop"></a><div class="section"><h2>Stop</h2>

    <p>
    <em>#stop</em> elementin avulla sivupohjan suunnittelija voi
    pysäyttää sivun tulkitsemisen. Tämä on hyödyllistä sivupohjan
    virheidenetsinnän aikana.
    </p>

<div class="source"><pre>
#stop
</pre></div>
 </div>

<a name="velocimakrot"></a><div class="section"><h2>Velocimakrot</h2>

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

<div class="source"><pre>
#macro( d )
&lt;tr&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;
#end
</pre></div>

    <p>
    Esimerkissä määriteltiin Velocimakro nimeltään <em>d</em>, ja sitä
    voidaan kutsua muiden VTL ohjeiden tapaan:
    </p>

<div class="source"><pre>
#d()
</pre></div>

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

<div class="source"><pre>
#macro( taulurivit $vari $jokulista )
#foreach( $jotain in $jokulista )
    &lt;tr&gt;&lt;td bgcolor=$vari&gt;$jotain&lt;/td&gt;&lt;/tr&gt;
#end
#end
</pre></div>

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

<div class="source"><pre>
#set( $suuretjarvet = [&quot;Superior&quot;,&quot;Michigan&quot;,&quot;Huron&quot;,&quot;Erie&quot;,&quot;Ontario&quot;] )
#set( $vari = &quot;blue&quot; )
&lt;table&gt;
    #taulurivit( $vari $suuretjarvet )
&lt;/table&gt;
</pre></div>

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

<div class="source"><pre>
&lt;table&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Superior&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Michigan&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Huron&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Erie&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;blue&quot;&gt;Ontario&lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;
</pre></div>

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

<div class="source"><pre>
#set( $osat = [&quot;volva&quot;,&quot;stipe&quot;,&quot;annulus&quot;,&quot;gills&quot;,&quot;pileus&quot;] )
#set( $cellbgcol = &quot;#CC00FF&quot; )
&lt;table&gt;
#tablerows( $cellbgcol $osat )
&lt;/table&gt;
</pre></div>

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

<div class="source"><pre>
&lt;table&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;volva&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;stipe&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;annulus&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;gills&lt;/td&gt;&lt;/tr&gt;
    &lt;tr&gt;&lt;td bgcolor=&quot;#CC00FF&quot;&gt;pileus&lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;
</pre></div>

  <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 &quot;$foo&quot; tai 'hei'
    </li>
    <li>
      Numerovakio : 1, 2 jne
    </li>
    <li>
      Numeroväli : [ 1..2] tai [$foo .. $bar]
    </li>
    <li>
      ObjectArray : [ &quot;a&quot;, &quot;b&quot;, &quot;c&quot;]
    </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>

   <div class="source"><pre>
     #macro( kutsu $a )
         $a $a $a
     #end

     #kutsu( $foo.bar() )
   </pre></div>

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

    <div class="source"><pre>
     #set( $uusiarvo = $foo.bar() )
     #kutsu( $uusiarvo )
   </pre></div>

    <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="../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>
 </div>

<a name="vtl_ohjeiden_suojaaminen"></a><div class="section"><h2>VTL ohjeiden suojaaminen</h2>
  <p>
    VTL ohjeet voidaan suojata kenoviivalla (&quot;\&quot;) samalla tavalla kuin
    VTL viittauksetkin.
  </p>

<div class="source"><pre>
## #include( &quot;a.txt&quot; ) tulostuu &lt;tiedoston a.txt sisältö&gt;
#include( &quot;a.txt&quot; )

## \#include( &quot;a.txt&quot; ) tulostuu #include( &quot;a.txt&quot; )
\#include( &quot;a.txt&quot; )

## \\#include ( &quot;a.txt&quot; ) tulostuu \&lt;tiedoston a.txt sisältö&gt;
\\#include ( &quot;a.txt&quot; )
</pre></div>

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

<div class="source"><pre>
#if( $jazz )
    Vyacheslav Ganelin
#end
</pre></div>

  <p>
  Jos <em>$jazz</em> on tosi (true), tuloste on
  </p>
<div class="source"><pre>
Vyacheslav Ganelin
</pre></div>

  <p>
  Jos <em>$jazz</em> on epätosi (false), tulostetta ei
  tule. Skriptielementtien suojaaminen muuttaa tulostetta. Katso
  seuraavaa esimerkkiä:
  </p>

<div class="source"><pre>
\#if( $jazz )
    Vyacheslav Ganelin
\#end
</pre></div>

  <p>
  Riippumatta siitä onko <em>$jazz</em> tosi vai epätosi, tuloste on
  aina:
  </p>

 <div class="source"><pre>
 #if($ jazz )
     Vyacheslav Ganelin
 #end
 </pre></div>

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

<div class="source"><pre>
\\#if( $jazz )
   Vyacheslav Ganelin
\\#end
</pre></div>

  <p>
  Mikäli <em>$jazz</em> on tässä tapauksessa tosi, tuloste on:
  </p>

<div class="source"><pre>
\ Vyacheslav Ganelin
\
</pre></div>

  <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, tuloste on:
  </p>

<div class="source"><pre>
\
</pre></div>

  <p>
  Huomaa että
  ongelmia tulee mikäli skriptielementtejä ei ole suojattu oikein.
  </p>

<div class="source"><pre>
\\\#if( $jazz )
    Vyacheslave Ganelin
\\#end
</pre></div>

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

 </div>

<a name="vtl:_muotoilu"></a><div class="section"><h2>VTL: Muotoilu</h2>


    <p>
    Vaikka tässä ohjeessa oleva VTL on usein muotoiltu rivivaihdoin ja
    välilyönnein, alla oleva VTL
    </p>

<div class="source"><pre>
#set( $imperial = [&quot;Munetaka&quot;,&quot;Koreyasu&quot;,&quot;Hisakira&quot;,&quot;Morikune&quot;] )
#foreach( $shogun in $imperial )
    $shogun
#end
</pre></div>

    <p>
    on yhtä toimiva kuin seuraava kodinpätkä jonka Geir Magnusson
    Jr. lähetti Velocityn käyttäjien postituslistalle:
    </p>

<div class="source"><pre>
Send me #set($foo = [&quot;$10 and &quot;,&quot;a cake&quot;])#foreach($a in $foo)$a #end please.
</pre></div>

    <p>
    Velocity syö ylimääräiset välilyönnit. Edellinen koodinpätkä
    voitaisiin kirjoittaa seuraavasti:
    </p>

<div class="source"><pre>
Send me
#set( $foo = [&quot;$10 and &quot;,&quot;a cake&quot;] )
#foreach( $a in $foo )
$a
#end
please.
</pre></div>

    <p>
    tai
    </p>

<div class="source"><pre>
Send me
#set($foo       = [&quot;$10 and &quot;,&quot;a cake&quot;])
                 #foreach           ($a in $foo )$a
         #end please.
</pre></div>

    <p>
    Kussakin tapauksessa tulos on sama.
    </p>

</div>

<a name="muita_ominaisuuksia_ja_sekalaista"></a><div class="section"><h2>Muita ominaisuuksia ja sekalaista</h2>

<a name="matematiikka"></a><div class="section"><h3>Matematiikka</h3>

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

<div class="source"><pre>
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
</pre></div>

  <p>
    Jako-operaation tapauksessa tulos on kokonaisluku. Jakojäännös
    saadaan käyttöön jäännösoperandilla (<em>%</em>).
  </p>

<div class="source"><pre>
#set( $foo = $bar % 5 )
</pre></div>


  <p>
    Velocityllä on sisäänrakennettu keino nollalla jakamisen
    käsittelemiseen. Seuraavassa esimerkissä:
  </p>

<div class="source"><pre>
#set( $foo = 5 )
#set( $bar = $foo - 5 )
#set( $uhoh = $foo / $bar )
$uhoh
</pre></div>

  <p>
    Viittaukseen <em>$uhoh</em> asetetaan tulos operaatiosta viisi
    jaettuna nollalla. Kun Velocity näyttää tämän sivupohjan, tuloste
    on:
  </p>

<div class="source"><pre>
$uhoh
</pre></div>

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

<div class="source"><pre>
#set($a = &quot;7&quot;)
#set($b = $int.valueOf($a) + 10)
$b
</pre></div>

  <p>
    Tuloksena on <em>17</em>.
  </p>

  </div>

<a name="vaihteluväli_range_operator"></a><div class="section"><h3>Vaihteluväli (Range Operator)</h3>

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

<div class="source"><pre>
[n..m]
</pre></div>

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

<div class="source"><pre>
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]
</pre></div>

  <p>
    Tuottaa seuraavan tulosteen:
  </p>

<div class="source"><pre>
Ensimmäinen esimerkki:
1 2 3 4 5

Toinen esimerkki:
2 1 0 -1 -2

Kolmas esimerkki:
0 1

Neljäs esimerkki:
[1..3]
</pre></div>

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

  </div>

<a name="edistyneet_kysymykset:_suojaaminen_ja_"></a><div class="section"><h3>Edistyneet kysymykset: Suojaaminen ja !</h3>

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

<div class="source"><pre>
#set( $foo = &quot;bar&quot; )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
</pre></div>

  <p>
   Tulosteena on:
  </p>

<div class="source"><pre>
$!foo
$!{foo}
$\!foo
$\\!foo
</pre></div>

  <p>
   Vertaa tätä normaaliin suojaukseen, jossa <em>\</em> on <em>$</em>
   merkin edellä:
  </p>

<div class="source"><pre>
\$foo
\$!foo
\$!{foo}
\\$!{foo}
</pre></div>

  <p>
    Tulosteena on:
  </p>

<div class="source"><pre>
$foo
$!foo
$!{foo}
\bar
</pre></div>

 </div>

<a name="yleistä_velocimakroista"></a><div class="section"><h3>Yleistä Velocimakroista</h3>

<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(&quot;hello&quot;) )</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ä (&quot;) oleva teksti
tulkitaan. Tämä ansiosta voit tehdä seuraavasti:
</p>

<div class="source"><pre>
#set($stuff = &quot;#bold('hello')&quot; )
#center( $stuff )
</pre></div>

<p>
Voit myös säästää rivin...
</p>

<div class="source"><pre>
#center( &quot;#bold( 'hello' )&quot; )
</pre></div>

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

<div class="source"><pre>

#macro( inner $foo )
  inner : $foo
#end

#macro( outer $foo )
   #set($bar = &quot;outerlala&quot;)
   outer : $foo
#end

#set($bar = 'calltimelala')
#outer( &quot;#inner($bar)&quot; )

</pre></div>

<p>
Tulosteeksi tulee
</p>

<div class="source"><pre>
Outer : inner : outerlala
</pre></div>

<p>
koska parametrin &quot;#inner($bar)&quot; 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>

<div class="source"><pre>
#macro( foo $vari )
  &lt;tr bgcolor=$vari&gt;&lt;td&gt;Hei&lt;/td&gt;&lt;/tr&gt;
  &lt;tr bgcolor=$vari&gt;&lt;td&gt;Siellä&lt;/td&gt;&lt;/tr&gt;
#end

#foo( $bar.rivinVari() )
</pre></div>

<p>
jossa rivinVari() metodia kutsutaan toistuvasti, ei vain kerran. Sen
välttämiseksi kutsu metodia VM:n ulkopuolelta ja siirrä arvo VM:oon.
</p>

<div class="source"><pre>
#set($vari = $bar.rivinVari())
#foo( $vari )
</pre></div>


<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>&lt;type&gt;.resource.loader.cache = false</code>
   </p>

    <p>
    kanssa (jossa &lt;type&gt; 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>

    <div class="source"><pre>
    file.resource.loader.path = templates
    file.resource.loader.cache = false
    velocimacro.library.autoreload = true
    </pre></div>

    <p>
    Älä käytä näitä asetuksia tuotantokäytössä.
    </p>

</div>

<a name="merkkijonojen_yhdistäminen"></a><div class="section"><h3>Merkkijonojen yhdistäminen</h3>

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

   <div class="source"><pre>
       #set( $koko = &quot;Big&quot; )
       #set( $nimi = &quot;Ben&quot; )

      Kello on $iso$nimi.
   </pre></div>

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

   <div class="source"><pre>
      #set( $koko = &quot;Big&quot; )
      #set( $nimi = &quot;Ben&quot; )

      #set($kello = &quot;$koko$nimi&quot; )

      Kello on $kello.
    </pre></div>

    <p>
     Josta tulee sama tuloste. Viimeisenä esimerkkinä, kun haluat
     sekoittaa 'staattisia' merkkijonoja viittauksiin, saatat joutua
     käyttämään 'muodollista viittausten merkintää' :
    </p>

    <div class="source"><pre>
      #set( $koko = &quot;Big&quot; )
      #set( $nimi = &quot;Ben&quot; )

      #set($kello = &quot;${koko}Tall$nimi&quot; )

      Kello on $kello.
    </pre></div>

    <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>
</div>

</div>

<a name="palaute"></a><div class="section"><h2>Palaute</h2>

  <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:user@velocity.apache.org">Velocity
    käyttäjälistalle</a>.  Kiitos!
  </p>

</div>


      </div>
    </div>
    <div class="clear">
      <hr/>
    </div>
    <div id="footer">
      <div class="xright">&#169;  
          2000-2007
    
          The Apache Software Foundation
          
  
             Last Published: 2007-03-06 19:34:54
            </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
  </body>
</html>