NAME

HTML::Template::HTX - Handle HTML Extension template (.htx) files

SYNOPSIS

  use HTML::Template::HTX;

  $htx = HTML::Template::HTX->new('template.htx') or die "Oops!";

  $htx->param('counter' => 0);
  $htx->print_header(1);

  foreach(qw(I used to care but Things Have Changed)) {
    $htx->param(
      'counter' => $htx->param('counter')+1,
      'Name'    => $_,
    );
    $htx->print_detail;
  }

  $htx->print_footer;
  $htx->close;

template.htx

  <HTML><HEAD><TITLE>Sample results</TITLE>

  </HEAD><BODY>

   <H2>Sample results:</H2>

  <%begindetail%>
   <%counter%>. <%Name%><BR>
  <%enddetail%>

  </BODY></HTML>

ABSTRACT

Reads and outputs HTML Extension template (.htx) files, which enable you to seperate your Perl code from HTML code.

The .htx file format was originally used by Microsoft's Index Server and their Internet Database Connector, but may be useful for any server side program that outputs HTML (or even some other ASCII file format), and especially for scripts generating sequential data, such as search engines.

Note that this module and its template format are not directly related nor compatible with the popular HTML::Template module.

DESCRIPTION

To use a .htx template file in your Perl script, basically follow these steps:

  1. Create a new HTML::Template::HTX object.

  2. Optionally define some parameters, and output the header of the template.

  3. Optionally change or define some parameters, and output the detail section. This step is optionally repeated a number of times, depending on the data you're processing.

  4. Optionally change or define some parameters, and output the footer of the template.

  5. Close the template file, or destroy the HTML::Template::HTX object.

If you don't have any repeated data, then you can skip steps 2 and 3, and just use print_footer to output the whole template file at once. If you have multiple sets of repeated data, then you should probably follow a slightly altered schema (see the detail_section method).

Basic methods

$htx = HTML::Template::HTX->new($template, [$output], [-utf8], [common parameters])
$htx = HTML::Template::HTX->new(template => $template, [output => $output], [-utf8], [common parameters])

Opens the specified .htx template file. If an open file handle is specified instead of a file name, then the template is read from this file handle. If a scalar reference is specified, then the contents of the scalar will be used as the template.

If no output file is specified, then the STDOUT is used for output. If an open file handle is specified, then this file handle is used for output. If a scalar reference is specified instead of an output file, then all output will be appended to the specified scalar.

By default UTF-8 coding will be disabled, but you can specify -utf8 to enable it. For more on UTF-8 coding and this module see the utf8 method.

When any common parameters are specified, certain frequently used parameters are automatically defined and maintained. For more information see the common_params method.

When using the named parameters interface, you can also use filename => $template instead of template => $template (for backward compatibility).

$htx->param($name => $value, [$name => $value...])
$value = $htx->param($name)
@names = $htx->param()

Sets or retrieves a user defined variable, or a list of variables. If one or more name and value pairs are specified, then these variables will be set to the specified values.

If only one argument is specified, than the value of that variable is returned. Without arguments the param method returns a list of names of all defined variables.

See also The .htx file format, and the common_params method.

$htx->print_header([$http_header] [-nph])

Reads, parses and outputs the template file up to <%begindetail%>, and only reads what's between <%begindetail%> and <%enddetail%>, but does not parse and output this section yet. If no <%begindetail%> was found, then simply reads, parses and outputs the entire file. In this last case print_header returns a false value, else it returns a true value. If a section name was specified inside the template file, then this true value is actually the specified section name. This make life very easy for .htx files with multiple detail sections (see also the detail_section method).

If this is the very first call to print_header and only a content type is specified in $http_header (usually this should be 'text/html'), then the following simplified HTTP header is printed before anything else:

    Content-Type: $http_header

If $http_header is not a valid content type (i.e. there's no '/' in it) but its value is true, then the default content type of 'text/html' is used. This is very useful, because you can thus simply do $htx->print_header(1) to get a valid HTTP header with the 'text/html' content type. If you don't want any header, then simply do a print_header with a false value, e.g. $htx->print_header('') (or even just $htx->print_header).

If a full HTTP header is specified in $http_header (i.e. if $http_header contains one or more "\n" characters), then that header printed before anything else. Beware that a valid HTTP header should include a trailing empty line.

The -nph option is ignored, but still included for backward(s) ;-) compatibility. If you need to print a full HTTP header, you could simply pass the header function of the CGI module, e.g. $htx->print_header(header(-nph => 1)).

