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écisément, il facilite
   la séparation entre la logique applicative et la présentation.
   Celà s'explique plus facilement dans une situation où le
   programmeur et le designer de templates jouent des rôles diffé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 éléments de contenu, ils ne contiennent aucune information
   concernant la présentation. Ils sont transmis à Smarty par l'application,
   puis le designer de templates éditent les templates et utilisent une
   combinaison de balises HTML et de balises de templates pour formater
   la présentation de ces éléments (tableaux HTML, couleurs d'arrière-plan,
   tailles des polices, feuilles de styles, etc.). Un beau jour le programmeur
   a besoin de changer la façon dont le contenu de l'article
   est récupéré (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çon. De même, si le
   le designer de templates veut changer complé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ésentation. Celà signifie que les templates peuvent contenir 
   des traitements, du moment qu'il soit relatif à de la présentation.
   Inclure d'autres templates, alterner les couleurs des lignes 
   d'un tableau, mettre du texte en majuscule, parcourir un tableau de données
   pour l'afficher, etc. sont toutes des actions relatives à du traitement
   de présentation. Celà ne signifie pas que Smarty requiert une telle séparation
   de votre part. Smarty ne sais pas quoi est quoi, c'est donc à vous de placer
   la logique de pré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à signifie que Smarty lit les templates et crée des scripts PHP à partir
   de ces derniers. Une fois créés, ils sont exécutés.
   Il n'y a donc pas d'analyse coûteuse de template à chaque requête,
   et les templates peuvent béné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éristiques de Smarty :
  </para>
  <itemizedlist>
   <listitem>
    <para>
     Il est trè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ûteuse, une seule compilation.
    </para>
   </listitem>
   <listitem>
    <para>
     Il sait ne recompiler que les fichiers de templates qui ont été modifiés.
    </para>
   </listitem>
   <listitem>
    <para>
     Vous pouvez créer des <link linkend="language.custom.functions">
     fonctions utilisateurs</link> et des <link linkend="language.modifiers">
     modificateurs de variables</link> personnalisés, le langage de
     template est donc extré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ées au parser PHP, la syntaxe de l'expression {if...}
     peut être aussi simple ou aussi complexe que vous
     le désirez.
    </para>
   </listitem>
   <listitem>
    <para>
     Imbrication illimitée de sections, de 'if', etc. autorisée.
    </para>
   </listitem>
   <listitem>
    <para>
     Il est possible d'inclure du code PHP
     directement dans vos templates, bien que celà ne soit pas obligatoire
     (ni conseillé), vû que le moteur est extensible.
    </para>
   </listitem>
   <listitem>
    <para>
     Support de cache intégré.
    </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érieur.
   </para>
  </sect1>
  
  <sect1 id="installing.smarty.basic">
   <title>Installation de base</title>
   <para>
    Copiez les fichiers bibliothèques de Smarty du répertoire
    /libs/ de la distribution à un emplacement accessible à PHP.
    Ce sont des fichiers PHP que vous NE DEVEZ PAS
    modifier. Ils sont partagés par toutes les applications et ne seront
    mis à jour que lorsque vous installerez une nouvelle version de
    Smarty.
   </para>
   <example>
    <title>fichiers de la bibliothè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ée <link
    linkend="constant.smarty.dir">SMARTY_DIR</link> qui
    représente le chemin complet de la bibliothè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 à votre application, vous
    devez définir SMARTY_DIR explicitement. SMARTY_DIR
    <emphasis>doit</emphasis> avoir être terminé par un slash.
   </para>
   
   <para>
    Voici comment créer une instance de Smarty dans vos scripts PHP :
   </para>
   
   <example>
    <title>cré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é,
    tentez l'une des actions suivantes :
   </para>
   
   <example>
    <title>fournir un chemin absolu vers la bibliothè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è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èque Smarty et redémarrez les serveur web.
// la ligne suivante doit alors fonctionner :
require('Smarty.class.php');
$smarty = new Smarty;
?>
]]>
    </programlisting>
   </example>
   
   <example>
    <title>Dé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 ê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é que vous régliez ces répertoires séparément pour chaque
    application qui utilise Smarty.
   </para>
   <para>
    Assurez-vous de bien connaî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ède aux répertoires en question, et jamais le serveur Web.
    Pour des raisons de sécurité, il est donc conseillé 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 é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 à la racine de
    l'arborescence Web,
    il s'agit du script auquel l'internaute a accès. Nous allons l'appeler
    <filename>index.php</filename> et le placer dans un sous-répertoire
    appelé <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é 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écuté sans que "index.php" ne soit spécifié dans l'URL. Avec Apache
     vous pouvez régler celà en ajoutant "index.php" à la ligne où se
     trouve DirectoryIndex (séparez chaque entrée par un espace).
    </para>
   </note>
   <para>
    Jetons un coup d'oeil à 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éder en é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ès.
    Il s'agit géné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éral dans
    "/usr/local/apache/conf/") pour déterminer quel est l'utilisateur
    et le groupe auquel il appartient.
   </para>
   
   <example>
    <title>régler les permissions d'accè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ée, elle donne
     à l'utilisateur "nobody" et au groupe "nobody" les accès en
     lecture/écriture aux répertoires. Si vous voulez donner le droit d'accès
     en lecture à tout le monde (principalement pour pouvoir accéder
     vous-même à ces fichiers), vous pouvez lui préférer chmod 775.
    </para>
   </note>
   
   <para>
    Nous devons cré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à rend le fichier facilement
     reconnaissable en plus de son extension. Les éditeurs
     de texte peuvent par exemple reconnaître le fichier et
     adapter la coloration syntaxique.
    </para>
   </note>
   
   <para>
    Maintenant passons à l'édition du fichier index.php. Nous allons
    créer une instance de Smarty, assigner une valeur à 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>édition de  /web/www.example.com/docs/livredor/index.php</title>
    <screen>
<![CDATA[
<?php     
    // charge la bibliothè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é 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érience)
     moins générateur d'erreurs de les définir avec des chemins
     absolus. Celà nous garantit que Smarty récupè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ée</title>
   
   <para>
    Ceci est la suite de <link
    linkend="installing.smarty.basic">l'installation de base</link>, veuillez
    lire cette dernière avant de poursuivre.
   </para>
   
   <para>
    Une maniè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 à chaques fois les
    chemins de notre environnement. Créons un nouveau répertoire
    "/php/includes/livredor/" et un nouveau fichier appelé <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>é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à juste ici. Par exemple :
     // require('livredor/livredor.lib.php');
     
     class Smarty_livredor extends Smarty {
     
     function Smarty_livredor() {
     
     // Constructeur de la classe. 
     // Appelé automatiquement à 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éer une instance de Smarty,
    correctement configuré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
-->