/ 
HTML-EasyTemplate-0.95
/ HTML::EasyTemplate

NAME

EasyTemplate - simple tag-based HTML templating.

VERSION

Version 0.95 26/04/2001 14:59

DESCRIPTION

This package impliments the manipulation of templates: loading, saving, filling, and so on.

A template is a file parsable by HTML::TokeParser, that contains TEMPLATE elements with one attribute, name, used to identitfy and/or order editable regions in the template.

SYNOPSIS

Example tempalte:

<HTML><HEAD><TITLE>Test Doc</TITLE></HEAD>
<BODY>
<H1><TEMPLATEITEM name="articleTitle"></TEMPLATEITEM></H1>
<TEMPLATEITEM name="articleText">
	This text <I>can</I> be over-writen - see the <EM>POD</EM>.
</TEMPLATEITEM>
</BODY>
</HTML>

Example of filling a template with content:

use EasyTemplate;
my %items = (
	'articleTitle'=> 'An Example Article',
	'articleText' => 'This is boring sample text: hello world...',
);
my $TEMPLATE = new EasyTemplate('test_template.html');
$TEMPLATE->title("Latka Lover");
$TEMPLATE -> process('fill',\%items);
$TEMPLATE -> save( '.','new.html');
print "Saved the new document as <$TEMPLATE->{ARTICLE_PATH}>\n";
__END__

Example of collecting from a template with content:

use EasyTemplate;
my $TEMPLATE = new EasyTemplate('test_template.html');
$TEMPLATE -> process('collect');
my %template_items = %{$TEMPLATE->{TEMPLATEITEMS}};
foreach (keys %template_items){
	print "NAME=$_\nCONTENT=$template_items{$_}\n\n";
}
print "HTML doc's title was: $TEMPLATE->title\n";
__END__

DEPENDENCIES

Cwd;
HTML::TokeParser
Strict;

TEMPLATE FORMAT

A template may be any document parsable by HTML::TokeParser that contains elements TEMPLATEITEM with an attribute name. Beware that an empty element of XHTML form may not be readable by HTML::TokeParser, and that all empty TEMPLATEITEM elements are ignored by this module - if you wish to draw attention to them, make sure they contain at least a space character.

PUBLIC METHODS

CONSTRUCTOR METHOD (new)

Requires references to the new object's class, and a scalar representing the path at which the source of the new template is to be found, plus a hash or reference to a hash that contains name/value pairs as follows:

$self-{NO_TAGS}>

if this slot evaluates to true, the template will not contain TEMPLATEITEM tags when saved.

$self-{HTML_TITLE}>

See the title method below.

$self-{FULL_TEMPLATE}>

This slot will contain the filled template once the process/fill method has been called. See the save method.

ARTICLE_ROOT

The directory in which the site is rooted.

The ARTICLE_ROOT is stripped from filepaths when creating HTML A href elements within your site, and is replaced with...

If this is not set by the user, it is sought in the main:: namespace.

URL_ROOT

This slot is used as the BASE for created hyperlinks to files, instead of the filesystems actual ARTICLE_ROOT, above.

If this is not set by the user, it is sought in the main:: namespace.

METHOD title

Sets $TEMPLATE-{HTML_TITLE}>, which is the HTML title to be substituted in the template.

Accepts: scalar. Returns: nothing.

METHOD save

Save the file. If a path is specified, use it; otherwise or make one up.

Accepts:

  1. reference to Template object;

  2. directory in which to save article in;

  3. optionally a filename to save as.

Returns: file path of saved file.

This method incidently returns a reset $self's ARTICLE_PATH;

DEVELOPMENT NOTE: it may be an idea to bear in mind temporary renaming of files: as File::Copy says:

"The newer version of File::Copy exports a move() function."

METHOD process

Fill a template or take variables from a template.

Accepts, in this order:

  1. method of operation: 'fill' or 'collect'.

  2. if method argument above is set to 'fill', a reference to a hash.

If the first argument is set to 'collect', the values of all TEMPLATEITEM elements will be collected into the instance variable %TEMPLATEITEMS, with the name attribute of the element forms the key of the hash.

If the first argument is set to 'fill', the template will be filled with values stored in the hash refered to in the third argument.

The second parameter, if present, should refer to a hash whose keys are TEMPLATEITEM element name attributes, and values are the element's contents.

Uses HTML::TokeParser to iterate through template,replacing all text tagged with TEMPLATEITEM name="x" with the value of x being the keys of the third argument. So if that parser module can't read it, neither can this module.

METHOD set_article_path

Accepts and returns one scalar, the path to use for the object's ARTICLE_PATH slot.

METHOD set_article_url

Acceptsand returns one scalar, the ARTICLE_URL slot.

If ARTICLE_ROOT is set, strips this from the path supplied,.

If URL_ROOT is set, prepends this to the path supplied.

Mainly for the author's private use in other packages that may later appear on CPAN.

See also HTML::EasyTemplate::DirMenu

AUTHOR

Lee Goddard (LGoddard@CPAN.org)

COPYRIGHT

Copyright 2000-2001 Lee Goddard.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.