smarty/docs/fr/getting-started.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.7 Maintainer: didou 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 d<>limiteurs.
    </para>
   </listitem>
   <listitem>
    <para>
     Les instructions if/elseif/else/endif
     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 sections, de 'if', etc. autoris<69>e.
    </para>
   </listitem>
   <listitem>
    <para>
     Il est possible d'inclure du code PHP
     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 cache int<6E>gr<67>.
    </para>
   </listitem>
   <listitem>
    <para>
     Sources de templates arbitraires.
    </para>
   </listitem>
   <listitem>
    <para>
     Fonctions de gestion de cache personnalisables.
    </para>
   </listitem>
   <listitem>
    <para>
     Architecture de plugins
    </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 r<>pertoire
    /libs/ 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 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)
]]>
    </screen>   
   </example>
   
   <para>
    Smarty utilise une constante PHP appel<65>e <link
    linkend="constant.smarty.dir">SMARTY_DIR</link> qui
    repr<70>sente le chemin complet 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 SMARTY_DIR, 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 SMARTY_DIR explicitement. SMARTY_DIR
    <emphasis>doit</emphasis> avoir <20>tre termin<69> par un slash.
   </para>
   
   <para>
    Voici comment cr<63>er une instance de Smarty dans vos scripts PHP :
   </para>
   
   <example>
    <title>cr<EFBFBD>er une instance de Smarty</title>
    <programlisting role="php">
<![CDATA[
<?php
require('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>fournir un chemin absolu vers la biblioth<74>que Smarty</title>
    <programlisting role="php">
<![CDATA[
<?php
require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty;
?>
]]>
    </programlisting>
   </example>
   
   <example>
    <title>Ajouter le r<>pertoire de la biblioth<74>que dans l'include_path de PHP</title>
    <programlisting role="php">
<![CDATA[
<?php
// Editez votre fichier php.ini file, ajoutez le chemin de la 
// biblioth<74>que Smarty et red<65>marrez les serveur web.
// la ligne suivante doit alors fonctionner :
require('Smarty.class.php');
$smarty = new Smarty;
?>
]]>
    </programlisting>
   </example>
   
   <example>
    <title>D<EFBFBD>finir explicitement la constante SMARTY_DIR</title>
    <programlisting role="php">
<![CDATA[
<?php
define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
require(SMARTY_DIR . '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.
    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>. Chacun d'entre eux peut <20>tre d<>fini
    via les attributs <varname>$template_dir</varname>,
    <varname>$compile_dir</varname>, <varname>$config_dir</varname> et
    <varname>$cache_dir</varname> 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 "livredor" 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
    <filename>index.php</filename> 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 "index.php" soit identifi<66> comme fichier
     par d<>faut de ce r<>pertoire. Aicnsi, si l'on tape
     "http://www.example.com/livredor/", le script index.php soit
     ex<65>cut<75> sans que "index.php" ne soit sp<73>cifi<66> dans l'URL. Avec Apache
     vous pouvez r<>gler cel<65> en ajoutant "index.php" <20> la ligne o<> se
     trouve DirectoryIndex (s<>parez chaque entr<74>e par un espace).
    </para>
   </note>
   <para>
    Jetons un coup d'oeil <20> la structure de fichier obtenue :
   </para>
   
   <example>
    <title>exemple de structure de fichiers</title>
    <screen>
<![CDATA[
/usr/local/lib/php/Smarty/Smarty.class.php
/usr/local/lib/php/Smarty/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty/Config_File.class.php
/usr/local/lib/php/Smarty/debug.tpl
/usr/local/lib/php/Smarty/internals/*.php
/usr/local/lib/php/Smarty/plugins/*.php

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

/web/www.example.com/docs/livredor/index.php
]]>
    </screen>
   </example>
   
   <para>
    Smarty a besoin d'acc<63>der en <20>criture aux r<>pertoires
    <emphasis>$compile_dir</emphasis> et <emphasis>$cache_dir</emphasis>,
    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 httpd.conf (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 technique</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 index.tpl que Smarty va charger.
    Il va se trouver dans $template_dir.
   </para>
   
   <example>
    <title>Edition de  /web/www.example.com/smarty/templates/index.tpl</title>
    <screen>
<![CDATA[

{* Smarty *}

Hello, {$name}!
]]>
    </screen>
   </example>
   
   
   <note>
    <title>Note technique</title>
    <para>
     {* Smarty *} est un commentaire 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 index.php. Nous allons
    cr<63>er une instance de Smarty, assigner une valeur <20> une variable
    de template et afficher le r<>sultat avec index.tpl. Dans notre
    exemple d'environnement, "/usr/local/lib/php/Smarty" est dans notre
    include_path. Assurez-vous de faire la m<>me chose ou d'utiliser
    des chemins absolus.
   </para>
   
   <example>
    <title><EFBFBD>dition de  /web/www.example.com/docs/livredor/index.php</title>
    <screen>
<![CDATA[
<?php     
    // charge la biblioth<74>que Smarty
     require('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');
?>
]]>
    </screen>
   </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 "Hello, Ned!".
   </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
    "/php/includes/livredor/" et un nouveau fichier appel<65> <filename>setup.php</filename>.
    Dans notre exemple d'environnement, "/php/includes" 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 index.php pour qu'il utilise "setup.php"
   </para>
   
   <example>
    <title>Edition 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 Smarty_livredor 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
-->