Template模块文档翻译

1、package Template;$Template:VERSION = 2.6;=head1 NAMETemplate - 在CGI中使用HTML模板的模块=head1 SYNOPSIS首先你需要创建一个模板 - 仅仅是带有扩展的标志的 HTML 文件,最常见的扩展标志就是 例如, test.tmpl:Test TemplateMy Home Directory is My Path is set to 现在创建一个小 CGI 程序:#!/usr/bin/perl -wuse Template;# 打开HTML模板my $template = Template-new(filename =

2、test.tmpl);# 填充部分参数$template-param(HOME = $ENVHOME);$template-param(PATH = $ENVPATH);#发送必须的 Content-Type，并且打印模板输出print Content-Type: text/htmlnn, $template-output;如果设置正确的话，运行CGI程序以后，将在浏览器中显示如下的内容：My Home Directory is /home/some/directoryMy Path is set to /bin;/usr/bin=head1 DESCRIPTION本模块试图简单并且自然的使用

3、 HTML 模板.她继承了 HTML 并且扩展了部分新的HTML标签-,和.使用HTML和上述的标签编写的模板将会被调用，也就是说你的模板可以和你的脚本分离，甚至可以由其他人来创建，修改，然后使用本模块来填充模板中的变量，循环和分支申明.这将帮助你将脚本使用的 数据结构设计 和 HTML 分开.=head1 THE TAGS=head2 TMPL_VAR 标签非常的简单.模板中的每个 都要调用$template-param(PARAMETER_NAME = VALUE).当页面输出的时候， 将会被你赋的变量值取代.如果你没有设置模板中的一些变量值，在输出时仅仅跳过.一个可选的属性：你可以在你的

4、标签里面使用 ESCAPE=HTML ，以在输出前编码部分HTML字符.也就是说, , 和 & 字符将转换为 , 和 &.这个属性在你的变量中如果包含HTML代码可能会带来麻烦的时候才非常有用.例:input name=param type=text value=如果你给 param() 传递类似与 sammy ，那么你将会在双引号部分引来麻烦.在另外一个方面, 如果你使用ESCAPE=HTML, 例如:input name=param type=text value=无论提交者提交的参数怎么变化，你将会得到任何你想得到的值.你可以使用的格式： ESCAPE=HTML, ESCAPE=HTML

5、 和 ESCAPE=1.如果传递给 ESCAPE 的参数0，将关闭过滤，而且默认的设置是关闭的.同样你也可以使用 ESCAPE=URL 来处理URL.她将做 URL 过滤, 比如，替换 为 +和替换 / 为 %2F.你也可以使用一个 DEFAULT 来设置缺省的默认值.例如, 你要输出 the devil gave me a taco，如果 who 变量没有被设置.The gave me a taco.=head2 TMPL_LOOP . 标签比稍微复杂一点. 允许你划定一块文本区块，并且给她一个名字. 在区块内部，你可以放置标签. 为了循环，需要传递给param()的参数分配(散列引用（ha

6、sh refs）)一个表 (一个数组（array ref）).循环将重述列表，并且给每个参数产生文本块. 未设置的参数将会被跳过. 举例如下：模板文件:Name: Job: 脚本:$template-param(EMPLOYEE_INFO = name = Sam, job = programmer , name = Steve, job = soda jerk ,);print $template-output();浏览器中的输出:Name: SamJob: programmerName: SteveJob: soda jerk如上面你所见进行了参数的分配并且重述了循环输出一般情况下，如果你

7、想用程序产生一个的循环，下面是一个详细的例子(可能有很多种其他方法可以实现!):# 需要放入循环中的数组:my words = qw(I Am Cool);my numbers = qw(1 2 3);my loop_data = (); # 初始化循环数组while (words and numbers) my %row_data; # 使用新的散列# fill in this row$row_dataWORD = shift words;$row_dataNUMBER = shift numbers;# 先将数据保存在散列中，然后在压入数组push(loop_data, %row_data

8、);# 为 param()传递参数（引用）$template-param(THIS_LOOP = loop_data);上面的例子可以与下面的模板一起工作:Word: Number: 她将产生如下的输出:Word: INumber: 1Word: AmNumber: 2Word: CoolNumber: 3嵌套的 也可以很好按照你的期望的情况正确的工作.如果传递给 param() 的参数有冗余, 下面是使用嵌套的一个例子:$template-param(LOOP = name = Bobby,nicknames = name = the big bad wolf , name = He-Man

