src/content/engine/2.1/translations/user-guide

<!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> > <a href="../../../">Velocity</a> > <a href="../">Velocity Engine</a> </div> <div class="xright"> <a href="../">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 "Kurakauppa Online":ksi. Kauppa käy hyvin. Asiakkaat tilaavat vaihtelevia määriä eri kuratyyppejä. He pääsevät tutkimaan tekemiään tilauksia sekä tekemään uusia ostoja kirjautumalla sivullesi käyttäen käyttäjätunnustaan ja salasanaansa. Tällä hetkellä suosittu Terracotta -kura on alennusmyynnissä. Pieni osa asiakkaistasi ostaa säännöllisesti Kirkkaanpunaista Kuraa, joka myös on alennusmyynnissä, mutta pienemmän suosionsa vuoksi yleensä mainittu sivulla hieman syrjässä. Tiedot kustakin asiakkaasta talletetaan tietokantaan, joten eräänä päivänä herää kysymys; Miksipä emme käyttäisi Velocityä kohdentamaan erikoistarjouksia kurasta asiakkaille jotka ovat kiinnostuneita juuri tuosta kuratyypistä? </p> <p> Velocityn avulla verkkosivut on helppo personoida kävijöidesi mukaan. Kurakauppa Onlinen sivusuunnittelijana haluat tehdä sivun jonka asiakas näkee kirjauduttuaan järjestelmään. </p> <p> Tapaat yrityksesi ohjelmoijat ja sovitte, että muuttuja <em>$asiakas</em> pitää sisällään tiedot parhaillaan kirjautuneena olevasta asiakkaasta. Muuttujassa <em>$kuratTarjouksessa</em> ovat tiedot kuratyypeistä jotka ovat parhaillaan erikoistarjouksessa. <em>$tarjous</em> objektissa on metodeja jotka auttavat mainostamisessa. Tällä kertaa keskitymme vain näihin kolmeen viittaukseen. Muista, että sinun ei tarvitse huolehtia siitä kuinka ohjelmoijat hakevat tarvittavat tiedot tietokannasta, sinun tarvitsee tietää vain että se toimii. Näin pääset tekemään omaa työtäsi ja ohjelmoijat pääsevät tekemään omaansa. </p> <p> Voisit lisätä seuraavat VTL lauseen sivulle: </p> <div class="source"><pre> <HTML> <BODY> Hei $asiakas.Nimi! <table> #foreach( $kura in $kuratTarjouksessa ) #if ( $asiakas.onOstanut($kura) ) <tr> <td> $tarjous.haePromo( $kura ) </td> </tr> #end #end </table> </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 = "Velocity" ) </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 "Velocity". </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> <html> <body> #set( $foo = "Velocity" ) Hei $foo Maailma! </body> <html> </pre> </div> <p> Tuloksena on web sivu jossa lukee "Hei Velocity Maailma!". </p> <p> Jotta VTL lauseet olisivat helpommin luettavissa on suositeltavaa aloittaa jokainen lause uudelta riviltä, vaikkakaan tämä ei ole pakollista. <em>set</em> ohjeeseen palaamme tarkemmin myöhemmin. </p> </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 "$" merkistä, jonka jälkeen tulee VTL <em>tunniste</em>. VTL tunnisteen on alettava aakkosnumeerisella merkillä (a..z tai A..Z). Muuttujan loput merkit ovat rajoitettu seuraaviin: </p> <p><ul><li>aakkoset (a .. z, A .. Z)</li> <li>numerot (0 .. 9)</li> <li>viiva ("-")</li> <li>alaviiva ("_")</li> </ul> </p> <p> Seuraavassa muutamia esimerkkejä toimivista muuttujaviittauksista: </p> <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 = "bar" ) </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 (".") 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 "$" merkistä, jota seuraa VTL tunniste, jonka jälkeen tulee VTL <em>Metodirunko</em>. VTL Metodirunko koostuu VTL tunnisteesta jota seuraa vasen sulkumerkki "(", jota seuraa valinnainen parametrilista, jota seuraa oikeanpuoleinen sulkumerkki ")". Seuraavassa on esimerkkejä toimivista metodiviittauksista: </p> <div class="source"><pre> $asiakas.getOsoite() $ostos.getSumma() $sivu.setOtsake( "Minun kotisivuni" ) $henkilo.setOminaisuudet( ["Outo", "Kummallinen", "Innostunut"] ) </pre> </div> <p> Metodirungossa esiintyvä get tarkoittaa "hae" ja set "aseta". </p> <p> Kaksi ensimmäistä esimerkkiä -- <em>$asiakas.getOsoite()</em> ja <em>$ostos.getSumma()</em> -- näyttävät samanlaisilta kuin Ominaisuudet -osiossa aiemmin; <em>$asiakas.Osoite</em> ja <em>$ostos.Summa</em>. Jos arvasit että näillä esimerkeillä on jotakin yhteyttä toisiinsa, olit oikeassa! </p> <p> VTL ominaisuuksia voidaan käyttää lyhyempinä muotoina VTL metodeista. Ominaisuudella <em>$asiakas.Osoite</em> on täysin sama vaikutus kuin käyttämällä metodia <em>$asikas.getOsoite()</em>. Yleisesti ottaen ominaisuuksien käyttö on suositeltavaa silloin kuin se vain on mahdollista. Suurin ero ominaisuuksien ja metodien välillä on se, että metodeille voi antaa parametreja. </p> <p> Seuraavien metodien kanssa voidaan käyttää lyhyttä muotoa: </p> <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( ["Maa", "Mars", "Neptunus"] ) ## lyhyessä muodossa $sun.Planets ei voida antaa parametreja $sisyphus.pushRock() ## Velocity olettaa että tarkoitan $sisyphus.getRock() $kirja.setOtsake( "Catalonian kotisivu" ) ## Parametrilistaa ei voida antaa </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: "Juha on pyromaani." tai "Juha on kleptomaani.". 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> <input type="text" name="email" value="$email"/> </pre> </div> <p> Kun lomake latautuu ensimmäisen kerran muuttujaviittauksella <em>$email</em> ei ole arvoa. Oletuksena Velocity täyttää lomakkeen tekstillä "$email". Haluaisit kuitenkin kenttään mieluummin tyhjän arvon. Käyttämällä hiljaista viittausten merkintää voidaan Velocityn normaali toiminta estää; <em>$email</em> koodin sijaan käytät viittausta <em>$!email</em>. Yllä oleva koodi näyttäisi siis seuraavalta: </p> <div class="source"><pre> <input type="text" name="email" value="$!email"/> </pre> </div> <p> Kun lomake latautuu ensimmäisen kerran eikä muuttujalla <em>$email</em> ole arvoa, tulostetaankin kenttään tyhjä teksti "$email" tekstin sijaan. </p> <p> Muodollista ja hiljaista muuttujien merkintää voidaan käyttää myös yhdessä; </p> <div class="source"><pre> <input type="text" name="email" value="$!{email}"/> </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: "Ostin markkinoilta säkin perunoita hintaan $2.50!". Kuten mainittu, VTL tunniste alkaa aina aakkosmerkillä, joten merkintää $2.50 ei ole vaaraa sekoittaa viittaukseksi. </p> <p><a name="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 = "foo" ) $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 = "foo" ) $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 = "gibbous" ) $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("juha") ## on sama kuin #set( $data.Kayttaja = "juha" ) $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 = "apina" ) #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 = "monica" ) ## tekstivakio #set( $apina.Syytos = $valkoinentalo.vuoto ) ## ominaisuusviittaus #set( $apina.Suunnitelma = $spindoctor.weave($web) ) ## metodiviittaus #set( $apina.Numero = 123 ) ## numeerinen vakio #set( $apina.Sano = ["Ei", $minun, "vikani"] ) ## taulukko </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("nimi") ) Ensimmäisen kyselyn tulos on $tulos #set( $tulos = $kysely.kriteeri("osoite") ) Toisen kyselyn tulos on $tulos </pre> </div> <p> Jos <em>$kysely.kriteeri("nimi")</em> palauttaa merkkijonon "pete", ja <em>$kysely.kriteeri("osoite")</em> palauttaa arvon <em>null</em>, on esimerkin tuloste seuraava: </p> <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 = ["nimi", "osoite"] ) #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 = ["nimi", "osoite"] ) #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 (" ") suljettu teksti tulkitaan ja tulostetaan kuten seuraavasta esimerkistä käy ilmi: </p> <div class="source"><pre> #set( $hakemistoJuuri = "www" ) #set( $sivupohjaNimi = "index.vm" ) #set( $sivupohja = "$hakemistoJuuri/$sivupohjaNimi" ) $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 = "bar" ) $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 ) <strong>Velocity!</strong> #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: "Velocity!". Toisaalta, mikäli <em>$foo</em> on epätosi, on myös ehtolause epätosi eikä tulostetta tule. </p> <p><em>#elseif</em> tai <em>#else</em> elementtejä voidaan käyttää <em>#if</em> elementin kanssa. Huomaa, että Velocityn sivumoottori lopettaa ensimmäisen tosiarvon saaneen testimuuttujan kohdalla. Oletetaan seuraavassa esimerkissä että muuttujalla <em>$foo</em> on arvo 15 ja muuttujalla <em>$bar</em> on arvo 6. </p> <div class="source"><pre> #if( $foo < 10 ) <strong>Mene pohjoiseen</strong> #elseif( $foo == 10 ) <strong>Mene itään</strong> #elseif( $bar == 6 ) <strong>Mene etelään</strong> #else <strong>Mene länteen</strong> #end </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 = "deoksiribonukleiinihappo") #set ($bar = "ribonukleiinihappo") #if ($foo == $bar) Muuttujat eivät selvästikään ole samanlaiset. Joten... #else Vastaavuusvertaus on epätosi, ja tämä teksti tulee tulosteeksi. #end </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 && $bar ) <strong> Tämä JA tuo</strong> #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 ) <strong>Tämä TAI tuo</strong> #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 ) <strong>EI tuota</strong> #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> <ul> #foreach( $tuote in $kaikkiTuotteet ) <li>$tuote</li> #end </ul> </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> <ul> #foreach( $avain in $kaikkiTuotteet.keySet() ) <li>Avain: $avain -> Arvo: $kaikkiTuotteet.get($avain)</li> #end </ul> </pre> </div> <p> Velocityllä on helppo keino silmukkalaskurin käyttämiseen. Voit käyttää laskuria esimerkiksi seuraavasti: </p> <div class="source"><pre> <table> #foreach( $asiakas in $asiakasLista ) <tr><td>$foreach.count</td><td>$asiakas.Nimi</td></tr> #end </table> </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( "yksi.txt" ) </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( "yksi.gif","kaksi.txt","kolme.htm" ) </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( "terveiset.txt", $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( "mina.vm" ) </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( "parsefoo.vm" ) 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 > 0 ) #parse( "parsefoo.vm" ) #else Kaikki valmista: parsefoo.vm! #end </pre> </div> <p> Kun "Laske alaspäin." on näytetty, Velocity lataa ja siirtää kontrollin sivupohjalle <code>parsefoo.vm</code>, joka laskee alas luvusta 8. Kun laskuri saavuttaa arvon 0, tulostetaan "Kaikki valmista: parsefoo.vm!". Tämän jälkeen Velocity palaa sivupohjaan <code>dofoo.vm</code> ja tulostaa "Kaikki valmista: dofoo.vm!" tekstin. </p> </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 ) <tr><td></td></tr> #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 ) <tr><td bgcolor=$vari>$jotain</td></tr> #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 = ["Superior","Michigan","Huron","Erie","Ontario"] ) #set( $vari = "blue" ) <table> #taulurivit( $vari $suuretjarvet ) </table> </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> <table> <tr><td bgcolor="blue">Superior</td></tr> <tr><td bgcolor="blue">Michigan</td></tr> <tr><td bgcolor="blue">Huron</td></tr> <tr><td bgcolor="blue">Erie</td></tr> <tr><td bgcolor="blue">Ontario</td></tr> </table> </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 = ["volva","stipe","annulus","gills","pileus"] ) #set( $cellbgcol = "#CC00FF" ) <table> #tablerows( $cellbgcol $osat ) </table> </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> <table> <tr><td bgcolor="#CC00FF">volva</td></tr> <tr><td bgcolor="#CC00FF">stipe</td></tr> <tr><td bgcolor="#CC00FF">annulus</td></tr> <tr><td bgcolor="#CC00FF">gills</td></tr> <tr><td bgcolor="#CC00FF">pileus</td></tr> </table> </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 "$foo" tai 'hei' </li> <li> Numerovakio : 1, 2 jne </li> <li> Numeroväli : [ 1..2] tai [$foo .. $bar] </li> <li> ObjectArray : [ "a", "b", "c"] </li> <li> boolean arvo true (tosi) </li> <li> boolean arvo false (epätosi) </li> </ul> <p> Kun siirrät viittauksia argumentteina Velocimakroille, huomaa, että viittaukset siirretään 'nimen mukaan' ('by name'). Tämä tarkoittaa sitä, että viittausten arvo 'haetaan' Velocimakrossa itsessään. Tämän ominaisuuden avulla voit siirtää viittauksia jotka ovat metodikutsuja, ja näin ko. metodeja kutsutaan Velocimakrossa. Esimerkiksi kun Velocimakroa kutsutaan seuraavasti: </p> <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.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 ("\") samalla tavalla kuin VTL viittauksetkin. </p> <div class="source"><pre> ## #include( "a.txt" ) tulostuu <tiedoston a.txt sisältö> #include( "a.txt" ) ## \#include( "a.txt" ) tulostuu #include( "a.txt" ) \#include( "a.txt" ) ## \\#include ( "a.txt" ) tulostuu \<tiedoston a.txt sisältö> \\#include ( "a.txt" ) </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 = ["Munetaka","Koreyasu","Hisakira","Morikune"] ) #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 = ["$10 and ","a cake"])#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 = ["$10 and ","a cake"] ) #foreach( $a in $foo ) $a #end please. </pre> </div> <p> tai </p> <div class="source"><pre> Send me #set($foo = ["$10 and ","a cake"]) #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 = "7") #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 = "bar" ) $\!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("hello") )</code></p> <p> Et. Ohje ei ole sallittu argumentti ohjeelle, ja VM on käytännöllisesti katsoen ohje. </p> <p><i>Kuitenkin...</i>, voit kiertää rajoituksen. Yksinkertainen ratkaisu on käyttää hyväksi sitä että lainausmerkeissä (") oleva teksti tulkitaan. Tämä ansiosta voit tehdä seuraavasti: </p> <div class="source"><pre> #set($stuff = "#bold('hello')" ) #center( $stuff ) </pre> </div> <p> Voit myös säästää rivin... </p> <div class="source"><pre> #center( "#bold( 'hello' )" ) </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 = "outerlala") outer : $foo #end #set($bar = 'calltimelala') #outer( "#inner($bar)" ) </pre> </div> <p> Tulosteeksi tulee </p> <div class="source"><pre> Outer : inner : outerlala </pre> </div> <p> koska parametrin "#inner($bar)" tulkitseminen tapahtuu lauseen #outer() sisällä, käytetään muuttujan $bar arvoa joka asetettiin #outer VM:ssa. </p> <p> Tämä on tarkoituksellinen ja tarkkaan vaalittu ominaisuus - parametrit siirretään 'nimen mukaan' ('by name') VM:oon, jotta voit siirtää VM:oon tilansa muistavia (stateful) viittauksia kuten </p> <div class="source"><pre> #macro( foo $vari ) <tr bgcolor=$vari><td>Hei</td></tr> <tr bgcolor=$vari><td>Siellä</td></tr> #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><type>.resource.loader.cache = false</code></p> <p> kanssa (jossa <type> on resurssilataajan nimi jota käytät, kuten 'file'), silloin Velocity lataa automaattisesti Velocitymakroihin tekemäsi muutokset silloin kun teet niitä, joten sinun ei tarvitse käynnistää uudelleen sovellusalustaa (tai ohjelmaa) tai turvautua johonkin muuhun kikkaan saadaksesi muuttuneet Velocitymakrosi käyttöön. </p> <p> Yksinkertainen konfiguraatio saattaisi näyttää seuraavalta: </p> <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 = "Big" ) #set( $nimi = "Ben" ) 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 = "Big" ) #set( $nimi = "Ben" ) #set($kello = "$koko$nimi" ) 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 = "Big" ) #set( $nimi = "Ben" ) #set($kello = "${koko}Tall$nimi" ) 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">© 2000-2010 The Apache Software Foundation Last Published: 2010-11-29 23:49:22 </div> <div class="clear"> <hr/> </div> </div> </body> </html>

src/content/engine/2.1/translations/user-guide_fi.html (2,106 lines of code) (raw):