template.pm

稀饭伊人相册系统继承了新天堂多用户相册系统的功能

    ....
  </TMPL_LOOP>

=cut

=head2 NOTES

HTML::Template's tags are meant to mimic normal HTML tags.  However,
they are allowed to "break the rules".  Something like:

   <img src="<TMPL_VAR IMAGE_SRC>">

is not really valid HTML, but it is a perfectly valid use and will
work as planned.

The "NAME=" in the tag is optional, although for extensibility's sake I
recommend using it.  Example - "<TMPL_LOOP LOOP_NAME>" is acceptable.

If you're a fanatic about valid HTML and would like your templates
to conform to valid HTML syntax, you may optionally type template tags
in the form of HTML comments. This may be of use to HTML authors who
would like to validate their templates' HTML syntax prior to
HTML::Template processing, or who use DTD-savvy editing tools.

  <!-- TMPL_VAR NAME=PARAM1 -->

In order to realize a dramatic savings in bandwidth, the standard
(non-comment) tags will be used throughout this documentation.

=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().  The options
are available:

=over 4

=item Error Detection Options

=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 *

vanguard_compatibility_mode - if set to 1 the module will expect to
see <TMPL_VAR>s that look like %NAME% in addition to the standard
syntax.  Also sets die_on_bad_params => 0.  If you're not at Vanguard
Media trying to use an old format template don't worry about this one.
Defaults to 0.

=back

=item Caching Options

=over 4

=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.

=back

=item Filesystem Options

=over 4

=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.  Also, if
HTML_TEMPLATE_ROOT is set then an attempt will be made to prepend
HTML_TEMPLATE_ROOT onto paths in the path array.  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 *

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.

=back

=item Debugging Options

=over 4

=item *

debug - if set to 1 the module will write random debugging information
to STDERR.  Defaults to 0.

=item *

stack_debug - if set to 1 the module will use Data::Dumper to print
out the contents of the parse_stack to STDERR.  Defaults to 0.

=item *

cache_debug - if set to 1 the module will send information on cache
loads, hits and misses to STDERR.  Defaults to 0.

=item *

shared_cache_debug - if set to 1 the module will turn on the debug
option in IPC::SharedCache - see L<IPC::SharedCache> for
details. Defaults to 0.

=item *

memory_debug - if set to 1 the module will send information on cache
memory usage to STDERR.  Requires the GTop module.  Defaults to 0.

=back

=item Miscellaneous Options

=over 4

=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.

NOTE: with case_sensitive and loop_context_vars the special loop
variables are available in lower-case only.