9、 ,);基本上, 每个将获取一个数组引用.数组内部是任意数量的散列引用.这些散列包含name=value对来给模板中的循环传递单个的参数.在中, 变量仅仅能够在 以后才可用.模板中的的区块外的变量将不可见.由于Perl语言的面向对象的特殊性, 引入了新的类似于Perl子程序的调用.如果你想变量是全局可用的，你可以在new()使用global_vars选项描述.=head2 TMPL_INCLUDE该标签在当前模板点包含一个模板进来. 被包含的模板内容与直接放置在主模板中的效果一样.文件路径可以是绝对路径(在UNIX中以 /开头).如果不是绝对路径，模块将在文件的当前路径搜索.如果没有找到，并且

10、环境变量中的HTML_TEMPLATE_ROOT变量如果存在，该路径将会被搜索.最后, path 选项将要考虑;总之，首先是当前，其次是HTML_TEMPLATE_ROOT,最后文件名将传递给 open().查看下面的关于HTML_TEMPLATE_ROOT和 new()的path选项获得更多的信息.作为HTML_INCLADE的多重递归调用的保护措施, 默认HTML_INCLADE只在10层以内才起作用.你可以使用 max_includes 选项转换限制条件.查看下面的 max_includes 选项获得更多的细节.=head2 TMPL_IF . 标签可以由传递的参数决定是不是要在输出中包

11、含一段文字块.如果参数是Perl中的真值的话（例如 1），然后文字块将会被包含.如果是未定义或者是否（例如0），然后文字块将会被跳过.参数传递方法类似于TMPL_VAR.例:Some text that only gets displayed if BOOL is true!如果你调用$template-param(BOOL = 1)，然后上面的文字块将会被包含在输出中.块可以包含在任意的有效模板中，比如VARs和LOOPs以及其他的IF/ELSE结构.注意,交叉的和是无效的.下面的将不能够正常的工作:如果TMPL_LOOP的名字与TMPL_IF相同,并且LOOP至少含有一行，IF块将会输出.

12、例:This will output if the loop is not empty.警告: 模块的最大的优点就是协调了HTML和Perl的相互关系.如果你使用TMPL_IF和Perl if()交叉使用很多的话，那么你会给维护带来很多的困难.所以我建议你仅仅使用TMPL_IF，只要你可以不使用Perl代码中的 if()的情况下.=head2 TMPL_ELSE.你可以使用TMPL_ELSE在你的TMPL_IF中包含一个选择.注意:你仍然要用来结束，而不是!例:Some text that is included only if BOOL is trueSome text that is in

13、cluded only if BOOL is false=head2 TMPL_UNLESS.这是对立的标签.如果控制参数为假，或者未定义，文字块将会输出.你可以使用来搭配，使用方法类似与.例:Some text that is output only if BOOL is FALSE.Some text that is output only if BOOL is TRUE.如果TMPL_LOOP的名字被使用在TMPL_UNLESS中, 那么并且LOOP没有内容，UNLESS块将会输出.例：This will output if the loop is empty.=cut=head2 NO

14、TESTemplate的标签试图模仿标准的HTML的语法.然而,它们被允许打破惯例.类似于:img src=这并不是真正有效的HTML, 但是却是非常有效的代码，可以按照希望的要求工作.选项 NAME= 是可选的, 虽然为了更好的展开，我强烈建议使用她.例如 是接受的.如果你是标准HTML的追随者，并且希望你的模板也遵循标准的HTML语法,你可以按照HTML的形式随意的定义模板的标签.这可能对使用HTML的编辑器或者那些使用DTD格式的工具来检查模板的HTML语法的人员.为了方便说明, 标准的标签将在本文档中使用.=head1 METHODS=head2 new()调用 new() 创建一个新

