/ 
HTML-EasyTemplate-0.983
/ HTML::EasyTemplate

NAME

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

VERSION

Version 0.98 15/05/2001

SYNOPSIS

Example tempalte:

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

Example of filling and collecting:

use HTML::EasyTemplate;

my $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',
	});

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

# Do something with them
my %template_items = %{$TEMPLATE->{TEMPLATEITEMS}};
foreach (keys %template_items){ warn "ID=$_\nCONTENT=$template_items{$_}\n\n" }
warn "Template doc's title was: ",$TEMPLATE->title,"\n";

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

# Add them to the page
$TEMPLATE -> process('fill', \%template_items );
$TEMPLATE -> save;
warn "Specified no filename, so new 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 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 HTML file (or other file parsable by HTML::TokeParser) that contains TEMPLATEITEM elements with one attribute, name or id, used to identitfy and/or order editable regions in the template.

A template may also include TEMPLATEBLOCK elements. 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.

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

HTML_TITLE

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.

Accepts:

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

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

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

'=item' outside of any '=over'

Around line 553:

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