ktemplate.pm

Astercon2 开源软交换 2.2.0

  $tpl->assign( VARIABLE => 'Value' );

To access a multidimensional hash data structure, the variable names are separated by a dot. In the following example, two values for the variables C<[% USER.NAME %]> and C<[% USER.EMAIL %]> are assigned:

  $tpl->assign(
  
      USER => {
          NAME  => 'Kasper Dziurdz',     # [% USER.NAME %]
          EMAIL => '[e-mail]',   # [% USER.EMAIL %]
      },
      
  );

If the value of a variable is a reference to a subroutine, the subroutine is called and the returned string is included in the output. This is the only way to execute Perl code in a template.

  $tpl->assign(
  
      BENCHMARK => sub {
          # get benchmark data
          return 'created in 0.01 seconds';
      }
  
  );


=head1 BLOCKS

Blocks allow you to create loops and iterate over a part of a template or to write simple if-statements. A block begins with C<< <!-- BEGIN BLOCKNAME --> >> and ends with C<< <!-- END BLOCKNAME --> >>. This is an example of creating a block with the C<block()> method:

  $tpl->assign( HEADER  => 'Some numbers:' );
  
  @block_values = ('One', 'Two', 'Three', 'Four');
  
  foreach (@block_values) {
  
      $tpl->block('LOOP_NUMBERS');
      $tpl->assign( NUMBER    => $_ );
      $tpl->assign( SOMETHING => '' );
  
  }
  
  $tpl->block();  # leave block
  
  $tpl->assign( FOOTER => '...in words.' );

Each time C<block()> is called it creates a new loop in the selected block. All variable values passed to C<assign()> are assigned only to this loop until a new loop is created or C<block()> is called without any arguments to assign global variables again. This is a template for the script above:

  [% HEADER %]
  
  <!-- BEGIN LOOP_NUMBERS -->
  
    [% NUMBER %]
  
  <!-- END LOOP_NUMBERS -->
  
  [% FOOTER %]

Global variables (or outer block variables) are also available inside a block. However, if there is a block variable with the same name, the block variable is preferred.

Because a block is a normal variable with an array reference, blocks can also be created without the C<block()> method:

  $tpl->assign( 
      HEADER  => 'Some numbers:',
      LOOP_NUMBERS => 
          [
              { NUMBER => 'One'   },
              { NUMBER => 'Two'   },
              { NUMBER => 'Three' },
              { NUMBER => 'Four'  },
          ],
      FOOTER => '...in words.',
  );

Loops within loops work as you would expect. To create a nested loop with C<block()>, you have to pass all block names separate as a list or joined with a dot, for example as C<BLOCK_1.BLOCK_2>. This way, a new loop for C<BLOCK_2> is created in the last loop of C<BLOCK_1>. The variable values are assigned with C<assign()>.

  foreach (@block_one) {
  
      $tpl->block('BLOCK_1');
      $tpl->assign(VAR => $_);
  
      foreach (@block_two) {
  
          $tpl->block('BLOCK_1', 'BLOCK_2');
          $tpl->assign(VAR => $_);
  
      }
  }
  
  $tpl->block();  # leave block

The template would look like this:

  <!-- BEGIN BLOCK_1 -->
  
      <!-- BEGIN BLOCK_2 -->
  
      <!-- END BLOCK_2 -->
  
  <!-- END BLOCK_1 -->

B<Important: You have to call C<block()> without any arguments to assign global variables again.>

It is also possible to create a loop with the C<assign()> method by passing the block name as the first argument (or all block names joined with a dot to create nested loops). The variables can be assigned only once and not as a hash reference but there is no need to use the C<block()> method.

  $tpl->assign( BLOCK,  # assign to this block
      VARIABLE_1 => 'Block ...',
      VARIABLE_2 => 'Block ...',
  );
  
  $tpl->assign(  # assign global again
      VARIABLE_3 => 'Global ...'.
  );

Blocks can even be used to create if-statements. Simply assign a variable with a true or false value. Based on that, the block is skipped or included in the output. 

  $tpl->assign( SHOW_INFO  => 1 );  # show block SHOW_INFO
  $tpl->assign( SHOW_LOGIN => 0 );  # skip block SHOW_LOGIN

For a better control of the loop output, three special loop variables can be made available inside a loop: C<FIRST>, C<INNER> and C<LAST>. This variables are disabled by default (see L<OPTIONS|"Loop Vars"> section how to enable them).

  <!-- BEGIN LOOP -->
  
  
      <!-- BEGIN FIRST -->
       First loop pass
      <!-- END FIRST -->
  
  
      <!-- BEGIN INNER -->
       Neither first nor last
      <!-- END INNER -->
  
  
      <!-- BEGIN LAST -->
       Last loop pass
      <!-- END LAST -->
  
  
  <!-- END LOOP -->


=head1 INCLUDES

Includes are used to process and include the output of another template file directly into the current template in place of the include tag. All variables and blocks assigned to the current template are also available inside the included template.

  <!-- INCLUDE file.tpl -->
  
  <!-- INCLUDE "file.tpl" -->
  
  <!-- INCLUDE 'file.tpl' -->

If the template can't be found under the specified file path (considering the root path), the path to the enclosing file is tried. See L<OPTIONS|"No Includes"> section how to disable includes or change the limit for recursive includes. 

It is possible to include template files defined by a variable when the option for including variables is enabled (it is disabled by default).

  <!-- INCLUDE VARIABLE -->


=head1 ADVANCED

Although it is possible to create loops and if statements with the block tag, sometimes the template syntax might get too confusing or not allow to write the wanted conditions in an easy way. For this reason if, unless, else and loop tags are available.

  <!-- IF VARIABLE -->
  
  <!-- END VARIABLE -->
   
   
  <!-- UNLESS VARIABLE -->
 
  <!-- END VARIABLE -->
   
   
  <!-- LOOP ARRAY -->
  
  <!-- END ARRAY -->
   
   
  <!-- IF VARIABLE -->
  
  <!-- ELSE VARIABLE -->
  
  <!-- END VARIABLE -->

The else tag can be used with all statements, even with loops. For an even cleaner template syntax, the else and the end tag can be written without the variable name.

  <!-- BEGIN ARRAY -->
  
  <!-- END -->
   
   
  <!-- IF VARIABLE -->
  
  <!-- ELSE -->
  
  <!-- END -->

The following syntax is also allowed but will not work with the block tag:

  <!-- IF VARIABLE -->
  
  <!-- ELSE -->
  
  <!-- END IF -->
   
   
  <!-- LOOP ARRAY -->
  
  <!-- END LOOP -->


=head1 METHODS

=head2 new()

Creates a new template object.

  $tpl = HTML::KTemplate->new();
  
  $tpl = HTML::KTemplate->new('/path/to/templates');
  
  $tpl = HTML::KTemplate->new( 
      root         => '/path/to/templates',
      cache        => 0,
      strict       => 0,
      no_includes  => 0,
      max_includes => 15,
      loop_vars    => 0,
      blind_cache  => 0,
      include_vars => 0,
      parse_vars   => 0,
  );


=head2 assign()

Assigns values for the variables used in the template.

  %hash = (
      VARIABLE => 'Value',
  );
  
  $tpl->assign( %hash );
  $tpl->assign(\%hash );
  $tpl->assign( VARIABLE => 'Value' ); 
    
  $tpl->assign( BLOCK,
      VARIABLE => 'Value',
      VARIABLE => 'Value',
  );

=head2 block()

See the description of L<BLOCKS|"BLOCKS">.

  $tpl->block('BLOCK_1');
  
  $tpl->block('BLOCK_1','BLOCK_2');
  $tpl->block('BLOCK_1.BLOCK_2');
  
  $tpl->block();  # leave block

=head2 process()

The C<process()> method is called to process the template files passed as arguments. It loads each template file, parses it and adds it to the template output. It is also possible to pass a reference to a scalar, array or file handle to initialize the template from memory. The use of the template output is determined by the C<print()> or the C<fetch()> method. 

  $tpl->process('header.tpl', 'footer.tpl');
  
  $tpl->process('header.tpl');
  $tpl->process('footer.tpl');
  
  $tpl->process(\$scalar);
  $tpl->process(\@array);
  $tpl->process(\*FH);

=head2 print()

Prints the output data to C<STDOUT>. If a file handle reference is passed, it is used instead of the standard output.

  $tpl->print();
  
  $tpl->print(\*FILE);

=head2 fetch()

Returns a scalar reference to the output data. 

  $output_ref = $tpl->fetch();
  
  print FILE $$output_ref;

=head2 clear()

Clears all variable values and other data being held in memory (except cache data). 

  $tpl->clear();

Equivalent to:

  $tpl->clear_vars();
  $tpl->clear_out();

=head2 clear_vars()

Clears all assigned variable values.

  $tpl->clear_vars();

=head2 clear_out()

Clears all output data created by C<process()>.

  $tpl->clear_out();