15、的模板对象:my $template = Template-new( filename = file.tmpl,option = value);调用 new() 的时候，你必须至少含有一对name = value对来指定访问模板文件的方法.你可以使用filename = file.tmpl 来指定一个文件名来打开她作为一个模板.类似的，你也可以使用:my $t = Template-new( scalarref = $ref_to_template_text,option = value);和my $t = Template-new( arrayref = $ref_to_array_of_l

16、ines ,option = value);这些都是初始化模板进入内存资源.在大多数的情况下，你可以想使用文件名参数.如果你担心使用mod_perl以后，所有的模板的访问权限，那么缓冲选项的细节部分如下.你可以从已经打开的文件句柄中读取模板，类似与传统的typeglob以及FileHandle:my $t = Template-new( filehandle = *FH, option = value);如果你喜欢，四个新的 new() 调用方法样式也可以使用.my $t = Template-new_file(file.tmpl, option = value);my $t = Templa

17、te-new_scalar_ref($ref_to_template_text,option = value);my $t = Template-new_array_ref($ref_to_array_of_lines,option = value);my $t = Template-new_filehandle($fh,option = value);作为最后一个选项, 可能会有人需要, 你可以这样调用new()方法:my $t = Template-new( type = filename,source = file.tmpl);她将可以与三种源一起工作.如果环境变量HTML_TEMPLA

18、TE_ROOT被设置，并且文件名是以/开始(UNIX),那么文件的路径将关联到$HTML_TEMPLATE_ROOT 的值.例如,环境变量HTML_TEMPLATE_ROOT被设置为/home/sam并且我使用文件名sam.tmpl调用，那么Template将会打开/home/sam/sam.tmpl访问模板.你仍然可以使用new()的path选项来影响路径（查看下面获得更多的信息）.你可以使用new来修改Template对象的行为.这些选项都是有效的:=over 4=item Error Detection Options=over 4=item *die_on_bad_params - 如

19、果设置为0，那么，模块允许在param_name不存在的情况下，调用$template-param(param_name = value)，而不退出. 默认设置为1.=item *strict - 如果设置为0，那么，模块允许在TMPL_*被使用而不退出.例:通常情况下将是一个错误, 但是你在调用new的时候使用strict = 0,标签将会忽略.默认设置为 1.=item *vanguard_compatibility_mode - 如果设置为1，那么模块将愿意看到标签看起来类似于 %NAME% 作为传统方式（早期）的补充.同时也要设置 die_on_bad_params = 0.默认为 0

20、.=back=item Caching Options=over 4=item *cache - 如果设置为1，模块将要在内存中缓冲，然后按参数分析模板并且修正文件中的数据.这仅仅作用适用于使用指定文件名的方式打开模板, 而不是标量引用(scalarref)和数组引用模块(arraryref).缓冲同样也查看任何文件的修正时间,包含使用的标签, 但是，再一次说明：仅仅适用于指定文件名的方式打开模板的.这主要是服务于类似于Apache/mod_perl等持久稳固的环境中使用.这对使用普通的CGI环境是绝对没有任何益处的，因为程序在每次请求以后都要从内存中清除的.为了能够与通常的CGI程序缓冲，查

21、看下面的shared_cache选项.注意：不同的new()参数设置不会导致缓冲的刷新, 仅仅修正模板的时间更改将会引发缓冲的刷新.对大多数的使用，这种方法是很好的.在mod_perl下，我简单测试了一下，使用cache使90%的执行过程提高了速度.Cache 默认为0.=item *shared_cache - 如果设置为 1 模块将使用IPC:SharedCache(可以从 CPAN 站点获得)模块，保存缓冲在共享的内存中.这样做的的好处就是为使用每个分析模板的一个共享进程，这将在多用户的服务器环境中大幅度的减少内存的使用.举例,在一个系统上，我们使用 4MB 模板高速缓冲并且维持 25

22、个httpd进程shared_cache可以节省大约 100MB!当然, 相对与使用传统的高速缓冲来言，一些速度损失是不可以避免的.另外一个在cache和shared_cache就是shared_cache可以工作在CGI环境中，而cache仅仅在Apache/mod_perl等持久稳定的系统中有效.默认的，模板使用IPC键 TMPL 作为共享的根段(0x4c504d54 in hex),但是，这将可以通过在new()中对四种另外的方式和整数关键字设置ipc_key来修改.另外的相应与IPC:SharedCache可选项可以影响共享的内存-ipc_mode, ipc_segment_size

