=encoding iso-8859-1 =head1 NOM HTML::Template - Module Perl pour utiliser les modèles HTML depuis des scripts CGI =head1 SYNOPSIS D'abord vous créez un modèle - c'est juste un fichier HTML normal avec quelques balises supplémentaires, la plus simple étant Par exemple, S Modèle Test Mon répertoire personnel est

Mon Path est actuellement Maintenant écrivons un petit script S #!/usr/bin/perl -w use HTML::Template; # ouvrir le modèle html my $template = HTML::Template->new(filename => 'test.tmpl'); # lui donner quelques paramètres $template->param(HOME => $ENV{HOME}); $template->param(PATH => $ENV{PATH}); # envoyer le Content-Type obligatoire et afficher le modèle print "Content-Type: text/html\n\n", $template->output; Si tout va pour le mieux dans le meilleur des mondes vous devez voir quelque chose comme çà dans votre navigateur quand vous appelez le CGIE: Mon répertoire personnel est /home/some/directory Mon Path est actuellement /bin;/usr/bin =head1 DESCRIPTION Ce module tente de créer une page HTML en utilisant des modèles simples et classiques. Il modifie le HTML standard avec quelques balises supplémentaires - , , , , et . Le fichier écrit en HTML et avec ces balises est appelé un modèle. Il est généralement sauvé séparément de votre script - il est même possible qu'il soit créé par quelqu'un d'autreE! En utilisant ce module vous remplacez par des valeurs les variables, boucles et conditions déclarées dans le modèle. Cela vous permet de séparer la conception - le HTML - des données, que vous générez dans le script Perl. Ce module est sous licence GPL. Voir la section LICENCE plus bas pour plus de détails. =head1 TUTORIEL Si vous ne connaissez pas HTML::Template, je vous suggère de commencer avec l'article de présentation disponible sur le site web d'HTML::TemplateE: http://html-template.sourceforge.net =head1 MOTIVATION Il est vrai qu'il y a bon nombre d'autres packages pour faire des modèles HTML. D'un côté vous avez des choses comme HTML::Embperl qui vous permettent de mélanger librement Perl et HTML. D'un autre côté il y a des solutions de substitution de variables maison. Heureusement le module peut trouver sa place entre les deux. Un avantage de ce module par rapport à une solution 100% HTML::Embperl est qu'il oblige une séparation complète entre la conception et la programmation. En limitant le programmeur à seulement utiliser de simples variable et boucles dans le HTML, le modèle reste accessible aux concepteurs et autres non-perlistes. L'utilisation d'une syntaxe type HTML fait en sorte que le format soit compréhensible pour les autres. Plus tard cette similitude pourra être utilisée pour étendre la compréhension d'HTML::Template aux éditeurs/analyseurs HTML existants. Un autre avantage de ce module par rapport aux solutions maison est le support des boucles. Dans mon travail je suis souvent appelé à produire des tables de données en html. Les produire en utilisant des modèles HTML simplistes revient à faire des CGI contenant plein de HTML sachant que le HTML lui-même ne peut pas faire des boucles. L'introduction de déclarations de boucles dans le HTML simplifie cette situation considérablement. Le concepteur peut écrire une seule ligne et la programmeur peut s'en servir autant de fois que nécessaire - ils ont juste à se mettre d'accord sur les noms des paramètres. Pour tout ça, je pense que la meilleure chose à propos de ce module est qu'il ne fait qu'une chose et qu'il le fait rapidement et sans erreur. Il n'essaie pas de remplacer Perl et HTML, il les améliore juste un peu pour qu'ils interagissent un petit peu mieux. Et c'est assez rapide. =head1 LES BALISES =head2 TMPL_VAR La balise est très simple. Pour chaque balise dans le modèle vous appelez $template->param(NOM_PARAMETRE => "VALEUR"). Quand le modèle s'affiche le est remplacé par la VALEUR que vous avez spécifié. Si vous ne mettez pas de paramètre celui-ci est juste enlevé de l'affichage. Éventuellement vous pouvez utiliser l'option "ESCAPE=HTML" dans la balise pour indiquer que vous voulez que la valeur soit HTML-encodée avant d'être affichée (l'ancienne syntaxe ESCAPE=1 est toujours supportée). Cela veut dire que les caractères ", <, > et & sont transformés respectivement en ", <, > et &. C'est très pratique quand vous voulez utiliser un TMPL_VAR dans un contexte où ces caractères peuvent poser problème. ExempleE: "> Si vous avez appelé param() avec une valeur comme sam"my vous aurez des problèmes avec la manière dont HTML interprète un guillemet double. D'un autre côté, si vous utilisez ESCAPE=HTMl, comme çaE: "> Vous aurez ce que vous voulez peut importe la valeur que vous aurez passé en paramètre. Vous pouvez aussi écrire ESCAPE="HTML", ESCAPE='HTML' and ESCAPE='1'. Remplacez par 0 le HTML et vous stopperez l'encodage, qui est le mode par défaut de toutes façons. Il y a aussi l'option "ESCAPE=URL" qui peut être utilisée pour les variables qui se trouvent dans une URL. Cela fera l'encodage de l'URL, par exemple en remplaçant ' ' par '+' et '/' par '%2F'. Il y a aussi l'option "ESCAPE=JS" qui peut être utilisée pour les variables qui doivent être mises dans une chaîne Javascript. Tous les caractères \n, \r, ' et " sont encodés. Vous pouvez assigner une valeur par défaut à une variable avec l'attribut DEFAULT. Par exemple, ceci affichera "Le diable m'a donné une voiture" si la variable "QUI" n'est pas renseignée. Le m'a donné une voiture. =head2 TMPL_LOOP ... La balise un peu plus compliquée que . La balise vous permet à délimiter une section de texte et à lui donner un nom. Dans cette boucle vous mettez des . Maintenant vous donnez à param() une liste (une référence à un tableau) de paramètres associés (hash refs) pour cette boucle. La boucle va lire toute la liste et va afficher le bloc de texte pour chaque élément. Les paramètres non renseignés sont passés. Voici un exempleE: Dans le modèleE: Nom:
Job:

