Added: velocity/site/cms/trunk/content/engine/2.1/translations/user-guide_fr.html URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.1/translations/user-guide_fr.html?rev=1854714&view=auto ============================================================================== --- velocity/site/cms/trunk/content/engine/2.1/translations/user-guide_fr.html (added) +++ velocity/site/cms/trunk/content/engine/2.1/translations/user-guide_fr.html Sun Mar 3 13:56:00 2019 @@ -0,0 +1,2092 @@ +<!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 - Guide de l'utilisateur Velocity</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 - Guide de l'utilisateur Velocity News" /> + <meta name="author" content="Velocity Documentation Team" /> + <meta name="author" content="John Castura" /> + <meta name="author" content="Jean-François El Fouly" /> + <meta name="author" content="Claude Brisson" /> + <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"> + <a href="../translations/user-guide_fi.html">User's Guide (Finnish)</a> + </li> + + <li class="none"> + <strong>User's Guide (French)</strong> + </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="Table_des_Matières"></a>Table des Matières</h2> +<ol type="1"><li><a href="#Aproposdecedocument">A propos de ce document</a></li> +<li><a href="#Velocity,qu'est-cequec'est?">Velocity, qu'est-ce que c'est?</a></li> +<li><a href="#Qu'est-cequeVelocitypeutfairepourmoi?">Qu'est-ce que Velocity peut faire pour moi?</a><ol type="1"><li><a href="#L'exempledeMudStore">L'exemple de MudStore</a></li> +</ol> +</li> +<li><a href="#IntroductionauVelocityTemplateLanguage(VTL)">Introduction au Velocity Template Language (VTL)</a></li> +<li><a href="#HelloVelocityWorld!">Hello Velocity World!</a></li> +<li><a href="#Lescommentaires">Les commentaires</a></li> +<li><a href="#Lesréférences">Les références</a><ol type="1"><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> +<li><a href="#Recherche">Règles de recherche des méthodes</a></li> +<li><a href="#Rendu">Rendu</a></li> +</ol> +</li> +<li><a href="#Notationformelledesréférences">Références formelles</a></li> +<li><a href="#Notationsilencieusedesréférences">Références silencieuses</a></li> +<li><a href="#Modedenotationstrictedesréférences">Mode de notation stricte des références</a></li> +<li><a href="#Substitutiondecas">Substitution de cas</a></li> +<li><a href="#Directives">Directives</a><ol type="1"><li><a href="#Set">Set</a></li> +<li><a href="#Chaînesdecaractèreslittérales">Chaînes de caractères littérales</a></li> +<li><a href="#Conditions">Conditions</a><ol type="1"><li><a href="#Opérateursrelationnelsetlogiques">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="#Evaluate">Evaluate</a></li> +<li><a href="#Define">Define</a></li> +<li><a href="#Velocimacros">Velocimacros</a></li> +</ol> +</li> +<li><a href="#Sortielittérale">Sortie littérale</a><ol type="1"><li><a href="#Devise">Devise</a></li> +<li><a href="#EchapperdesréférencesVTLvalides">Echapper des références VTL valides</a></li> +<li><a href="#EchapperdesréférencesVTLinvalides">Echapper des références VTL invalides</a></li> +<li><a href="#EchappementdesdirectivesVTL">Echappement des directives VTL</a></li> +</ol> +</li> +<li><a href="#VTL:Questionsdeformat">VTL: Questions de format</a></li> +<li><a href="#Autrescaractéristiquesetsujetsdivers">Autres caractéristiques et sujets divers</a><ol type="1"><li><a href="#Math">Math</a></li> +<li><a href="#Opérateurdeportée(range)">Opérateur de portée (range)</a></li> +<li><a href="#Questionspointues:Echappementet!">Questions pointues: Echappement et !</a></li> +<li><a href="#ComplémentsdiverssurlesVelocimacros">Compléments divers sur les Velocimacros</a></li> +<li><a href="#Concaténationdechaînes">Concaténation de chaînes</a></li> +</ol> +</li> +<li><a href="#Donnezvotreavis">Donnez votre avis</a></li> +</ol> +</div> +<div class="section"><h2><a name="A_propos_de_ce_document"></a>A propos de ce document</h2> +<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> +</div> +<div class="section"><h2><a name="Velocity_quest-ce_que_cest"></a>Velocity, qu'est-ce que c'est?</h2> +<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/"; class="externalLink">Java Server Pages</a> (JSPs) ou à + <a href="http://www.php.net/"; class="externalLink">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/"; class="externalLink">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> +</div> +<div class="section"><h2><a name="Quest-ce_que_Velocity_peut_faire_pour_moi"></a>Qu'est-ce que Velocity peut faire pour moi?</h2> +<div class="section"><h3><a name="Lexemple_de_MudStore"></a>L'exemple de MudStore</h3> +<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> +<div class="source"><pre> +<HTML> +<BODY> +Hello $customer.Name! +<table> +#foreach( $mud in $mudsOnSpecial ) + #if ( $customer.hasPurchased($mud) ) + <tr> + <td> + $flogger.getPromo( $mud ) + </td> + </tr> + #end +#end +</table> + + </pre> +</div> +<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> +</div> +</div> +<div class="section"><h2><a name="Introduction_au_Velocity_Template_Language_VTL"></a>Introduction au Velocity Template Language (VTL)</h2> +<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> +<div class="source"><pre> +#set( $a = "Velocity" ) +</pre> +</div> +<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> +</div> +<div class="section"><h2><a name="Hello_Velocity_World"></a>Hello Velocity World!</h2> +<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> +<div class="source"><pre> +<html> +<body> +#set( $foo = "Velocity" ) +Hello $foo World! +</body> +</html> +</pre> +</div> +<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> +</div> +<div class="section"><h2><a name="Les_commentaires"></a>Les commentaires</h2> +<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> +<div class="source"><pre> +## Ceci est un commentaire d'une seule ligne. +</pre> +</div> +<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> +<div class="source"><pre> +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. +</pre> +</div> +<p>Voici quelques exemples pour clarifier la manière dont les commentaires d'une et plusieurs lignes fonctionnent:</p> +<div class="source"><pre> +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. +</pre> +</div> +<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> +<div class="source"><pre> +#** +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 +*# +</pre> +</div> +</div> +<div class="section"><h2><a name="Les_références"></a>Les références</h2> +<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> +<div class="source"><pre> +$foo +$mudSlinger +$mud-slinger +$mud_slinger +$mudSlinger1 +</pre> +</div> +<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> +<div class="source"><pre> +#set( $foo = "bar" ) +</pre> +</div> +<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> +<div class="source"><pre> +$customer.Address +$purchase.Total +</pre> +</div> +<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> +<div class="source"><pre> +$customer.getAddress() +$purchase.getTotal() +$page.setTitle( "My Home Page" ) +$person.setAttributes( ["Strange", "Weird", "Excited"] ) +</pre> +</div> +<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> +<div class="source"><pre> +$sun.getPlanets() +$annelid.getDirt() +$album.getPhoto() +</pre> +</div> +<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> +<div class="source"><pre> +$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 +</pre> +</div> +<p>Depuis Velocity 1.6, toutes les références à des tableaux sont "magiquement" considérées comme des listes de taille fixe. + Cela signifie que vous pouvez appeler les méthodes de java.util.List sur les références contenant des tableaux. Ainsi, si vous + avez une référence sur un tableau (mettons que celui-ci soit un tableau de String avec trois valeurs), vous pouvez écrire :</p> +<div class="source"><pre> +$myarray.isEmpty() + +$myarray.size() + +$myarray.get(2) + +$myarray.set(1, 'test') +</pre> +</div> +<p>Autre nouveauté de Velocity 1.6, la reconnaissance des méthodes à nombre variable d'arguments. Une méthode telle que + <em>public void setPlanets(String... planets)</em> ou même simplement <em>public void setPlanets(String[] planets)</em> + (si vous utilisez une version de Java antérieure au JDK5) peut maintenant accepter un nombre variable d'arguments + quand elle est appelée depuis un gabarit. + </p> +<p><a name="Recherche"><strong>Règles de recherche des méthodes</strong></a><br /> +Comme mentionné plus haut, les propriétés font souvent référence à des méthodes de l'objet parent. Velocity est relativement + malin quand il s'agit de déterminer à quelle méthode correspond une propriété demandée. Il essaye différentes alternatives + basées sur plusieurs conventions de nommage établies. L'ordre exact de recherche dépend de ce que le nom la propriété + commence ou non avec une majuscule. Pour des noms en minuscule, comme <em>$customer.address</em>, la séquence de recherche est : + <ol type="1"><li>getaddress()</li> +<li>getAddress()</li> +<li>get("address")</li> +<li>isAddress()</li> +</ol> + + Pour des noms de propriété en majuscules, comme <em>$customer.Address</em>, c'est légèrement différent : + <ol type="1"><li>getAddress()</li> +<li>getaddress()</li> +<li>get("Address")</li> +<li>isAddress()</li> +</ol> +</p> +<p><a name="Rendu"><strong>Rendu</strong></a><br /> +La valeur finale résultant de toute référence (que ce soit une variable, une propriété ou une méthode) est convertie + en objet String quand elle est intégrée à la sortie finale. S'il y a un objet qui représente <em>$foo</em> (tel qu'un objet + Integer), alors Velocity appellera sa méthode .toString() pour résoudre l'objet en une chaîne de caractère. + </p> +<p><a name="Notationformelledesré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> +<div class="source"><pre> +${mudSlinger} +${customer.Address} +${purchase.getTotal()} +</pre> +</div> +<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> +<div class="source"><pre> +Jacques est un $vicemane. +</pre> +</div> +<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> +<div class="source"><pre> +Jacques est un ${vice}mane. +</pre> +</div> +<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="Notationsilencieusedesré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> +<div class="source"><pre> +<input type="text" name="email" value="$email"/> +</pre> +</div> +<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> +<div class="source"><pre> +<input type="text" name="email" value="$!email"/> +</pre> +</div> +<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> +<div class="source"><pre> +<input type="text" name="email" value="$!{email}"/> +</pre> +</div> +</div> +<div class="section"><h2><a name="Mode_de_notation_stricte_des_références"></a>Mode de notation stricte des références</h2> +<p>Velocity 1.6 introduit le concept de références strictes, qui est activé en mettant à <em>true</em> le paramètre + de configuration Velocity <em>runtime.references.strict</em>. Dans cette configuration les références doivent + être soit placées explicitement dans le contexte, soit définies avec une directive <em>#set</em>, sinon Velocity + jettera une exception. Les références qui sont dans le contexte avec une valeur nulle ne produiront pas d'exception. + De plus, si une tentative est faite d'appeler une méthode ou une propriété sur un objet contenu dans une référence + qui ne définit pas cette méthode ou cette propriété, alors Velocity jettera une exception. Cela reste vrai pour une + tentative d'appeler une propriété ou une méthode sur une valeur nulle. + </p> +<p>Dans les exemples suivants <em>$bar</em> est défini mais pas <em>$foo</em>, et toutes ces expressions jetteront une exception :</p> +<div class="source"><pre> +$foo ## Exception +#set($bar = $foo) ## Exception +#if($foo == $bar)#end ## Exception +#foreach($item in $foo)#end ## Exception +</pre> +</div> +<p>Les expressions suivantes montrent des exemples pour lesquels Velocity jettera une exception lors d'une tentative d'appel +à des méthodes ou propriétés qui n'existent pas. Dans ces exemples, <em>$bar</em> contient un objet définissant la propriété <em>foo</em> +qui renvoie une chaîne de caractères, et la propriété <em>retnull</em> qui renvoie null.</p> +<div class="source"><pre> +$bar.bogus ## $bar does not provide property bogus, Exception +$bar.foo.bogus ## $bar.foo does not provide property bogus, Exception +$bar.retnull.bogus ## cannot call a property on null, Exception +</pre> +</div> +<p>En général ce comportement de référence stricte est vrai pour toutes les situations dans lesquelles des références sont utilisées excepté +dans un cas spécifique à l'intérieure de la directive <em>#if</em>. Si une référence est utilisée à l'intérieur d'une directive <em>#if</em> +ou <em>#elseif</em> sans méthode ou propriété, et si elle n'est pas en train d'être comparée à une autre valeur, alors les références indéfinies +sont autorisées. Ce comportement fournit un moyen simple de tester si une réference est définie avant de l'utiliser dans un gabarit. Dans +l'exemple suivant, ou <em>$foo</em> n'est pas définit, les expressions ne produiront pas d'exceptions:</p> +<div class="source"><pre> +#if ($foo)#end ## False +#if ( ! $foo)#end ## True +#if ($foo && $foo.bar)#end ## False and $foo.bar will not be evaluated +#if ($foo && $foo == "bar")#end ## False and $foo == "bar" wil not be evaluated +#if ($foo1 || $foo2)#end ## False $foo1 and $foo2 are not defined +</pre> +</div> +<p>Une remarque supplémentaire : les références à des macros indéfinies jetteront également une exception.</p> +</div> +<div class="section"><h2><a name="Substitution_de_cas"></a>Substitution de cas</h2> +<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> +<div class="source"><pre> +$foo + +$foo.getBar() +## est équivalent à +$foo.Bar + +$data.setUser("jon") +## est équivalent à +#set( $data.User = "jon" ) + +$data.getRequest().getServerName() +## est équivalent à +$data.Request.ServerName +## est équivalent à +${data.Request.ServerName} +</pre> +</div> +<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> +</div> +<div class="section"><h2><a name="Directives"></a>Directives</h2> +<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> +<p>Les directives commencent toujours par un <em>#</em>. Comme les références, le nom des directives peut être entouré + par des accolades <em>{</em> et <em>}</em>. C'est utile quand les directives sont immédiatement suivies par du texte. + Par exemple, l'expression suivante produit une erreur : + </p> +<div class="source"><pre> +#if($a==1)true ça va#elsepas question!#end +</pre> +</div> +<p>Dans ce cas, il faut utiliser des accolades pour séparer le <em>#else</em> du reste de la ligne :</p> +<div class="source"><pre> +#if($a==1)true ça va#{else}pas question!#end +</pre> +</div> +<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> +<div class="source"><pre> +#set( $primate = "monkey" ) +#set( $customer.Behavior = $primate ) +</pre> +</div> +<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 variable</li> +<li>Une chaîne de caractères littérale</li> +<li>Une propriété</li> +<li>Une méthode</li> +<li>Un nombre littéral</li> +<li>Une liste</li> +<li>Un dictionnaire</li> +</ul> +</p> +<p>Les exemples suivants montrent chacun des types susmentionnés:</p> +<div class="source"><pre> +#set( $monkey = $bill ) ## variable +#set( $monkey.Friend = "monica" ) ## chaîne de caractères littérale +#set( $monkey.Blame = $whitehouse.Leak ) ## propriété +#set( $monkey.Plan = $spindoctor.weave($web) ) ## méthode +#set( $monkey.Number = 123 ) ## nombre littéral +#set( $monkey.Say = ["Not", $my, "fault"] ) ## liste +#set( $monkey.Map = {"banana" : "good", "roast beef" : "bad"}) ## dictionnaire +</pre> +</div> +<p> + NOTE: Pour l'exemple de la liste, les éléments définis avec l'opérateur <em>[..]</em> 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 + <em>$monkey.Say.get(0)</em></p> +<p>De même, pour l'exemple du dictionnaire, les éléments définis avec l'opérateur { } sont accessibles en utilisant + les méthodes définies dans la classe Map. Ainsi, par exemple, on peut accéder au premier élément en écrivant + <em>$monkey.Map.get("banana")</em> pour retourner la chaîne 'good', ou même <em>$monkey.Map.banana</em> pour retourner + la même valeur.</p> +<p>Le membre de droite peut aussi être une expression arithmétique simple:</p> +<div class="source"><pre> +#set( $value = $foo + 1 ) +#set( $value = $bar - 1 ) +#set( $value = $foo * $bar ) +#set( $value = $foo / $bar ) +</pre> +</div> +<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> +<div class="source"><pre> +#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 +</pre> +</div> +<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> +<div class="source"><pre> +Le résultat de la première requête est bill + +Le résultat de la seconde requête est bill +</pre> +</div> +<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> +<div class="source"><pre> +#set( $criteria = ["name", "address"] ) + +#foreach( $criterion in $criteria ) + + #set( $result = $query.criteria($criterion) ) + + #if( $result ) + Query was successful + #end + +#end +</pre> +</div> +<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> +<div class="source"><pre> +#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 +</pre> +</div> +<p>Contrairement à d'autres directives Velocity, la directive <em>#set</em> n'a pas d'instruction <em>#end</em>.</p> +<a name="Chaînesdecaractèreslitté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> +<div class="source"><pre> +#set( $directoryRoot = "www" ) +#set( $templateName = "index.vm" ) +#set( $template = "$directoryRoot/$templateName" ) +$template +</pre> +</div> +<p>La sortie produite sera</p> +<div class="source"><pre> +www/index.vm +</pre> +</div> +<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> +<div class="source"><pre> +#set( $foo = "bar" ) +$foo +#set( $blargh = '$foo' ) +$blargh +</pre> +</div> +<p>Ce qui est rendu de la manière suivante:</p> +<div class="source"><pre> + bar + $foo +</pre> +</div> +<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> +<p>Ãgalement, la directive <em>#[[ ]]#</em> permet au concepteur de gabarits de facilement utiliser de gros morceaux de contenu +non interprété de code VTL. Ceci peut être particulièrement utile en remplacement de multiples <a href="#EchappementdesdirectivesVTL">échappements de directives</a>.</p> +<div class="source"><pre> +#[[ +#foreach ($woogie in $boogie) + nothing will happen to $woogie +#end +]]# +</pre> +</div> +<p>Sera rendu comme :</p> +<div class="source"><pre> +#foreach ($woogie in $boogie) + nothing will happen to $woogie +#end +</pre> +</div> +</div> +<div class="section"><h2><a name="Conditions"></a>Conditions</h2> +<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> +<div class="source"><pre> +#if( $foo ) + <strong>Velocity!</strong> +#end +</pre> +</div> +<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> +<div class="source"><pre> +#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 +</pre> +</div> +<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><a name="Opérateurslogiquesetrelationnels"><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> +<div class="source"><pre> +#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 +</pre> +</div> +<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> +<div class="source"><pre> +##ET logique + +#if( $foo && $bar ) + <strong> Ceci ET cela.</strong> +#end + +</pre> +</div> +<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> +<div class="source"><pre> +##OU logique + +#if( $foo || $bar ) + <strong>Ceci OU cela</strong> +#end +</pre> +</div> +<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> +<div class="source"><pre> +##NON logique + +#if( !$foo ) + <strong>PAS ça</strong> +#end +</pre> +</div> +<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> +<p>Il y a des versions textes de tous les opérateurs logiques, incluant <em>eq</em> (égal), <em>ne</em> (différent), +<em>and</em> (et), <em>or</em> (ou), <em>not</em> (négation), <em>gt</em> (strictement plus grand), <em>ge</em> (plus grand +ou égal), <em>lt</em> (strictement plus petit) et <em>le</em> (plus petit ou égal).</p> +<p>Une dernière remarque. Quand on souhaite inclure du texte immédiatement après une directive <em>#else</em>, on doit +utiliser des accolades directement autour de la directive pour la différencier du texte qui suit (toutes les directives +peuvent être délimitées avec des accolades, même si c'est principalement utile avec <em>#else</em>).</p> +<div class="source"><pre> +#if( $foo == $bar )C'est ça !#{else}C'est pas ça!#end +</pre> +</div> +</div> +<div class="section"><h2><a name="Boucles"></a>Boucles</h2> +<strong>Boucle Foreach</strong><p>L'élément <em>#foreach</em> permet d'itérer. Par exemple:</p> +<div class="source"><pre> +<ul> +#foreach( $product in $allProducts ) + <li>$product</li> +#end +</ul> +</pre> +</div> +<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> +<div class="source"><pre> +<ul> +#foreach( $key in $allProducts.keySet() ) + <li>Key: $key -> Value: $allProducts.get($key)</li> +#end +</ul> +</pre> +</div> +<p> + Velocity fournit un moyen simple de connaître le compteur de boucle, de sorte qu'on puisse faire quelque chose comme: + </p> +<div class="source"><pre> +<table> +#foreach( $customer in $customerList ) + <tr><td>$foreach.count</td><td>$customer.Name</td></tr> +#end +</table> +</pre> +</div> +<p>Velocity fournit aussi un moyen simple de savoir si l'on est sur la dernière itération d'une boucle :</p> +<div class="source"><pre> +#foreach( $customer in $customerList ) + $customer.Name #if( $velocityHasNext ),#end +#end +</pre> +</div> +<p>Il est possible de définir le maximum autorisé du nombre de fois qu'une boucle peut être exécutée. Par défaut il +n'y a pas de maximum (c'est indiqué par la valeur 0 ou moins), mais on peut le fixer à un nombre arbitraire dans le +fichier <code>velocity.properties</code>. Cela peut être utile comme garde-fou.</p> +<div class="source"><pre> +# The maximum allowed number of loops. +directive.foreach.maxloops = -1 +</pre> +</div> +<p>Si l'on veut arrêter de boucler depuis l'intérieur d'un <em>#foreach</em>, on peut maintenant utiliser la directive +<em>#break</em> à n'importe quelle itération de la boucle :</p> +<div class="source"><pre> +## list first 5 customers only +#foreach( $customer in $customerList ) + #if( $foreach.count > 5 ) + #break + #end + $customer.Name +#end +</pre> +</div> +</div> +<div class="section"><h2><a name="Include"></a>Include</h2> +<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> +<div class="source"><pre> +#include( "one.txt" ) +</pre> +</div> +<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> +<div class="source"><pre> +#include( "one.gif","two.txt","three.htm" ) +</pre> +</div> +<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> +<div class="source"><pre> +#include( "greetings.txt", $seasonalstock ) +</pre> +</div> +</div> +<div class="section"><h2><a name="Parse"></a>Parse</h2> +<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> +<div class="source"><pre> +#parse( "me.vm" ) +</pre> +</div> +<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> +<div class="source"><pre> +Count down. +#set( $count = 8 ) +#parse( "parsefoo.vm" ) +All done with dofoo.vm! +</pre> +</div> +<p>Il fait référence au gabarit <code>parsefoo.vm</code>, qui peut contenir le VTL suivant:</p> +<div class="source"><pre> +$count +#set( $count = $count - 1 ) +#if( $count > 0 ) + #parse( "parsefoo.vm" ) +#else + All done with parsefoo.vm! +#end +</pre> +</div> +<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> +</div> +<div class="section"><h2><a name="Stop"></a>Stop</h2> +<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> +<div class="source"><pre> +#stop +</pre> +</div> +</div> +<div class="section"><h2><a name="Evaluate"></a>Evaluate</h2> +<p>La directive <em>#evaluate</em> peut être utilisée pour évaluer dynamiquement du code VTL. Cela permet au gabarit +d'évaluer une chaîne qui est construite au moment du rendu. Une telle chaîne pourrait être utilisée pour internationaliser +le gabarit ou pour include des fragments de gabarit depuis une base de donnée.</p> +<p>L'exemple ci-dessous affiche <em>abs</em></p> +<div class="source"><pre> +#set($source1 = "abc") +#set($select = "1") +#set($dynamicsource = "$source$select") +## $dynamicsource is now the string '$source1' +#evaluate($dynamicsource) +</pre> +</div> +</div> +<div class="section"><h2><a name="Define"></a>Define</h2> +<p>La directive <em>#define</em> permet d'assigner un bloc de VTL à une référence.</p> +<p>L'exemple ci-dessous affiche <em>Hello World!</em></p> +<div class="source"><pre> +#define( $block )Hello $who#end +#set( $who = 'World!' ) +$block +</pre> +</div> +</div> +<div class="section"><h2><a name="Velocimacros"></a>Velocimacros</h2> +<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> +<div class="source"><pre> +#macro( d ) +<tr><td></td></tr> +#end +</pre> +</div> +<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> +<div class="source"><pre> +#d() +</pre> +</div> +<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> +<div class="source"><pre> +#macro( tablerows $color $somelist ) +#foreach( $something in $somelist ) + <tr><td bgcolor=$color>$something</td></tr> +#end +#end +</pre> +</div> +<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> +<div class="source"><pre> +#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] ) +#set( $color = "blue" ) +<table> + #tablerows( $color $greatlakes ) +</table> +</pre> +</div> +<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> +<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> + 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> +<div class="source"><pre> +#set( $parts = ["volva","stipe","annulus","gills","pileus"] ) +#set( $cellbgcol = "#CC00FF" ) +<table> +#tablerows( $cellbgcol $parts ) +</table> +</pre> +</div> +<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> +<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>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> +<div class="source"><pre> + #macro( callme $a ) + $a $a $a + #end + + #callme( $foo.bar() ) + </pre> +</div> +<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> +<div class="source"><pre> + #set( $myval = $foo.bar() ) + #callme( $myval ) + </pre> +</div> +<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.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> +</div> +<div class="section"><h2><a name="Sortie_littérale"></a>Sortie littérale</h2> +<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="EchapperdesréférencesVTLvalides"><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> +<div class="source"><pre> +#set( $email = "foo" ) +$email +</pre> +</div> +<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> +<div class="source"><pre> +## La ligne qui suit définit $email dans ce gabarit: +#set( $email = "foo" ) +$email +\$email +\\$email +\\\$email +</pre> +</div> +<p>sera rendu comme:</p> +<div class="source"><pre> +foo +$email +\foo +\$email +</pre> +</div> +<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> +<div class="source"><pre> +$email +\$email +\\$email +\\\$email +</pre> +</div> +<p>sera rendu comme:</p> +<div class="source"><pre> +$email +\$email +\\$email +\\\$email +</pre> +</div> +<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> +<div class="source"><pre> +#set( $foo = "gibbous" ) +$moon = $foo +</pre> +</div> +<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><a name="EchapperdesréférencesVTLvalides"><strong>Echapper des références VTL valides</strong></a><br /> +Velocity a parfois des problèmes à interpréter un gabarit quand il rencontre une "référence invalide" pour du texte + dont on n'a jamais souhaité que ce soit une référence. Ãchapper les caractères spéciaux est de nouveau le meilleur moyen + de gérer ces situations, mais le caractère <em>\</em> risque de ne pas fonctionner dans ce cas. Au lieu d'essayer de juste + échapper le caractère <em>$</em> ou <em>#</em> problématique, il faut probabement simplement remplacer : + </p> +<div class="source"><pre> +${my:invalid:non:reference} +</pre> +</div> +<p>Par :</p> +<div class="source"><pre> +#set( $D = '$' ) +${D}{my:invalid:non:reference} +</pre> +</div> +<p>Vous pouvez bien sûr mettre vos chaînes <em>$</em> et <em>#</em> directement dans le contexte depuis votre code Java (i.e. +<code>context.put("D","$");</code>) pour éviter les directives <em>#set</em> additionnelles dans vos gabarits. Ou, si vous utilisez +<a href="http://velocity.apache.org/tools/devel/"; class="externalLink">VelocityTools</a>, vous pouvez tout simplement utiliser l'outil EscapeTool comme suit :</p> +<div class="source"><pre> +${esc.d}{my:invalid:non:reference} +</pre> +</div> +<p><a name="EchappementdesdirectivesVTL">Echappement des directives VTL</a><br /> +</p> +<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> +<div class="source"><pre> +## #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" ) +</pre> +</div> +<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> +<div class="source"><pre> +#if( $jazz ) + Vyacheslav Ganelin +#end +</pre> +</div> +<p>Si <em>$jazz</em> est vrai, la sortie produite est:</p> +<div class="source"><pre> +Vyacheslav Ganelin +</pre> +</div> +<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> +<div class="source"><pre> +\#if( $jazz ) + Vyacheslav Ganelin +\#end +</pre> +</div> +<p>Que <em>$jazz</em> soit vrai ou faux, la sortie sera:</p> +<div class="source"><pre> + #if($ jazz ) + Vyacheslav Ganelin + #end +</pre> +</div> +<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> +<div class="source"><pre> +\\#if( $jazz ) + Vyacheslav Ganelin +\\#end +</pre> +</div> +<p>Dans ce cas, si <em>$jazz</em> est vrai, la sortie est</p> +<div class="source"><pre> +\ Vyacheslav Ganelin +\ +</pre> +</div> +<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, la sortie est + </p> +<div class="source"><pre> +\ +</pre> +</div> +<p> + Notons que les choses vont commencer à mal se passer + si des éléments de script ne sont pas échappés correctement. + </p> +<div class="source"><pre> +\\\#if( $jazz ) + Vyacheslave Ganelin +\\#end +</pre> +</div> +<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> +</div> +<div class="section"><h2><a name="VTL:_Questions_de_format"></a>VTL: Questions de format</h2> +<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> +<div class="source"><pre> +#set( $imperial = ["Munetaka","Koreyasu","Hisakira","Morikune"] ) +#foreach( $shogun in $imperial ) + $shogun +#end +</pre> +</div> +<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> +<div class="source"><pre> +Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a #end please. +</pre> +</div> +<p>Velocity digère les blancs inutiles. La directive qui précède peut donc s'écrire de la manière suivante:</p> +<div class="source"><pre> +Send me +#set( $foo = ["$10 and ","a cake"] ) +#foreach( $a in $foo ) +$a +#end +please. +</pre> +</div> +<p>ou encore:</p> +<div class="source"><pre> +Send me +#set($foo = ["$10 and ","a cake"]) + #foreach ($a in $foo )$a + #end please. +</pre> +</div> +<p>Dans tous les cas, la sortie sera identique.</p> +</div> +<div class="section"><h2><a name="Autres_caractéristiques_et_sujets_divers"></a>Autres caractéristiques et sujets divers</h2> +<div class="section"><h3><a name="Math"></a>Math</h3> +<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> +<div class="source"><pre> +#set( $foo = $bar + 3 ) +#set( $foo = $bar - 4 ) +#set( $foo = $bar * 6 ) +#set( $foo = $bar / 2 ) +</pre> +</div> +<p> + Lorsqu'une opération de division est exécutée entre deux entiers, le résultat sera un entier. Le reste éventuel de la division peut + être obtenu en utilisant l'opérateur modulo (<em>%</em>). + </p> +<div class="source"><pre> +#set( $foo = $bar % 5 ) +</pre> +</div> +</div> +<div class="section"><h3><a name="Opérateur_dintervalle_range"></a>Opérateur d'intervalle (range)</h3> +<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> +<div class="source"><pre> +[n..m] +</pre> +</div> +<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> +<div class="source"><pre> +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] +</pre> +</div> +<p>Produit la sortie suivante:</p> +<div class="source"><pre> +Premier exemple: +1 2 3 4 5 + +Second exemple: +2 1 0 -1 -2 + +Troisième exemple: +0 1 + +Quatrième exemple: +[1..3] +</pre> +</div> +<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> +</div> +<div class="section"><h3><a name="Questions_pointues:_Echappement_et_"></a>Questions pointues: Echappement et !</h3> +<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> +<div class="source"><pre>
[... 225 lines stripped ...]