23、和ipc_max_size. 查看L了解这些是怎么工作的（在大多数情况下，我们不需要改变默认值）.查看L获得更多关于共享内存的系统信息.=item *double_cache - 如果设置为1模块将使用shared_cache和cache模式的联合体来获取更优的缓冲方式.当然，她仍然是消耗两种的模式中其中一种的内存.同样的 ipc_* 选项，也可以以shared_cache方式工作应用.默认，double_cache是关闭的.=item *blind_cache - 如果设置为1，模块将以通常的cache方式工作，只是每次请求时不检查文件是不是已经更新. 该选项的使用请无比小心, 但是切可以用

24、与高负载的服务器上.我的测试显示，在mod_perl下，使用blind_cache仅仅使提高了速度1-2%.注意: 综合该选项与shared_cache，会导致陈旧的模板长贮内存！=item *file_cache - 如果设置为1，模块将使用Storable模块，将缓冲保存在文件中.她将不再使用额外的内存, 我的简单测试显示她收到了50% 的执行效益.类似与shared_cache, 她也可以适应CGI环境. 默认设置为0.如果你设置改属性，你还必须设置file_cache_dir选项.查看获得更多细节问题.注意: Storable模块使用flock()来保证缓冲文件的安全访问.在一个不支持

25、flock()的系统（Win95等）或者文件系统（NFS等）使用将会带来危害.=item *file_cache_dir - 如果使用file_cache，设置文件高速缓冲的高速缓冲文件目录.你的脚本必须获得此目录的写权限. 你又必须确保有足够的可用空间来保存缓冲文件.=item *file_cache_dir_mode - 设置新建的缓冲文件的目录和子目录模式.为了服务器的安全，默认为0700，但是在你使用你的服务器帐号登陆时，可能会给您带来不便.=item *double_file_cache - 如果设置为1，模块将综合使用file_cache和cache来获得多可能的缓冲.与file_

26、cache协同工作的file_cache_* 选项使用于double_file_cache.默认情况下，double_file_cache设置为0.=back=item Filesystem Options=over 4=item *path - 在new()中，你可以向该变量传递一个列表来设置filename和标签指定的文件和来设置搜索的目录. 在文件名为相对路径，该列表仅仅是用来参考的.如果HTML_TEMPLATE_ROOT环境变量存在的话，她将会首先被尝试的.同样, 如果设置了HTML_TEMPLATE_ROOT，系统将会尝试把优先把HTML_TEMPLATE_ROOT路径添加到pat

27、h数组. 在文件中, 当HTML_TEMPLATE_ROOT路径被参考之前，被包含的文件的路径将会被优先考虑.例:my $template = Template-new( filename = file.tmpl,path = /path/to/templates,/alternate/path);注意: 路径信息中的路径必须是unix的路径表达形式,使用斜杠(/)来分割的.=item *search_path_on_include - 如果设置为真值的话，对每个标签，模块将中path指定的路径数组的顶端开始搜索，并且使用找到第一个匹配的模板.通常情况下，仅仅在当前的目录中查找模板. 默认设置

28、为0.=back=item Debugging Options=over 4=item *debug - 如果设置为1，模块将会把任意的调试信息写到STDERR.默认为0.=item *stack_debug - 如果设置为1，模块将使用 Data:Dumper 打印分析栈的内容到STDERR.默认设置为 0.=item *cache_debug - 如果设置为1，模块将发送关于缓冲加载，采样和错误信息到STDERR.默认设置0.=item *shared_cache_debug - 如果设置为1，模块将打开IPC:SharedCache中的调试选项（查看 L获得更多信息）. 默认设置0.=i

