template.pm

1. 记录每个帖子的访问人情况

  </TMPL_LOOP>

=cut

=head1 Methods

=head2 new()

Call new() to create a new Template object:

  my $template = HTML::Template->new( filename => 'file.tmpl', 
                                      option => 'value' 
                                    );

You must call new() with at least one name => value pair specifying how
to access the template text.  You can use "filename => 'file.tmpl'" to
specify a filename to be opened as the template.  Alternately you can
use:

  my $t = HTML::Template->new( scalarref => $ref_to_template_text, 
                               option => 'value' 
                             );

and

  my $t = HTML::Template->new( arrayref => $ref_to_array_of_lines , 
                               option => 'value' 
                             );


These initialize the template from in-memory resources.  In almost
every case you'll want to use the filename parameter.  If you're
worried about all the disk access from reading a template file just
use mod_perl and the cache option detailed below.

You can also read the template from an already opened filehandle,
either traditionally as a glob or as a FileHandle:

  my $t = HTML::Template->new( filehandle => *FH, option => 'value');

The four new() calling methods can also be accessed as below, if you
prefer.

  my $t = HTML::Template->new_file('file.tmpl', option => 'value');

  my $t = HTML::Template->new_scalar_ref($ref_to_template_text, 
                                        option => 'value');

  my $t = HTML::Template->new_array_ref($ref_to_array_of_lines, 
                                       option => 'value');

  my $t = HTML::Template->new_filehandle($fh, 
                                       option => 'value');

And as a final option, for those that might prefer it, you can call new as:

  my $t = HTML::Template->new(type => 'filename', 
                              source => 'file.tmpl');

Which works for all three of the source types.

If the environment variable HTML_TEMPLATE_ROOT is set and your
filename doesn't begin with /, then the path will be relative to the
value of $HTML_TEMPLATE_ROOT.  Example - if the environment variable
HTML_TEMPLATE_ROOT is set to "/home/sam" and I call
HTML::Template->new() with filename set to "sam.tmpl", the
HTML::Template will try to open "/home/sam/sam.tmpl" to access the
template file.  You can also affect the search path for files with the
"path" option to new() - see below for more information.

You can modify the Template object's behavior with new.  These options
are available:

=over 4

=item *

die_on_bad_params - if set to 0 the module will let you call
$template->param(param_name => 'value') even if 'param_name' doesn't
exist in the template body.  Defaults to 1.

=item *

strict - if set to 0 the module will allow things that look like they might be TMPL_* tags to get by without dieing.  Example:

   <TMPL_HUH NAME=ZUH>

Would normally cause an error, but if you call new with strict => 0,
HTML::Template will ignore it.  Defaults to 1.

=item *

cache - if set to 1 the module will cache in memory the parsed
templates based on the filename parameter and modification date of the
file.  This only applies to templates opened with the filename
parameter specified, not scalarref or arrayref templates.  Caching
also looks at the modification times of any files included using
<TMPL_INCLUDE> tags, but again, only if the template is opened with
filename parameter.  

This is mainly of use in a persistent environment like
Apache/mod_perl.  It has absolutely no benefit in a normal CGI
environment since the script is unloaded from memory after every
request.  For a cache that does work for normal CGIs see the
'shared_cache' option below.

Note that different new() parameter settings do not cause a cache
refresh, only a change in the modification time of the template will
trigger a cache refresh.  For most usages this is fine.  My simplistic
testing shows that using cache yields a 90% performance increase under
mod_perl.  Cache defaults to 0.

=item *

shared_cache - if set to 1 the module will store its cache in shared
memory using the IPC::SharedCache module (available from CPAN).  The
effect of this will be to maintain a single shared copy of each parsed
template for all instances of HTML::Template to use.  This can be a
significant reduction in memory usage in a multiple server
environment.  As an example, on one of our systems we use 4MB of
template cache and maintain 25 httpd processes - shared_cache results
in saving almost 100MB!  Of course, some reduction in speed versus
normal caching is to be expected.  Another difference between normal
caching and shared_cache is that shared_cache will work in a CGI
environment - normal caching is only useful in a persistent
environment like Apache/mod_perl.

By default HTML::Template uses the IPC key 'TMPL' as a shared root
segment (0x4c504d54 in hex), but this can be changed by setting the
'ipc_key' new() parameter to another 4-character or integer key.
Other options can be used to affect the shared memory cache correspond
to IPC::SharedCache options - ipc_mode, ipc_segment_size and
ipc_max_size.  See L<IPC::SharedCache> for a description of how these
work - in most cases you shouldn't need to change them from the
defaults.

For more information about the shared memory cache system used by
HTML::Template see L<IPC::SharedCache>.

=item *

double_cache - if set to 1 the module will use a combination of
shared_cache and normal cache mode for the best possible caching.  Of
course, it also uses the most memory of all the cache modes.  All the
same ipc_* options that work with shared_cache apply to double_cache
as well.  By default double_cache is off.

=item *

blind_cache - if set to 1 the module behaves exactly as with normal
caching but does not check to see if the file has changed on each
request.  This option should be used with caution, but could be of use
on high-load servers.  My tests show blind_cache performing only 1 to
2 percent faster than cache under mod_perl.

NOTE: Combining this option with shared_cache can result in stale
templates stuck permanently in shared memory!

=item *

file_cache - if set to 1 the module will store its cache in a file
using the Storable module.  It uses no additional memory, and my
simplistic testing shows that it yields a 50% performance advantage.
Like shared_cache, it will work in a CGI environment. Default is 0.

If you set this option you must set the "file_cache_dir" option.  See
below for details.

NOTE: Storable using flock() to ensure safe access to cache files.
Using file_cache on a system or filesystem (NFS) without flock()
support is dangerous.


=item *

file_cache_dir - sets the directory where the module will store the
cache files if file_cache is enabled.  Your script will need write
permissions to this directory.  You'll also need to make sure the
sufficient space is available to store the cache files.

=item *

file_cache_dir_mode - sets the file mode for newly created file_cache
directories and subdirectories.  Defaults to 0700 for security but
this may be inconvenient if you do not have access to the account
running the webserver.

=item *

double_file_cache - if set to 1 the module will use a combination of
file_cache and normal cache mode for the best possible caching.  The
file_cache_* options that work with file_cache apply to double_file_cache
as well.  By default double_file_cache is 0.

=item *

associate - this option allows you to inherit the parameter values
from other objects.  The only requirement for the other object is that
it have a param() method that works like HTML::Template's param().  A
good candidate would be a CGI.pm query object.  Example:

  my $query = new CGI;
  my $template = HTML::Template->new(filename => 'template.tmpl',
                                     associate => $query);

Now, $template->output() will act as though 

  $template->param('FormField', $cgi->param('FormField'));

had been specified for each key/value pair that would be provided by
the $cgi->param() method.  Parameters you set directly take precedence
over associated parameters.  

You can specify multiple objects to associate by passing an anonymous
array to the associate option.  They are searched for parameters in
the order they appear:

  my $template = HTML::Template->new(filename => 'template.tmpl',
                                     associate => [$query, $other_obj]);

The old associateCGI() call is still supported, but should be
considered obsolete.

NOTE: The parameter names are matched in a case-insensitve manner.  If
you have two parameters in a CGI object like 'NAME' and 'Name' one
will be chosen randomly by associate.  This behavior can be changed by
the following option.

=item *

case_sensitive - setting this option to true causes HTML::Template to
treat template variable names case-sensitively.  The following example
would only set one parameter without the "case_sensitive" option:

  my $template = HTML::Template->new(filename => 'template.tmpl',
                                     case_sensitive => 1);
  $template->param(
    FieldA => 'foo',
    fIELDa => 'bar',
  );

This option defaults to off.

=item *

