smarty/docs/fr/getting-started.sgml

<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>
   Et maintenant un mot rapide sur ce que Smarty NE fait PAS. Smarty n'a
   pas pour pr<70>tention de supprimer compl<70>tement les traitements au sein des
   templates.
   Il est tout <20> fait envisageable de recontrer un traitement dans un template,
   <20> condition que ce dernier ne d<>sserve que des besoins de pr<70>sentation.
   Un conseil : laissez la logique applicative en dehors des templates et
   la logique de pr<70>sentation en dehors de l'application. A l'avenir, cela permet
   une meilleure gestion des <20>v<EFBFBD>nements.
   </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 (http://www.zend.com) ou PHP Accelerator
   (http://www.php-accelerator.co.uk).
   </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>
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/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<63>er une instance de Smarty</title>
     <screen>
require('Smarty.class.php');
$smarty = new Smarty;</screen>
	</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 choses suivantes :
   </para>

	<example>
     <title>fournir un chemin absolu vers la biblioth<74>que Smarty</title>
     <screen>
require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty;</screen>
	</example>

	<example>
     <title>Ajouter le r<>pertoire de la biblioth<74>que au chemin de php_include</title>
     <screen>
// Editez le fichier php.ini, ajoutez le r<>pertoire de la
// biblioth<74>que Smarty au include_path et red<65>marrez le serveur Web.
// Cela devrait ensuite fonctionner :
require('Smarty.class.php');
$smarty = new Smarty;</screen>
	</example>

	<example>
     <title>D<>finir explicitement la constante SMARTY_DIR</title>
     <screen>
define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;</screen>
	</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/". 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>
   <para>
   Jetons un coup d'oeil <20> la structure de fichier obtenue :
   </para>

	<example>
     <title>exemple de structure de fichiers</title>
     <screen>
/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/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<>gler les permissions d'acc<63>s</title>
     <screen>

chown nobody:nobody /web/www.mydomain.com/smarty/templates_c/
chmod 770 /web/www.mydomain.com/smarty/templates_c/

chown nobody:nobody /web/www.mydomain.com/smarty/cache/
chmod 770 /web/www.mydomain.com/smarty/cache/</screen>
	</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>

{* 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><3E>dition de  /web/www.mydomain.com/docs/livredor/index.php</title>
     <screen>
// 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><3E>dition de /php/includes/livredor/setup.php</title>
    <screen>

// 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');
   }

}</screen>
   </example>

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

   <example>
    <title><3E>dition de /web/www.mydomain.com/docs/livredor/index.php</title>
    <screen>

require('livredor/setup.php');

$smarty = new Smarty_livredor;

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

$smarty->display('index.tpl');</screen>
   </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>