NAME
HTML::Template::Default - unless template file is on disk, use default hard coded
DESCRIPTION
I sometimes code implementations of CGI::Application for multiple client installations. I want to provide and use a default template for runmodes, and also allow the site admin to change the templates. This module allows me to do this, without requiring that tmpl files be in place, and if they are, those override the defaults.
Of course you don't have to use CGI::Application to find this module useful.
The files are sought in $ENV{HTML_TEMPLATE_ROOT}
SYNOPSIS
use HTML::Template::Default 'get_tmpl';
$ENV{HTML_TEMPLATE_ROOT} = '/home/myself/public_html/templates';
my $default = '
<html>
<head>
<title><TMPL_VAR TITLE></title>
</head>
<body>
<h1><TMPL_VAR TITLE></h1>
<p><TMPL_VAR CONTENT></p>
</body>
</html>
';
# if super.tmpl exists, use it, if not, use my default
my $tmpl = get_tmpl('super.tmpl',\$default);
$tmpl->param( TITLE => 'Great Title' );
$tmpl->param( CONTENT => 'Super cool content is here.' );get_tmpl()
Takes arguments. Returns HTML::Template object.
two argument usage
If there are two arguments, the values are to be at least one of the following..
- A path or filename to an HTML::Template file.
- A scalar ref with default code for the template.
Examples:
my $tmpl = get_tmpl('main.html', \$default_tmpl_html );
my $tmpl = get_tmpl('main.html');
my $tmpl = get_tmpl(\$default_html);hash argument usage
arguments are the same as to HTML::Template constructor. The difference is that you can set *both* 'filename' and 'scalarref' arguments, and we try to instance via 'filename' first (if it is defined), and second via 'scalarref'.
If neither filename or scalarref are defined, will throw a nasty exception with confess.
If returns undef if we cannot instance.
my $tmpl = get_tmpl( filename => 'main.html', scalarref =>\$default_tmpl_html );Erroneous usage
These examples will be interpreted as two argument usage when you meant hash usage..
my $tmpl = get_tmpl( filename => 'main.html' );
my $tmpl = get_tmpl( scalarref => \$default_html );EXAMPLE USAGE
Example 1
In the following example, if main.html does not exist in $ENV{HTML_TEMPLATE_ROOT}, the '$default' code provided is used as the template.
my $default = "<html>
<head>
<title>Hi.</title>
</head>
<body>
<TMPL_VAR BODY>
</body>
</html>";
my $tmpl = get_tmpl('main.html', \$default);To override that template, one would create the file main.html in $ENV{HTML_TEMPLATE_ROOT}. The perl code need not change. This merely lets you provide a default, optionally.
Again, if main.html is not in $ENV{HTML_TEMPLATE_ROOT}, it will use default string provided- if no default string provided, and filename is not found, croaks.
Example 2
In the following example, the template file 'awesome.html' must exist in $ENV{HTML_TEMPLATE_ROOT}. Or the application croaks. Because no default is provided.
my $tmpl = get_tmpl('awesome.html');Example 3
If you don't provide a filename but do provide a default code, this is ok..
my $tmpl = get_tmpl(\$defalt_code);Example 4
If you want to pass arguments to the template..
my $tmpl = get_tmpl( filename => 'super.tmpl', scalarref => \$default, case_sensitive => 1 );
Example 5
In this example we provide both the default code we want, and filename for a file on disk that is given higher priority. If the file 'main.html' is on disk, it will be loaded.
use HTML::Template::Default 'get_tmpl';
my $code = '<html><title><TMPL_VAR TITLE></title></html>';
my $tmpl = get_tmpl (
filename => 'main.html',
scalarref => \$code,
die_on_bad_params => 0,
case_sensitive => 1,
);DEBUG
To set debug:
$HTML::Template::Default::DEBUG = 1;Gives useful info like if we got from disk or default provided etc to STDERR.
AUTHOR
Leo Charre leocharre at cpan dot org
CAVEATS
In two argument usage, die_on_bad_params is set to 0, if you want to change that, use hash argument.
get_tmpl(filename => $filename, scalarref => \$code); # leaves HTML::Template defaults intact
get_tmpl( $filename, \$scalarref ) # invokes die_on_bad_params => 0SEE ALSO
HTML::Template