NAME

HTML::EasyTemplate::DirMenu - HTML menus of directories.

DESCRIPTION

Provide an easy means of creating from a directory a representative block of HTML suitable for use as a substitution item in an HTML::Easytemplate, or as freestanding mark-up.

SYNOPSIS

Print a simple menu of HTML files in current working directory:

use HTML::EasyTemplate::DirMenu;
my $m = new HTML::EasyTemplate::DirMenu (
	'MODE'		=> 'ALL',
	'RECURSE'	=> 'TRUE',
	'START'		=> 'E:/www/emc2.vhn.net/live',
	'URL_ROOT'	=> 'http://dev.localhost',
	'EXTENSIONS'=> '\.html?',
	'TITLE_IN'	=> 'title',
	'LIST_START'	=> '<OL>',
	'LIST_END'	=> '</OL>',
	'ARTICLE_START'	=> '<LI>',
	'ARTICLE_END'	=> '</LI>',
	'DIR_START'	=> '<BIG>',
	'DIR_END'	=> '</BIG>',
	'EXC_DIRS'	=> '^(ignore_these_dirs|ignoreme2)$',
	'EXC_FILES'	=> '^(private\.html?|_.*\.html)$',
);
print $m->{HTML};

Add the following lines to the above for a menu to an EasyTemplate, as TEMPLATEITEM name='menu1', based on the example provided in HTML::EasyTemplate:

use HTML::EasyTemplate;
my $m = new HTML::EasyTemplate::DirMenu (
	'START'		=> 'E:/www/emc2.vhn.net/live',
	'URL_ROOT'	=> 'http://dev.localhost',
	'EXTENSIONS'=> '.*',
	'MODE'		=>	'all',
	'RECURSE'	=> 'true',
	'TITLE_IN'	=> 'true',
	'LIST_START'	=> '<OL>',
	'LIST_END'	=> '</OL>',
	'ARTICLE_START'	=> '<LI>',
	'ARTICLE_END'	=> '</LI>',
	'DIR_START'	=> '<BIG>',
	'DIR_END'	=> '</BIG>',
);

my %items = (
	'articleTitle'=> 'An Example Article',
	'articleText' => 'This is boring sample text: hello world...',
	'menu1'		  => $m->{HTML},
);
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__

DEPENDENCIES and PRAGMA

EasyTemplate;
cwd;
HTML::TokeParser;
strict;

Constructor method (new)

The method expects a package/class referemnce as it's first parameter. Following that, arguments should be passed in the form of an anonymous hash or as name/value pairs:

my $m = new HTML::EasyTemplate::DirMenu (
		'arg1'=>'val1','arg2'=>'val2',
);

or:

my $m = new HTML::EasyTemplate::DirMenu (
		{'arg1'=>'val1','arg2'=>'val2',}
);

Arguments

MODE

Must be set to one of either 'all', 'dirs', 'files'.

START

The directory to menu, or at which to start menuing.

EXTENSIONS

Filter - a regular expression fragment applied to the filenames within a directory. The regular expression fragment is insensitive to case, is bracketed, and matches after a dot and before the end:

m/\.($HERE)$/i

Deafults to .*\.html?$.

EXC_DIRS, EXC_FILES

A regular expression to be applied against directories/files to decide exclusion.

TITLE_IN

Should DirMenu access the document to collect a title to use in the menu?

If so, set this to the name of the tag of which the first instance contains the text to use as a title. Could be better if we had XPath, but then using title is normally enough, as it gets the text from the HTML's TITLE element.

PRINTEXTENSIONS

Request that filename extensions, defined in the object's EXTENSIONS slot above, be included in the printing of a filename.

LIST_START, LIST_END

HTML to put at the top and bottom of the menu output.

ARTICLE_START, ARTICLE_END

HTML to put at before and after each menu item.

HTMLDEFAULT

HTML to use when no files are found in a directory. Defaults to [No content].

TOPDIRTEXT

Text used as top-level directory title

ARTICLE_ROOT

The directory in which to begin work; defaults to the same value as the START slot detailed above.

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

URL_ROOT

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

URL_ROOT_TEXT

Text to use in a link that refers to URL_ROOT. =head2 Other Slots

HTML

It is in this slot that a single scalar representing the composed HTML menu will be found.

OUTPUT

Defaults to LIST, which produces HTML output using the options and defaults above. Could be used to call another processing sub (in &new) to output maybe a drop-down menu.

METHOD collect_this_dir

Collects content info of a directory, the path to which it accepts as it's sole argument.

Returns undef on failure.

METHOD create_html

Fills the calling object's HTML slot detailed in the constructor method's documentation.

Incidentaly returns that HTML.

CAVEATS

Does not list directories empty of files mathcing the search pattern.

SEE ALSO

HTML::EasyTemplate

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.

cpanm HTML::EasyTemplate::DirMenu

perl -MCPAN -e shell
install HTML::EasyTemplate::DirMenu