/documentation/fr/getting-started.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision: 2972 $ -->
<!-- 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é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.
  </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 
     <link linkend="variable.left.delimiter">délimiteurs tag</link>.
    </para>
   </listitem>
   <listitem>
    <para>
     Les instructions <link
     linkend="language.function.if">if/elseif/else/endif</link>
     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 <link linkend="language.function.section">sections</link>, de 'if', etc. autorisé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à ne soit pas obligatoire
     (ni conseillé), vû que le moteur est extensible.
    </para>
   </listitem>
   <listitem>
    <para>
     Support de <link linkend="caching">cache</link> intégré.
    </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érieur.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
   <title>Installation de base</title>
   <para>
    Copiez les fichiers bibliothèques de Smarty du sous-dossier
    <filename>/libs/</filename> 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 nécessaires 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 doivent être sûr, peut-ê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ée <link
    linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link> qui
    représente le <emphasis role="bold">chemin complet</emphasis> 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
    <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 à votre application, vous
    devez définir <constant>SMARTY_DIR</constant> explicitement.
    <constant>SMARTY_DIR</constant>
    <emphasis role="bold">doit</emphasis> avoir être terminé par un slash.
   </para>

   <example>
    <title>Créer une instance de Smarty</title>
    <para>
     Voici comment cré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é,
    tentez l'une des actions suivantes :
   </para>

   <example>
    <title>Dé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éfinir le chemin absolu au fichier de la bibliothè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èque à l'include_path de PHP</title>
    <programlisting role="php">
<![CDATA[
<?php
// Editez votre fichier php.ini, ajoutez le dossier contenant la
// bibliothèque Smarty à l'include_path et redé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 ê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é 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 <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 à la racine de
    l'arborescence Web,
    il s'agit du script auquel l'internaute a accès. Nous allons l'appeler
    <emphasis>'index.php'</emphasis> 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 <filename>index.php</filename> soit identifié 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écuté sans que
     <filename>index.php</filename> ne soit spécifié dans l'URL. Avec
     Apache, vous pouvez régler cela en ajoutant <filename>index.php</filename>
     à la ligne où se trouve <literal>DirectoryIndex</literal> (séparez chaque entré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 à 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éder en é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è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 <filename>httpd.conf</filename> (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</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 <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à 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 <filename>index.php</filename>. Nous allons
    créer une instance de Smarty,
    <link linkend="api.assign"><varname>assigner</varname></link>
    une valeur à une variable de template et
    <link linkend="api.display">afficher</link> le résultat avec <filename>index.tpl</filename>.
   </para>

   <example>
    <title>Édition de  /web/www.example.com/docs/livredor/index.php</title>
    <programlisting role="php">
<![CDATA[
<?php
// charge la bibliothè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é 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 "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é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
    <filename>/php/includes/livredor/</filename> et un nouveau fichier
    appelé <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>É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 <filename>index.php</filename> pour qu'il utilise 
    <filename>setup.php</filename>
   </para>

   <example>
    <title>É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éer une instance de Smarty,
    correctement configuré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
-->