HTML-CalendarMonth
view release on metacpan or search on metacpan
- Added linux 'ncal' harness
1.19 Sat Mar 15 00:47:26 EDT 2008
- Fixed longstanding test failure due to HTML::Tree (properly)
deciding to put quotes around numeric attributes in tags.
- Also changed i8n test to Zulu rather than Basque since the
DateTime::Local::eu (Basque) module no longer has
abbreviated day names
- Some of the DateTool modules had a minor bug in add_days() not
checking for defined vs 0
- I released a calendar-related module update on the Ides of
March. I'm just sayin'.
1.18 Fri Feb 24 15:53:41 EST 2006
- Fixed some scoping issues in DateTool/DateCalc.pm (thanks
Carl Franks)
- Fixed a Win32 test module location issue (File::Spec tricks)
(thanks Carl Franks)
1.17 Fri Jan 6 16:09:46 EST 2006
- Updated tests with more recent test cases
* unix 'cal' command
1.10 Sat Feb 26 00:47:37 EST 2005
- Added more robust language support. Currently supports en,
de, and fr.
1.09 Tue Mar 26 05:21:59 CST 2002
- Fixed obscure bug that caused March 31 2002
to be dropped; related to a localtime/gmtime
issue with DST effects.
- Added tests for calendars over 1-year span
plus special cases such as the aforementioned
March 31 2002 instance.
1.08 Mon Jan 8 19:15:16 CST 2001
- Added Date::Manip fallback from Date::Calc,
so a C compiler is not strictly necessary
for folks wanting week-of-year numbering
or exotic dates.
1.07 Wed Nov 8 01:42:40 CST 2000
- Day-of-week bug REALLY fixed. Should now work
properly with all perumutations of calendar
pecularities and concepts of what the first
day of the week should be.
1.06 Wed Oct 4 13:37:31 CDT 2000
- Day-of-week bug fixed for cases where Sunday is
the first day of the month (such as Oct, 2000),
or last day of the month (such as Dec, 2000),
over various configurations of what is considered
the first day of the week.
HTML-CalendarMonth
-------------------
HTML::CalendarMonth is a module that simplifies the rendering of a
calendar month in HTML. It is NOT a scheduling system.
Calendars are represented as HTML::Element based structures, derived
from the HTML::ElementTable class.
The module includes support for 'week of the year' numbering, arbitrary
1st day of the week definitions, and locale support.
If you wish to use 'week of the year' numbering, or want to explore
dates beyond the capability of the internal perl time functions, then
you will need Date::Calc, DateTime, or Date::Manip.
http://www.cpan.org/authors/id/M/MS/MSISK/
The package is also available at the Toadstool:
http://www.mojotoad.com/sisk/projects/HTML-CalendarMonth/
ACKNOWLEDGMENTS
Thanks to William R. Ward for some conceptual nudging. Thanks to Fabian
Aichele, Jarkko Hietaniemi, Wolfgang Jürgensen, and David 'Sniper'
Rigaudiere for some suggestions on global calendar customs. Thanks to
Gael Marziou, Raul Rivero, Ricardo Signes, T. Bugra Uytun, and Philipp
W. for some helpful bug spotting.
COPYRIGHT
Copyright (c) 1999-2015 Matthew P. Sisk. All rights reserved. All wrongs
revenged. This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
lib/HTML/CalendarMonth.pm view on Meta::CPAN
return($self->month, $self->year);
}
# class factory access
use constant CLASS_HET => 'HTML::ElementTable';
use constant CLASS_DATETOOL => 'HTML::CalendarMonth::DateTool';
use constant CLASS_LOCALE => 'HTML::CalendarMonth::Locale';
sub _gencal {
# generate internal calendar representation
my $self = shift;
# new calendar...clobber day-specific settings
my $itoc = $self->_itoch({});
my $ctoi = $self->_ctoih({});
# figure out dow of 1st day of the month as well as last day of the
# month (uses date calculator backends)
$self->_anchor_month();
# row count for weeks in grid
my $wcnt = 0;
lib/HTML/CalendarMonth.pm view on Meta::CPAN
}
sub items {
# return list of all items (days, headers)
my $self = shift;
wantarray ? ($self->headers, $self->days)
: [$self->headers, $self->days];
}
sub last_col {
# what's the max col of the calendar?
my $self = shift;
$self->head_week ? LDC + 1 : LDC;
}
sub last_day_col { LDC }
sub last_row {
# last row of the calendar
my $self = shift;
return ($self->coords_of($self->lastday))[0];
}
*last_week_row = \&last_row;
sub first_week_row { FWR };
sub past_days {
my $self = shift;
lib/HTML/CalendarMonth.pm view on Meta::CPAN
}
sub item_box {
# return a glob of the box defined by two items
my($self, $item1, $item2) = splice(@_, 0, 3);
defined $item1 && defined $item2 or croak "Two items required";
$self->box($self->coords_of($item1), $self->coords_of($item2));
}
sub all {
# return a glob of all calendar cells, including empty cells.
my $self = shift;
$self->box( 0,0 => $self->last_row, $self->last_col );
}
sub alldays {
# return a glob of all cells other than header cells
my $self = shift;
$self->box( 2, 0 => $self->last_row, 6 );
}
lib/HTML/CalendarMonth.pm view on Meta::CPAN
use constant last_week_col => 6;
###
1;
__END__
=head1 NAME
HTML::CalendarMonth - Generate and manipulate HTML calendar months
=head1 SYNOPSIS
use HTML::CalendarMonth;
# Using regular HTML::Element creation
my $c = HTML::CalendarMonth->new( month => 8, year => 2010 );
print $c->as_HTML;
# Full locale support via DateTime::Locale
my $c2 = HTML::CalendarMonth->new(
month => 8,
year => 2010,
locale => 'zu-ZA'
);
print $c2->as_HTML;
# HTML-Tree integration
my $tree = HTML::TreeBuilder->parse_file('cal.html');
$tree->find_by_attribute(class => 'hcm-calendar')->replace_with($c);
print $tree->as_HTML;
# clean up if you're not done, HTML::Element structures must be
# manually destroyed
$c->delete; $c2->delete;
=head1 DESCRIPTION
HTML::CalendarMonth is a subclass of HTML::ElementTable. See
L<HTML::ElementTable(3)> for how that class works, for it affects this
module on many levels. Like HTML::ElementTable, HTML::CalendarMonth is
an enhanced HTML::Element with methods added to facilitate the
manipulation of the calendar table elements as a whole.
The primary interaction with HTML::CalendarMonth is through I<items>
rather than cell coordinates like HTML::ElementTable uses. An I<item> is
merely a string that represents the content of the cell of interest
within the calendar. For instance, the element representing the 14th day
of the month would be returned by C<$c-E<gt>item(14)>. Similarly, the
element representing the header for Monday would be returned by C<$c-
E<gt>item('Mo')>. If the year happened to by 2010, then C<$c-
E<gt>item(2010)> would return the cell representing the year. Since
years and particular months change frequently, it is probably more
useful to take advantage of the C<month()> and C<year()> methods, which
return their respective values. The following is therefore the same as
explicitely referencing the year: C<$c-E<gt>item($c- E<gt>year())>.
Multiple cells of the calendar can be manipulated as if they were a
single element. For instance, C<$c-E<gt>item(15)-E<gt>attr(class =E<gt>
'fancyday')> would alter the class of the cell representing the 15th. By
the same token, C<$c-E<gt>item(15, 16, 17,
23)-E<gt>attr(class =E<gt> 'fancyday')> would do the same thing for all
cells containing the days passed to the C<item()> method.
Underneath, the calendar is still nothing more than a table structure,
the same as provided by the HTML::ElementTable class. In addition to the
I<item> based access methods above, calendar cells can still be accessed
using row and column grid coordinates using the C<cell()> method
provided by the table class. All coordinate-based methods in the table
class are accessible to the calendar class.
The module includes support for week-of-the-year numbering, arbitrary
1st day of the week definitions, and locale support.
Dates that are beyond the range of the built-in time functions of perl
are handled either by the ncal/cal command, Date::Calc, DateTime, or
Date::Manip. The presence of any one of these utilities and modules will
suffice for these far flung date calculations. One of these utilities
(with the exception of 'cal') is also required if you want to use week-of-
year numbering.
lib/HTML/CalendarMonth.pm view on Meta::CPAN
All arguments appearing in [brackets] are optional, and do not represent
anonymous array references.
=head2 Constructor
=over
=item new()
With no arguments, the constructor will return a calendar object
representing the current month with a default appearance. The initial
configuration of the calendar is controlled by special attributes. Non-
calendar related attributes are passed along to HTML::ElementTable. Any
non-table related attributes left after that are passed to HTML::Element
while constructing the E<lt>tableE<gt> tag. See L<HTML::ElementTable> if
you are interested in attributes that can be passed along to that class.
Special Attributes for HTML::CalendarMonth:
=over
=item month
lib/HTML/CalendarMonth.pm view on Meta::CPAN
=item head_dow
Specifies whether to display days of the week header. Default 1.
=item head_week
Specifies whether to display the week-of-year numbering. Default 0.
=item locale
Specifies the id of the locale in which to render the calendar. Default
is 'en-US'. By default, this will also control determine which day is
considered to be the first day of the week. See
L<HTML::CalendarMonth::Locale> for more information. If for some reason
you prefer to use different labels than those provided by C<locale>, see
the C<alias> attribute below. NOTE: DateTime::Locale versions 0.92 and
earlier use underscores rather than dashes, e.g. 'en_US'.
=item full_days
Specifies whether or not to use full day names or their abbreviated
lib/HTML/CalendarMonth.pm view on Meta::CPAN
=item full_months
Specifies whether or not to use full month names or their abbreviated
names. Default is 1, use full names. Use -1 for 'narrow' mode, the
shortest (not guaranteed to be unique) abbreviations.
=item alias
Takes a hash reference mapping labels provided by C<locale> to any
custom label you prefer. Lookups, such as C<day('Sun')>, will still use
the locale string, but when the calendar is rendered the aliased value
will appear.
=item week_begin
Specify first day of the week, which can be 1..7, starting with Sunday.
In order to specify Monday, set this to 2, and so on. By default, this
is determined based on the locale.
=item enable_css
Set some handy CSS class attributes on elements, enabled by default.
Currently the classes are:
hcm-table Set on the E<lt>tableE<gt> tag of the calendar
hcm-day-head Set on the day-of-week E<lt>trE<gt> or E<lt>tdE<gt> tags
hcm-year-head Set on the E<lt>tdE<gt> tag for the year
hcm-month-head Set on the E<lt>tdE<gt> tag for the month
hcm-week-head Set on the E<lt>tdE<gt> tags for the week-of-year
=item semantic_css
Sets some additional CSS class attributes on elements, disabled by
default. The notion of 'today' is taken either from the system clock
(default) or from the 'today' parameter as provided to new(). Currently
lib/HTML/CalendarMonth.pm view on Meta::CPAN
hcm-today Set on the E<lt>tdE<gt> tag for today, if present
hcm-past Set on the E<lt>tdE<gt> tags for prior days, if present
hcm-future Set on the E<lt>tdE<gt> tags for subsequent days, if present
=item today
Specify the value for 'today' if different from the local time as
reported by the system clock (the default). If specified as two or less
digits, it is assumed to be one of the days of the month in the current
calendar. If more than two digits, it is assumed to be a epoch time in
seconds. Otherwise it must be given as a string of the form 'YYYY-mm-
dd'. Note that the default value as determined by the system clock uses
localtime rather than gmtime.
=item historic
This option is ignored for dates that do not exceed the range of the built-
in perl time functions. For dates that B<do> exceed these ranges, this
option specifies the default calculation method. When set, if the 'ncal'
or 'cal' command is available on your system, that will be used rather
than the Date::Calc or Date::Manip modules. This can be an issue since
the date modules blindly extrapolate the Gregorian calendar, whereas
ncal/cal will revert to the Julian calendar during September 1752. If
either ncal or cal are not available on your system, this attribute is
meaningless. Defaults to 1.
=back
=back
=head2 Item Query Methods
The following methods return lists of item *symbols* (28, 29, 'Thu',
lib/HTML/CalendarMonth.pm view on Meta::CPAN
Returns a list of all day headers (Su..Sa)
=item headers()
Returns a list of all headers (month, year, dayheaders)
=item items()
Returns a list of all item symbols (day number, header values) in
the calendar.
=item last_col()
Returns the index of the last column of the calendar (note that this
could be the week-of-year column if head_week is enabled).
=item last_day_col()
Returns the index of the last column of the calendar containing days of
the month (same as last_col() unless week-of-year is enabled).
=item first_week_row()
Returns the index of the first row of the calendar containing day items
(ie, the first week).
=item last_row()
Returns the index of the last row of the calendar.
=item today()
Returns the day of month for 'today', if present in the current
calendar.
=item past_days()
Returns a list of days prior to 'today'. If 'today' is in a future
month, all days are returned. If 'today' is in a past month, no days
are returned.
=item future_days()
Returns a list of days after 'today'. If 'today' is in a past
month, all days are returned. If 'today' is in a future month, no
days are returned.
=back
=head2 Glob Methods
Glob methods return references that are functionally equivalent to an
individual calendar cell. Mostly, they provide item based analogues to
the glob methods provided in HTML::ElementTable. In methods dealing with
rows, columns, and boxes, the globs include empty calendar cells (which
would otherwise need to be accessed through native HTML::ElementTable
methods). The row and column numbers returned by the item methods above
are compatible with the grid based methods in HTML::ElementTable.
For details on how these globs work, check out L<HTML::ElementTable> and
L<HTML::ElementGlob>.
=over
=item item(item1, [item2, ...])
lib/HTML/CalendarMonth.pm view on Meta::CPAN
=item allheaders()
Returns all header cells.
=item alldays()
Returns all non header cells, including empty cells.
=item all()
Returns all cells in the calendar, including empty cells.
=back
=head2 Transformation Methods
The following methods provide ways of translating between various item
symbols, coordinates, and other representations.
=over
lib/HTML/CalendarMonth.pm view on Meta::CPAN
a day of the week, where I<daynum> is 1..7.
=item daynum(dayname)
Returns the number of the day of the week given the symbolic name for
that day (Su..Sa).
=item daytime(day)
Returns the number in seconds since the epoch for a given day. The day
must be present in the current calendar.
=back
=head2 Other Methods
=over
=item default_css()
Returns a simple style sheet as a string that can be used in an HTML
lib/HTML/CalendarMonth/DateTool.pm view on Meta::CPAN
=over
=item new()
Constructor. Takes the following parameters:
=over
=item year
Year of calendar in question (required). If you are rendering exotic
dates (i.e. dates outside of 1970 to 2038) then something besides
Time::Local will be used for calendrical calculations.
=item month
Month of calendar in question (required). 1 through 12.
=item weeknum
Optional. When specified, will limit class excursions to those that are
currently set up for week of year calculations.
=item historic
Optional. If the the ncal or cal commands are available, use one of them
rather than other available date modules since these utilities
lib/HTML/CalendarMonth/DateTool/Cal.pm view on Meta::CPAN
my($self, $month, $year) = @_;
$month ||= $self->month;
$year ||= $self->year;
my $cmd = $self->_cal_cmd or croak "cal command not found\n";
my @cal = grep(!/^\s*$/,`$cmd $month $year`);
chomp @cal;
my @days = grep(/\d+/,split(/\s+/,$cal[2]));
my $dow1st = 6 - $#days;
my($lastday) = $cal[$#cal] =~ /(\d+)\s*$/;
# With dow1st and lastday, one builds a calendar sequentially.
# Historically, in particular Sep 1752, days have been skipped. Here's
# the chance to catch that.
$self->_skips(undef);
if ($month == 9 && $year == 1752) {
my %skips;
grep(++$skips{$_}, 3 .. 13);
$self->_skips(\%skips);
}
($dow1st, $lastday);
}
lib/HTML/CalendarMonth/Locale.pm view on Meta::CPAN
sub first_day_of_week { shift->loc->first_day_of_week % 7 }
sub days {
my $self = shift;
my $code = $self->code;
unless ($Register{$code}{days}) {
my $method = $self->full_days ? 'day_stand_alone_wide'
: 'day_stand_alone_abbreviated';
# adjust to H::CM standard expectation, 1st day Sun
# Sunday is first, regardless of what the calendar considers to be
# the first day of the week
my @days = @{$self->loc->$method};
unshift(@days, pop @days);
$Register{$code}{days} = \@days;
}
wantarray ? @{$Register{$code}{days}} : $Register{$code}{days};
}
sub narrow_days {
my $self = shift;
my $code = $self->code;
unless ($Register{$code}{narrow_days}) {
# Sunday is first, regardless of what the calendar considers to be
# the first day of the week
my @days = @{ $self->loc->day_stand_alone_narrow };
unshift(@days, pop @days);
$Register{$code}{narrow_days} = \@days;
}
wantarray ? @{$Register{$code}{narrow_days}}
: $Register{$code}{narrow_days};
}
sub months {
lib/HTML/CalendarMonth/Locale.pm view on Meta::CPAN
my $locale_name = $loc->code;
# the actual DateTime::Locale object
my $loc = $loc->loc;
1;
=head1 DESCRIPTION
HTML::CalendarMonth utilizes the powerful locale capabilities of
DateTime::Locale for rendering its calendars. The default locale is
'en-US' but many others are available. To see this list, invoke the
class method HTML::CalendarMonth::Locale->locales() which in turn
invokes DateTime::Locale::codes().
This module is mostly intended for internal usage within
HTML::CalendarMonth, but some of its functionality may be of use for
developers:
=head1 METHODS
lib/HTML/CalendarMonth/Locale.pm view on Meta::CPAN
See L<DateTime::Locale>.
=item locales()
Lists all available locale codes. Equivalent to locale()->codes(), or
DateTime::Locale->codes().
=item days()
Returns a list of days of the week, Sunday first. These are the actual
unique day strings used for rendering calendars, so depending on which
attributes were provided to C<new()>, this list will either be
abbreviations or full names. The default uses abbreviated day names.
Returns a list in list context or an array ref in scalar context.
=item narrow_days()
Returns a list of short day abbreviations, beginning with Sunday. The
narrow abbreviations are not guaranteed to be unique (i.e. 'S' for both
Sat and Sun).
( run in 0.552 second using v1.01-cache-2.11-cpan-5dc5da66d9d )