You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ge...@apache.org on 2002/06/17 11:18:05 UTC
cvs commit: jakarta-velocity/xdocs user-guide_fr.xml
geirm 2002/06/17 02:18:04
Added: xdocs user-guide_fr.xml
Log:
contribution from Jean-Francois El Fouly <je...@wanadoo.fr>
Revision Changes Path
1.1 jakarta-velocity/xdocs/user-guide_fr.xml
Index: user-guide_fr.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<properties>
<title>Guide de l'utilisateur Velocity</title>
<author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
<author email="jcastura@kw.igs.net">John Castura</author>
<author email="jean-francois.elfouly@wanadoo.fr">Jean-Fran�ois El Fouly</author>
</properties>
<body>
<section name="Table des Mati�res">
<ol>
<li><a href="#A propos de ce document">A propos de ce document</a></li>
<li><a href="#Velocity, qu'est-ce que c'est?">Velocity, qu'est-ce que c'est?</a></li>
<li><a href="#Qu'est-ce que Velocity peut faire pour moi?">Qu'est-ce que Velocity peut faire pour moi?</a>
<ol>
<li><a href="#L'exemple de MudStore">L'exemple de MudStore</a></li>
</ol>
</li>
<li><a href="#Introduction au Velocity Template Language (VTL)">Introduction au Velocity Template Language (VTL)</a></li>
<li><a href="#Hello Velocity World!">Hello Velocity World!</a></li>
<li><a href="#Les commentaires">Les commentaires</a></li>
<li><a href="#Les r�f�rences">Les r�f�rences</a>
<ol>
<li><a href="#Variables">Variables</a></li>
<li><a href="#Propri�t�s">Propri�t�s</a></li>
<li><a href="#M�thodes">M�thodes</a></li>
</ol>
</li>
<li><a href="#Notation formelle des r�f�rences">Notation formelle des r�f�rences</a></li>
<li><a href="#Notation silencieuse des r�f�rences">Notation silencieuse des r�f�rences</a></li>
<li><a href="#Sortie litt�rale">Sortie litt�rale</a>
<ol>
<li><a href="#Devise">Devise</a></li>
<li><a href="#Echapper des r�f�rences VTL valides">Echapper des r�f�rences VTL valides</a></li>
</ol>
</li>
<li><a href="#Substitution de cas">Substitution de cas</a></li>
<li><a href="#Directives">Directives</a>
<ol>
<li><a href="#Set">Set</a></li>
<li><a href="#Cha�nes de caract�res litt�rales">Cha�nes de caract�res litt�rales</a></li>
<li><a href="#Conditions">Conditions</a>
<ol>
<li><a href="#Op�rateurs relationnels et logiques">Op�rateurs relationnels et logiques</a></li>
</ol>
</li>
<li><a href="#Boucles">Boucles</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="#Velocimacros">Velocimacros</a></li>
</ol>
</li>
<li><a href="#Echappement des directives VTL">Echappement des directives VTL</a></li>
<li><a href="#VTL: Questions de format">VTL: Questions de format</a></li>
<li><a href="#Autres caract�ristiques et sujets divers">Autres caract�ristiques et sujets divers</a>
<ol>
<li><a href="#Math">Math</a></li>
<li><a href="#Op�rateur de port�e (range)">Op�rateur de port�e (range)</a></li>
<li><a href="#Questions pointues: Echappement et !">Questions pointues: Echappement et !</a></li>
<li><a href="#Compl�ments divers sur les Velocimacros">Compl�ments divers sur les Velocimacros</a></li>
<li><a href="#Concat�nation de cha�nes">Concat�nation de cha�nes</a></li>
</ol>
</li>
<li><a href="#Donnez votre avis">Donnez votre avis</a></li>
</ol>
</section>
<section name="A propos de ce document">
<p>
Le Guide de l'utilisateur Velocity a pour but d'aider les concepteurs de page et les fournisseurs de contenu � se
familiariser avec Velocity et avec la syntaxe de son langage de script, simple mais puissant, le Velocity Template
Language (VTL). Beaucoup d'exemples dans ce guide concernent l'utilisation de Velocity pour l'inclusion de contenu
dynamique dans des sites web, mais tous les exemples du VTL pourraient aussi bien s'appliquer � d'autres pages ou
gabarits.
</p>
<p>Merci de choisir Velocity!</p>
</section>
<section name="Velocity, qu'est-ce que c'est?">
<p>
Velocity est un moteur de substitution, bas� sur Java. Il permet aux concepteurs de pages web de faire r�f�rence
� des m�thodes d�finies dans du code Java. Les concepteurs de pages peuvent travailler en �quipe avec des
programmeurs Java pour d�velopper des sites web dans l'architecture MVC (Mod�le-Vue-Contr�leur), ce qui signifie
que les infographistes peuvent se concentrer sur la cr�ation d'un site au d�sign attractif et les programmeurs
peuvent se consacrer enti�rement � l'�criture de code de qualit�. Velocity s�pare le code Java des pages web,
ce qui rend le site plus facile � maintenir dans le long terme et fournit une alternative r�aliste aux
<a href="http://java.sun.com/products/jsp/">Java Server Pages</a> (JSPs) ou �
<a href="http://www.php.net/">PHP</a>.
</p>
<p>
Velocity peut �tre utilis� pour g�n�rer des pages web, du SQL, du Postcript et tout ce qui peut �tre g�n�r� � partir
d'un gabarit. Vous pouvez l'utiliser comme un utilitaire ind�pendant pour g�n�rer du code source ou des �tats
imprim�s, ou bien comme un composant int�gr� dans d'autres syst�mes. A terme, Velocity fournira les services
d'inclusion pour le framework d'applications web <a href="http://java.apache.org/turbine/">Turbine</a>.
Velocity et Turbine fournissent un service d'inclusion qui permettra de d�velopper des applications web dans une
v�ritable architecture MVC.
</p>
</section>
<section name="Qu'est-ce que Velocity peut faire pour moi?">
<subsection name="L'exemple de MudStore">
<p>Supposons que vous soyez un concepteur de pages pour une boutique en ligne sp�cialis�e dans la vente de terre cuite. Appelons-la "The Online Mud Store". Les affaires marchent fort. Les clients passent commande pour diff�rents types et diverses quantit�s de terre cuite. Ils s'identifient sur votre site avec un nom d'utilisateur et un mot de passe, ce qui leur permet de suivre leurs commandes et d'en passer de nouvelles. Pour l'instant, vous vendez de la glaise Terracotta, un produit qui marche bien. Quelques-uns de vos clients ach�tent r�guli�rement de la glaise Bright Red, que vous vendez aussi, bien s�r, mais qui n'a pas autant la cote et qui se trouve d'habitude rel�gu�e dans les marges de vos pages. Les informations relatives � chaque client sont suivies dans votre base de donn�es, et donc un jour la question se pose: pourquoi ne pas utiliser Velocity pour proposer des offres sp�ciales � une client�le cibl�e, celle qui est la plus int�ress�e � un type de marchandise?</p>
<p>Avec Velocity, il est tr�s facile de personnaliser les pages web pour certains visiteurs. En tant que concepteur de pages du MudRoom, vous voulez maintenant r�aliser la page d'accueil que verra votre client apr�s s'�tre identifi� sur votre site. </p>
<p>Vous tenez une r�union avec les ing�nieurs d�veloppement de votre entreprise, et tout le monde s'accorde sur le fait que <em>$customer</em> contiendra les informations relatives au client qui s'est connect� et <em>$mudsOnSpecial</em> tous les types de terre disponibles � la vente en ce moment. L'objet <em>$flogger</em> contient diff�rentes m�thodes pour aider � la promotion de certains produits. Pour la t�che qui nous concerne, occupons-nous seulement de ces trois r�f�rences. Rappelez-vous que vous n'avez pas � vous soucier de la mani�re dont les d�veloppeurs vont extraire les informations n�cessaires de la base de donn�es, vous supposez seulement que �a fonctionne -- ce qui vous permet de vous occuper de votre part du boulot et les d�veloppeurs de la leur.</p>
<p>Vous pouvez inclure l'instruction VTL suivante dans votre page web:</p>
<source><![CDATA[
<HTML>
<BODY>
Hello $customer.Name!
<table>
#foreach( $mud in $mudsOnSpecial )
#if ( $customer.hasPurchased($mud) )
<tr>
<td>
$flogger.getPromo( $mud )
</td>
</tr>
#end
#end
</table>
]]>
</source>
<p>Les d�tails pr�cis de l'instruction <em>foreach</em> seront d�crits un peu plus loin; ce qui compte pour l'instant, c'est l'impact que peut avoir ce petit script sur votre site web. Quand un client qui appr�cie habituellement la glaise BrightRed se connecte, et que ce produit est en vente, c'est ce qu'il verra en premier lieu. Si un client qui a achet� beaucoup de Terracotta se connecte, c'est la vente de Terracotta qui sera affich�e en t�te et au centre. La flexibilit� de Velocity est tr�s grande, limit�e seulement par votre cr�ativit�.</p>
<p>Dans le manuel de r�f�rence du VTL, vous trouverez la documentation de beaucoup d'autres �l�ments de Velocity, qui ensemble vous donnent la puissance et la souplesse dont vous avez besoin pour faire de votre site web une <em>pr�sence</em> sur le web. Lorsque vous deviendrez de plus en plus familiers avec ces �l�ments, vous mettrez � votre service toute la puissance de Velocity.</p>
</subsection>
</section>
<section name="Introduction au Velocity Template Language (VTL)">
<p>Le Velocity Template Language (VTL) a �t� con�u pour inclure du contenu dynamique dans une page web de la mani�re la plus facile, la plus simple et la plus propre. M�me un infographiste avec peu ou pas de bagage en programmation sera rapidement capable d'utiliser le VTL pour incorporer du contenu dynamique dans un site web.</p>
<p>VTL utilise des <em>r�f�rences</em> pour embarquer du contenu dynamique dans un site web, et une variable est un type de r�f�rence. Une variable fait r�f�rence � quelque chose qui est d�fini dans le code Java, ou elle peut prendre sa valeur d'une <em>instruction</em> VTL dans la page web. Voici un exemple d'instruction VTL</p>
<source><![CDATA[
#set( $a = "Velocity" )
]]></source>
<p>
Cette instruction VTL -- comme toutes les instructions VTL d'ailleurs -- commence par le caract�re <em>#</em> et
contient une directive <em>set</em>. Quand un visiteur demande votre page web, le moteur de substitution Velocity
(Velocity Templating Engine) recherche dans votre page tous les caract�res <em>#</em>, d�termine lesquels marquent le
d�but d'instructions VTL, et quels caract�res <em>#</em> n'ont rien � voir avec le VTL.
</p>
<p>
Le caract�re <em>#</em>est suivi d'une directive, <em>set</em>. La directive <em>set</em>utilise une expression
(entre parenth�ses) -- une �quation qui assigne une <em>valeur</em>� une <em>variable</em>. La variable est �crite
� gauche et sa valeur � droite; les deux sont s�par�s par un caract�re <em>=</em>.
</p>
<p>
Dans l'exemple ci-dessus, la variable est <em>$a</em>et la valeur est <em>Velocity</em>. Cette variable, comme toutes
les r�f�rences, commence par le caract�re <em>$</em>. Les valeurs sont toujours entour�es d'apostrophes;
dans Velocity, il n'y a jamais de confusion possible entre les types de donn�es puisque seules des cha�nes de
caract�res (informations de type texte) peuvent �tre pass�es � des variables.
</p>
<p>
Le truc suivant peut �tre utile pour mieux comprendre comment Velocity fonctionne :<strong>Les r�f�rences commencent
par <em>$</em> et sont utilis�es pour r�cup�rer quelque chose. Les directives commencent par <em>#</em>et sont
utilis�es pour faire quelque chose.</strong>
</p>
<p>
Dans l'exemple ci-dessus, <em>#set</em>est utilis� pour assigner une valeur � une variable. La variable, <em>$a</em>,
peut alors �tre utilis�e dans le gabarit pour produire "Velocity".
</p>
</section>
<section name="Hello Velocity World!">
<p>
Une fois qu'une valeur a �t� assign�e � une variable, vous pouvez faire r�f�rence � cette variable n'importe o� dans
votre document HTML. Dans l'exemple suivant, une valeur est assign�e � <em>$foo</em> et r�f�renc�e plus loin.
</p>
<source><![CDATA[
<html>
<body>
#set( $foo = "Velocity" )
Hello $foo World!
</body>
</html>
]]></source>
<p>Le r�sultat est une page web o� s'imprime "Hello Velocity World!".</p>
<p>
Pour rendre les instructions contenant des directives VTL plus lisibles, nous vous encourageons � d�buter chaque
instruction VTL sur une nouvelle ligne -- mais vous n'�tes pas oblig� de proc�der ainsi. La directive <em>set</em>
sera revue avec davantage de d�tails plus loin.
</p>
</section>
<section name="Les commentaires">
<p>
Les commentaires permettent d'inclure du texte descriptif qui ne sera pas report� dans la sortie du moteur
d'inclusion. Les commentaires sont une mani�re utile de se rappeler et d'expliquer � d'autres ce que font les
instructions VTL, ou � toute autre fin utile. Voici un exemple de commentaire en VTL.
</p>
<source><![CDATA[
## Ceci est un commentaire d'une seule ligne.
]]></source>
<p>
Un commentaire d'une ligne commence par <em>##</em> et se termine � la fin de la ligne. Si vous voulez �crire
quelques lignes de commentaires, pas besoin de multiplier ces commentaires d'une ligne. Les commentaires multi-lignes,
qui commencent par <em>#*</em> et se terminent par <em>*#</em>, sont l� pour ce cas de figure.
</p>
<source><![CDATA[
Ceci est du texte � l'ext�rieur du commentaire multi-lignes. Les visiteurs du site peuvent le voir.
#*
Ici commence donc un commentaire de plusieurs lignes.
Les visiteurs du site ne le verront pas, parce que le
moteur de substitution de Velocity
(Velocity Templating Engine) l'ignore.
*#
Ce texte-ci est � l'ext�rieur du commentaire: il est visible.
]]></source>
<p>Voici quelques exemples pour clarifier la mani�re dont les commentaires d'une et plusieurs lignes fonctionnent:</p>
<source><![CDATA[
Ce texte est visible. ## Ce texte ne l'est pas.
Ce texte est visible.
Ce texte est visible. #* Ce texte, qui fait partie d'un commentaire
de plusieurs lignes, n'est pas visible. Ce texte n'est pas visible;
il faut aussi partie du commentaire multi-lignes.
Ce texte n'est toujours pas visible. *# Ce texte est � l'ext�rieur
du commentaire, il est donc visible.
## Ce texte n'est pas visible.
]]></source>
<p>
Il y a un troisi�me type de commentaires, le bloc de commentaires VTL, que vous pouvez utiliser pour �crire des
informations telles que l'auteur du document ou la version.
</p>
<source><![CDATA[
#**
Ceci est un bloc de commentaires VTL, qui
peut �tre utilis� pour inscrire des informations
telles que l'auteur ou la version du document.
@author
@version 5
*#
]]></source>
</section>
<section name="Les r�f�rences">
<p>
Il y a trois types de r�f�rences en VTL: les variables, les propri�t�s et les m�thodes. En tant que concepteur
utilisant le VTL, vous et vos ing�nieurs devez vous mettre d'accord sur les noms des r�f�rences, de mani�re � pouvoir
les utiliser correctement dans vos gabarits de pages.
</p>
<p>
Tout ce qui entre et sort d'une r�f�rence est trait� comme un objet cha�ne de caract�res. S'il y a un objet qui
repr�sente <em>$foo</em>(un objet Integer par exemple), Velocity appellera sa m�thode <code>.toString()</code>
pour convertir l'objet en String.
</p>
<p>
<a name="Variables"><strong>Variables</strong></a>
<br/>
La notation abr�g�e pour une variable consiste en un caract�re "$" initial suivi d'un <em>Identificateur</em>VTL.
Un identificateur VTL doit commencer par une lettre (a .. z ou A .. Z). Le reste des caract�res est limit� aux types
suivants:
</p>
<p>
<ul>
<li>lettre (a .. z, A .. Z)</li>
<li>chiffre (0 .. 9)</li>
<li>tiret ("-")</li>
<li>trait de soulignement ("_")</li>
</ul>
</p>
<p>Voici quelques exemples de r�f�rences valides en VTL: </p>
<source><![CDATA[
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
]]></source>
<p>
Lorsque VTL r�f�rence une variable, telle que <em>$foo</em>, la variable peut prendre sa valeur soit d'une directive
<em>set</em> dans le gabarit, soit d'un programme Java. Par exemple, si la variable Java <em>$foo</em> a la valeur
<em>bar</em> � la ligne � laquelle il est fait appel au gabarit, <em>bar</em> remplace toutes les instances de
<em>$foo</em> dans la page web. Autrement, si j'inclus l'instruction
</p>
<source><![CDATA[
#set( $foo = "bar" )
]]></source>
<p>la sortie sera la m�me pour toutes les instances de <em>$foo</em> qui suivent cette directive.</p>
<p>
<a name="Propri�t�s"><strong>Propri�t�s</strong></a>
<br/>Les propri�t�s sont la seconde esp�ce de r�f�rences en VTL et elles ont un format qui les distingue.
La notation abr�g�e consiste en un caract�re <em>$</em> initial suivi d'un identifiant VTL, suivi d'un point (".")
et d'un autre identifiant VTL. Quelques exemples de r�f�rences valides de propri�t�s en VTL:
</p>
<source><![CDATA[
$customer.Address
$purchase.Total
]]></source>
<p>
Prenons le premier exemple, <em>$customer.Address</em>. Cette expression peut avoir deux significations.
Elle peut signifier: "Regarde dans la table de hachage identifi�e par <em>customer</em> et renvoie la valeur associ�e
� la cl� <em>Address</em>. Mais <em>$customer.Address</em> peut aussi faire r�f�rence � une m�thode (les r�f�rences
qui d�signent des m�thodes seront discut�es dans la section suivante); <em>$customer.Address</em> pourrait �tre
une mani�re abr�g�e d'�crire <em>$customer.getAddress()</em>. Quand quelqu'un demande votre page, Velocity va
d�terminer laquelle de ces deux possibilit�s a un sens, et retournera la valeur appropri�e.
</p>
<p>
<a name="M�thodes"><strong>M�thodes</strong></a>
<br/>Une m�thode est d�finie dans le code Java et peut faire quelque chose d'utile, comme effectuer un calcul ou
prendre une d�cision. Les m�thodes sont des r�f�rences qui consistent en un caract�re "$" initial, suivi d'un
identifiant VTL, suivi d'un <em>corps de m�thode</em>. Un corps de m�thode VTL consiste en un identifiant VTL
suivi du caract�re parenth�se ouvrante ("("), �ventuellement suivi d'une liste de param�tres, suivi du caract�re
parenth�se fermante (")"). Quelques exemples de r�f�rences de m�thodes valides en VTL:
</p>
<source><![CDATA[
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
]]></source>
<p>
Les deux premiers exemples -- <em>$customer.getAddress()</em> et
<em>$purchase.getTotal()</em> -- peuvent avoir l'air semblables � ceux utilis�s dans la section pr�c�dente,
consacr�e aux Propri�t�s, <em>$customer.Address</em> et
<em>$purchase.Total</em>. Si vous avez devin� que ces exemples sont li�s entre eux d'une mani�re ou d'une autre,
vous avez raison!
</p>
<p>
Les propri�t�s VTL peuvent �tre utilis�es comme une notation abr�g�e pour des m�thodes VTL.
La propri�t� <em>$customer.Address</em> a exactement le m�me effet que l'utilisation de la m�thode
<em>$customer.getAddress()</em>. Il est g�n�ralement pr�f�rable d'utiliser une propri�t� lorsqu'il y en a une
de disponible. La principale diff�rence entre les Propri�t�s et les M�thodes est que pour les m�thodes, on peut
sp�cifier une liste de param�tres.
</p>
<p>La notation abr�g�e peut �tre utilis�e pour les m�thodes suivantes</p>
<source><![CDATA[
$sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()
]]></source>
<p>
On s'attend logiquement � ce que ces m�thodes retournent les noms des plan�tes qui tournent autour du soleil,
qu'elles nourissent notre ver de terre ou prennent une photo dans un album. Il n'y a que la notation longue
qui fonctionne pour les m�thodes suivantes:
</p>
<source><![CDATA[
$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## On ne peut pas passer une liste de param�tres avec $sun.Planets
$sisyphus.pushRock()
## Velocity suppose que je veux dire $sisyphus.getRock()
$book.setTitle( "Homage to Catalonia" )
## On ne peut pas passer une liste de param�tres
]]></source>
<p>
<a name="Notation formelle des r�f�rences"><strong>Notation formelle des r�f�rences</strong></a>
<br/>Dans les exemples ci-dessus, nous avons utilis� la notation abr�g�e pour les r�f�rences, mais il y a aussi
une notation formelle pour les r�f�rences, illustr�e ci-dessous:
</p>
<source><![CDATA[
${mudSlinger}
${customer.Address}
${purchase.getTotal()}
]]></source>
<p>
Dans presque tous les cas, vous utiliserez pour les r�f�rences la notation abr�g�e, mais dans certains cas
la notation formelle est requise pour une ex�cution correcte.
</p>
<p>
Supposons que vous soyez en train de construire dynamiquement une phrase dans laquelle <em>$vice</em> doit �tre
utilis� comme base pour la construction d'un nom de la phrase. Le but est de permettre � quelqu'un de choisir le mot
de base et de produire l'un des deux r�sultats suivants:
"Jacques est pyromane" ou "Jacques est cleptomane".
L'utilisation de la notation abr�g�e ne convient pas pour cette t�che. Consid�rons en effet l'exemple suivant:
</p>
<source><![CDATA[
Jacques est un $vicemane.
]]></source>
<p>
La syntaxe est ici ambigu�, et Velocity suppose que <em>$vicemane</em>, et non <em>$vice</em>, est l'identifiant
que vous pensiez utiliser. Ne trouvant pas de valeur pour <em>$vicemane</em>, il renverra <em>$vicemane</em>.
L'utilisation de la notation formelle peut r�soudre ce probl�me.
</p>
<source><![CDATA[
Jacques est un ${vice}mane.
]]></source>
<p>
Cette fois Velocity sait que <em>$vice</em>, et non <em>$vicemane</em>, est la r�f�rence. La notation formelle est
souvent utile quand les r�f�rences sont directement adjacentes � du texte au sein d'un gabarit.
</p>
<p>
<a name="Notation silencieuse des r�f�rences"><strong>Notation silencieuse des r�f�rences</strong></a>
<br/>Lorsque Velocity rencontre une r�f�rence non d�finie, son comportement normal est de produire une image de la
r�f�rence. Par exemple, supposons que la r�f�rence suivante apparaisse dans un gabarit VTL:
</p>
<source><![CDATA[
<input type="text" name="email" value="$email"/>
]]></source>
<p>
Quand le formulaire est charg� pour la premi�re fois, la variable r�f�renc�e par <em>$email</em> n'a pas de valeur,
mais vous pr�f�reriez un champ de texte vide � la valeur "$email". L'utilisation de la notation silencieuse contourne
le comportement normal de Velocity; au lieu d'utiliser <em>$email</em> dans le code VTL, utilisez <em>$!email</em>.
L'exemple pr�c�dent ressemblerait donc � ceci:
</p>
<source><![CDATA[
<input type="text" name="email" value="$!email"/>
]]></source>
<p>
A pr�sent, quand le formulaire est charg� pour la premi�re fois et que <em>$email</em> n'a toujours pas de valeur,
une cha�ne vide sera produite au lieu de "$email".
</p>
<p>La notation formelle et la notation silencieuse peuvent �tre utilis�es ensemble, comme illustr� ci-dessous.</p>
<source><![CDATA[
<input type="text" name="email" value="$!{email}"/>
]]></source>
</section>
<section name="Sortie litt�rale">
<p>
VTL utilise des caract�res sp�ciaux, comme <em>$</em> et <em>#</em> pour accomplir sa t�che; il faut donc prendre
quelques pr�cautions pour utiliser ces caract�res dans vos gabarits. Cette section est consacr�e � l'�chappement
du caract�re <em>$</em>.
</p>
<p>
<a name="Devise"><strong>Devise</strong></a>
<br/>Il n'y a pas de probl�me particulier � �crire "J'ai achet� un sac de 2 kg de patates au march� de la ferme
pour seulement $2.50!". Comme dit plus haut, un identifiant VTL commence toujours par une lettre, majuscule ou
minuscule, et donc $2.50 ne serait pas pris par erreur pour une r�f�rence.
</p>
<p>
<a name="Echapper des r�f�rences VTL valides"><strong>Echapper des r�f�rences VTL valides</strong></a>
<br/>Il peut se produire dans certains cas que Velocity se trouve induit en confusion. <em>Echapper</em> les
caract�res sp�ciaux est le meilleur moyen de traiter les caract�res sp�ciaux du VTL dans vos gabarits, et ceci se
fait en utilisant le caract�re backslash (<em>\</em>).
</p>
<source><![CDATA[
#set( $email = "foo" )
$email
]]></source>
<p>
Lorsque Velocity rencontre une r�f�rence � <em>$email</em> dans votre gabarit VTL, il cherche dans le contexte la
valeur correspondante. Ici, la sortie sera <em>foo</em>, parce que <em>$email</em> est d�fini. Si <em>$email</em>
n'�tait pas d�fini, la sortie serait <em>$email</em>.
</p>
<p>
Supposons que <em>$email</em> soit d�fini (par exemple, cette r�f�rence a la valeur <em>foo</em>)
et que vous vouliez produire <em>$email</em>. Il y a diff�rentes mani�res de le faire, mais la plus simple est
d'utiliser le caract�re d'�chappement.
</p>
<source><![CDATA[
## La ligne qui suit d�finit $email dans ce gabarit:
#set( $email = "foo" )
$email
\$email
\\$email
\\\$email
]]></source>
<p>sera rendu comme:</p>
<source><![CDATA[
foo
$email
\foo
\$email
]]></source>
<p>
Notez que le caract�re <em>\</em> s'applique au <em>$</em> � partir de la gauche. Cette r�gle d'application
� partir de la gauche fait que <em>\\\$email</em> est rendu comme <em>\\$email</em>. Comparons maintenant ces examples
� ce qui se passe lorsque <em>$email</em> n'est pas d�fini.
</p>
<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>
<p>sera rendu comme:</p>
<source><![CDATA[
$email
\$email
\\$email
\\\$email
]]></source>
<p>
Remarquez comment Velocity traite les r�f�rences d�finies diff�remment de celles qui n'ont pas �t� d�finies.
Voici par exemple une directive set qui donne � <em>$foo</em> la valeur <em>gibbous</em>.
</p>
<source><![CDATA[
#set( $foo = "gibbous" )
$moon = $foo
]]></source>
<p>
La sortie sera: <em>$moon = gibbous</em> -- o� <em>$moon</em> est rendu litt�ralement puisqu'il n'est pas d�fini,
alors que <em>gibbous</em> est rendu au lieu de <em>$foo</em>.
</p>
<p>Il est aussi possible d'�chapper les directives VTL; ceci est d�crit plus en d�tail dans la section Directives.</p>
</section>
<section name="Substitution de cas">
<p>
Maintenant que les r�f�rences vous sont famili�res, vous pouvez commencer � les mettre en pratique dans vos propres
gabarits. Les r�f�rences, dans Velocity, tirent avantage de certains principes Java que les concepteurs de gabarits
vont trouver commodes. Par exemple:
</p>
<source><![CDATA[
$foo
$foo.getBar()
## est �quivalent �
$foo.Bar
$data.getUser("jon")
## est �quivalent �
$data.User("jon")
$data.getRequest().getServerName()
## est �quivalent �
$data.Request.ServerName
## est �quivalent �
${data.Request.ServerName}
]]></source>
<p>
Ces exemples illustrent diff�rentes mani�res d'utiliser les m�mes r�f�rences. Velocity tire parti de l'introspection
Java et des caract�ristiques des beans pour r�soudre les noms de r�f�rence en objets du contexte et aussi en leurs
m�thodes. Il est possible d'inclure et d'�valuer des r�f�rences � peu pr�s partout dans votre gabarit.
</p>
<p>
Velocity utilise comme mod�les les sp�cifications des Beans telles qu'elles ont �t� d�finies par Sun Microsystems;
il est donc sensible � la casse (majuscules/minuscules); les d�veloppeurs se sont toutefois battus pour intercepter
et corriger les erreurs des utilisateurs chaque fois que c'est possible. Lorsque la m�thode <em>getFoo()</em> est
r�f�renc�e dans un gabarit par <code>$bar.foo</code>, Velocity essayera d'abord <code>$getfoo</code>. Si ceci �choue,
Velocity essayera <code>$getFoo</code>. De m�me, si un gabarit fait r�f�rence � <code>$bar.Foo</code>,
Velocity essayera d'abord <em>$getFoo()</em> et ensuite <em>getfoo()</em>.
</p>
<p>
Note: <em>Dans un gabarit, les r�f�rences � des variables d'instance ne sont pas r�solues.</em> Il n'y a que les
r�f�rences �quivalentes aux attributs des accesseurs (getter / setter) des JavaBeans qui sont r�solues
(autrement dit <code>$foo.Name</code> est r�solu par l'appel de la m�thode d'instance <code>getName()</code>
de la classe Foo, mais pas en une variable d'instance publique <code>Name</code> de cette classe Foo).
</p>
</section>
<section name="Directives">
<p>
Les r�f�rences permettent aux concepteurs de pages de g�n�rer du contenu dynamique pour des sites web alors que les
<em>directives</em> -- des �l�ments de script, faciles � utiliser, qui peuvent �tre mis en oeuvre pour manipuler de
mani�re cr�ative la sortie d'un code Java -- permet aux concepteurs de vraiment prendre en charge l'apparence et le
contenu du site web.
</p>
<a name="Set"><strong>#set</strong></a>
<p>
La directive <em>#set</em> s'utilise pour donner une valeur � une r�f�rence. Une valeur peut �tre assign�e soit � une
r�f�rence de type variable, soit � une r�f�rence de type propri�t�, et ceci toujours entre parenth�ses, comme montr�
ici:
</p>
<source><![CDATA[
#set( $primate = "monkey" )
#set( $customer.Behavior = $primate )
]]></source>
<p>
Le c�t� gauche (left hand side -- LHS) de l'assignation doit �tre une r�f�rence variable ou propri�t�. Le membre de
droite (right hand side -- RHS) peut �tre de l'un des types suivants:
</p>
<p>
<ul>
<li>Une r�f�rence (variable)</li>
<li>Une cha�ne de caract�res litt�rale</li>
<li>Une r�f�rence (propri�t�)</li>
<li>Une r�f�rence � une m�thode</li>
<li>Un nombre litt�ral</li>
<li>Une ArrayList</li>
</ul>
</p>
<p>Les exemples suivants montrent chacun des types susmentionn�s:</p>
<source><![CDATA[
#set( $monkey = $bill ) ## r�f�rence (variable)
#set( $monkey.Friend = "monica" ) ## cha�ne de caract�res litt�rale
#set( $monkey.Blame = $whitehouse.Leak ) ## r�f�rence (propri�t�)
#set( $monkey.Plan = $spindoctor.weave($web) ) ## r�f�rence � une m�thode
#set( $monkey.Number = 123 ) ## nombre litt�ral
#set( $monkey.Say = ["Not", $my, "fault"] ) ## ArrayList
]]></source>
<p>
NOTE: Dans le dernier exemple, les �l�ments d�finis avec l'op�rateur [..] sont accessibles en utilisant les m�thodes
d�finies dans la classe ArrayList. Ainsi, par exemple, on peut acc�der au premier �l�ment en �crivant
$monkey.Say.get(0)
</p>
<p>Le membre de droite peut aussi �tre une expression arithm�tique simple:</p>
<source><![CDATA[
#set( $value = $foo + 1 )
#set( $value = $bar - 1 )
#set( $value = $foo * $bar )
#set( $value = $foo / $bar )
]]></source>
<p>
Si le membre de droite est une r�f�rence � une m�thode ou � une propri�t� dont la valeur est <em>null</em>, il ne
sera <b>pas</b> affect� au membre de gauche. Il n'est pas possible d'enlever une r�f�rence existante du contexte
par ce biais-l�. Ceci peut troubler les d�butants en Velocity. Par exemple:
</p>
<source><![CDATA[
#set( $result = $query.criteria("name") )
Le r�sultat de la premi�re requ�te est $result
#set( $result = $query.criteria("address") )
Le r�sultat de la seconde requ�te est $result
]]></source>
<p>
Si <em>$query.criteria("name")</em> renvoie la cha�ne "bill", et que <em>$query.criteria("address")</em> renvoie
<em>null</em>, le code VTL ci-dessus sera rendu de la mani�re suivante:
</p>
<source><![CDATA[
Le r�sultat de la premi�re requ�te est bill
Le r�sultat de la seconde requ�te est bill
]]></source>
<p>
Ceci induit en confusion les nouveaux venus, qui construisent des boucles <em>#foreach</em> qui tentent de faire
un <em>#set</em> sur une r�f�rence � partir d'une r�f�rence � une propri�t� ou une m�thode et testent imm�diatement
cette r�f�rence avec une directive <em>#if</em>. Par exemple:
</p>
<source><![CDATA[
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = $query.criteria($criterion) )
#if( $result )
Query was successful
#end
#end
]]></source>
<p>
Dans l'exemple ci-dessus, il ne serait pas avis� de se reposer sur l'�valuation de <em>$result</em> pour d�terminer
si une requ�te a �t� couronn�e de succ�s. Une fois que <em>$result</em> a re�u une valeur par un <em>#set</em>
(et a donc �t� ajout� au contexte), il ne peut pas recevoir la valeur <em>null</em> (et se trouver ainsi enlev� du
contexte). Les d�tails des directives <em>#if</em> et <em>#foreach</em> sont trait�s plus loin dans ce document.
</p>
<p>
Une solution � ce probl�me serait de pr�-positionner <em>$result</em> � <em>false</em>. Si l'appel �
<em>$query.criteria()</em> �choue, il est possible de faire la v�rification.
</p>
<source><![CDATA[
#set( $criteria = ["name", "address"] )
#foreach( $criterion in $criteria )
#set( $result = false )
#set( $result = $query.criteria($criterion) )
#if( $result )
La requ�te a abouti correctement
#end
#end
]]></source>
<p>Contrairement � d'autres directives Velocity, la directive <em>#set</em> n'a pas d'instruction <em>#end</em>.</p>
<a name="Cha�nes de caract�res litt�rales"><strong>Cha�nes de caract�res litt�rales</strong></a>
<p>
Lorsque vous utilisez la directive <em>#set</em>, les cha�nes de caract�res litt�rales d�limit�es par des guillements
sont interpr�t�es et rendues de la mani�re suivante:
</p>
<source><![CDATA[
#set( $directoryRoot = "www" )
#set( $templateName = "index.vm" )
#set( $template = "$directoryRoot/$templateName" )
$template
]]></source>
<p>La sortie produite sera</p>
<source><![CDATA[
www/index.vm
]]></source>
<p>Toutefois, lorsque la cha�ne de caract�res litt�rale est d�limit�e par des apostrophes, elle n'est pas interpr�t�e.</p>
<source><![CDATA[
#set( $foo = "bar" )
$foo
#set( $blargh = '$foo' )
$blargh
]]></source>
<p>Ce qui est rendu de la mani�re suivante:</p>
<source><![CDATA[
bar
$foo
]]></source>
<p>
Cette caract�ristique d'utilisation des apostrophes pour rendre du texte non interpr�t� est le comportement par d�faut
de Velocity. Ce comportement peut �tre chang� en �ditant le fichier <code>velocity.properties</code> et en y �crivant
l'entr�e: <code>stringliterals.interpolate=false</code>.
</p>
</section>
<section name="Conditions">
<strong>If / ElseIf / Else</strong>
<p>
La directive <em>#if</em> de Velocity permet � du texte d'�tre inclus � la g�n�ration d'une page web seulement si la
condition qui suit l'instruction if est v�rifi�e. Par exemple:
</p>
<source><![CDATA[
#if( $foo )
<strong>Velocity!</strong>
#end
]]></source>
<p>
La variable <em>$foo</em> est �valu�e pour d�terminer si elle vaut true, ce qui se produit dans l'une des deux cas
suivants; (i) <em>$foo</em> est une variable bool�enne (true/false) dont la valeur est vrai (true), ou (ii) la valeur
de <em>$foo</em> est diff�rente de null. On se rappelle que le contexte de Velocity ne contient que des Objets,
et donc lorsqu'on dit un bool�en, il sera repr�sent� comme un objet de la classe Boolean contenant la valeur logique
appropri�e.
</p>
<p>
Ce qui est contenu entre l'instruction <em>#if</em> et l'instruction <em>#end</em> sera produit en sortie si la
condition est �valu�e comme vraie. Dans l'exemple pr�c�dent, si <em>$foo</em> est true, la sortie sera: "Velocity!".
A l'inverse, si <em>$foo</em> a la valeur null, ou si c'est un bool�en de valeur false, l'instruction est �valu�e
comme fausse, et il n'y a pas de sortie produite.
</p>
<p>
Un �l�ment <em>#elseif</em> ou <em>#else</em> peut �tre utilis� dans la directive <em>#if</em>.
Notez que le moteur Velocity (Velocity Template Engine) s'arr�tera � la premi�re expression �valu�e comme vraie.
Dans l'exemple suivant, supposons que <em>$foo</em> vaut 15 et que <em>$bar</em> vaut 6.
</p>
<source><![CDATA[
#if( $foo < 10 )
<strong>Go North</strong>
#elseif( $foo == 10 )
<strong>Go East</strong>
#elseif( $bar == 6 )
<strong>Go South</strong>
#else
<strong>Go West</strong>
#end
]]></source>
<p>
Dans cet exemple, <em>$foo</em> est plus grand que 10, donc les deux premi�res comparaisons �chouent. Ensuite,
<em>$bar</em> est compar� � 6, ce qui donne vrai, et dont la sortie produit est <strong>Go South</strong>.
</p>
<p>
Notez que pour l'instant, dans Velocity, les comparaisons num�riques sont restreintes aux comparaisons d'entiers
(Integers) -- tout le reste sera �valu� comme faux. La seule exception est l'�galit� '==': dans ce cas Velocity teste
si les objets de chaque c�t� de '==' sont de la <em>m�me classe</em>.
</p>
<p><a name="Op�rateurs logiques et relationnels"><strong>Op�rateurs logiques et relationnels</strong></a></p>
<p>Velocity utilise l'op�rateur d'�quivalence pour d�terminer les relations entre des variables. Voici un exemple simple pour illustrer la mani�re d'utiliser l'op�rateur d'�quivalence.</p>
<source><![CDATA[
#set ($foo = "deoxyribonucleic acid")
#set ($bar = "ribonucleic acid")
#if ($foo == $bar)
Dans ce cas, il est clair qu'ils ne sont pas �quivalents. Donc...
#else
Ils ne sont pas �quivalents et c'est ceci qui sera produit en sortie.
#end
]]></source>
<p>
Velocity a aussi des op�rateurs ET, OU et NON. Pour plus d'informations, r�f�rez-vous au
<a href="vtl-reference-guide.html">VTL Reference Guide</a> (en anglais).
Ci-dessous, quelques exemples illustrent l'utilisation des op�rateurs logiques ET, OU et NON.
</p>
<source><![CDATA[
##ET logique
#if( $foo && $bar )
<strong> Ceci ET cela.</strong>
#end
]]></source>
<p>
La directive <em>#if()</em> ne sera �valu�e comme <em>true</em> que si <em>$foo</em> et <em>$bar</em> sont
<em>true</em> tous les deux. Si <em>$foo</em> est <em>false</em>, l'expression sera globalement �valu�e comme
<em>false</em> et <em>$bar</em> ne sera pas �valu�. Si <em>$foo</em> vaut <em>true</em>, le moteur Velocity testera
la valeur de <em>$bar</em>; si <em>$bar</em> vaut <em>true</em>, alors l'expression dans son enti�ret� vaut
<em>true</em> et la sortie <strong>Ceci ET cela</strong> est produite. Si <em>$bar</em> est <em>false</em>,
alors il n'y aura pas de sortie produite puisque l'expression enti�re est fausse.
</p>
<p>
Les op�rateurs logiques OU fonctionnent de la m�me mani�re, si ce n'est qu'une seule des r�f�rences doit �tre �valu�e
� <em>true</em> pour que l'expression enti�re soit consid�r�e comme vraie. Voyez l'exemple suivant:
</p>
<source><![CDATA[
##OU logique
#if( $foo || $bar )
<strong>Ceci OU cela</strong>
#end
]]></source>
<p>
Si <em>$foo</em> vaut <em>true</em>, le moteur Velocity n'a pas besoin d'�valuer <em>$bar</em>; que <em>$bar</em>
soit vrai ou faux ne change rien � l'affaire, l'expression sera vraie, et <strong>Ceci OU cela</strong> sera produit
en sortie. Mais si <em>$foo</em> est false, la valeur de <em>$bar</em> doit �tre v�rifi�e.
Dans ce cas, si <em>$bar</em> est faux lui aussi, l'expression sera fausse et il n'y aura pas de sortie produite.
Sinon, si <em>$bar</em> est vrai, alors l'expression enti�re est vraie, et la sortie est
<strong>Ceci OU cela</strong>.
</p>
<p>Avec l'op�rateur logique NON, il n'y a qu'un seul argument :</p>
<source><![CDATA[
##NON logique
#if( !$foo )
<strong>PAS �a</strong>
#end
]]></source>
<p>
Cette fois, si <em>$foo</em> vaut <em>true</em>, alors <em>!$foo</em> est �valu� comme <em>false</em>,
et il n'y a pas de sortie. Si <em>$foo</em> est <em>false</em>, alors <em>!$foo</em> est �valu� � <em>true</em>
et <strong>PAS �a</strong> est produit en sortie. Attention � ne pas confondre ceci avec la
<em>r�f�rence silencieuse $!foo</em> que nous avons d�j� rencontr�e et qui repr�sente quelque chose de compl�tement
diff�rent.
</p>
</section>
<section name="Boucles">
<strong>Boucle Foreach</strong>
<p>L'�l�ment <em>#foreach</em> permet d'it�rer. Par exemple:</p>
<source><![CDATA[
<ul>
#foreach( $product in $allProducts )
<li>$product</li>
#end
</ul>
]]></source>
<p>
Cette boucle <em>#foreach</em> parcourt un � un tous les produits (cibles) de la liste <em>$allProducts</em> (objet).
A chaque passage dans la boucle, une valeur de <em>$allProducts</em> est plac�e dans la variable <em>$product</em>.
</p>
<p>
Le contenu de la variable <em>$allProducts</em> est un vecteur (Vector), une table de hachage (Hashtable)
ou un tableau (Array). La valeur assign�e � <em>$product</em> est un objet Java, et peut �tre r�f�renc�e en tant
que telle par une variable. Par exemple, si <em>$product</em> est en effet une classe Product en Java,
son nom peut �tre r�cup�r� en r�f�ren�ant la m�thode <em>$product.Name</em> (c'est-�-dire <em>$Product.getName()</em>).
</p>
<p>
Supposons que <em>$allProducts</em> soit une Hashtable. Si vous voulez retrouver les valeurs des cl�s et les objets
de la Hashtable, vous pouvez utiliser un bout de code comme celui-ci:
</p>
<source><![CDATA[
<ul>
#foreach( $key in $allProducts.keySet() )
<li>Key: $key -> Value: $allProducts.get($key)</li>
#end
</ul>
]]></source>
<p>
Velocity fournit un moyen simple de conna�tre le compteur de boucle, de sorte qu'on puisse faire quelque chose comme:
</p>
<source><![CDATA[
<table>
#foreach( $customer in $customerList )
<tr><td>$velocityCount</td><td>$customer.Name</td></tr>
#end
</table>
]]></source>
<p>
Le nom par d�faut de la variable/r�f�rence du compteur de bouche est sp�cifi� dans le fichier
<code>velocity.properties</code>. Par d�faut le compteur d�marre � 1, mais ceci aussi peut �tre param�tr� (� 0 ou 1)
dans le fichier <code>velocity.properties</code>. Voici � quoi ressemble la section Propri�t�s du compteur de boucle
dans le fichier <code>velocity.properties</code>:
</p>
<source><![CDATA[
# Default name of the loop counter
# variable reference.
directive.foreach.counter.name = velocityCount
# Default starting value of the loop
# counter variable reference.
directive.foreach.counter.initial.value = 1
]]></source>
</section>
<section name="Include">
<p>
L'�l�ment de script <em>#include</em> permet au concepteur de gabarits d'importer un fichier local, qui est alors
ins�r� � l'endroit o� la directive <em>#include</em> est d�finie. Le contenu du fichier n'est pas rendu en passant
par le moteur de substitution. Pour des raisons de s�curit�, le fichier � inclure ne peut se trouver que sous
TEMPLATE_ROOT.
</p>
<source><![CDATA[
#include( "one.txt" )
]]></source>
<p>
Le fichier auquel la directive <em>#include</em> fait r�f�rence est inclus entre des guillemets.
Si plusieurs fichiers doivent �tre inclus, leurs noms doivent �tre s�par�s par des virgules.
</p>
<source><![CDATA[
#include( "one.gif","two.txt","three.htm" )
]]></source>
<p>
Le fichier � inclure ne doit pas n�cessairement �tre appel� par son nom; en fait, il est souvent pr�f�rable
d'utiliser une variable plut�t qu'un nom de fichier. Ce qui peut �tre utile pour cibler ce qui est produit en
fonction de crit�res d�termin�s au moment o� la page est demand�e. Voici un exemple qui utilise � la fois un nom
de fichier et une variable.
</p>
<source><![CDATA[
#include( "greetings.txt", $seasonalstock )
]]></source>
</section>
<section name="Parse">
<p>
L'�l�ment de script <em>#parse</em> permet au concepteur de gabarits d'importer un fichier local contenant du VTL.
Velocity va alors interpr�ter le VTL et rendre le gabarit sp�cifi�.
</p>
<source><![CDATA[
#parse( "me.vm" )
]]></source>
<p>
Comme la directive <em>#include</em>, <em>#parse</em> peut prendre en argument une variable plut�t qu'un nom
de gabarit. Tous les gabarits auxquels il est fait r�f�rence par <em>#parse</em> doivent se trouver
sous TEMPLATE_ROOT. Contrairement � la directive <em>#include</em>, <em>#parse</em> ne peut prendre qu'un seul
argument.
</p>
<p>
Les gabarits VTL peuvent contenir des instructions <em>#parse</em> faisant r�f�rence � des gabarits qui � leur tour
contiennent des <em>#parse</em>. Par d�faut � 10, la ligne <em>parse_directive.maxdepth</em> du fichier
<code>velocity.properties</code> permet aux utilisateurs de personnaliser le nombre de r�f�rences <em>#parse</em>
que l'on peut rencontrer dans un gabarit. (Note: Si la propri�t� <em>parse_directive.maxdepth</em> est absente du
fichier <code>velocity.properties</code>, Velocit� positionne cette valeur par d�faut � 10).
La r�cursion est permise; par exemple si le gabarit <code>dofoo.vm</code> contient les lignes suivantes:
</p>
<source><![CDATA[
Count down.
#set( $count = 8 )
#parse( "parsefoo.vm" )
All done with dofoo.vm!
]]></source>
<p>Il fait r�f�rence au gabarit <code>parsefoo.vm</code>, qui peut contenir le VTL suivant:</p>
<source><![CDATA[
$count
#set( $count = $count - 1 )
#if( $count > 0 )
#parse( "parsefoo.vm" )
#else
All done with parsefoo.vm!
#end
]]></source>
<p>
Apr�s que "Count down." soit affich�, Velocity passe par <code>parsefoo.vm</code>, comptant � rebours � partir de 8.
Lorsque le compte � rebours atteint 0, il affiche le message "All done with parsefoo.vm!".
A ce stade, Velocity va retourner � <code>dofoo.vm</code> et produire le message "All done with dofoo.vm!".
</p>
</section>
<section name="Stop">
<p>
L'�l�ment de script <em>#stop</em> permet au concepteur de gabarits d'arr�ter l'ex�cution du moteur de substitution.
Cette directive peut �tre utile pour le d�bogage.
</p>
<source><![CDATA[
#stop
]]></source>
</section>
<section name="Velocimacros">
<p>
L'�l�ment de script <em>#macro</em> permet aux concepteurs de d�finir un segment r�p�table d'un gabarit VTL.
Les "Velocimacros" sont tr�s utiles dans un grand nombre de sc�narios, simples ou complexes.
Une Velocimacro, �crite dans le seul but de s'�conomiser un peu de frappe et de minimiser les fautes,
servira d'introduction au concept de Velocimacro.
</p>
<source><![CDATA[
#macro( d )
<tr><td></td></tr>
#end
]]></source>
<p>
La Velocimacro d�finie dans cet exemple est <em>d</em>; elle peut �tre appel�e d'une mani�re semblable � toute autre
directive VTL:
</p>
<source><![CDATA[
#d()
]]></source>
<p>Lorsque ce gabarit est appel�, Velocity remplace <em>#d()</em> par une ligne contenant une cellule de donn�es vide.</p>
<p>
Une Velocimacro peut prendre n'importe quel nombre d'arguments -- m�me z�ro, comme on l'a vu dans l'exemple --
mais lorsque la macro est appel�e, elle doit l'�tre avec le m�me nombre d'arguments que dans la d�finition.
Beaucoup de Velocimacros sont plus sophistiqu�es que celle d�finie ci-dessus; voici une Velocimacro qui prend deux
arguments, une couleur et un tableau.
</p>
<source><![CDATA[
#macro( tablerows $color $somelist )
#foreach( $something in $somelist )
<tr><td bgcolor=$color>$something</td></tr>
#end
#end
]]></source>
<p>
La Velocimacro d�finie dans cet exemple, <em>tablerows</em>, prend deux arguments. Le premier argument prend la place
de <em>$color</em> et le second argument prend la place de <em>$somelist</em>.
</p>
<p>
Tout ce qui peut �tre mis dans un gabarit VTL peut aussi trouver place dans le corps d'une Velocimacro.
La Velocimacro <em>tablerows</em> contient une instruction <em>foreach</em>. On remarquera qu'il y a deux
instructions <em>#end</em> dans la d�finition de la Velocimacro <em>#tablerows</em>; la premi�re termine
le <em>#foreach</em>, la seconde termine la d�finition de la Velocimacro.
</p>
<source><![CDATA[
#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
#tablerows( $color $greatlakes )
</table>
]]></source>
<p>
Notez que <em>$greatlakes</em> prend la place de <em>$somelist</em>. Quand la Velocimacro <em>#tablerows</em>
est appel�e dans ce contexte, la sortie suivante est produite:
</p>
<source><![CDATA[
<table>
<tr><td bgcolor="blue">Superior</td></tr>
<tr><td bgcolor="blue">Michigan</td></tr>
<tr><td bgcolor="blue">Huron</td></tr>
<tr><td bgcolor="blue">Erie</td></tr>
<tr><td bgcolor="blue">Ontario</td></tr>
</table>
]]></source>
<p>
Les Velocimacros peuvent �tre d�finies <i>inline</i> dans un gabarit Velocity; elles ne sont pas disponibles dans
ce cas pour d'autres gabarits Velocity sur le m�me site web. D�finir une Velocimacro pour qu'elle puisse �tre partag�e
par tous les gabarits a des avantages �vidents: cela r�duit le besoin de red�finir la Velocimacro dans de nombreux
gabarits, cela �conomise du travail et r�duit les occasions de se tromper, cela assure qu'un chagement fait une seule
fois dans une macro est aussit�t disponible dans tous les gabarits.
</p>
<p>
Si la Velocimacro <em>#tablerows($color $list)</em> avait �t� d�finie dans une biblioth�que de gabarits Velocimacros,
cette macro aurait pu �tre utilis�e dans n'importe lequel des gabarits usuels. Elle pourrait �tre utilis�e de
nombreuses fois et dans des buts diff�rents. Dans le gabarit <code>mushroom.vm</code> consacr� � toute esp�ce de
champignons, la Velocimacro <em>#tablerows</em> pourrait �tre appel�e pour donner la liste des parties
d'un champignon typique.
</p>
<source><![CDATA[
#set( $parts = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $parts )
</table>
]]></source>
<p>
Lors de l'ex�cution d'une requ�te pour <code>mushroom.vm</code>, Velocity trouverait la Velocimacro
<em>#tablerows</em> dans la biblioth�que de gabarits (d�finie dans le fichier <code>velocity.properties</code>)
et produirait la sortie suivante:
</p>
<source><![CDATA[
<table>
<tr><td bgcolor="#CC00FF">volva</td></tr>
<tr><td bgcolor="#CC00FF">stipe</td></tr>
<tr><td bgcolor="#CC00FF">annulus</td></tr>
<tr><td bgcolor="#CC00FF">gills</td></tr>
<tr><td bgcolor="#CC00FF">pileus</td></tr>
</table>
]]></source>
<strong>Arguments d'une Velocimacro</strong>
<p>Les Velocimacros peuvent prendre comme argument tout �l�ment VTL parmi les suivants:</p>
<ul>
<li>R�f�rence: tout ce qui commence par '$'</li>
<li>Cha�ne de caract�res litt�rale: quelque chose comme "$foo" ou 'hello'</li>
<li>Nombre litt�ral: 1, 2 etc</li>
<li>Intervalle d'entiers (IntegerRange) : [ 1..2] ou [$foo .. $bar]</li>
<li>ObjectArray : [ "a", "b", "c"]</li>
<li>Valeur bool�enne true</li>
<li>Valeur bool�enne false</li>
</ul>
<p>
Lorsqu'on passe des r�f�rences comme arguments � des Velocimacros, notez que ces r�f�rences sont pass�es "par nom".
Ce qui veut dire que leur valeur est "g�n�r�e" � chaque utilisation � l'int�rieur d'une Velocimacro.
Cette particularit� vous permet de passer des r�f�rences contenant des appels de m�thodes et que la m�thode soit
appel�e � chaque fois. Par exemple, en appelant la Velocimacro suivante comme indiqu�:
</p>
<source><![CDATA[
#macro( callme $a )
$a $a $a
#end
#callme( $foo.bar() )
]]></source>
<p>le r�sultat est que la m�thode bar() de la r�f�rence $foo est appel�e trois fois.</p>
<p>
A premi�re vue, cette particularit� est surprenante mais si vous consid�rez la raison d'�tre originelle des
Velocimacros (�liminer la duplication par couper/coller de VTL d'usage courant), �a a bien s�r un sens.
Cela vous permet de faire des choses �tonnantes telles que passer � la Velocimacro des objets ayant un �tat,
comme un objet qui g�n�re des couleurs en s�quences r�p�t�es pour colorer les lignes d'un tableau.
</p>
<p>
Si vous �prouvez le besoin de contourner ce comportement, vous pouvez toujours assigner la valeur re�ue de la m�thode
� une nouvelle r�f�rence et passer cette r�f�rence:
</p>
<source><![CDATA[
#set( $myval = $foo.bar() )
#callme( $myval )
]]></source>
<strong>Propri�t�s des Velocimacros</strong>
<p>
Plusieurs entr�es du fichier <code>velocity.properties</code> permettent une impl�mentation flexible des Velocimacros.
Ces lignes sont comment�es en d�tail dans le <a href="developer-guide.html">Developer Guide</a> (en anglais).
</p>
<p>
<code>velocimacro.library</code> - Une liste (d�limit�e par des virgules, de toutes les biblioth�ques de gabarits
Velocimacro. Par d�faut, Velocity ne recherche qu'une biblioth�que: <em>VM_global_library.vm</em>.
Le chemin de gabarits donn� ici est utilis� pour trouver les biblioth�ques de Velocimacros.
</p>
<p>
<code>velocimacro.permissions.allow.inline</code> - Cette propri�t�, qui peut prendre les valeurs true ou false,
d�termine si les Velocimacros peuvent �tre d�finies dans des gabarits ordinaires.
La valeur par d�faut, true, permet aux concepteurs de gabarits de d�finir des Velocimacros dans les gabarits eux-m�mes.
</p>
<p>
<code>velocimacro.permissions.allow.inline.to.replace.global</code> - Les valeurs possibles sont true ou false,
pour cette propri�t� qui permet � l'utilisateur de sp�cifier si une Velocimacro d�finie en ligne dans un gabarit
peut remplacer un gabarit d�fini globalement, celui qui a �t� d�fini au d�marrage par la propri�t�
<code>velocimacro.library</code>. La valeur par d�faut, <code>false</code>, emp�che les Velocimacros d�fines
<i>inline</i> dans un gabarit de remplacer celles qui sont d�finies dans les biblioth�ques de gabarits charg�es
au d�marrage.
</p>
<p>
<code>velocimacro.permissions.allow.inline.local.scope</code> - Cette propri�t�, qui peut prendre les valeurs true
ou false (false par d�faut), contr�le si les Velocimacros d�finies <i>inline</i> ont leur visibilit� limit�e au
gabarit qui les d�finit. En d'autres mots, avec cette propri�t� d�finie � true, un gabarit peut d�finir des
Velocimacros <i>inline</i> qui ne seront utilisables que par le gabarit qui les d�finit. Vous pouvez utiliser
cette possibilit� pour concocter quelques artifices amusants: si une VM globale appelle une autre VM globale,
d�finie <i>inline</i>, un gabarit peut d�finir une impl�mentation "priv�e" de la seconde VM, qui sera appell�e
par la premi�re VM quand celle-ci est appel�e elle-m�me dans le gabarit. Aucun autre gabarit n'est affect�.
</p>
<p>
<code>velocimacro.context.localscope</code> - Cette propri�t� peut valoir true ou false, la valeur par d�faut est
false. Quand elle vaut true, toute modification du contexte via #set() � l'int�rieur d'une Velocimacro est consid�r�e
'locale' � cette Velocimacro et n'affectera pas le contexte de fa�on permanente.
</p>
<p>
<code>velocimacro.library.autoreload</code> - Cette propri�t� contr�le le chargement automatique de la biblioth�que
de Velocimacro. La valeur par d�faut est <code>false</code>. Quand elle est positionn�e � <code>true</code>
la biblioth�que source appel�e pour une Velocimacro sera v�rifi�e pour voir si elle a chang� et sera recharg�e
si n�cessaire. Ceci vous permet de modifier et de tester des biblioth�ques de Velocimacro sans avoir � red�marrer
votre application ou votre moteur de servlets, exactement comme vous pouvez le faire pour des gabarits ordinaires.
Ce mode ne fonctionne que quand le cache est d�sactiv� dans les <i>resource loaders</i>
(par exemple <code>file.resource.loader.cache = false</code>). Cette possibilit� a �t� con�ue pour le d�veloppement,
pas pour la production.
</p>
<strong>Autres remarques sur les Velocimacros</strong>
<p>
A ce stade, les Velocimacros doivent �tre d�finies avant d'�tre utilis�es dans un gabarit.
Cela signifie que vos d�clarations #macro() doivent pr�c�der l'usage des Velocimacros.
</p>
<p>
Il est important de s'en souvenir si l'on essaye d'interpr�ter (#parse()) un gabarit contenant des directives #macro()
<i>inline</i>. Puisque l'interpr�tation se fait au moment de l'ex�cution, et que l'interpr�teur d�cide au moment de
l'interpr�tation si, dans un gabarit, un �l�ment qui a l'air d'une VM en est vraiment une, #parse()-er un ensemble de
d�clarations de VM ne produira pas le r�sultat escompt�. Pour contourner ce probl�me potentiel, on peut utiliser la
propri�t� <code>velocimacro.library</code> pour que Velocity charge vos VMs au d�marrage.
</p>
</section>
<section name="Echappement des directives VTL">
<p>
Les directives VTL peuvent �tre �chapp�es avec le caract�re barre de fraction invers�e ("\"), de la m�me mani�re que
les r�f�rences VTL valides.
</p>
<source><![CDATA[
## #include( "a.txt" ) renders as <contents of a.txt>
#include( "a.txt" )
## \#include( "a.txt" ) renders as \#include( "a.txt" )
\#include( "a.txt" )
## \\#include ( "a.txt" ) renders as \<contents of a.txt>
\\#include ( "a.txt" )
]]></source>
<p>
Il faut prendre des pr�cautions particuli�res lorsqu'on �chappe des directives VTL qui contiennent plusieurs �l�ments
de script en une seule directive (comme dans le cas d'une instruction conditionnelle if-else-end).
Voici un exemple typique d'instruction VTL if:
</p>
<source><![CDATA[
#if( $jazz )
Vyacheslav Ganelin
#end
]]></source>
<p>Si <em>$jazz</em> est vrai, la sortie produite est:</p>
<source><![CDATA[
Vyacheslav Ganelin
]]></source>
<p>
Si <em>$jazz</em>, il n'y a pas de sortie produite. Echapper des �l�ments de script modifie la sortie.
Consid�rons le cas suivant:
</p>
<source><![CDATA[
\#if( $jazz )
Vyacheslav Ganelin
\#end
]]></source>
<p>Que <em>$jazz</em> soit vrai ou faux, la sortie sera:</p>
<source><![CDATA[
#if($ jazz )
Vyacheslav Ganelin
#end
]]></source>
<p>
En fait, puisque tous les �l�ments de script sont �chapp�s, <em>$jazz</em> n'est jamais �valu� en vue d'en conna�tre
la valeur logique. Supposons que les barres de fraction inverses pr�c�dent les �l�ments de script qui sont
l�gitimement �chapp�s:
</p>
<source><![CDATA[
\\#if( $jazz )
Vyacheslav Ganelin
\\#end
]]></source>
<p>Dans ce cas, si <em>$jazz</em> est vrai, la sortie est</p>
<source><![CDATA[
\ Vyacheslav Ganelin
\
]]></source>
<p>
Pour comprendre, notons que le <code>#if( arg ) </code>, lorsqu'il est termin� par un retour � la ligne, omettra
ce retour � la ligne de la sortie produite. Donc, le corps du bloc <code>#if()</code> suit la premi�re barre '\',
rendue par le '\\' qui pr�c�de <code>#if()</code>. Le dernier \ est sur une ligne diff�rente du texte qui pr�c�de
parce qu'il y a un retour chariot apr�s 'Ganelin', et donc le \\ final, qui pr�c�de le <code>#end</code> fait partie
du corps du bloc.
</p>
<p>
Si <em>$jazz</em> est faux, il n'y a pas de sortie produite. Notons que les choses vont commencer � mal se passer
si des �l�ments de script ne sont pas �chapp�s correctement.
</p>
<source><![CDATA[
\\\#if( $jazz )
Vyacheslave Ganelin
\\#end
]]></source>
<p>
Ici le <em>#if</em> est �chapp�, mais il y a un <em>#end</em> qui reste l�, et trop de terminaisons vont causer
une erreur dans l'interpr�tation.
</p>
</section>
<section name="VTL: Questions de format">
<p>
Bien que le VTL soit souvent montr� dans ce guide de l'utilisateur avec des sauts de ligne et des espaces,
le VTL ci-dessous:
</p>
<source><![CDATA[
#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] )
#foreach( $shogun in $imperial )
$shogun
#end
]]></source>
<p>
est tout aussi valide que le bout de code suivant, post� par Geir Magnusson Jr. � la liste de diffusion Velocity
(pour illustrer un point sans rapport avec notre sujet):
</p>
<source><![CDATA[
Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please.
]]></source>
<p>Velocity dig�re les blancs inutiles. La directive qui pr�c�de peut donc s'�crire de la mani�re suivante:</p>
<source><![CDATA[
Send me
#set( $foo = ["$10 and ","a cake"] )
#foreach( $a in $foo )
$a
#end
please.
]]></source>
<p>ou encore:</p>
<source><![CDATA[
Send me
#set($foo = ["$10 and ","a cake"])
#foreach ($a in $foo )$a
#end please.
]]></source>
<p>Dans tous les cas, la sortie sera identique.</p>
</section>
<section name="Autres caract�ristiques et sujets divers">
<subsection name="Math">
<p>
Velocity a quelques fonctions math�matiques int�gr�es, fonctions que l'on peut utiliser dans les gabarits
avec la directive <em>set</em>. Les �quations suivantes sont des exemples d'addition, soustraction, multiplication
et division respectivement:
</p>
<source><![CDATA[
#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
]]></source>
<p>
Lorsqu'une op�ration de division est ex�cut�e, le r�sultat sera un entier. Le reste �ventuel de la division peut
�tre obtenu en utilisant l'op�rateur modulo (<em>%</em>).
</p>
<source><![CDATA[
#set( $foo = $bar % 5 )
]]></source>
<p>
Seuls les entiers (...-2, -1, 0, 1, 2...) sont admis comme op�randes des �quations math�matiques en Velocity;
lorsqu'un non-entier est rencontr�, cela est signal� et null sera renvoy� dans la sortie produite.
</p>
</subsection>
<subsection name="Op�rateur d'intervalle (range)">
<p>
L'op�rateur d'intervalle peut �tre utilis� en conjonction avec les instructions <em>#set</em> et
<em>#foreach</em>. C'est assez commode pour produire un tableau d'objets contenant des entiers;
l'op�rateur d'intervalle est construit comme ceci:
</p>
<source><![CDATA[
[n..m]
]]></source>
<p>
<em>n</em> et <em>m</em> doivent tous deux �tre ou renvoyer des entiers. Que <em>m</em> soit plus grand ou plus
petit que <em>n</em> importe peu, si cela se produit le tableau d�compte. Voici quelques exemples de l'op�rateur
de port�e:
</p>
<source><![CDATA[
Premier exemple:
#foreach( $foo in [1..5] )
$foo
#end
Second exemple:
#foreach( $bar in [2..-2] )
$bar
#end
Troisi�me exemple:
#set( $arr = [0..1] )
#foreach( $i in $arr )
$i
#end
Quatri�me exemple:
[1..3]
]]></source>
<p>Produit la sortie suivante:</p>
<source><![CDATA[
Premier exemple:
1 2 3 4 5
Second exemple:
2 1 0 -1 -2
Troisi�me exemple:
0 1
Quatri�me exemple:
[1..3]
]]></source>
<p>
Il est � noter que l'op�rateur d'intervalle ne produit le tableau qu'utilis� en conjonction avec les directives
<em>#set</em> et <em>#foreach</em>, comme d�montr� dans le quatri�me exemple.
</p>
<p>
Les concepteurs de pages web soucieux de construire des tables de taille standard, mais dans lequelles il n'y a
pas assez de donn�es pour remplir la table, trouveront cet op�rateur d'intervalle particuli�rement utile.
</p>
</subsection>
<subsection name="Questions pointues: Echappement et !">
<p>
Lorsqu'une r�f�rence est annul�e par le caract�re <em>!</em> et que ce caract�re
<em>!</em> est pr�c�d� par un caract�re d'�chappement <em>\</em>, la r�f�rence est trait�e de mani�re particuli�re.
A noter: les diff�rences entre l'�chappement ordinaire et le cas particulier o� <em>\</em> pr�c�de <em>!</em>
comme ici:
</p>
<source><![CDATA[
#set( $foo = "bar" )
$\!foo
$\!{foo}
$\\!foo
$\\\!foo
]]></source>
<p>Ceci produit la sortie suivante:</p>
<source><![CDATA[
$!foo
$!{foo}
$\!foo
$\\!foo
]]></source>
<p>A comparer avec l'�chappement ordinaire, o� <em>\</em> pr�c�de <em>$</em>:</p>
<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\\$!{foo}
]]></source>
<p>Ce qui produit la sortie suivante:</p>
<source><![CDATA[
\$foo
\$!foo
\$!{foo}
\bar
]]></source>
</subsection>
<subsection name="Compl�ments divers sur les Velocimacros">
<p>
Cette section est une mini-FAQ sur diff�rents sujets relatifs aux Velocimacros.
Cette section �voluera au fil du temps, et cela vaudra donc la peine d'y revenir occasionnellement pour y
chercher de nouvelles informations.
</p>
<p>Note: tout au long de cette section, 'Velocimacro' sera habituellement abr�g� en 'VM'.</p>
<strong>Puis-je utiliser une directive ou une autre VM comme argument d'une VM?</strong>
<p>Exemple : <code>#center( #bold("hello") )</code></p>
<p>
Non. Une directive n'est pas un argument valide d'une directive, et en pratique, pour l'essentiel,
une VM est une directive.
</p>
<p>
<i>Pourtant...</i>, il y a des choses que vous pouvez faire. Une solution, simple, est de tirer avantage du fait
que l'apostrophe (") restitue son contenu. Vous pouvez donc �crire quelque chose comme
</p>
<source><![CDATA[
#set($stuff = "#bold('hello')" )
#center( $stuff )
]]></source>
<p>Vous pouvez m�me vous �pargner une �tape...</p>
<source><![CDATA[
#center( "#bold( 'hello' )" )
]]></source>
<p>
Mais il est � noter, dans ce dernier exemple, que l'argument est �valu� <i>� l'int�rieur</i> de la VM, pas au niveau
de l'appel. En d'autres termes, l'argument pass� � la VM est pass� dans son int�gralit� et �valu� dans la VM �
laquelle il a �t� pass�. Ceci permet d'�crire des choses comme:
</p>
<source><![CDATA[
#macro( inner $foo )
inner : $foo
#end
#macro( outer $foo )
#set($bar = "outerlala")
outer : $foo
#end
#set($bar = 'calltimelala')
#outer( "#inner($bar)" )
]]></source>
<p>La sortie produite est</p>
<source><![CDATA[
Outer : inner : outerlala
]]></source>
<p>
puisque l'�valuation de "#inner($bar)" se produit � l'int�rieur de #outer(), et c'est donc la valeur $bar
positionn�e � l'int�rieur de #outer() qui est utilis�e.
</p>
<p>
Ceci est tout � fait intentionnel, et c'est une caract�ristique jalousement gard�e - les arguments sont pass�s
'par nom' aux VM, de sorte qu'on puisse passer aux VM un genre de "r�f�rences avec �tat" telles que
</p>
<source><![CDATA[
#macro( foo $color )
<tr bgcolor=$color><td>Hi</td></tr>
<tr bgcolor=$color><td>There</td></tr>
#end
#foo( $bar.rowColor() )
]]></source>
<p>
et appeler rowColor() plusieurs fois, plut�t qu'une fois. Pour �viter cela, il faut appeler la m�thode hors de la VM
et passer la valeur � la VM.
</p>
<source><![CDATA[
#set($color = $bar.rowColor())
#foo( $color )
]]></source>
<strong>Peut-on enregistrer des Velocimacros avec #parse() ?</strong>
<p>
Pour l'instant, les Velocimacros doivent �tre d�finies avant d'�tre utilis�es dans un gabarit.
Ce qui signifie que les d�clarations #macro() doivent pr�c�der l'usage des Velocimacros.
</p>
<p>
Il est important de s'en souvenir si l'on essaye d'interpr�ter avec #parse() un gabarit qui contient des directives
#macro() d�finies <i>inline</i>. Puisque le #parse() a lieu au moment de l'ex�cution, et que l'interpr�teur d�cide
� ce moment si quelque chose qui ressemble syntaxiquement � une VM dans le gabarit en est vraiment une au moment de
l'interpr�tation, #parse()-r un ensemble de d�clarations de VM ne fonctionnera pas comme on pourrait le pr�voir.
Pour contourner ce comportement, il suffit d'utiliser <code>velocimacro.library</code> pour que Velocity charge
vos VM's au d�marrage.
</p>
<strong>Qu'est-ce que le <i>Velocimacro Autoreloading</i>?</strong>
<p>Il existe une propri�t�, con�ue pour le <i>d�veloppement</i>, pas pour la production:</p>
<p><code>velocimacro.library.autoreload</code></p>
<p>dont la valeur par d�faut est <i>false</i>. Lorsque cette propri�t� est positionn�e � <i>true</i>, en m�me temps que</p>
<p><code><type>.resource.loader.cache = false</code></p>
<p>
(o� <type> est le nom du chargeur de ressources que vous utilisez, par exemple 'file'), le moteur Velocity va
automatiquement prendre en compte les changements apport�s � vos fichiers de biblioth�ques Velocimacro, au fur et �
mesure que vous les modifiez, de sorte que vous n'ayez pas � arr�ter le moteur de servlet (ou l'application) ou avoir
recours � tout autre subterfuge de ce genre pour recharger vos Velocimacros.
</p>
<p>Voici � quoi peut ressembler un ensemble simple de propri�t�s.</p>
<source><![CDATA[
file.resource.loader.path = templates
file.resource.loader.cache = false
velocimacro.library.autoreload = true
]]></source>
<p>Ne gardez pas cette configuration en production.</p>
</subsection>
<subsection name="Concat�nation de cha�nes">
<p>
Une question habituelle parmi les d�veloppeurs est:
<i>Comment concat�ner des cha�nes de caract�res? Y a-t'il quelque chose de semblable � l'op�rateur '+' en Java?</i>.
</p>
<p>
Pour concat�ner des r�f�rences en VTL, il suffit de les 'mettre ensemble'. Le contexte dans lequel vous voulez les
assembler ainsi a une certaine importance, il faut donc illustrer notre propos par quelques exemples.
</p>
<p>Dans le flux habituel d'un gabarit (lorsqu'on m�lange les r�f�rences avec du contenu ordinaire):</p>
<source><![CDATA[
#set( $size = "Big" )
#set( $name = "Ben" )
Cette horloge sonne comme $size$name.
]]></source>
<p>
produira 'Cette horloge sonne comme BigBen'. Pour prendre des exemples plus int�ressants, lorsqu'on veut concat�ner
des cha�nes pour les passer � une m�thode ou les assigner � une nouvelle r�f�rence, il suffit d'�crire:
</p>
<source><![CDATA[
#set( $size = "Big" )
#set( $name = "Ben" )
#set($clock = "$size$name" )
Cette horloge sonne comme $clock.
]]></source>
<p>
Ce qui produit le m�me r�sultat. Dernier exemple, lorsqu'on veut m�langer des cha�nes "statiques" avec des
r�f�rences, il peut �tre n�cessaire d'utiliser les "r�f�rences formelles" rencontr�es plus haut:
</p>
<source><![CDATA[
#set( $size = "Big" )
#set( $name = "Ben" )
#set($clock = "${size}Tall$name" )
Cette horloge sonne comme $clock.
]]></source>
<p>
Et maintenant le r�sultat produit est 'Cette horloge sonne comme BigTallBen'.
La notation formelle est requise pour que l'interpr�teur comprenne que l'on souhaite utiliser '$size' et non
'$sizeTall', ce qui serait le cas si les accolades n'�taient pas pr�sentes.
</p>
</subsection>
</section>
<section name="Donnez votre avis">
<p>
Si vous rencontrez des erreurs dans le manuel (autres que des erreurs de traduction), ou si vous voulez faire part de
votre avis sur le Guide de l'utilisateur Velocity,
envoyez un mail � la <a href="mailto:velocity-user@jakarta.apache.org">Velocity user list</a>.
Merci!
</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>