smarty/docs/fr/getting-started.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.6 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.
   Cela 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.
   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. Cela 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. Cela 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 NE d<>sirez PAS
   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.
   Cela 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 cela ne soit pas obligatoire
   (ni conseill<6C>), vu 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
    <emphasis>Smarty.class.php</emphasis>, vous n'aurez pas
    besoin de d<>finir la variable SMARTY_DIR, Smarty s'en chargera pour vous.
    En revanche, si <emphasis>Smarty.class.php</emphasis>
    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 <emphasis>Smarty.class.php</emphasis> 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)
    <emphasis>templates</emphasis>,
    <emphasis>templates_c</emphasis>, <emphasis>configs</emphasis> et
    <emphasis>cache</emphasis>. Chacun d'entre eux peut <20>tre d<>fini
    via les attributs <emphasis>$template_dir</emphasis>,
    <emphasis>$compile_dir</emphasis>, <emphasis>$config_dir</emphasis> et
    <emphasis>$cache_dir</emphasis> 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 "/web/www.mydomain.com/docs". 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
    "/web/www.mydomain.com/smarty/livredor/".
   </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
    "index.php" et le placer dans un sous-r<>pertoire
    appel<65> "/livredor/". 
   </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.mydomain.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 cela 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.mydomain.com/smarty/livredor/templates/
/web/www.mydomain.com/smarty/livredor/templates_c/
/web/www.mydomain.com/smarty/livredor/configs/
/web/www.mydomain.com/smarty/livredor/cache/

/web/www.mydomain.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.mydomain.com/smarty/livredor/templates_c/
chmod 770 /web/www.mydomain.com/smarty/livredor/templates_c/

chown nobody:nobody /web/www.mydomain.com/smarty/livredor/cache/
chmod 770 /web/www.mydomain.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.mydomain.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. Cela 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.mydomain.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.mydomain.com/smarty/livredor/templates/';
     $smarty->compile_dir = '/web/www.mydomain.com/smarty/livredor/templates_c/';
     $smarty->config_dir = '/web/www.mydomain.com/smarty/livredor/configs/';
     $smarty->cache_dir = '/web/www.mydomain.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
     '/web/www.mydomain.com/smarty/livredor/' 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. Cela nous garantit que Smarty r<>cup<75>rera les bons fichiers.
    </para>
   </note>
   
   <para>
    Et maintenant appelez le fichier index.php 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> "setup.php".
    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 cela 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.mydomain.com/smarty/livredor/templates/';
     $this->compile_dir = '/web/www.mydomain.com/smarty/livredor/templates_c/';
     $this->config_dir = '/web/www.mydomain.com/smarty/livredor/configs/';
     $this->cache_dir = '/web/www.mydomain.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><EFBFBD>dition de /web/www.mydomain.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
-->