Dans le scriptE: $template->param(EMPLOYE_INFO => [ { nom => 'Sam', job => 'programmeur' }, { nom => 'Steve', job => 'soda jerk' }, ] ); print $template->output(); L'affichage dans un navigateurE: Nom: Sam Job: programmeur Nom: Steve Job: soda jerk Comme vous pouvez voir au-dessus le prend une liste de paramètres et ensuite les affiche en passant le corps de la boucle pour chaque élément. Souvent vous voudrez générer le contenu d'une boucle en programmant. Voici un exemple pour le faire (il y a plein d'autres possibilitésE!)E: # un couple de tableaux de données à mettre dans une boucle: my @words = qw(Je suis Calme); my @numbers = qw(1 2 3); my @loop_data = (); # initialise an un tableau pour contenir votre boucle while (@words and @numbers) { my %row_data; # créez un tableau associatif pour ranger votre ligne de données # remplissez cette ligne $row_data{WORD} = shift @words; $row_data{NUMBER} = shift @numbers; # l'étape cruciale - mettez une référence à cette ligne dans la boucle! push(@loop_data, \%row_data); } # enfin, assignez les données de la boucle au paramètre de celle-ci, de nouveau avec # une référence: $template->param(THIS_LOOP => \@loop_data); L'exemple ci-dessus marchera avec un modèle commeE: Mot:
Nombre:

