Hi,
I've written a module which I propose naming
HTML::Template::Dropdown::Date.
Please see the POD below for description and usage.
The module doesn't actually require HTML::Template and could be used
for other things, though this is the use it was created for and will
be maintained and developed for.
I asked a while ago for comments but unfortunately didn't hear
anything back.
This time I'm asking if there's any objections to using the namespace
(suggestions for alternative names welcome), as I want to upload to
CPAN as it's used in a larger app that I'll be releasing soon.
Many thanks,
Carl Franks
=head1 NAME
HTML::Template::Dropdown::Date
=head1 SYNOPSIS
use HTML::Template::Dropdown::Date;
my $menu = HTML::Template::Dropdown::Date->new (
date => '2004-02-26',
noSelect => 1,
emptyFirst => '');
$menu->startYear(2000);
$menu->endYear(2010);
$menu->lessYears(1);
$menu->plusYears(5);
$menu->secondMenu;
$menu->minuteMenu;
$menu->hourMenu;
$menu->dayMenu;
$menu->monthMenu;
$menu->yearMenu;
=head1 DESCRIPTION
Creates data structures suitable for populating HTML::Template
templates with
dropdown date and time menus.
Allows any number of dropdown menus to be displayed on a page, each
independantly configurable.
=head1 MOTIVATION
To keep the creation of HTML completely seperate from the program, to
easily
allow css styles, javascript, etc. to be added to individual menus.
To make the creation of menus as simple as possible, with extra
options if
needed. Menus can be created as easily as:
#!/usr/bin/perl
use strict;
use warnings;
use CGI ':standard';
use HTML::Template;
use HTML::Template::Dropdown::Date;
my $tmpl = HTML::Template->new (filename => $filename);
my $menu = HTML::Template::Dropdown::Date->new;
$tmpl->param (day => $menu->dayMenu(),
month => $menu->monthMenu(),
year => $menu->yearMenu(),
);
print header();
print $tmpl->output();
=head1 METHODS
=head2 new()
my $menu1 = HTML::Template::Dropdown::Date->new
(date => $date,
startYear => $start,
endYear => $end,
noSelect => 1,
emptyFirst => 1);
my $menu2 = HTML::Template::Dropdown::Date->new
(lessYears => $less,
plusYears => $plus);
C<new()> accepts the following arguments (in the form of a hash or
list):
=over4
=item date
Can be in any of the formats 'YYYY-MM-DD hh:mm:ss', 'YYYYMMDDhhmmss',
'YYYYMMDDhhmm', 'YYYYMMDDhh', 'YYYYMMDD', 'YYYYMM', 'YYYY', 'YYYY-MM--
DD',
'hh:mm:ss'.
The date passed to C<new()> is used to decide which item should be
selected
in all of the *Menu methods.
=item startYear, endYear, lessYears, plusYears
The equivalent of calling the method of the same name.
=item noSelect
If true, ensures no item in any menu will be selected.
=item emptyFirst
If 'defined', will create an extra list item at the start of each
menu. The
form value will be the empty string (''), the value passed to
C<emptyFirst('value')> will be the visible label for the first item
(the
empty string is allowed).
=back
=head2 startYear()
$date->startYear(2004);
Sets the absolute year that the dropdown menu will start from.
=head2 endYear()
$date->endYear(2009);
Sets the absolute year that the dropdown menu will end on.
=head2 lessYears()
$date->lessYears(2);
Sets the year that the dropdown menu will start from, relative to the
selected
year.
=head2 plusYears()
$date->plusYears(7);
Sets the year that the dropdown menu will end on, relative to the
selected
year.
=head2 secondMenu() minuteMenu() hourMenu() dayMenu() monthMenu()
yearMenu()
$tmpl->param (secMenu => $date->secondMenu(),
minMenu => $date->minuteMenu(0),
hourMenu => $date->hourMenu('-1'),
dayMenu => $date->dayMenu('+1'),
monthMenu => $date->monthMenu(12),
yearMenu => $date->yearMenu(),
);
Accepts a value that will override the date (if any) in the C<new()>
method.
Accepts relative values such as '+1' or '-1'.
Returns an array-reference suitable for passing directly to $tmpl-
>param().
=head1 EXAMPLES
=head2 Templates
The 'examples' folder in this distribution contains the files
second.html,
minute.html, hour.html, day.html, month.html and year.html. Simply
copy these
files into the folder containing the rest of your templates.
=head2 Displaying date dropdown menus
Contents of template file "date.html":
<html>
<body>
<form method="POST" action="">
<TMPL_INCLUDE day.html>
<TMPL_INCLUDE month.html>
<TMPL_INCLUDE year.html>
<input type="submit" name="Submit" value="Submit">
</form>
</body>
</html>
Contents of program file:
#!/usr/bin/perl
use strict;
use warnings;
use CGI ':standard';
use HTML::Template::Dropdown::Date;
use HTML::Template;
my $tmpl = HTML::Template->new (filename => 'date.html');
my $menu = HTML::Template::Dropdown::Date->new
(date => '2004-04-01',
lessYears => 2,
plusYears => 0);
$tmpl->param (day => $menu->dayMenu(),
month => $menu->monthMenu(),
year => $menu->yearMenu(),
);
print header(),
print $tmpl->output();
=head2 Multiple Menus in a Single Page
To create, for example, 2 'month' menus in a single page you could
copy the
month.html file to end_month.html and then change the line
C<<select name="month">> in end_month.html to C<<select
name="end_month">>.
Then include both files in your main template:
<html>
<body>
<form method="POST" action="">
<TMPL_INCLUDE month.html>
<TMPL_INCLUDE end_month.html>
<input type="submit" name="Submit" value="Submit">
</form>
</body>
</html>
When this form is submitted, it will send 2 different values, 'month'
and
'end_month'.
=head1 DEFAULT VALUES
If a date is not passed to the C<new()> or *Menu() methods, then
C<localtime(time)> is called.
If neither 'startYear' or 'lessYears' is set, the default used is
C<lessYears(5)>.
If neither 'endYear' or 'plusYears' is set, the default used is
C<plusYears(5)>.
=head1 EXPORT
None.
=head1 TIPS
Years before 1000 AD passed to the C<new()> method in
the 'YYYYMMDDhhmmss'
format should be passed as strings, as the leading zeros are
necessary. (e.g.
'09990101000000').
Years before 1000 AD may be passed to the C<yearMenu()> method as
literal
numbers.
Years before 1 AD are not allowed at all.
DO NOT set both 'startYear' and 'lessYears' at the same time, it just
doesn't
make sense.
DO NOT set both with 'endYear' and 'plusYears' at the same time, it
just
doesn't make sense.
To start or end the range on the same year as selected, set lessYears
or
plusYears to zero, DO NOT set startYear or endYear to zero.
When settting either 'startYear' or 'endYear', ensure that the
selected year
will fall within the range of years.
When passing relative values to methods, ensure they are sent as
strings.
C<+1> numerically means C<1> which is not the same as the string
C<'+1'>.
If a date is set in C<new()> and either 'lessYears' or 'plusYears' set
and
then a value passed to the c<yearMenu()> method. The start / end year
of the
menu will be relative to the value passed to C<yearMenu()>, not the
date set
in C<new()>.
'Relative' parameter values sent to *Menu methods, which result in
out-of-range selections are silently ignored and no item in the output
menu
will be selected.
=head1 SEE ALSO
HTML::Template
=head1 AUTHOR
Carl Franks
=head1 COPYRIGHT AND LICENSE
Copyright 2004, Carl Franks. All rights reserved.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself (L<perlgpl>, L<perlartistic>).
=cut
-------------------------------------------------------
This SF.Net email is sponsored by: YOU BE THE JUDGE. Be one of 170
Project Admins to receive an Apple iPod Mini FREE for your judgement on
who ports your project to Linux PPC the best. Sponsored by IBM.
Deadline: Sept. 24. Go here: http://sf.net/ppc_contest.php
_______________________________________________
Html-template-users mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/html-template-users
