/ 
HTML-EasyTemplate-0.96
/ HTML::EasyTemplate

NAME

EasyTemplate - simple tag-based HTML templating.

VERSION

Version 0.96 10/05/2001 14:33

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 or id, used to identitfy and/or order editable regions in the template.

SYNOPSIS

Example tempalte:

<HTML><HEAD><TITLE>Test Doc</TITLE></HEAD>
<BODY>
<H1><TEMPLATEITEM id="articleTitle"></TEMPLATEITEM></H1>
<TEMPLATEITEM id="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 $TEMPLATE = new HTML::EasyTemplate($page) or die "Couldn't make template!";
$TEMPLATE -> process('fill', {
	'menu'=>$m->{HTML},
} );
$TEMPLATE -> save( $page );
warn "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 "ID=$_\nCONTENT=$template_items{$_}\n\n";
}
print "Template doc's title was: $TEMPLATE->title\n";
__END__

DEPENDENCIES

Cwd;
HTML::TokeParser;
strict;
warnings;

TEMPLATE FORMAT

A template may be any document parsable by HTML::TokeParser that contains elements TEMPLATEITEM with an attribute ID. 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)

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

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

NO_TAGS

If this item evaluates to true, the template will not contain TEMPLATEITEM tags when saved. Defaults is to leave them in, so that the page may again function as an EasyTemplate.

FULL_TEMPLATE

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

HTML_TITLE

See the title method below.

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 to the supplied path, or in the supplied directory with a new name.

Accepts:

  • directory in which to save article in, or full path to save article as;

  • optionally a filename to save as.

If no filename is suppiled in either argument, one is created without significance.

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 or id 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 or id attributes, and values are the element's contents.

Uses HTML::TokeParser to iterate through template,replacing all text tagged with TEMPLATEITEM id="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::TokeParser
HTML::EasyTemplate::DirMenu
HTML::EasyTemplate::PageMenu

HISTORY

0.96

Removed our checks on input file/string to allow HTML::TokeParser to sort it out; reversed wrong NO_TAGS behaviour; removed some limiting defaults.

0.95

Allow use of id in addition to name as the C>TEMPLATEITEM> unique identifier attribute.

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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 396:

'=item' outside of any '=over'

Around line 405:

You forgot a '=back' before '=head1'