29、tem *memory_debug - 如果设置为1，模块将发送关于缓冲内存的使用情况到STDERR，该功能依赖于GTop模块.默认设置0.=back=item Miscellaneous Options=over 4=item *associate - 该选项允许你继承其他对象的参数.仅仅的要求就是所继承的对象要有一个类似与Template的param()的param()方法.一个比较优秀的就是CGI.pm的查询对象.例:my $query = new CGI;my $template = Template-new(filename = template.tmpl,associate = $

30、query);然后, $template-output()将会安照$template-param(FormField, $cgi-param(FormField)方式运行;每个指定的 key/value 对将由$cgi-param()方法提供.你所设置的参数将优先于关联的参数.你可以通过传递匿名的数组指定多重的对象来关联.他们按照他们出现的顺序来查找参数:my $template = Template-new(filename = template.tmpl,associate = $query, $other_obj);老版本的 associateCGI() 调用仍然支持, 但是现在考虑荒废

31、她.注意: 参数名是不区分大小写的.如果你在CGI对象中有两个参数名，NAME 和 Name，他们其中之一将会被随机的使用.该行为可能被下面的选项控制.=item *case_sensitive - 设置该选项为真，将导致Template处理模板变量名时区分大小写.如果不使用case_sensitive，下面的例子将仅仅设置一个参数：my $template = Template-new(filename = template.tmpl,case_sensitive = 1);$template-param(FieldA = foo,fIELDa = bar,);该选项默认是关闭的.注意: 使

32、用case_sensitive和loop_context_vars，那么特殊的循环变量将仅仅小写有效.=item *loop_context_vars - 当该参数设置为真时(默认为非) 四个循环的上下文变量将在循环中生效:_first_, _last_, _inner_, _odd_. 他们可以与, 和 一起使用来控制循环的输出.做为以上的补充, 当循环的上下文变量打开以后，一个 _counter_ 变量也将生效.例:This only outputs on the first pass.This outputs every other pass, on the odd passes.Thi

33、s outputs every other pass, on the even passes.This outputs on passes that are neither first nor last.This is pass number .This only outputs on the last pass.该功能的一个典型用法就是提供一个离析器，类似于perl的函数join().例: and , .将输出 (在浏览器中) :Apples, Oranges, Brains, Toes, and Kiwi.当然，必须提供一个适当的param()调用.注意: 一个只有一个参数的循环，_fir

34、st_ 和 _last_将全部设置为真, 但是却没有_inner_.=item *no_includes - 该选项设置为1，将在模板中禁止使用 标签.这样可以可以给开放的模板减少危险. 默认设置为 0.=item *max_includes - 设置包含功能能够达到的最大的深度. 默认设置为 10.包含超过深度的文件将会显示一个错误. 设置为 0，可以关闭该保护功能.=item *global_vars - 通常的，在循环外面定义的变量将在循环中无效.该选项使 类似与全局变量- 她们将变的没有现在.该选项也会影响和.例:This is a normal variable: .Here it

35、is inside the loop: 通常她不能够按照期望来工作, 因为在循环以外的 值在循环内是无效的.global_vars 允许你访问装入循环的值.例如, 在本循环在中，内部循环将可以存取循环外部的值OUTER_VAR:OUTER: INNER: INSIDE OUT: =item *filter - 该选项允许你指定一个你的模板文件的过滤方法.一个过滤其实是一个在模板阅读以后，但是在解析模板标签之前的子程序.在大多数的简单运用中, 你简单的给过滤参数分配一个代码引用.该子程度将接受一个参数 - 一个指向模板中的字符串引用. 下面是一个接受类似于!ZAP_VARFOO!的标签的例子，然

36、后将他转换为模板的标签:my $filter = sub my $text_ref = shift;$text_ref = s/!ZAP_(.*?)!/g;# open zap.tmpl using the above filtermy $template = Template-new(filename = zap.tmpl,filter = $filter);更多可能的使用方法都是可能的. 您可以要求您的过滤接受一个模板文件作为一个行数组而不是单独的一个标量.要做的就是，你指点你的一个使用散列的过滤.在这样的形式，你使用sub关键字指定一个过滤和使用format关键字指定要求的参数形式.有效

37、的格式就是scalar和array.使用array格式将招致执行错误，但是在很多情况下可以带来方便.my $template = Template-new(filename = zap.tmpl,filter = sub = $filter,format = array );你可能使用多重的过滤. 为可过多的具体的功能，她可以允许简单的过滤的组合.仅仅要做的就是指定一个过滤数组. 过滤将按照他们被指定的顺序来过滤.my $template = Template-new(filename = zap.tmpl,filter = sub = &decompress,format = scalar

38、, sub = &remove_spaces,format = array );类似于主模板中，指定的过滤将会在任何TMPL_INCLUDE包含的文件中起作用.=back=back 4=cutuse integer; # no floating point math so far!use strict; # and no funny business, either.use Carp; # generate better errors with more contextuse File:Spec; # generate paths that work on all platforms# define accessor constants used to improve readability of array# accesses into objects. I used to use use constant but that# seems to cause occasional irritating warnings in older Perls.package Template:LOOP;sub TEMPLATE_HASH () 0; sub PARAM