$htx->print_detail

Parses and outputs the detail section that was read by the print_header method. The method print_detail method is usually called from a loop to output each subsequent record.

$htx->print_footer([$http_header] [-nph])

Reads, parses and outputs the rest of the template file, skipping any <%begindetail%>..<%enddetail%> sections it might encounter. For the optional arguments, see the print_header method.

A script that uses a template file without a detail section could call this method immediately after HTML::Template::HTX->new (without calling print_header). This is because this method actually does subsequent calls to the print_header method until the end of the file is reached.

$htx->close

Closes the template and output files. This is usually done directly after the print_footer method. When a HTML::Template::HTX object is destroyed the files will be closed automatically, so you don't need to call close (but I think it's very rude not to call close!). ;-)

Common parameters

Common parameters are a sets of parameters that are automatically defined and maintained so you won't have to worry about them, but which can be used inside a template just like any parameters you've defined yourself. You can specify common parameters while creating the HTML::Template::HTX object, or you can use the common_params method to define them later on.

$htx->common_params([options])

Automatically defines and sets certain frequently used parameters. You can specify one or more options, or nothing if you want to use the default set of options (which is -count and -date).

The following options are currently supported:

-count [=> $enable]

Enables or disables the use of automated counters. When called with no argument or a true value, automated counters will be enabled. When called with a false value, automated counters will be disabled.

The following HTX counter parameters are defined and maintained:

  • <%COUNT%> - The number of times print_detail was called within the current detail section.

  • <%NUMBER%> - The number of times print_detail was called within the current detail section, and actually produced data (thus not an empty string).

  • <%TOTAL%> - The number of times print_detail was called within all detail section.

  • <%SECTION%> - The name of the current detail section.

<%NUMBER%>, <%COUNT%> and <%TOTAL%> can be followed by a question mark to get its value modules 2, e.g. <%NUMBER?%>.

You should always enable automated counters when creating the HTML::Template::HTX object or right after. You can disable them again whenever you feel like it.

The automated counters only change when calling print_detail, and after calling print_header. This means you can still query them in print_footer (or the next print_header, if you're using multiple detail sections).

-date [=> $epoch_time]

Defines a set of date and time parameters for the given epoch date/time, or the current date and time if no epoch date/time is specified.

The following HTX date and time parameters are defined and set:

  • <%YEAR%> - The year as a 4-digit number.

  • <%MONTH%> - The month as a 2-digit number (01..12).

  • <%MONTH$%> - The month as a 3-character string (in English).

  • <%DAY%> - The day as a 2-digit number (01..31).

  • <%DATE%> - The date ("dd mmm yyyy").

  • <%WEEKDAY%> - The weekday as a 1-digit number (1..7; 1 = Sun, 2 = Mon ... 7 = Sat).

  • <%WEEKDAY$%> - The weekday as a 3-character string (in English).

  • <%HOUR%> - The hour of the day as a 2-digit number (00..23).

  • <%MINUTE%> - The minutes part of time time as a 2-digit number (00..59).

  • <%TIME%> - The time ("hh:mm").

  • <%SECOND%> - The seconds part of time time a 2-digit number (00..59).

  • <%TIME_ZONE%> - The timezone (e.g. "+0100" or "GMT").

  • <%DATE_TIME%> - The date and time (e.g. "Thu, 30 Oct 1975 17:10:00 +0100").

Each of these variables is also available in GMT, e.g. <%GMT_DATE_TIME%>, <%GMT_TIME_ZONE%> (which naturally always is "GMT") etc.

Multiple detail sections

If you have multiple sets of repeated data which you want to pass to a single .htx template, you could simply do:

  1. print_header (header of 1st detail section)

  2. print_detail foreach(0..n) (1st detail section)

  3. print_header (footer of 1st and header of 2nd detail section)

  4. print_detail foreach(0..n) (2nd detail section)

  5. print_footer (footer of 2nd detail section)

Steps 3 and 4 could be repeated a number of times before continuing to step 5, depending on the number of detail sections in both your Perl script and your .htx template.

But what if you'd change the order in which the detail sections appear inside the template? You would also have to change the order in which the data is processed inside your Perl script. :-( This is where the detail_section method and the <%detailsection name%> .htx command come in. :-)

$name = $htx->detail_section
$htx->detail_section($name)

Retrieves (or sets) the name of the current detail section. You can define a logical name for the next detail section inside a template file (which sort of announces the next detail section), and your Perl script that passes data to the template can check this section name and pass the data belonging to that specific section. This comes in handy if your template contains multiple detail sections.

Normally you should never set the section name from your Perl script, but rather use the <%detailsection name%> command in your template file. Normally you do not even have to retrieve the section name using this method, because the print_header method already returns the current section name.

Consider this Perl example:

  $htx = HTML::Template::HTX->new('template.htx');
  ...
  while($section = $htx->print_header(1)) {
    if($section eq 'LINKS') {
      foreach(@url) {
        ...
        print_detail;
      }
      next;
    }
    if($section eq 'ADS') {
      while(<$ads>) {
        ...
        print_detail;
      }
      next;
    }
  }
  $htx->close;

And the corresponding template.htx example file:

  <HTML><HEAD><TITLE>Sample results</TITLE></HEAD><BODY>

  <%detailsection ADS%>
  <%begindetail%>
   <A HREF="<%EscapeRaw URL%><IMG SRC="<%EscapeURL Image%>></A>
  <%enddetail%>

  <%detailsection LINKS%>
  <H2>Links to Perly websites</H2>
  <%begindetail%>
   <A HREF="<%EscapeRaw URL%><%URL%></A><BR>
  <%enddetail%>

  </BODY></HTML>

UTF-8 support

The transparent UTF-8 support in Perl is very useful when reading data from different sources, but it's not very useful when returning data to client software (e.g. an internet browser) that almost certainly won't have transparent UTP-8 support. That's why the utf8 method lets you control whether your output will be UTF-8 coded or not.

$htx->utf8([$enable])

Enables or disables UTF-8 coding for the output of user defined or "environmental" :-) variables. When called with no argument (thus undef) or a true value, UTF-8 coding will be enabled. When called with a false value, UTF-8 coding will be disabled. For UTF-8 coding Perl 5.6 or newer is required. You may also need versions of the HTML::Entities and URI::Escape modules that understand UTF-8.

You should always enable or disable UTF-8 coding when creating the HTML::Template::HTX object or right after. You should never change the UTF-8 flag later on.

You can always use UTF-8 characters inside user defined variables, regardless of the state of the UTF-8 flag. With UTF-8 coding disabled, all UTF-8 characters that are found inside variable values will be converted to their 8-bit counterparts (where possible). With UTF-8 coding enabled, all 8-bit non-UTF-8 characters will be converted to their UTF-8 counterparts.

Note that enabling the UTF-8 flag will only UTF-8 code variables, not the rest of the template file, which is parsed "as is". So when enabling UTF-8, make sure your template is also UTF-8 coded.

THE .HTX FILE FORMAT

