mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-30 20:01:37 +01:00
428 lines
16 KiB
Plaintext
428 lines
16 KiB
Plaintext
<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.
|
|
Cela 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.
|
|
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>
|
|
Et maintenant un mot rapide sur ce que Smarty NE fait PAS. Smarty n'a
|
|
pas pour prétention de supprimer complétement les traitements au sein des
|
|
templates.
|
|
Il est tout à fait envisageable de recontrer un traitement dans un template,
|
|
à condition que ce dernier ne désserve que des besoins de présentation.
|
|
Un conseil : laissez la logique applicative en dehors des templates et
|
|
la logique de présentation en dehors de l'application. A l'avenir, cela permet
|
|
une meilleure gestion des évènements.
|
|
</para>
|
|
<para>
|
|
L'un des aspects unique de Smarty est la compilation des templates.
|
|
Cela 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 (http://www.zend.com) ou PHP Accelerator
|
|
(http://www.php-accelerator.co.uk).
|
|
</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 {}, {{}}, <!--{}-->, 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 cela ne soit pas obligatoire
|
|
(ni conseillé), vu 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>
|
|
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é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
|
|
<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 à 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>
|
|
<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é,
|
|
tentez l'une des choses suivantes :
|
|
</para>
|
|
|
|
<example>
|
|
<title>fournir un chemin absolu vers la bibliothè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èque au chemin de php_include</title>
|
|
<screen>
|
|
// Editez le fichier php.ini, ajoutez le répertoire de la
|
|
// bibliothèque Smarty au include_path et redé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 ê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é 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 "/web/www.mydomain.com/docs". 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
|
|
"/web/www.mydomain.com/smarty/livredor/".
|
|
</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
|
|
"index.php" et le placer dans un sous-répertoire
|
|
appelé "/livredor/". 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.mydomain.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 cela en ajoutant "index.php" à la ligne où se
|
|
trouve DirectoryIndex (séparez chaque entrée par un espace).
|
|
</para>
|
|
<para>
|
|
Jetons un coup d'oeil à 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é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>
|
|
<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é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.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 é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.mydomain.com/docs/livredor/index.php</title>
|
|
<screen>
|
|
// charge la bibliothè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é 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érience)
|
|
moins générateur d'erreurs de les définir avec des chemins
|
|
absolus. Cela nous garantit que Smarty récupè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é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é "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>é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é automatiquement
|
|
// à 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>é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é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>
|