loop_context_vars - when this parameter is set to true (it is false by
default) four loop context variables are made available inside a loop:
__FIRST__, __LAST__, __INNER__, __ODD__.  They can be used with
<TMPL_IF>, <TMPL_UNLESS> and <TMPL_ELSE> to control how a loop is
output.  Example:

   <TMPL_LOOP NAME="FOO">
      <TMPL_IF NAME="__FIRST__">
        This only outputs on the first pass.
      </TMPL_IF>

      <TMPL_IF NAME="__ODD__">
        This outputs every other pass, on the odd passes.
      </TMPL_IF>

      <TMPL_UNLESS NAME="__ODD__">
        This outputs every other pass, on the even passes.
      </TMPL_IF>

      <TMPL_IF NAME="__INNER__">
        This outputs on passes that are neither first nor last.
      </TMPL_IF>

      <TMPL_IF NAME="__LAST__">
        This only outputs on the last pass.
      <TMPL_IF>
   </TMPL_LOOP>

One use of this feature is to provide a "separator" similar in effect
to the perl function join().  Example:

   <TMPL_LOOP FRUIT>
      <TMPL_IF __LAST__> and </TMPL_IF>
      <TMPL_VAR KIND><TMPL_UNLESS __LAST__>, <TMPL_ELSE>.</TMPL_UNLESS>
   </TMPL_LOOP>

Would output (in a browser) something like:

  Apples, Oranges, Brains, Toes, and Kiwi.

Given an appropriate param() call, of course.  NOTE: A loop with only
a single pass will get both __FIRST__ and __LAST__ set to true, but
not __INNER__.

=item *

path - you can set this variable with a list of paths to search for
files specified with the "filename" option to new() and for files
included with the <TMPL_INCLUDE> tag.  This list is only consulted
when the filename is relative.  The HTML_TEMPLATE_ROOT environment
variable is always tried first if it exists.  In the case of a
<TMPL_INCLUDE> file, the path to the including file is also tried
before path is consulted.

Example:

   my $template = HTML::Template->new( filename => 'file.tmpl',
                                       path => [ '/path/to/templates',
                                                 '/alternate/path'
                                               ]
                                      );

NOTE: the paths in the path list must be expressed as UNIX paths,
separated by the forward-slash character ('/').

=item *

no_includes - set this option to 1 to disallow the <TMPL_INCLUDE> tag
in the template file.  This can be used to make opening untrusted
templates B<slightly> less dangerous.  Defaults to 0.

=item *

max_includes - set this variable to determine the maximum depth that
includes can reach.  Set to 10 by default.  Including files to a depth
greater than this value causes an error message to be displayed.  Set
to 0 to disable this protection.

=item *

search_path_on_include - if set to a true value the module will search
from the top of the array of paths specified by the path option on
every <TMPL_INCLUDE> and use the first matching template found.  The
normal behavior is to look only in the current directory for a
template to include.  Defaults to 0.

=item *

global_vars - normally variables declared outside a loop are not
available inside a loop.  This option makes <TMPL_VAR>s like global
variables in Perl - they have unlimited scope.  This option also
affects <TMPL_IF> and <TMPL_UNLESS>.

Example:

  This is a normal variable: <TMPL_VAR NORMAL>.<P>

  <TMPL_LOOP NAME=FROOT_LOOP>
     Here it is inside the loop: <TMPL_VAR NORMAL><P>
  </TMPL_LOOP>

Normally this wouldn't work as expected, since <TMPL_VAR NORMAL>'s
value outside the loop is not available inside the loop.

=item *

filter - this option allows you to specify a filter for your template
files.  A filter is a subroutine that will be called after
HTML::Template reads your template file but before it starts parsing
template tags.

In the most simple usage, you simply assign a code reference to the
filter parameter.  This subroutine will recieve a single arguement - a
reference to a string containing the template file text.  Here is an
example that accepts templates with tags that look like "!!!ZAP_VAR
FOO!!!" and transforms them into HTML::Template tags:

   my $filter = sub {
     my $text_ref = shift;
     $$text_ref =~ s/!!!ZAP_(.*?)!!!/<TMPL_$1>/g;
   }   

   # open zap.tmpl using the above filter
   my $template = HTML::Template->new(filename => 'zap.tmpl',
                                      filter => $filter);