/ 
HTML-EasyTemplate-0.985
/ HTML::EasyTemplate

NAME

EasyTemplate - tag-based HTML templates, guestbooks and 'latest news' pages.

VERSION

Version 0.985 (23/07/2001) cleans up API: constructor method now takes SOURCE_PATH explicitly and not as arg outside of hash. Version 0.984 (15/06/2001) adds option to hide template items.

SYNOPSIS

Example tempalte:

<HTML><HEAD><TITLE>Latest News</TITLE></HEAD><BODY>
<H1>Latest News</H1>
<!--<TEMPLATEBLOCK valign="above">
	<H2><TEMPLATEITEM id="1.Headline">This is in a non-displayed template</TEMPLATEITEM></H2>
	<DIV><TEMPLATEITEM id="2.Story">This will not be shown, within templateitem tags, will be destroyed</TEMPLATEITEM></DIV>
</TEMPLATEBLOCK>-->
</BODY></HTML>

Example of filling and collecting:

use HTML::EasyTemplate;

my $TEMPLATE = new HTML::EasyTemplate(
	{	SOURCE_PATH => "test_template.html",
		NO_TAGS => 1,
		ARTICLE_ROOT => 'E:/www/leegoddard_com',
		URL_ROOT => 'http://localhost/leegoddard_com',
	});

# Collect the values
$TEMPLATE -> process('collect');

# Do something with them
my %template_items = %{$TEMPLATE->{TEMPLATEITEMS}};

warn "** Template content was:\n";
foreach (keys %template_items){ warn "ID=$_\nCONTENT=$template_items{$_}\n\n" }
warn "** Template doc's title was: ",$TEMPLATE->title,"\n\n";

# Make new values, for example:
$template_items{'1.Headline'} 	= "News in paper";
$template_items{'2.Story'}	= "Reports are coming in on ". scalar(localtime)." of a newspaper carrying a news item.";

warn "\n** New template contents will be:\n";
foreach (keys %template_items) {
	warn "$_ -> $template_items{$_}\n";
}

# Add them to the page
$TEMPLATE -> process('fill', \%template_items );
$TEMPLATE -> save;
warn "\n** Document saved as (",$TEMPLATE->{ARTICLE_PATH},")\n";

exit;

See also the EXAMPLE: NEWS PAGE / GUESTBOOK, below.

DEPENDENCIES

Cwd;
HTML::TokeParser;
strict;
warnings;

DESCRIPTION

This package impliments the most easy possible manipulation of templates: loading, saving, filling, and so on. It makes it easy to produce guestbooks, 'latest news' pages and simple websites.

A template is an area of an HTML page that this module can fill with data.

A template is a <!--commented out--> area of an HTML file (or other file parsable by HTML::TokeParser) that contains TEMPLATEBLOCK elements with TEMPLATEITEM elements within. Any elements, including TEMPLATEITEMs, within a TEMPLATEBLOCK element will be replicated either above or below the existing TEMPLATEBLOCK, depending on the value of the element's valign attribute, which may be either above or below.

See the enclosed examples for further information.

TEMPLATE ELEMENT REFERENCE

	Element name    Attributes   Function
	------------------------------------------------------------------------------------------------
	TEMPLATE_ITEM                Editable region - all contents may be easily collected/replaced.
	                id           Unique identifier.
	                name         Synonymn for id.
	------------------------------------------------------------------------------------------------
	TEMPLATEBLOCK                All contents will be replicated before the original block is filled.
	                id           Unique identifier.
	                name         Synonymn for id.
                    valign       Either 'C<above>' or 'C<below>' to indicate where the repliacted
                                 block should appear in relation to the original.
	------------------------------------------------------------------------------------------------

PUBLIC METHODS

CONSTRUCTOR METHOD (new)

Besides a references to the new object's class, the constructor requires a hash or reference to a hash that contains paramters of name/value pairs as follows:

SOURCE_PATH

scalar representing the path at which the source of the template is to be found,

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

This is really a legacy attribute. Defaulting to true, if the user sets it to evaluate to false, new template items will be surrounded by the TEMPLATEITEM and TEMPLATEBLOCK elements when saved. See also the next item.

ADD_TAGS

If present, will surround output with respective TEMPLATEITEM and TEMPLATEBLOCK elements. See also previous item.

HTML_TITLE

Contains the HTML TITLE element for reading/setting - see the title method below.

FULL_TEMPLATE

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

METHOD title

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

METHOD save

Save the file to the supplied path, or in the supplied directory with a new name.

You may supply:

  • just the full path to a file

  • both a directory and a filename

  • just a directory, with the filename being composed by the routine out of the time and an .html extension.

  • supply no arguments, and the documents original source path is used - ie. the source document is updated (cf. $self-{SOURCE_PATH}>.

Returns the path to the saved file, incidently 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.

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.

Accepts:

  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.

Returns either $self-{FULL_TEMPLATE}> or $self-{TEMPLATEITEMS}>, depending on the calling parameter.

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.

EXAMPLE: NEWS PAGE / GUESTBOOK

Three files can be used to produce a guestbook-like news page. One file is an HTML file that takes form input, which is fed to a script that calls this module, that updates a further HTML page. The form field names in the HTML form page are the same as the TEMPLATEITEM ids in the updated/template page.

File One,

the viewable template, known as E:/www/leegoddard_com/latest.html in the second file:

<HTML><HEAD><TITLE>Latest News</TITLE></HEAD><BODY>
<H1>Latest News</H1>
<TEMPLATEBLOCK valign="above">
	<H2><TEMPLATEITEM id="1.Headline"></TEMPLATEITEM></H2>
	<DIV><TEMPLATEITEM id="2.Story"></TEMPLATEITEM></DIV>
</TEMPLATEBLOCK>
</BODY></HTML>
File Two,

perl script to do the business, in the first file called as http://localhost/cgi-bin/latestnews.pl:

use HTML::EasyTemplate;
use CGI;
$QUERY = new CGI;
$TEMPLATE = new HTML::EasyTemplate("E:/www/leegoddard_com/latest.html",
	{	NO_TAGS => 1,
		ARTICLE_ROOT => 'E:/www/leegoddard_com',
		URL_ROOT => 'http://localhost/leegoddard_com',
	});
if ($QUERY->param){
	foreach ($QUERY->param) {
		$template_items{$_} = join(', ',($QUERY->param($_)));
	}
	# Add them to the page
	$TEMPLATE -> process('fill', \%template_items );
	$TEMPLATE -> save( "$TEMPLATE->{ARTICLE_ROOT}/latest.html" );
}
print "Location:$TEMPLATE->{ARTICLE_URL}\n\n";
exit;
__END__
File Three,

the HTML form to add news items to the template; never referenced by other files:

<HTML><HEAD><TITLE>Add a headline</TITLE></HEAD><BODY>
<H1>Add a headline<HR></H1>
<FORM action="http://localhost/cgi-bin/latestnews.pl" method="post">
	<H2>Headline</H2><INPUT type='text' name="1.Headline" size='60'></H2>
	<H3>Story</H3><TEXTAREA name="2.Story" COLS="40"  ROWS="5"  WRAP="HARD" size='60'></TEXTAREA>
	<HR><INPUT type="submit">
</FORM></BODY></HTML>

SEE ALSO

HTML::TokeParser
HTML::EasyTemplate::DirMenu
HTML::EasyTemplate::PageMenu

KEYWORDS

Template, guestbook, news page, CGI, HTML, update, easy.

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 550:

'=item' outside of any '=over'

Around line 599:

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