Cela produira un affichage commeE: Mot: Je Nombre: 1 Mot: suis Nombre: 2 Mot: Calme Nombre: 3 Les dans des sont sympa et marchent comme vous le pensez. Si la syntaxe pour l'appel à param() vous a séché, voici un exemple d'appel à param avec une boucle imbriquéeE: $template->param(LOOP => [ { nom => 'Bobby', nicknames => [ { nom => 'le grand méchant loup' }, { nom => 'Musclor' }, ], }, ], ); Classiquement, chaque prend une référence à un tableau. Dans ce tableau se trouvent plein de références à des tableaux associatifs. Ces tableaux associatifs contiennent des paires nom=>valeur pour un seul passage dans le modèle de la boucle. Dans un , les seules variables utilisables sont celles venant de . Les variables d'autres blocs en dehors ne sont pas visible dans le modèle de boucle. Pour les geeks qui sont parmi vous, un apporte une nouvelle portée un peu comme un appel à une sous-routine Perl. Si vous voulez que vos variables soient globales vous pouvez utiliser l'option 'global_vars' à new() décrit plus bas. =head2 TMPL_INCLUDE Cette balise inclut un modèle directement dans le modèle actuel là où se trouve la balise. Le contenu du modèle inclus est utilisé exactement comme s'il était physiquement inclus dans le modèle principal. Le fichier spécifié peut être avec un path absolu (commençant par '/' sous Unix, par exemple). S'il n'est pas absolu, le path du fichier à inclure est d'abord testé. Après çà, le path dans la variable d'environnement HTML_TEMPLATE_ROOT est testé, s'il existe. Ensuite, l'option "path" est essayée, d'abord réellement et ensuite avec HTML_TEMPLATE_ROOT prépondérant si disponible. En dernier recours, le nom du fichier est passé à open() directement. Voyez plus bas pour plus d'informations sur HTML_TEMPLATE_ROOT et l'option "path" de new(). Pour une protection contre les inclusions récursives, une limite arbitraire à 10 niveaux est imposée. Vous pouvez modifier cette limite avec l'option "max_includes". Regardez la section sur l'option "max_includes" plus bas pour plus de détails. =head2 TMPL_IF ... La balise vous permet d'inclure ou de ne pas inclure un bloc du modèle basé sur la valeur d'un paramètre donné. Si le paramètre est à une valeur considéré comme vraie par Perl - comme '1' - alors le bloc est inclus dans l'affichage. S'il n'est pas défini, ou à une valeur fausse - comme '0' - alors il est sauté. Les paramètres sont spécifiés de la même manière que TMPL_VAR. Modèle d'exempleE: Du texte qui est affiché seulement si BOOL est vrai! Maintenant si vous appelez $template->param(BOOL => 1) alors le bloc ci-dessus sera affiché. Les blocs peuvent inclure n'importe quelle construction HTML::Template valide - VAR et LOOP et autres blocs IF/ELSE. Notez, toutefois, que croiser un et un est invalide. Ne marchera pasE: Si le nom d'un TMPL_LOOP est utilisé dans un TMPL_IF, le bloc IF sera affiché si la boucle a au moins une ligne. ExempleE: Ceci s'affichera si la boucle n'est pas vide. .... ATTENTIONE: L'essentiel de l'intérêt de HTML::Template est de séparer votre Perl et votre HTML. Si vous mettez beaucoup de choix où vous avez des TMPL_IF et correspondants à des if() Perl, vous allez créer un problème de maintenance pour garder les deux synchronisés. Je vous suggère de prendre l'habitude d'utiliser TMPL_IF seulement si vous pouvez faire sans utiliser un if() correspondant dans votre code Perl. =head2 TMPL_ELSE ... ... Vous pouvez inclure un bloc alternatif dans votre bloc TMPL_IF en utilisant TMPL_ELSE. NOTE : vous devez tout de même finir le bloc par , pas par E! ExempleE: Du texte qui est inclus seulement si BOOL est vrai Du texte qui est inclus seulement si BOOL est faux =head2 TMPL_UNLESS ... Cette balise est le contraire de . Le bloc est affiché si NOM_PARAMETRE est faux ou non défini. Vous pouvez utiliser avec aussi bien qu'avec . ExempleE: Du texte qui est inclus seulement si BOOL est faux Du texte qui est inclus seulement si BOOL est vrai Si le nom d'un TMPL_LOOP est utilisé dans un TMPL_UNLESS, le bloc UNLESS est affiché si la boucle n'a aucune ligne. Ceci s'affichera si la boucle est vide. .... =head2 NOTES Les balises HTML::Template sont censées imiter les balises HTML normales. Cependant, elle sont autorisées à "briser les règles". Quelque chose commeE: n'est pas vraiment du HTML valide, mais c'est un usage tout à fait valide et marchera comme prévu. Le "NAME=" dans une balise est optionnel, mais ...................... je recommande de l'utiliser. Exemple - "" est acceptable. Si vous êtes fanatique du HTML valide et que vous voulez que vos modèles soit conformes à la syntaxe du HTML valide, vous pouvez éventuellement mettre vos balises dans le modèle sous la forme de commentaires HTML. Cela peut être utilisé par des auteurs de HTML qui veulent valider la syntaxe HTML de leurs modèles avant d'utiliser HTML::Template, ou ceux qui utilisent des outils d'édition DTD-savvy. Pour économiser un maximum de bande passante, les balises standards (sans commentaires) seront utilisées au travers de cette documentation. =head1 MÉTHODES =head2 new() Appelle new() pour créer un nouvel objet ModèleE: my $template = HTML::Template->new( filename => 'file.tmpl', option => 'valeur' ); Vous devez appeler new() avec au moins une paire nom => valeur en spécifiant comment accéder au texte du modèle. Vous pouvez utiliser "filename => 'file.tmpl'" pour spécifier un nom de fichier qui doit être ouvert comme modèle. Sinon, vous pouvez utiliserE: my $t = HTML::Template->new( scalarref => $ref_to_template_text, option => 'valeur' ); et my $t = HTML::Template->new( arrayref => $ref_to_array_of_lines , option => 'valeur' ); Ça initialise le modèle avec les ressources en mémoire. Dans la plupart des cas vous voudrez utiliser le paramètre du nom de fichier. Si vous êtes embêté par l'accès disque représenté par la lecture du fichier modèle, utilisez mod_perl et l'option cache détaillée plus bas. Vous pouvez également lire le modèle à partir d'un handle de fichier déjà ouvert, aussi bien comme si c'était un glob ou un handle de fichierE: my $t = HTML::Template->new( filehandle => *FH, option => 'valeur'); Les quatre méthodes pour appeler new() peuvent évidemment être utilisées comme ci-dessous, si vous préférez. my $t = HTML::Template->new_file('file.tmpl', option => 'valeur'); my $t = HTML::Template->new_scalar_ref($ref_au_fichier_texte_modele, option => 'valeur'); my $t = HTML::Template->new_array_ref($ref_a_un_tableau_de_lignes, option => 'valeur'); my $t = HTML::Template->new_filehandle($fh, option => 'valeur'); Et comme dernière option, pour ceux qui préfèrent, vous pouvez appeler new comme ceciE: my $t = HTML::Template->new(type => 'filename', source => 'file.tmpl'); Qui marche pour chacun des trois types de source. Si la variable d'environnement HTML_TEMPLATE_ROOT est renseignée et que votre nom de fichier ne commence pas par /, alors le path sera relatif à la valeur de $HTML_TEMPLATE_ROOT. Exemple - si la variable d'environnement HTML_TEMPLATE_ROOT est "/home/sam" et que j'appelle HTML::Template->new() avec le nom de fichier "sam.tmpl", HTML::Template essaiera d'ouvrir "/home/sam/sam.tmpl" pour accéder au fichier modèle. Vous pouvez aussi modifier le path de recherche pour vos fichier avec l'option "path" de new() - Voir plus bas pour plus d'information. Vous pouvez modifier le comportement de l'objet Template avec new(). Les options disponibles sontE: =over 4 =item Options de détection d'erreur =over 4 =item * die_on_bad_params - si il est à 0 le module vous laissera appeler $template->param(param_name => 'valeur') même si 'param_name' n'existe pas dans le corps du modèle. Par défaut à 1. =item * strict - si il est mis à 0 le module autorisera des choses qui ressemblent à des balises TMPL_* sans bloquer. ExempleE: Devrait normalement renvoyer une erreur, mais si vous appelez new avec strict => 0, HTML::Template l'ignorera. Par défaut à 1. =item * vanguard_compatibility_mode - si il est mis à 1 le module s'attendra à voir des qui ressemblent à %NAME% en plus de la syntaxe standard. Mettez en même temps die_on_bad_params => 0. Si vous n'êtes pas chez Vanguard Media en train d'essayer un vieux format de modèle ne vous en préoccupez pas. Par défaut à 0. =back =item Options de cache =over 4 =item * cache - si il est mis à 1 le module gardera en mémoire les modèles analysés en fonction du nom du fichier et de la date de modification du fichier. Cela ne marche que sur les modèles ouverts avec le nom de fichier spécifié en paramètre, pas avec les modèles passé par référence scalaire ou tableau. La mémorisation vérifie les heures des modifications de tous les fichiers utilisant des balises , mais encore, seulement si le modèle est ouvert avec le nom du fichier en paramètre. C'est l'usage de base dans un environnement persistant comme Apache/mod_perl. Ça n'a absolument aucun intérêt dans un environnement CGI normal puisque le script est déchargé de la mémoire après chaque requête. Pour un cache qui fonctionne avec les CGI normaux, voyez l'option 'shared_cache' plus bas. Notez que les différents réglages des paramètres de new() ne cause pas de rafraîchissement du cache, seul un changement dans la date de modification d'un modèle déclenchera un rafraîchissement du cache. Dans la plupart des cas c'est bien. Mon simple test montre qu'utiliser le cache rapporte 90% de performance en plus sous mod_perl. Cache est par défaut à 0. =item * shared_cache - si il est mis à 1 le module enregistrera son cache dans de la mémoire partagée en utilisant le module IPC::SharedCache (disponible sur le CPAN). Le but sera d'avoir une seule copie partagée de chaque modèle analysé pour toutes les instances d'HTML::Template utilisées. Cela peut être une réduction significative de l'utilisation de mémoire sur un environnement multi-serveurs. Par exemple, sur un de nos systèmes nous utilisons 4Mo de cache pour les modèles et maintenons 25 processus httpd - shared_cache nous permet donc d'économiser plus de 100MoE! Bien sûr, quelques ralentissements par rapport à un cache normal sont à constater. Une autre différence entre le cache normal et shared_cache est que shared_cache marchera dans un environnement CGI - le cache normal n'est utile que dans un environnement persistant comme Apache/mod_perl. Par défaut HTML::Template utilise la clé IPC 'TMPL' comme segment racine partagé (0x4c504d54 en hexa), mais cela peut être changé en initialisant le paramètre 'ipc_key' de new() à une autre valeur de clé sur 4 caractères ou avec un entier. D'autres options peuvent être utilisées pour modifier le cache de mémoire partagé et correspondent aux options d'IPC::SharedCache - ipc_mode, ipc_segment_size et ipc_max_size. Voyez L pour une description de leur fonctionnement - dans la plupart des cas vous n'avez pas besoin de les modifier par rapport à leur valeur par défaut. Pour plus d'informations à propos du système de mémoire cache partagé utilisé par HTML::Template voyez L. =item * double_cache - si il est mis à 1 le module utilisera un mélange des modes shared_cache et de cache normal pour mémoriser le mieux possible. Bien sûr, cela utilise toute la mémoire des deux modes de cache. Les mêmes options ipc_* qui fonctionnent avec shared_cache sont aussi bien utilisables avec double_cache. Par défaut, double_cache est désactivé. =item * blind_cache - si il est mis à 1 le module fonctionne exactement comme le cache normal mais ne vérifie pas à chaque requête si le fichier a été modifié. Cette option est à utiliser avec précaution, but peut ne pas être active sur les serveurs très chargés. Mes tests montrent que blind_cache est uniquement meilleur de 1 ou 2 pourcent que le cache sous mod_perl. NOTEE: Mélanger cette option avec shared_cache peut faire en sorte que les modèles soient en permanence chargés dans la mémoire partagéeE! =item * file_cache - si il est mis à 1 le module enregistrera son cache dans un fichier en utilisant le module Storable. Cela n'utilise pas plus de mémoire, et mes tests simpliste montrent qu'il y a un un gain de performance de 50%. Comme shared_cache, il marchera dans un environnement CGI. Par défaut à 0. Si vous activez cette option vous devez activer l'option "file_cache_dir". Voir plus bas pour les détails. NOTEE: Storable utilise flock() pour assurer un accès fiable aux fichiers de cache. Utiliser file_cache sur un système ou un système de fichiers (NFS) qui ne connaît pas flock() est dangereux. =item * file_cache_dir - indique le répertoire ou le module enregistrera les fichiers de cache si file_cache est activé. Votre script aura besoin des droits d'écriture sur ce répertoire. Vous devrez aussi également vous assurer qu'il y a assez d'espace disponible pour enregistrer les fichiers de cache. =item * file_cache_dir_mode - indique le mode de fichier pour les répertoires et sous-répertoires file_cache nouvellement créés. Par défaut à 0700 par sécurité mais cela peut être gênant si vous n'avez pas accès au compte qui gère le service web. =item * double_file_cache - si il est mis à 1 le module utilisera un mélange des modes file_cache et cache normal pour la meilleure mémorisation possible. Les options file_cache_* qui fonctionnent avec file_cache s'appliquent aussi bien à double_file_cache. Par défaut double_file_cache est à 0. =back =item Options du système de fichiers =over 4 =item * path - vous pouvez activer cette variable avec une liste de paths pour chercher les fichiers spécifiés dans l'option "filename" de new() et les fichiers inclus dans la balise . Cette liste est utilisée uniquement quand le nom de fichier est relatif. La variable d'environnement HTML_TEMPLATE_ROOT est toujours testée en premier si elle existe. Bien sûr, si HTML_TEMPLATE_ROOT est active alors un essai sera fait pour utiliser HTML_TEMPLATE_ROOT devant les paths de la liste de path. Dans le cas d'un fichier , le path du fichier inclus est bien sûr testé avant de consulter path. ExempleE: my $modele = HTML::Template->new( filename => 'file.tmpl', path => [ '/path/des/modeles', '/path/alternatif' ] ); NOTEE: les paths de la liste de path doivent être sous la forme UNIX, séparés par le caractère slash ('/'). =item * search_path_on_include - si il est mis à une valeur vraie le module cherchera à partir du début de la liste de paths spécifiés par l'option path dans tous les et utilise le premier modèle trouvé. Le comportement normal est de ne regarder que dans le répertoire actif le modèle à inclure. Par défaut à 0. =back =item Options de débugage =over 4 =item * debug - si il est mis à 1 le module écrira au hasard les informations de debug dans STDERR. Par défaut à 0. =item * stack_debug - si il est mis à 1 le module utilisera Data::Dumper pour afficher le contenu de parse_stack dans STDERR. Par défaut à 0. =item * cache_debug - si il est mis à 1 le module enverra les informations concernant les chargements, utilisations et ratages du cache dans STDERR. Par défaut à 0. =item * shared_cache_debug - si il est mis à 1 le module l'option de debug dans IPC::SharedCache - Voir L pour les détails. Par défaut à 0. =item * memory_debug - si il est mis à 1 le module enverra les informations sur l'utilisation de la mémoire cache dans STDERR. Nécessite le module GTop. Par défaut à 0. =back =item Options diverses =over 4 =item * associate - cette option vous permet d'hériter des valeurs de paramètres venant d'autres objets. La seule obligation pour les autres objets est d'avoir une méthode param() qui fonctionne comme celle d'HTML::Template. Un bon exemple peut être un objet query CGI.pm. ExempleE: my $query = new CGI; my $modele = HTML::Template->new(filename => 'modele.tmpl', associate => $query); Maintenant, $modele->output() marchera comme ça $modele->param('FormField', $cgi->param('FormField')); comme spécifié pour chaque paire clé/valeur qui peut être fourni par la méthode $cgi->param(). Les paramètres que vous activez directement sont prioritaires sur les paramètres associés. Vous pouvez spécifier des objets multiples à associer en passant un tableau anonyme à l'option associate. Ils sont cherchés comme paramètres dans l'ordre où ils apparaissentE: my $modele = HTML::Template->new(filename => 'modele.tmpl', associate => [$query, $other_obj]); L'ancien appel associateCGI() est toujours supporté, mais doit être considéré comme obsolète. NOTEE: Les noms des paramètres sont testé de manière non sensible à la casse. Si vous avez deux paramètres dans un objet CGI comme 'NAME' et 'Name', l'un sera choisi de manière aléatoire par associate. Ce comportement peut être changé par l'option suivante. =item * case_sensitive - activer cette option rend HTML::Template sensible à la casse lors du traitement des noms des variables de modèles. L'exemple suivant permet juste de mettre un paramètre sans l'option "case_sensitive"E: my $modele = HTML::Template->new(filename => 'modele.tmpl', case_sensitive => 1); $modele->param( FieldA => 'foo', fIELDa => 'bar', ); Cette option est par défaut désactivée. NOTEE: avec case_sensitive et loop_context_vars les variable de boucle spéciales ne sont disponibles qu'en minuscule. =item * loop_context_vars - quand ce paramètre est actif (il ne l'est pas par défaut), quatre variable de contexte de boucle sont mises à disposition dans une boucleE: __first__, __last__, __inner__, __odd__. Elles peuvent être utilisées avec , et pour contrôler comment la boucle s'affiche. En plus de cela, une variable __counter__ est également disponible quand les variables de contexte de boucle sont activées. ExempleE: Cela n'affiche que le premier passage. Cela affiche tous les autres passages, sur les passages impairs. Cela affiche tous les autres passages, sur les mêmes passages. Cela affiche les passages qui ne sont ni le premier ni le dernier. Ceci est le numéro de passage . Cela n'affiche que le dernier passage. Un usage de cette possibilité est d'avoir un "séparateur" similaire à l'effet de la fonction perl join(). ExempleE: and , . Affichera (dans un navigateur) quelque chose commeE: Pommes, Oranges, Cerveaux, Orteils, et Kiwi. En fonction d'un appel à param() approprié, bien sûr. NOTEE: une boucle avec seulement un seul passage mettra aussi bien __first__ et __last__ à vrai, mais pas __inner__. =item * no_includes - mettez cette option à 1 pour désactiver la balise dans le fichier de modèle. Cela peut être utilisé pour permettre l'ouverture de modèles non vérifiés de manière B moins dangereuse. Par défaut à 0. =item * max_includes - activez cette variable pour déterminer la profondeur maximale que les inclusions peut atteindre. Positionné à 10 par défaut. Inclure des fichiers à une profondeur supérieure à cette valeur met un message d'erreur. Mettez la à 0 pour désactiver cette protection. =item * global_vars - habituellement les variables déclarées en dehors d'une boucle ne sont pas disponibles dans celle-ci. Cette option rend les comme les variables globales en Perl - elles ont un périmètre illimité. Cette option touche également et . ExempleE: Ceci est une variable normale: .

Ici elle est dans la boucle:

En temps normal ceci ne pourrait pas fonctionner de cette manière, tant que la valeur hors de la boucle n'est pas disponible dans celle-ci. L'option global_vars vous permet bien sûr d'accéder aux valeurs d'une boucle qui en contient une autre. Par exemple, dans cette boucle la boucle interne aura accès à la valeur de OUTER_VAR correctementE: OUTER: INNER: INSIDE OUT: BE: C n'est pas C (qui n'existe pas). Cela signifie que les boucles que vous déclarez à un niveau ne sont pas disponibles dans d'autres boucles même si C est actif. =item * filter - cette option vous permet de spécifier un filtre pour vos fichiers modèles. Un filtre est un sous-programme qui sera appelé après qu'HTML::Template ai lu votre fichier modèle mais avant qu'il ne commence à remplacer les balises du modèle. Dans le cas le plus courant, vous assignez simplement un code de référence au paramètre de filtre. Ce sous-programme recevra un seul argument - une référence à une chaîne contenant le texte du fichier modèle. Voici un exemple qui accepte les modèles avec les balises qui ressemblent à "!!!ZAP_VAR FOO!!!" et qui les transforme en balises HTML::TemplateE: my $filter = sub { my $text_ref = shift; $$text_ref =~ s/!!!ZAP_(.*?)!!!//g; }; # ouvre zap.tmpl en utilisant le filtre ci-dessus my $template = HTML::Template->new(filename => 'zap.tmpl', filter => $filter); Des usages plus complexes sont possibles. Vous pouvez demander que votre filtre reçoive les textes modèles comme un tableau de lignes plutôt que comme une variable scalaire. Pour faire cela vous devez spécifier votre filtre en utilisant une référence à un tableau associatif. De cette manière vous spécifiez le filtre en utilisant la clé "sub" et le format de l'argument désiré en utilisant la clé "format". Les formats disponibles sont "scalar" et "array". Utiliser le format "array" inclut une baisse de performance mais peut être plus pratique dans certains cas. my $template = HTML::Template->new(filename => 'zap.tmpl', filter => { sub => $filter, format => 'array' }); Vous pouvez aussi utiliser des filtres multiples. Cela permet à de simples filtres d'être combinés pour des fonctionnalités plus élaborées. Pour faire cela vous spécifiez un tableau de filtres. Les filtres sont appliqués dans l'ordre où ils sont spécifiés. my $template = HTML::Template->new(filename => 'zap.tmpl', filter => [ { sub => \&decompress, format => 'scalar' }, { sub => \&remove_spaces, format => 'array' } ]); Les filtres spécifiés seront appelés pour n'importe quel fichier "TMPL_INCLUDE" s'ils sont pour le fichier modèle principal. =back =back 4 =head2 param() param() peut être appelé dans de nombreux cas 1) Pour renvoyer une liste de paramètres dans le modèleE: my @parameter_names = $self->param(); 2) Pour renvoyer la valeur attribuée à un paramètreE: my $value = $self->param('PARAM'); 3) Pour donner une valeur à un paramètreE: # Pour de simples variables TMPL_VAR: $self->param(PARAM => 'value'); # avec une référence à un sous-programme qui sera appelé pour donner la valeur # du scalaire. Le sub recevra l'objet du modèle comme un # paramètre. $self->param(PARAM => sub { return 'value' }); # Et les TMPL_LOOPs: $self->param(LOOP_PARAM => [ { PARAM => VALUE_FOR_FIRST_PASS, ... }, { PARAM => VALUE_FOR_SECOND_PASS, ... } ... ] ); 4) Pour donner une valeur à plusieurs paramètresE: # Pour de simples variables TMPL_VAR: $self->param(PARAM => 'value', PARAM2 => 'value' ); # Et pour des TMPL_LOOPs: $self->param(PARAM => 'value', PARAM2 => 'value', LOOP_PARAM => [ { PARAM => VALUE_FOR_FIRST_PASS, ... }, { PARAM => VALUE_FOR_SECOND_PASS, ... } ... ], ANOTHER_LOOP_PARAM => [ { PARAM => VALUE_FOR_FIRST_PASS, ... }, { PARAM => VALUE_FOR_SECOND_PASS, ... } ... ] ); 5) Pour donner la valeur à un nombre de paramètres en utilisant une référence à tableau associatifE: $self->param( { PARAM => 'value', PARAM2 => 'value', LOOP_PARAM => [ { PARAM => VALUE_FOR_FIRST_PASS, ... }, { PARAM => VALUE_FOR_SECOND_PASS, ... } ... ], ANOTHER_LOOP_PARAM => [ { PARAM => VALUE_FOR_FIRST_PASS, ... }, { PARAM => VALUE_FOR_SECOND_PASS, ... } ... ] } ); =head2 clear_params() Mets tous les paramètres à undef. Utile en interne, pas ailleursE! =head2 output() output() renvoie le résultat final du modèle. Dans beaucoup de cas vous voudrez l'afficher, comme çaE: print $template->output(); Quand ouput est appelé chaque occurrence de est remplacé avec la valeur attribué à "name" via param(). Si un paramètre nommé n'est pas renseigné il est simplement remplacé par ''. Les sont évalués une fois par paramètre renseigné, accumulant l'affichage à chaque passage. Appeler output() garantie de ne rien changer à l'état de l'objet Template, au cas vous vous demandiez. Cette propriété est la plus importante pour le fonctionnement inter des boucles. Vous pouvez éventuellement utiliser un handle de ficher pour afficher dynamiquement au fur et à mesure que le modèle est généré. Cela peut améliorer les performance et moins de consommation de mémoire. ExempleE: $template->output(print_to => *STDOUT); La valeur de retour est indéfinie quand on utilise l'option "print_to". =head2 query() Cette méthode vous permet d'obtenir des informations à propos de la structure du modèle. Elle peut être appelée dans un certains nombre de cas. L'usage le plus courant de query est tout simplement de vérifier si un nom de paramètre existe dans un modèle, en utilisant l'option CE: if ($template->query(name => 'foo')) { # Faire quelque chose si une variable de n'importe quel type # appelée FOO est dans le modèle } Ce même usage renvoie le type du paramètre. Le type est la même chose que la deuxième partie dans une balise 'TMPL_'. Donc, par exemple, un paramètre TMPL_VAR renvoie 'VAR' dans query(). if ($template->query(name => 'foo') eq 'VAR') { # faire quelque chose si FOO existe et si c'est un TMPL_VAR } Notez que les variables associées à des TMPL_IF et TMPL_UNLESS seront reconnues comme des 'VAR' sauf si elles sont également utilisées dans un TMPL_LOOP, dans quel cas elles renverront 'LOOP'. C vous permet aussi d'obtenir une liste de paramètres dans une boucle (et dans les boucles dans les boucles). Exemple de boucleE: Et dans des appels à queryE: # renvoie 'LOOP' $type = $template->query(name => 'EXAMPLE_LOOP'); # renvoie ('bop', 'bee', 'example_inner_loop') @param_names = $template->query(loop => 'EXAMPLE_LOOP'); # les deux renvoient 'VAR' $type = $template->query(name => ['EXAMPLE_LOOP', 'BEE']); $type = $template->query(name => ['EXAMPLE_LOOP', 'BOP']); # et celui-ci renvoie 'LOOP' $type = $template->query(name => ['EXAMPLE_LOOP', 'EXAMPLE_INNER_LOOP']); # et finalement, ceci renvoie ('inner_bee', 'inner_bop') @inner_param_names = $template->query(loop => ['EXAMPLE_LOOP', 'EXAMPLE_INNER_LOOP']); # pour les noms de paramètres inexistants vous obtenez undef # ceci renvoie undef. $type = $template->query(name => 'DWEAZLE_ZAPPA'); # appeler une boucle avec un nom de paramètre ne correspondant pas à une boucle renverra une erreur. # celui-là plante: $type = $template->query(loop => 'DWEAZLE_ZAPPA'); Comme vous pouvez voir au-dessus l'option C renvoie une liste de noms de paramètres et les deux C et C prennent des références de tableaux pour se rapporter aux paramètres dans les boucles. C'est une erreur d'utiliser C avec un paramètres qui n'est pas une boucle. Notez que tous les noms sont renvoyés en minuscule et les types en majuscule. Tout comme C, C sans argument renvoie tous les noms de paramètre dans le modèle de premier niveau. =head1 QUESTIONS FRÉQUEMMENT POSÉES Dans l'intérêt d'une meilleure compréhension j'ai commencé une section FAQ des perldocs. Merci de regarder ici avant de m'envoyer un email. =over 4 =item 1 S Y a-t-il un endroit pour discuter de HTML::Template et/ou obtenir de l'aideE? S Il y a une mailing-liste causant de HTML::Template à html-template-users@lists.sourceforge.net. Pour nous rejoindreE: http://lists.sourceforge.net/lists/listinfo/html-template-users Si vous voulez seulement recevoir un email quand les nouvelles versions sont disponibles vous pouvez rejoindre la mailing-liste des annonces iciE: http://lists.sourceforge.net/lists/listinfo/html-template-announce =item 2 S Est-ce qu'il y a des archives pour la mailing-listeE? S Oui, vous pouvez trouver une archive de la liste SourceForge iciE: http://www.geocrawler.com/lists/3/SourceForge/23294/0/ Pour une archive de la vieille liste vm.com, montée par Sean P. Scanlon, voyezE: http://bluedot.net/mail/archive/ =item 3 S Je veux de l'aide pour E! Est-ce possibleE? S Peut-être. J'encourage les gens à discuter de leurs idées pour HTML::Template sur la mailing-liste. Soyez prêts à m'expliquer comment une nouvelle balise peut s'adapter dans la mission d'HTML::Template de fournir un système rapide et léger pour utiliser des modèles HTML. NOTEE: Proposer de programmer un ajout et le fournir sous la forme d'un patch à la plus récente version d'HTML::Template aura certainement un un effet de ramollissement de la part d'opposants éventuelsE! =item 4 S J'ai trouvé un bug, pouvez-vous le corrigerE? S Ça dépend. Est-ce que vous m'avez envoyé la VERSION d'HTML::Template, un script de test et un fichier de testE? Si oui, alors probablement. Si vous êtes vraiment aventureux, HTML::Template a un serveur CVS disponible au public. Voyez plus bas pour plus d'informations dans la section SERVEUR CVS PUBLIC. =item 5 S du modèle principal ne marchent pas dans un E! PourquoiE? S C'est le comportement attendu. présente une portée séparée pour les un peu comme un appel à un sous-programme dans Perl présente une portée séparée pour les variables "my". Si vous voulez que vos aient une portée globale, vous pouvez activer l'option 'global_vars' quand vous appelez new(). Voyez plus haut pour la documentation l'option 'global_vars' de new(). =item 6 S Pourquoi utilisez vous /[Tt]/ au lieu de /t/iE? C'est si laidE! S Simple - le switch de recherche non sensible à la casse est très inefficace. A en croire _Maitrise_des_Expressions_Régulières_ de chez O'Reilly, /[Tt]/ est plus rapide et plus économe de mémoire que /t/i - d'environ le double pour les chaînes longues. //i fait surtout un lc() sur la chaîne et garde une copie temporaire en mémoire. Dès que ça change, et c'est dans les séries de développement 5.6, je serais ravi d'utiliser //i. Croyez moi, je sais que [Tt] est affreusement laid. =item 7 S Comment puis-je précharger mes modèles en utilisant le mode cache et mod_perlE? S Ajoutez quelque chose comme ça dans votre startup.plE: use HTML::Template; use File::Find; print STDERR "Pré-chargement des modèles HTML...\n"; find( sub { return unless /\.tmpl$/; HTML::Template->new( filename => "$File::Find::dir/$_", cache => 1, ); }, '/path/des/modeles', '/path/des/autres/modèles/' ); Notez que vous devrez modifier la ligne "return unless" pour spécifier l'extension que vous utilisez pour vos fichiers modèle - j'utilise .tmpl, comme vous pouvez voir. Vous aurez aussi besoin de spécifier le path de vos fichiers modèles. Un problème potentielE: le "/path/des/modeles/" doit être EXACTEMENT le même path que vous utilisez quand vous appelez HTML::Template->new(). Sinon le cache ne saura pas qu'ils sont le même fichier et chargera une nouvelle copie - au lieu d'avoir un gain de rapidité, vous doublerez votre utilisation mémoire. Pour vérifier si c'est bon mettez cache_debug => 1 dans votre code applicatif et regardez pour les messages "CACHE MISS" dans les logs. =item 8 S Quels caractères sont autorisés dans les noms des TMPL_*E? S Nombres, lettres, '.', '/', '+', '-' and '_'. =item 9 S Comme puis-je exécuter un programme à l'intérieur de mon modèleE? S Réponse courteE: vous ne pouvez pas. Réponse longueE: vous ne devez pas puisque que cela viole le concept fondamental de HTML::Template - que le design et le code doivent être séparés. Mais, inévitablement des gens veulent toujours faire ça. Si cela vous décrit vous devez regarder L. En utilisant HTML::Template::Expr il sera facile d'écrire une une fonction run_program(). Et là vous pouvez faire des choses bien moches commeE: Seulement, merci de ne pas m'en parler. Je me sens déjà assez coupable d'avoir écrit HTML::Template::Expr. =item 10 S Est-ce que je peut obtenir une copie de cette doc en JaponaisE? S Oui vous pouvez. Voyez la traduction de Kawai Takanori àE: http://member.nifty.ne.jp/hippo2000/perltips/html/template.htm =item 11 S Quelle est la meilleure manière de créer un élément de formulaire entièrement dans le modèle. Ce que vous devez obtenir est un mélange de boucles et de conditions. A côté de ça vous pouvez renoncer à une certaine flexibilité en échange de la simplification de vos modèles. Je choisis généralement cette dernière solution. Une autre option est d'utiliser HTML::FillInForm qui a trouvé un certain succès pour résoudre ce problème. =back =head1 BUGS Je suis à l'affût de tout bug - si vous en trouvez un, rejoignez la mailing-liste et parlez nous-en. Vous pouvez rejoindre la mailing-liste HTML::Template en visitantE: http://lists.sourceforge.net/lists/listinfo/html-template-users Bien sûr, vous pouvez toujours m'envoyer un email directement (sam@tregar.com) avec les bugs, mais je me réserver le droit de faire suivre ces rapports de bug à la mailing-liste. Quand vous envoyez des rapports de bug, soyez sûr d'inclure tous les détails, en incluant la VERSION du module, un script de test et un modèle de test pour montrer le problèmeE! Si vous êtes vraiment aventureux, HTML::Template a un serveur CVS disponible au public. Voyez plus bas pour plus d'informations dans la section SERVEUR CVS PUBLIC. =head1 CRÉDITS Ce module est le résultat de la réflexion de mon chef, Jesse Erlbaum ( jesse@vm.com ) chez Vanguard Media ( http://vm.com ) . La plus grand partie de l'idée d'origine dans ce module - le - est entièrement de lui. Les Fixes, Rapports de Bug, Optimisations et Idées ont été généreusement fournies parE: Richard Chen Mike Blazer Adriano Nagelschmidt Rodrigues Andrej Mikus Ilya Obshadko Kevin Puetz Steve Reppucci Richard Dice Tom Hukins Eric Zylberstejn David Glasser Peter Marelas James William Carlson Frank D. Cringle Winfried Koenig Matthew Wickline Doug Steinwand Drew Taylor Tobias Brox Michael Lloyd Simran Gambhir Chris Houser Larry Moore Todd Larason Jody Biggs T.J. Mather Martin Schroth Dave Wolfe uchum Kawai Takanori Peter Guelich Chris Nokleberg Ralph Corderoy William Ward Ade Olonoh Mark Stosberg Lance Thomas Roland Giersig Jere Julian Peter Leonard Kenny Smith Sean P. Scanlon Martin Pfeffer David Ferrance Gyepi Sam Darren Chamberlain Paul Baker Gabor Szabo Craig Manley Merci beaucoupE! =head1 SITE WEB Vous pouvez trouver de l'information à propos d'HTML::Template et d'autres modules du genre àE: http://html-template.sourceforge.net =head1 SERVEUR CVS PUBLIC HTML::Template a désormais un serveur CVS publiquement accessible fourni par SourceForge (www.sourceforge.net). Vous pouvez y accéder en allant à http://sourceforge.net/cvs/?group_id=1075. Allez y jeter un oeilE! =head1 AUTEUR Sam Tregar, sam@tregar.com =head1 LICENCE HTML::TemplateE: un module pour utiliser des modèles HTML avec Perl Copyright(C) 2000-2002 Sam Tregar (sam@tregar.com) This module is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with this module. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA