Google Git
Sign in
apache / velocity-site / 89c3a15cf30ab2c0dbdf8253ed5c2eb24d9b1e21 / . / engine / 1.6 / translations / user-guide_fi.html
blob: 67e31aa46dde1c7c651e81aa6541c91883974eb3 [file] [log] [blame]
<!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/">Engine</a>
|
<a href="../../../../tools/devel/">Tools</a>
|
<a href="../../../../anakia/devel/">Anakia</a>
|
<a href="../../../../texen/devel/">Texen</a>
|
<a href="../../../../docbook/">DocBook</a>
|
<a href="../../../../dvsl/devel/">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="../glossary.html">Glossary</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</a>
</li>
<li class="none">
<a href="../jira-report.html">Resolved Issues</a>
</li>
<li class="none">
<a href="../upgrading.html">Upgrading</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/trunk/">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>
<iframe src="http://www.apache.org/ads/buttonbar.html"
style="border-width:0; float: left" frameborder="0" scrolling="no"
width="135"
height="265" ></iframe>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<div class="section"><h2><a name="Sisällys"></a>
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>
<div class="section"><h2><a name="Tietoja_tästä_oppaasta"></a>
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>
<div class="section"><h2><a name="Mikä_on_Velocity"></a>
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>
<div class="section"><h2><a name="Miten_voin_käyttää_Velocityä"></a>
Miten voin käyttää Velocityä?</h2>
<div class="section"><h3><a name="Kurakauppa_esimerkki"></a>
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>
<div class="section"><h2><a name="Velocity_Template_Language_VTL:_Johdanto"></a>
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>
<div class="section"><h2><a name="Hei_Velocity_Maailma"></a>
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>
<div class="section"><h2><a name="Kommentit"></a>
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>
<div class="section"><h2><a name="Viittaukset"></a>
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 />
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 />
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 />
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 />
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 />
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>
<div class="section"><h2><a name="Kirjaimellisesti"></a>
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 />
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 />
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>
<div class="section"><h2><a name="Kirjainkoon_muutos"></a>
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>
<div class="section"><h2><a name="Ohjeet"></a>
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>
<div class="section"><h2><a name="If-Else_ehtolauseet"></a>
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>
<div class="section"><h2><a name="Silmukat"></a>
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>
<div class="section"><h2><a name="Include"></a>
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>
<div class="section"><h2><a name="Parse"></a>
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>
<div class="section"><h2><a name="Stop"></a>
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>
<div class="section"><h2><a name="Velocimakrot"></a>
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>
<div class="section"><h2><a name="VTL_ohjeiden_suojaaminen"></a>
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>
<div class="section"><h2><a name="VTL:_Muotoilu"></a>
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>
<div class="section"><h2><a name="Muita_ominaisuuksia_ja_sekalaista"></a>
Muita ominaisuuksia ja sekalaista</h2>
<div class="section"><h3><a name="Matematiikka"></a>
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>
Kun kaksi kokonaislukua jaetaan keskenään, tuloksena on
kokonaisluku, jonka arvo on jakolaskun kokonaisosa.
Jakojäännös voidaan laskea modulo-operaattorilla
(<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>
<div class="section"><h3><a name="Vaihteluväli_Range_Operator"></a>
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>
<div class="section"><h3><a name="Edistyneet_kysymykset:_Suojaaminen_ja_"></a>
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>
<div class="section"><h3><a name="Yleistä_Velocimakroista"></a>
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>
<div class="section"><h3><a name="Merkkijonojen_yhdistäminen"></a>
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>
<div class="section"><h2><a name="Palaute"></a>
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" class="externalLink">Velocity
käyttäjälistalle</a>
. Kiitos!
</p>
</div>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">&#169;
2000-2008
The Apache Software Foundation
Last Published: 2008-12-01 08:05:37
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>