smarty/docs/fr/getting-started.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.15 Maintainer: yannick Status: ready -->

<part id="getting.started">
 <title>Pour commencer</title>

 <chapter id="what.is.smarty">
  <title>Qu'est-ce que Smarty ?</title>
  <para>
   Smarty est un moteur de template pour PHP. Plus pr<70>cis<69>ment, il facilite
   la s<>paration entre la logique applicative et la pr<70>sentation.
   Cel<65> s'explique plus facilement dans une situation o<> le
   programmeur et le designer de templates jouent des r<>les diff<66>rents, ou,
   comme la plupart du temps, sont deux personnes distinctes.
  </para>
  <para>
   Supposons par exemple que vous concevez une page Web qui affiche un
   article de newsletter. Le titre, le sous-titre, l'auteur et le corps
   sont des <20>l<EFBFBD>ments de contenu, ils ne contiennent aucune information
   concernant la pr<70>sentation. Ils sont transmis <20> Smarty par l'application,
   puis le designer de templates <20>ditent les templates et utilisent une
   combinaison de balises HTML et de balises de templates pour formater
   la pr<70>sentation de ces <20>l<EFBFBD>ments (tableaux HTML, couleurs d'arri<72>re-plan,
   tailles des polices, feuilles de styles, etc.). Un beau jour le programmeur
   a besoin de changer la fa<66>on dont le contenu de l'article
   est r<>cup<75>r<EFBFBD> (un changement dans la logique applicative). Ce
   changement n'affecte pas le designer de templates, le contenu
   arrivera toujours au template de la m<>me fa<66>on. De m<>me, si le
   le designer de templates veut changer compl<70>tement l'apparence
   du template, aucun changement dans la logique de l'application
   n'est n<>cessaire. Ainsi le programmeur peut changer la logique
   de l'application sans restructurer les templates, et le designer
   de templates peut changer les templates sans briser la logique
   applicative.
  </para>
  <para>
   Un des objectifs de Smarty est la s<>paration de la logique m<>tier de la 
   logique de pr<70>sentation. Cel<65> signifie que les templates peuvent contenir 
   des traitements, du moment qu'il soit relatif <20> de la pr<70>sentation.
   Inclure d'autres templates, alterner les couleurs des lignes 
   d'un tableau, mettre du texte en majuscule, parcourir un tableau de donn<6E>es
   pour l'afficher, etc. sont toutes des actions relatives <20> du traitement
   de pr<70>sentation. Cel<65> ne signifie pas que Smarty requiert une telle s<>paration
   de votre part. Smarty ne sais pas quoi est quoi, c'est donc <20> vous de placer
   la logique de pr<70>sentation dans vos templates. Ainsi, si vous 
   <emphasis>ne d<>sirez pas</emphasis>
   disposer de logique m<>tier dans vos templates, placez tous vos contenus
   dans des variables au format texte uniquement.
  </para>
  <para>
   L'un des aspects unique de Smarty est la compilation des templates.
   Cel<65> signifie que Smarty lit les templates et cr<63>e des scripts PHP <20> partir
   de ces derniers. Une fois cr<63><72>s, ils sont ex<65>cut<75>s.
   Il n'y a donc pas d'analyse co<63>teuse de template <20> chaque requ<71>te,
   et les templates peuvent b<>n<EFBFBD>ficier des solutions de cache PHP
   comme Zend Accelerator (<ulink url="&url.zend;">&url.zend;</ulink>) ou
   PHP Accelerator
   (<ulink url="&url.php-accelerator;">&url.php-accelerator;</ulink>).
  </para>
  <para>
   Quelques caract<63>ristiques de Smarty :
  </para>
  <itemizedlist>
   <listitem>
    <para>
     Il est tr<74>s rapide.
    </para>
   </listitem>
   <listitem>
    <para>
     Il est efficace, le parser PHP s'occupe du sale travail.
    </para>
   </listitem>
   <listitem>
    <para>
     Pas d'analyse de template co<63>teuse, une seule compilation.
    </para>
   </listitem>
   <listitem>
    <para>
     Il sait ne recompiler que les fichiers de templates qui ont <20>t<EFBFBD> modifi<66>s.
    </para>
   </listitem>
   <listitem>
    <para>
     Vous pouvez cr<63>er des <link linkend="language.custom.functions">
     fonctions utilisateurs</link> et des <link linkend="language.modifiers">
     modificateurs de variables</link> personnalis<69>s, le langage de
     template est donc extr<74>mement extensible.
    </para>
   </listitem>
   <listitem>
    <para>
     Syntaxe des templates configurable, vous
     pouvez utiliser {}, {{}}, &lt;!--{}--&gt;, etc. comme 
     <link linkend="variable.left.delimiter">d<EFBFBD>limiteurs tag</link>.
    </para>
   </listitem>
   <listitem>
    <para>
     Les instructions <link
     linkend="language.function.if">if/elseif/else/endif</link>
     sont pass<73>es au parser PHP, la syntaxe de l'expression {if...}
     peut <20>tre aussi simple ou aussi complexe que vous
     le d<>sirez.
    </para>
   </listitem>
   <listitem>
    <para>
     Imbrication illimit<69>e de <link linkend="language.function.section">sections</link>, de 'if', etc. autoris<69>e.
    </para>
   </listitem>
   <listitem>
    <para>
     Il est possible d'inclure du <link linkend="language.function.php">code PHP</link>
     directement dans vos templates, bien que cel<65> ne soit pas obligatoire
     (ni conseill<6C>), v<> que le moteur est extensible.
    </para>
   </listitem>
   <listitem>
    <para>
     Support de <link linkend="caching">cache</link> int<6E>gr<67>.
    </para>
   </listitem>
   <listitem>
    <para>
     Sources de <link
     linkend="template.resources">templates</link> arbitraires.
    </para>
   </listitem>
   <listitem>
    <para>
     Fonctions de <link
     linkend="section.template.cache.handler.func">gestion de cache</link> personnalisables.
    </para>
   </listitem>
   <listitem>
    <para>
     Architecture de <link linkend="plugins">plugins</link>
    </para>
   </listitem>
  </itemizedlist>
 </chapter>

 <chapter id="installation">
  <title>Installation</title>

  <sect1 id="installation.requirements">
   <title>Ce dont vous avez besoin</title>
   <para>
    Smarty n<>cessite un serveur Web utilisant PHP 4.0.6 ou sup<75>rieur.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
   <title>Installation de base</title>
   <para>
    Copiez les fichiers biblioth<74>ques de Smarty du sous-dossier
    <filename>/libs/</filename> de la distribution <20> un emplacement
    accessible <20> PHP. Ce sont des fichiers PHP que vous NE DEVEZ PAS
    modifier. Ils sont partag<61>s par toutes les applications et ne seront
    mis <20> jour que lorsque vous installerez une nouvelle version de
    Smarty.
   </para>
   <example>
    <title>fichiers n<>cessaires de la biblioth<74>que SMARTY</title>
    <screen>