A .htx file is a normal HTML file, but it also contains special tags, which are handled by this module. These special tags are enclosed by <% and %> (kinda like Microsoft's Active Server Pages), and may contain variables and simple statements. The following special tags are supported:

<%variable%>

Outputs the value of the variable in HTML encoding. The variable may be a user defined variable, but also a CGI environment variable.

User defined variables are defined or modified using the param method. This is typically done before a call to the print_detail method, but also before calling the print_header and print_footer methods.

<%EscapeRaw expression%>
<%EscapeHTML expression%>
<%EscapeURL expression%>
<%EscapeJS expression%>
<%EscapeScramble expression%>

Outputs the value of a variable or a literal string using HTML, URL, JavaScript, scrambled JavaScript or "raw" encoding.

JavaScript encoding can be used in JavaScript between double quotes, e.g. document.write("<%EscapeJS Variable%>");. Scrambled JavaScript encoding comes in handy when you want to "hide" e-mail addresses from spambots, e.g. document.write("<%EscapeScramble Email%>");.

<%begindetail%>

Repeats what comes next for each record, until <%enddetail%> or the end of the file is reached. This is the section that is printed by the print_detail method.

<%enddetail%>

See <%begindetail%>.

<%detailsection name%>

Defines a name for the next detail section, which makes life very easy when your template file contains multiple detail sections. For more information see the detail_section method.

<%if condition%>

Only output what comes next if condition is true. The condition has the following syntax:

expression1 operator [expression2]

expression1 and expression2 can be any value or variable name. Literal string values should be enclosed by "". If one of the values is a typical string value, then both values are treated as strings, otherwise they are treated as numerical values.

operator can be one of the following operators:

  • eq - expression1 and expression2 are identical.

  • ne - expression1 and expression2 are not identical.

  • lt - expression1 is less than expression2.

  • le - expression1 is less than or equal to expression2.

  • gt - expression1 is greater than expression2.

  • ge - expression1 is greater than or equal to expression2.

  • contains - expression1 contains expression2.

  • istypeeq - This is always true; it's included for compatibility.

  • isempty - expression1 equals an empty string (or zero in a numerical context). expression2 should be ommited when you use the isempty operator.

<%else%>

Only output what comes next if the condition of an earlier <%if%> was false.

<%endif%>

Ends a conditional block and returns to its earlier conditional state. Yes, this means that you can nest <%if%>..<%else%>..<%endif%> blocks. :-)

<%include file%>

Includes a file as if it were part of the current .htx file. In this include file you may also again use the special tags, or even the <%include%> tag for that matter. However, the use of <%include%> inside an include file is not recommended, because it may lead to recursive inclusion. You should also be careful with using <%begindetail%>..<%enddetail%> inside an include file, because detail sections cannot be nested.

KNOWN ISSUES

Since no syntax checking is performed on .htx files, any unsupported statements or non-existing variables will simply be ignored. If you misuse any of the supported statements, you can't be sure of what might happen.

Also, the <%if%>, <%else%> and <%endif%> statements are not really block statements, as they are in Perl or most other programming languages, but they rather just change the state of the internal condition flag. As a side effect you can disable a portion of a template file by placing <%else%>..<%endif%> around it (without <%if%>!).

The use of multiple <%begindetail%>..<%enddetail%> sections is not documented for Microsoft's Index Server, but is supported very elegantly by this module (see the detail_section method).

MODIFICATION HISTORY

Version 0.07

[May 5 - 15, 2005] Transparent UTF-8 support for both Perl 5.6 and 5.8 was a little buggy (really?), but now it works (really!). The template file can now also be an open file handle or a scalar in memory. Templates containing multiple detail sections are now much easier to handle. Two new encoding types have been added: <%EscapeJS%> and <%EscapeScramble%>. The common parameters feature has been added. The tests in test.pl now don't do just one simple "live" test anymore, but rather test most of the module. (The coverage of these tests is probably not 100%, but it's close.)

Version 0.06

[April 17/18, 2005] Added transparent UTF-8 support for both Perl 5.6 and 5.8. Also reviewed and partly rewrote all other code. Output to a scalar doesn't use tying anymore (which worked, but probably produced warnings, and probably was a bit slower), but it now simply appends the output to the specified scalar.

Version 0.05

[November 21, 2004] Added the option for output to a scalar instead of a file.

Version 0.04

[July 30, 2002] Fixed a minor bug concerning multi-line <%if%>'s.

Version 0.03

[July 21, 2002] Fixed a bug in the _evaluate sub, that resulted in warnings about uninitialized multiplications when using the isempty operator.

Version 0.02

[June 21/24, 2002] Fixed a few minor bugs concerning nested <%if%>'s, the isempty operator, and the use of HTTP headers.

Version 0.01

[April, 2002] Created the module. :-)

AUTHOR INFORMATION

Theo Niessink <niessink@martinic.nl>, http://www.taletn.com/

(The "I used to care but Things Have Changed" used in the Synopsis was written by Bob Dylan.) :-)

COPYRIGHT

© MARTINIC Computers 2002-2005. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

For more information on MARTINIC Computers visit http://www.martinic.nl/