=head2 clear_cache()

Empties all cache data.

  $tpl->clear_cache();


=head1 OPTIONS

=head2 Variable Tag

  $HTML::KTemplate::VAR_START_TAG = '[%';
  $HTML::KTemplate::VAR_END_TAG   = '%]';

=head2 Block Tag

  $HTML::KTemplate::BLOCK_START_TAG = '<!--';
  $HTML::KTemplate::BLOCK_END_TAG   = '-->';

=head2 Include Tag

  $HTML::KTemplate::INCLUDE_START_TAG = '<!--';
  $HTML::KTemplate::INCLUDE_END_TAG   = '-->';

=head2 Root

  $HTML::KTemplate::ROOT = undef;  # default
  $HTML::KTemplate::ROOT = '/path/to/templates';
  
  $tpl = HTML::KTemplate->new( '/path/to/templates' );
  $tpl = HTML::KTemplate->new( root => '/path/to/templates' );

=head2 No Includes

Set this option to 1 to disable includes. The include tags will be skipped unless the strict option is set to 1.

  $tpl = HTML::KTemplate->new( no_includes => 0 );  # default
  $tpl = HTML::KTemplate->new( no_includes => 1 );

=head2 Max Includes

Allows to set the maximum depth that includes can reach. An error is raised when this depth is exceeded.

  $tpl = HTML::KTemplate->new( max_includes => 15 );  # default

=head2 Include Vars

Allows to include template files defined by a variable (see the description of L<INCLUDES|"INCLUDES"> for more information).

  $tpl = HTML::KTemplate->new( include_vars => 0 );  # default
  $tpl = HTML::KTemplate->new( include_vars => 1 );

=head2 Cache

Caching option for a persistent environment like mod_perl. Parsed templates will be cached in memory based on their file path and modification date. Use C<clear_cache()> to empty cache.

  $tpl = HTML::KTemplate->new( cache => 0 );  # default
  $tpl = HTML::KTemplate->new( cache => 1 );

=head2 Blind Cache

Behaves as the normal caching option but does not check the modification date to see if the template has changed. This might result in some speed improvement over normal caching.

  $tpl = HTML::KTemplate->new( blind_cache => 0 );  # default
  $tpl = HTML::KTemplate->new( blind_cache => 1 );

=head2 Loop Vars

Set this option to 1 to enable the loop variables C<FIRST>, C<INNER> and C<LAST>.

  $tpl = HTML::KTemplate->new( loop_vars => 0 );  # default
  $tpl = HTML::KTemplate->new( loop_vars => 1 );

The default loop variables can be changed in the following way:

  $HTML::KTemplate::FIRST = { 'FIRST' => 1, 'first' => 1 };
  $HTML::KTemplate::INNER = { 'INNER' => 1, 'inner' => 1 };
  $HTML::KTemplate::LAST  = { 'LAST'  => 1, 'last'  => 1 };

=head2 Parse Vars

Set this option to 1 to parse variables. That way all template variables inside of a variable will be replaced with their assigned values.

  $tpl = HTML::KTemplate->new( parse_vars => 0 );  # default
  $tpl = HTML::KTemplate->new( parse_vars => 1 );


=head2 Strict

Set this option to 1 to raise errors on not defined variables and include tags when disabled.

  $tpl = HTML::KTemplate->new( strict => 0 );  # default
  $tpl = HTML::KTemplate->new( strict => 1 );

=head2 Chomp

Removes the newline before and after a block tag.

  $HTML::KTemplate::CHOMP = 1;  # default
  $HTML::KTemplate::CHOMP = 0;


=head1 MAILING LIST

If you want to get email when a new version of HTML::KTemplate is released, join the announcements mailing list:

  http://lists.sourceforge.net/lists/listinfo/html-ktemplate-announce

A mailing list for discussing HTML::KTemplate is available at <[e-mail]>. To join, visit:

  http://lists.sourceforge.net/lists/listinfo/html-ktemplate-users

You can also email me questions, comments, suggestions or bug reports directly to <[e-mail]>.


=head1 WEBSITE

More information about HTML::KTemplate can be found at:

  http://html-ktemplate.sourceforge.net/


=head1 COPYRIGHT

  Copyright (c) 2002-2003 Kasper Dziurdz. All rights reserved.
  
  This module is free software; you can redistribute it and/or
  modify it under the same terms as Perl itself.
  
  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 the
  Artistic License for more details.

=head1 AUTHOR

Kasper Dziurdz <[e-mail]>

=cut