<![CDATA[
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/internals/*.php (tous)
/plugins/*.php (tous doivent <20>tre s<>r, peut-<2D>tre votre site n'a besoin seulement que d'un sous-ensemble)
]]>
    </screen>
   </example>

   <para>
    Smarty utilise une <ulink url="&url.php-manual;define">constante</ulink> PHP appel<65>e <link
    linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link> qui
    repr<70>sente le <emphasis role="bold">chemin complet</emphasis> de la biblioth<74>que Smarty.
    En fait, si votre application trouve le fichier
    <filename>Smarty.class.php</filename>, vous n'aurez pas
    besoin de d<>finir la variable
    <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>,
    Smarty s'en chargera pour vous.
    En revanche, si <filename>Smarty.class.php</filename>
    n'est pas dans votre r<>pertoire d'inclusion ou que vous ne
    donnez pas un chemin absolu <20> votre application, vous
    devez d<>finir <constant>SMARTY_DIR</constant> explicitement.
    <constant>SMARTY_DIR</constant>
    <emphasis role="bold">doit</emphasis> avoir <20>tre termin<69> par un slash.
   </para>

   <example>
    <title>Cr<EFBFBD>er une instance de Smarty</title>
    <para>
     Voici comment cr<63>er une instance de Smarty dans vos scripts PHP :
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Note : Smarty a un 'S' majuscule
require_once('Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <para>
    Essayez de lancer le script ci-dessus. Si vous obtenez une erreur indiquant
    que le fichier <filename>Smarty.class.php</filename> n'est pas trouv<75>,
    tentez l'une des actions suivantes :
   </para>

   <example>
    <title>D<EFBFBD>finition manuelle de la constante SMARTY_DIR</title>
    <programlisting role="php">
<![CDATA[
<?php
// Style *nix (notez le 'S' majuscule)
define('SMARTY_DIR', '/usr/local/lib/php/Smarty-v.e.r/libs/');

// Style Windows
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>D<EFBFBD>finir le chemin absolu au fichier de la biblioth<74>que</title>
    <programlisting role="php">
<![CDATA[
<?php
// Style *nix (notez le 'S' majuscule)
require_once('/usr/local/lib/php/Smarty-v.e.r/libs/Smarty.class.php');

// Style Windows
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');

$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Ajout du dossier contenant la biblioth<74>que <20> l'include_path de PHP</title>
    <programlisting role="php">
<![CDATA[
<?php
// Editez votre fichier php.ini, ajoutez le dossier contenant la
// biblioth<74>que Smarty <20> l'include_path et red<65>marrez le serveur web.
// Puis, ce qui suit devrait fonctionner :
require_once('Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <para>
    Maintenant que les fichiers de la librairie sont en place,
    il est temps de d<>finir les r<>pertoires de Smarty, pour votre application.
   </para>
   <para>
    Smarty a besoin de quatre r<>pertoires qui sont, par d<>faut,
    <filename class="directory">'templates/'</filename>,
    <filename class="directory">'templates_c/'</filename>,
    <filename class="directory">'configs/'</filename> et
    <filename class="directory">'cache/'</filename>.
   </para>
   <para>
    Chacun d'entre eux peut <20>tre d<>fini
    via les attributs <link linkend="variable.template.dir">
    <varname>$template_dir</varname></link>,
    <link linkend="variable.compile.dir">
    <varname>$compile_dir</varname></link>, <link linkend="variable.config.dir">
    <varname>$config_dir</varname></link> et
    <link linkend="variable.cache.dir">
    <varname>$cache_dir</varname></link> respectivement. Il est vivement
    conseill<6C> que vous r<>gliez ces r<>pertoires s<>par<61>ment pour chaque
    application qui utilise Smarty.
   </para>
   <para>
    Assurez-vous de bien conna<6E>tre chemin de la racine
    de votre arborescence Web. Dans notre exemple, la racine
    est <filename 
    class="directory">/web/www.example.com/docs/</filename>. Seul Smarty
    acc<63>de aux r<>pertoires en question, et jamais le serveur Web.
    Pour des raisons de s<>curit<69>, il est donc conseill<6C> de
    sortir ces r<>pertoires dans un r<>pertoire
    <emphasis>en dehors</emphasis> de l'arborescence
    Web.
   </para>
   <para>
    Dans notre exemple d'installation, nous allons r<>gler l'environnement
    de Smarty pour une application de livre d'or. Nous avons ici choisi
    une application principalement pour mettre en <20>vidence une
    convention de nommage des r<>pertoires. Vous pouvez utiliser le m<>me
    environnement pour n'importe quelle autre application, il suffit de
    remplacer <quote>livredor</quote> avec le nom de votre application.
    Nous allons mettre nos r<>pertoires Smarty dans
    <filename 
    class="directory">/web/www.example.com/smarty/livredor/</filename>.
   </para>
   <para>
    Vous allez avoir besoin d'au moins un fichier <20> la racine de
    l'arborescence Web,
    il s'agit du script auquel l'internaute a acc<63>s. Nous allons l'appeler
    <emphasis>'index.php'</emphasis> et le placer dans un sous-r<>pertoire
    appel<65> <filename class="directory">/livredor/</filename>.
   </para>

   <note>
    <title>Technical Note</title>
    <para>
     Il est pratique de configurer le serveur Web de
     sorte que <filename>index.php</filename> soit identifi<66> comme fichier
     par d<>faut de ce r<>pertoire. Aicnsi, si l'on tape
     <literal>http://www.example.com/livredor/</literal>, le script
     <filename>index.php</filename> soit ex<65>cut<75> sans que
     <filename>index.php</filename> ne soit sp<73>cifi<66> dans l'URL. Avec
     Apache, vous pouvez r<>gler cela en ajoutant <filename>index.php</filename>
     <20> la ligne o<> se trouve <literal>DirectoryIndex</literal> (s<>parez chaque entr<74>e
     par un espace) dans le <filename>httpd.conf</filename>.
     <informalexample>
      <programlisting>
<![CDATA[DirectoryIndex index.htm index.html index.cgi index.php]]>
      </programlisting>
     </informalexample>
    </para>
   </note>
   <para>
    Jetons un coup d'oeil <20> la structure de fichier obtenue :
   </para>

   <example>
    <title>Structure de fichiers</title>
    <screen>
<![CDATA[
/usr/local/lib/php/Smarty-v.e.r/libs/Smarty.class.php
/usr/local/lib/php/Smarty-v.e.r/libs/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty-v.e.r/libs/Config_File.class.php
/usr/local/lib/php/Smarty-v.e.r/libs/debug.tpl
/usr/local/lib/php/Smarty-v.e.r/libs/internals/*.php
/usr/local/lib/php/Smarty-v.e.r/libs/plugins/*.php

/web/www.example.com/smarty/guestbook/templates/
/web/www.example.com/smarty/guestbook/templates_c/
/web/www.example.com/smarty/guestbook/configs/
/web/www.example.com/smarty/guestbook/cache/

/web/www.example.com/docs/guestbook/index.php
]]>
    </screen>
   </example>

   <para>
    Smarty a besoin d'<emphasis role="bold">acc<EFBFBD>der en <20>criture</emphasis>
    aux r<>pertoires <link linkend="variable.compile.dir">
     <parameter>$compile_dir</parameter></link> et <link linkend="variable.cache.dir">
     <parameter>$cache_dir</parameter></link>,
    assurez-vous donc que le serveur Web dispose de ces droits d'acc<63>s.
    Il s'agit g<>n<EFBFBD>ralement de l'utilisateur "nobody" et du group
    "nobody". Pour les utilisateurs de OS X, l'utilisateur par d<>faut
    est "web" et le group "web". Si vous utilisez Apache, vous pouvez
    parcourir le fichier <filename>httpd.conf</filename> (en g<>n<EFBFBD>ral dans
    "/usr/local/apache/conf/") pour d<>terminer quel est l'utilisateur
    et le groupe auquel il appartient.
   </para>

   <example>
    <title>r<EFBFBD>gler les permissions d'acc<63>s</title>
    <programlisting role="shell">
<![CDATA[
chown nobody:nobody /web/www.example.com/smarty/livredor/templates_c/
chmod 770 /web/www.example.com/smarty/livredor/templates_c/

chown nobody:nobody /web/www.example.com/smarty/livredor/cache/
chmod 770 /web/www.example.com/smarty/livredor/cache/
]]>
    </programlisting>
   </example>

   <note>
    <title>Note</title>
    <para>
     La commande chmod 770 est relativement bien s<>curis<69>e, elle donne
     <20> l'utilisateur "nobody" et au groupe "nobody" les acc<63>s en
     lecture/<2F>criture aux r<>pertoires. Si vous voulez donner le droit d'acc<63>s
     en lecture <20> tout le monde (principalement pour pouvoir acc<63>der
     vous-m<>me <20> ces fichiers), vous pouvez lui pr<70>f<EFBFBD>rer chmod 775.
    </para>
   </note>

   <para>
    Nous devons cr<63>er le fichier <filename>index.tpl</filename> que Smarty va charger.
    Il va se trouver dans le dossier
    <link linkend="variable.template.dir"><parameter>$template_dir</parameter></link>.
   </para>

   <example>
    <title>Notre  /web/www.example.com/smarty/templates/index.tpl</title>
    <screen>
<![CDATA[

{* Smarty *}

Bonjour, {$name}, Bienvenue dans Smarty !
]]>
    </screen>
   </example>


   <note>
    <title>Note technique</title>
    <para>
     <literal>{* Smarty *}</literal> est un
     <link linkend="language.syntax.comments">commentaire</link>
     de template. Il n'est pas obligatoire mais il est bon de commencer tous vos templates
     avec ce commentaire. Cel<65> rend le fichier facilement
     reconnaissable en plus de son extension. Les <20>diteurs
     de texte peuvent par exemple reconna<6E>tre le fichier et
     adapter la coloration syntaxique.
    </para>
   </note>

   <para>
    Maintenant passons <20> l'<27>dition du fichier <filename>index.php</filename>. Nous allons
    cr<63>er une instance de Smarty,
    <link linkend="api.assign"><varname>assigner</varname></link>
    une valeur <20> une variable de template et
    <link linkend="api.display">afficher</link> le r<>sultat avec <filename>index.tpl</filename>.
   </para>

   <example>
    <title><EFBFBD>dition de  /web/www.example.com/docs/livredor/index.php</title>
    <programlisting role="php">
<![CDATA[
<?php
// charge la biblioth<74>que Smarty
require_once(SMARTY_DIR . 'Smarty.class.php');

$smarty = new Smarty();

$smarty->template_dir = '/web/www.example.com/smarty/livredor/templates/';
$smarty->compile_dir = '/web/www.example.com/smarty/livredor/templates_c/';
$smarty->config_dir = '/web/www.example.com/smarty/livredor/configs/';
$smarty->cache_dir = '/web/www.example.com/smarty/livredor/cache/';

$smarty->assign('name','Ned');

$smarty->display('index.tpl');
?>
]]>
    </programlisting>
   </example>

   <note>
    <title>Note techique</title>
    <para>
     Dans notre exemple, nous avons configur<75> les chemins absolus
     pour chacun des r<>pertoires Smarty. Si
     <filename
     class="directory">/web/www.example.com/smarty/livredor/</filename>
     est dans votre include_path PHP alors ces r<>glages ne sont pas n<>cessaires.
     Quoi qu'il en soit, il est plus efficace et (par exp<78>rience)
     moins g<>n<EFBFBD>rateur d'erreurs de les d<>finir avec des chemins
     absolus. Cel<65> nous garantit que Smarty r<>cup<75>rera les bons fichiers.
    </para>
   </note>

   <para>
    Et maintenant appelez le fichier <filename>index.php</filename> avec navigateur
    Web. Vous devriez voir "Bonjour, Ned, Bienvenue dans Smarty !".
   </para>
   <para>
    Vous venez de terminer l'installation de base de Smarty !
   </para>
  </sect1>
  <sect1 id="installing.smarty.extended">
   <title>Configuration avanc<6E>e</title>

   <para>
    Ceci est la suite de <link
    linkend="installing.smarty.basic">l'installation de base</link>, veuillez
    lire cette derni<6E>re avant de poursuivre.
   </para>

   <para>
    Une mani<6E>re un peu plus commode de configurer Smarty est de faire votre
    propre classe fille et de l'initialiser selon votre environnement.
    De la sorte, nous n'aurons plus besoin de configurer <20> chaques fois les
    chemins de notre environnement. Cr<43>ons un nouveau r<>pertoire
    <filename>/php/includes/livredor/</filename> et un nouveau fichier
    appel<65> <filename>setup.php</filename>.
    Dans notre exemple d'environnement, <filename>/php/includes</filename> est notre
    include_path PHP. Assurez-vous de faire la m<>me chose ou alors d'utiliser
    des chemins absolus.
   </para>

   <example>
    <title><EFBFBD>dition de /php/includes/livredor/setup.php</title>
    <programlisting role="php">
<![CDATA[
<?php
// charge la librairie Smarty
require('Smarty.class.php');

// le fichier setup.php est un bon
// endroit pour charger les fichiers
// de librairies de l'application et vous pouvez
// faire cel<65> juste ici. Par exemple :
// require('livredor/livredor.lib.php');

class Smarty_livredor extends Smarty {

 function Smarty_livredor() {

 // Constructeur de la classe.
 // Appel<65> automatiquement <20> l'instanciation de la classe.

 $this->Smarty();

 $this->template_dir = '/web/www.example.com/smarty/livredor/templates/';
 $this->compile_dir = '/web/www.example.com/smarty/livredor/templates_c/';
 $this->config_dir = '/web/www.example.com/smarty/livredor/configs/';
 $this->cache_dir = '/web/www.example.com/smarty/livredor/cache/';

 $this->caching = true;
 $this->assign('app_name', 'Guest Book');
 }

}
?>
]]>
    </programlisting>
   </example>

   <para>
    Modifions maintenant le fichier <filename>index.php</filename> pour qu'il utilise 
    <filename>setup.php</filename>
   </para>

   <example>
    <title><EFBFBD>dition de /web/www.example.com/docs/livredor/index.php</title>
    <programlisting role="php">
<![CDATA[
<?php
require('livredor/setup.php');

$smarty = new Smarty_livredor();

$smarty->assign('name','Ned');

$smarty->display('index.tpl');

?>
]]>
    </programlisting>
   </example>

   <para>
    Vous savez maintenant qu'il est facile de cr<63>er une instance de Smarty,
    correctement configur<75>e, en utilisant <literal>Smarty_livredor()</literal>
    qui initialise automatiquement tout ce qu'il faut pour votre application.
   </para>

  </sect1>

 </chapter>
</part>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->