NAME

HTML::Menu::DateTime

Easily create HTML dropdown menus for use with HTML::Template or Template::Toolkit.

SYNOPSIS

use HTML::Menu::DateTime;

my $menu = HTML::Menu::DateTime->new (
  date        => '2004-02-26',
  no_select   => 1,
  empty_first => '');

$menu->start_year (2000);
$menu->end_year (2010);

$menu->less_years (1);
$menu->plus_years (5);

$menu->second_menu;
$menu->minute_menu;
$menu->hour_menu;
$menu->day_menu;
$menu->month_menu;
$menu->year_menu;

DESCRIPTION

Creates data structures suitable for populating HTML::Template or Template::Toolkit templates with dropdown date and time menus.

Allows any number of dropdown menus to be displayed on a single page, each independantly configurable.

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::Menu::DateTime;

my $template = HTML::Template->new (filename => $filename);

my $menu = HTML::Menu::DateTime->new;

$template->param (day   => $menu->day_menu,
                  month => $menu->month_menu,
                  year  => $menu->year_menu);

print header();
print $template->output;

METHODS

new()

my $menu1 = HTML::Menu::DateTime->new 
              (date        => $date,
               start_year  => $start,
               end_year    => $end,
               no_select   => 1,
               empty_first => 1);

my $menu2 = HTML::Menu::DateTime->new 
              (less_years => $less,
               plus_years => $plus);

new() accepts the following arguments (in the form of a hash or list):

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 new() is used to decide which item should be selected in all of the *_menu methods.

start_year, end_year, less_years, plus_years

The equivalent of calling the method of the same name.

no_select

If true, ensures no item in any menu will be selected.

empty_first

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 empty_first('value') will be the visible label for the first item (the empty string is allowed).

start_year()

$date->start_year (2004);

Sets the absolute year that the dropdown menu will start from.

end_year()

$date->end_year (2009);

Sets the absolute year that the dropdown menu will end on.

less_years()

$date->less_years (2);

Sets the year that the dropdown menu will start from, relative to the selected year.

plus_years()

$date->plus_years (7);

Sets the year that the dropdown menu will end on, relative to the selected year.

second_menu() minute_menu() hour_menu() day_menu() month_menu() year_menu()

$template->param (second => $date->second_menu,
                  minute => $date->minute_menu (0),
                  hour   => $date->hour_menu ('-1'),
                  day    => $date->day_menu ('+1'),
                  month  => $date->month_menu (12),
                  year   => $date->year_menu);

Accepts a value that will override the date (if any) in the new() method. Accepts relative values such as '+1' or '-1'.

Returns an array-reference suitable for passing directly to $template->param().

EXAMPLES

HTML::Template

Templates

The 'examples/html-template' folder in this distribution contains the files second.tmpl, minute.tmpl, hour.tmpl, day.tmpl, month.tmpl and year.tmpl. Simply copy these files into the folder containing the rest of your templates.

Contents of template file "date.tmpl":

<html>
<body>
  <form method="POST" action="">
    <TMPL_INCLUDE day.tmpl>
    <TMPL_INCLUDE month.tmpl>
    <TMPL_INCLUDE year.tmpl>
    <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::Menu::DateTime;
use HTML::Template;

my $template = HTML::Template->new (filename => 'date.tmpl');

my $menu = HTML::Menu::DateTime->new;

$template->param (day   => $menu->day_menu,
                  month => $menu->month_menu,
                  year  => $menu->year_menu);

print header(),
print $template->output;

Multiple Menus in a Single Page

To create, for example, 2 'month' menus in a single page you could copy the month.tmpl file to end_month.tmpl and then change the line <select name="month"> in end_month.tmpl to <select name="end_month">.

Then include both files in your main template:

<html>
<body>
  <form method="POST" action="">
    <TMPL_INCLUDE month.tmpl>
    <TMPL_INCLUDE end_month.tmpl>
    <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'.

Template::Toolkit

Templates

The 'examples/template-toolkit' 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.

Contents of template file "date.html":

<html>
<body>
  <form method="POST" action="">
    [% INCLUDE day.html %]
    [% INCLUDE month.html %]
    [% 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::Menu::DateTime;
use Template;

my $template = Template->new;

my $menu = HTML::Menu::DateTime->new;

my $vars = {day   => $menu->day_menu,
            month => $menu->month_menu,
            year  => $menu->year_menu};

$template->process ('date.html', $vars) 
  or die $template->error;

Multiple Menus in a Single Page

Then include both files in your main template:

<html>
<body>
  <form method="POST" action="">
    [% INCLUDE month.html %]
    [% 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'.

DEFAULT VALUES

If a date is not passed to the new() or *_menu() methods, then localtime(time) is called.

If neither 'start_year' or 'less_years' is set, the default used is less_years(5).

If neither 'end_year' or 'plus_years' is set, the default used is plus_years(5).

EXPORT

None.

TIPS

Years before 1000 AD passed to the 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 year_menu() method as literal numbers.

Years before 1 AD are not allowed at all.

DO NOT set both 'start_year' and 'less_years' at the same time, it just doesn't make sense.

DO NOT set both with 'end_year' and 'plus_years' at the same time, it just doesn't make sense.

To start or end the range on the same year as selected, set less_years or plus_years to zero, DO NOT set start_year or end_year to zero.

When settting either 'start_year' or 'end_year', ensure that the selected year will fall within the range of years.

When passing relative values to methods, ensure they are sent as strings. +1 numerically means 1 which is not the same as the string '+1'.

If a date is set in new() and either 'less_years' or 'plus_years' set and then a value passed to the c<year_menu()> method. The start / end year of the menu will be relative to the value passed to year_menu(), not the date set in 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.

TO DO

Allow an arrayref to be passed to the *_menu methods, to allow for selection of more than one item in a menu (for use with SELECT 'lists' rather than menus).

Add options to allow 'short' month names to be output, month numbers to be output, or other language month names to be output.

Add option to output html/xhtml menus rather than data structures for templates.

SUPPORT

Mailing list: html-menu-users@lists.sourceforge.net

AUTHOR

Carl Franks

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself (perlgpl, perlartistic).

To install HTML::Menu::DateTime, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::Menu::DateTime

CPAN shell

perl -MCPAN -e shell
install HTML::Menu::DateTime

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

MOTIVATION

METHODS

new()

start_year()

end_year()

less_years()

plus_years()

second_menu() minute_menu() hour_menu() day_menu() month_menu() year_menu()

EXAMPLES

HTML::Template

Templates

Displaying date dropdown menus

Multiple Menus in a Single Page

Template::Toolkit

Templates

Displaying date dropdown menus

Multiple Menus in a Single Page

DEFAULT VALUES

EXPORT

TIPS

TO DO

SUPPORT

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions