/ 
HTML-EasyTemplate-0.97
/ HTML::EasyTemplate

NAME

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

VERSION

Version 0.97 11/05/2001 13:51

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;

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         An alternative id.
	------------------------------------------------------------------------------------------------
	TEMPLATEBLOCK               All contents will be replicated before the original block is filled.
	                id           Unique identifier.
	                name         An alternative id.
                    valign       Maybe '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.

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: the value set.

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.

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

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.

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

'=item' outside of any '=over'

Around line 505:

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