1 package HTML::CalendarMonth;
3 $HTML::CalendarMonth::VERSION = '1.25';
10 BEGIN { $HTML::CalendarMonth::VERSION = 1.25 }
12 use HTML::ElementTable 1.18;
13 use HTML::CalendarMonth::Locale;
14 use HTML::CalendarMonth::DateTool;
16 use base qw( Class::Accessor HTML::ElementTable );
20 # default complex attributes
21 my %Calmonth_Attrs = (
22 head_m => 1, # month heading mode
23 head_y => 1, # year heading mode
24 head_dow => 1, # DOW heading mode
25 head_week => 0, # weak of year
26 year_span => 2, # default col span of year
28 today => undef, # DOM, if not now
29 week_begin => 1, # what DOW (1-7) is the 1st DOW?
31 historic => 1, # if able to choose, use ncal/cal
32 # rather than Date::Calc, which
33 # blindly extrapolates Gregorian
35 alias => {}, # what gets displayed if not
38 month => undef, # these will get initialized
50 # internal muckety muck
67 __PACKAGE__->mk_accessors(keys %Calmonth_Attrs);
69 # Class::Accessor overrides
72 my($self, $key) = splice(@_, 0, 2);
74 $Objects{$self}{$key} = $_[0];
77 $Objects{$self}{$key} = [@_];
80 Carp::confess("wrong number of arguments received");
87 return $Objects{$self}{$_[0]};
90 return @{$Objects{$self}{@_}};
93 Carp::confess("wrong number of arguments received.");
97 sub _is_calmonth_attr { shift; exists $Calmonth_Attrs{shift()} }
101 foreach (keys %Calmonth_Attrs) {
102 $self->$_($Calmonth_Attrs{$_});
107 sub DESTROY { delete $Objects{shift()} }
109 # last dow col, first week row
111 use constant LDC => 6;
112 use constant FWR => 2;
117 my($self, $item) = splice(@_, 0, 2);
118 defined $item or croak "item name required";
119 $self->alias->{$item} = shift if @_;
120 $self->alias->{$item} || $item;
124 my($self, $item) = splice(@_, 0, 2);
125 defined $item or croak "item name required.\n";
126 defined $self->alias->{$item};
132 # Set/test entire heading (month,year,and dow headers) (does not
133 # affect week number column). Return true if either heading active.
135 $self->head_m(@_) && $self->head_dow(@_) if @_;
136 $self->_head_my || $self->head_dow;
140 # Set/test month and year header mode
141 my($self, $mode) = splice(@_, 0, 2);
142 $self->head_m($mode) && $self->head_y($mode) if defined $mode;
143 $self->head_m || $self->head_y;
148 @_ ? $self->{_initialized} = shift : $self->{_initialized};
154 # set target month, year
157 my ($month, $year) = @_;
158 $month && defined $year || croak "date method requires month and year";
159 croak "Date already set" if $self->_initialized();
161 # get rid of possible leading 0's
165 $month <= 12 && $month >= 1 or croak "Month $month out of range (1-12)\n";
166 $year > 0 or croak "Negative years are unacceptable\n";
168 $self->month($self->monthname($month));
170 $month = $self->monthnum($month);
172 # trigger _gencal...this should be the only place where this occurs
175 return($self->month, $self->year);
178 # class factory access
180 use constant CLASS_HET => 'HTML::ElementTable';
181 use constant CLASS_DATETOOL => 'HTML::CalendarMonth::DateTool';
182 use constant CLASS_LOCALE => 'HTML::CalendarMonth::Locale';
185 # generate internal calendar representation
188 # new calendar...clobber day-specific settings
189 my $itoc = $self->_itoch({});
190 my $ctoi = $self->_ctoih({});
192 # figure out dow of 1st day of the month as well as last day of the
193 # month (uses date calculator backends)
194 $self->_anchor_month();
196 # row count for weeks in grid
199 my ($dowc) = $self->dow1st;
200 my $skips = $self->_caltool->_skips;
203 foreach (1 .. $self->lastday) {
204 next if $skips->{$_};
207 # this is a bootstrap until we know the number of rows in the month.
208 $itoc->{$_} = [$r, $c];
210 ++$wcnt unless $dowc || $_ == $self->lastday;
213 $self->{_week_rows} = $wcnt;
215 my $row_extent = $wcnt + FWR;
216 my $col_extent = LDC;
217 $col_extent += 1 if $self->head_week;
219 $self->SUPER::extent($row_extent, $col_extent);
221 # table can contain the days now, so replace our bootstrap coordinates
222 # with references to the actual elements.
223 foreach (keys %$itoc) {
224 my $cellref = $self->cell(@{$itoc->{$_}});
225 $self->_itoc($_, $cellref);
226 $self->_ctoi($cellref, $_);
229 # week num affects month/year spans
230 my $width = $self->head_week ? 8 : 7;
233 my $cellref = $self->cell(0, 0);
234 $self->_itoc($self->month, $cellref);
235 $self->_ctoi($cellref, $self->month);
236 $cellref = $self->cell(0, $width - $self->year_span);
237 $self->_itoc($self->year, $cellref);
238 $self->_ctoi($cellref, $self->year);
240 $self->item($self->month)->replace_content($self->item_alias($self->month));
241 $self->item($self->year)->replace_content($self->item_alias($self->year));
243 if ($self->_head_my) {
245 $self->item($self->month)->attr('colspan',$width - $self->year_span);
248 $self->item($self->month)->mask(1);
249 $self->item($self->year)->attr('colspan', $width);
252 $self->item($self->year)->attr('colspan',$self->year_span);
255 $self->item($self->year)->mask(1);
256 $self->item($self->month)->attr('colspan', $width);
260 $self->row(0)->mask(1);
265 my $days = $self->loc->days;
266 foreach (0..$#$days) {
267 # Transform for week_begin 1..7
268 $trans = ($_ + $self->week_begin - 1) % 7;
269 my $cellref = $self->cell(1, $_);
270 $self->_itoc($days->[$trans], $cellref);
271 $self->_ctoi($cellref, $days->[$trans]);
273 if ($self->head_dow) {
274 grep($self->item($_)->replace_content($self->item_alias($_)), @$days);
277 $self->row(1)->mask(1);
281 if ($self->head_week) {
282 # week nums can collide with days. Use "w" in front of the number
283 # for uniqueness, and automatically alias to just the number (unless
284 # already aliased, of course).
285 $self->_gen_week_nums();
288 foreach ($self->_numeric_week_nums) {
290 $self->item_alias($ws, $_) unless $self->item_aliased($ws);
291 my $cellref = $self->cell($row_count, $self->last_col);
292 $self->_itoc($ws, $cellref);
293 $self->_ctoi($cellref, $ws);
294 $self->item($ws)->replace_content($self->item_alias($ws));
299 # fill in days of the month
301 foreach my $r (FWR .. $self->last_row) {
302 foreach my $c (0 .. LDC) {
303 $self->cell($r,$c)->replace_content($self->item_alias($i))
304 if ($i = $self->item_at($r,$c));
309 if ($self->enable_css) {
310 $self ->push_attr(class => 'hcm-table' );
311 $self->item_row($self->dayheaders)->push_attr(class => 'hcm-day-head' );
312 $self->item ($self->year) ->push_attr(class => 'hcm-year-head' );
313 $self->item ($self->month) ->push_attr(class => 'hcm-month-head');
314 $self->item ($self->week_nums) ->push_attr(class => 'hcm-week-head' )
318 if ($self->semantic_css) {
319 my $today = $self->today;
321 $self->item($self->days)->push_attr(class => 'hcm-past');
323 elsif ($today == 0) {
324 $self->item($self->days)->push_attr(class => 'hcm-future');
327 for my $d ($self->days) {
329 $self->item($d)->push_attr(class => 'hcm-past');
331 elsif ($d > $today) {
332 $self->item($d)->push_attr(class => 'hcm-future');
335 $self->item($d)->push_attr(class => 'hcm-today');
345 my $hbgc = '#DDDDDD';
349 <style type="text/css">
353 border: thin solid $bc;
354 border-collapse: collapse;
365 background-color: $hbgc;
370 background-color: $hbgc;
375 background-color: $hbgc;
376 border-bottom: thin solid $bc;
381 background-color: $hbgc;
382 border-left: thin solid $bc;
394 if (! ($ct = $self->_caltool)) {
395 $ct = $self->_caltool(CLASS_DATETOOL->new(
397 month => $self->month,
398 weeknum => $self->head_week,
399 historic => $self->historic,
400 datetool => $self->datetool,
407 # Figure out what our month grid looks like.
408 # Let HTML::CalendarMonth::DateTool determine which method is
412 my $month = $self->monthnum($self->month);
413 my $year = $self->year;
415 my $tool = $self->_datetool;
417 my $dow1st = $tool->dow1st; # 0..6, starting with Sun
418 my $lastday = $tool->lastday;
420 # week_begin given as 1..7 starting with Sun
421 $dow1st = ($dow1st - ($self->week_begin - 1)) % 7;
423 $self->dow1st($dow1st);
424 $self->lastday($lastday);
430 # Generate week-of-the-year numbers. The first week is generally
431 # agreed upon to be the week that contains the 4th of January.
433 # For purposes of shenanigans with 'week_begin', we anchor the week
434 # number off of Thursday in each row.
438 my($year, $month, $lastday) = ($self->year, $self->monthnum, $self->lastday);
440 my $tool = $self->_caltool;
441 croak "Oops. " . ref $tool . " not set up for week of year calculations.\n"
442 unless $tool->can('week_of_year');
444 my $fdow = $self->dow1st;
445 my $delta = 4 - $fdow;
449 my @ft = $tool->add_days($delta, 1);
451 my $ldow = $tool->dow($lastday);
456 my @lt = $tool->add_days($delta, $lastday);
458 my $fweek = $tool->week_of_year(@ft);
459 my $lweek = $tool->week_of_year(@lt);
460 my @wnums = $fweek > $lweek ? ($fweek, 1 .. $lweek) : ($fweek .. $lweek);
462 # do we have days above our first Thursday?
463 if ($self->row_of($ft[0]) != FWR) {
464 unshift(@wnums, $wnums[0] -1);
467 # do we have days below our last Thursday?
468 if ($self->row_of($lt[0]) != $self->last_row) {
469 push(@wnums, $wnums[-1] + 1);
472 # first visible week is from last year
473 if ($wnums[0] == 0) {
474 $wnums[0] = $tool->week_of_year($tool->add_days(-7, $ft[0]));
477 # last visible week is from subsequent year
478 if ($wnums[-1] > $lweek) {
479 $wnums[-1] = $tool->week_of_year($tool->add_days(7, $lt[0]));
482 $self->_weeknums(\@wnums);
488 # given a list of items, return all items in rows shared by the
492 foreach my $item (@_) {
493 my $row = ($self->coords_of($item))[0];
494 foreach my $col (0 .. $self->last_col) {
495 my $i = $self->item_at($row, $col) || next;
499 keys %items > 1 ? keys %items : (keys %items)[0];
503 # return all item cells in the columns occupied by the provided list
506 $self->_col_items(0, $self->last_row, @_);
510 # same as col_items(), but excludes header cells.
512 $self->_col_items(FWR, $self->last_row, @_);
516 # given row bounds and a list of items, return all item elements
517 # in the columns occupied by the provided items. Does not return
519 my($self, $rfirst, $rlast) = splice(@_, 0, 3);
521 my($item, $row, $col, %i);
522 foreach my $item (@_) {
523 my $col = ($self->coords_of($item))[1];
524 foreach my $row ($rfirst .. $rlast) {
525 my $i = $self->item_at($row,$col) || next;
529 keys %items > 1 ? keys %items : (keys %items)[0];
533 # return seconds since epoch for a given day
534 my($self, $day) = splice(@_, 0, 2);
535 $day or croak "must specify day of month";
536 croak "day does not exist" unless $self->_daycheck($day);
537 $self->_caltool->day_epoch($day);
541 # return list of all week number labels
542 my @wnums = map("w$_", shift->_numeric_week_nums);
543 wantarray ? @wnums : \@wnums;
546 sub _numeric_week_nums {
547 # return list of all week numbers as numbers
549 return unless $self->head_week;
550 wantarray ? @{$self->_weeknums} : $self->_weeknums;
554 # return list of all days of the month (1..$c->lastday).
556 my $skips = $self->_caltool->_skips;
557 my @days = grep { !$skips->{$_} } (1 .. $self->lastday);
558 wantarray ? @days : \@days;
562 # return list of all day headers (Su..Sa).
567 # return list of all headers (month,year,dayheaders)
569 wantarray ? ($self->year, $self->month, $self->dayheaders)
570 : [$self->year, $self->month, $self->dayheaders];
574 # return list of all items (days, headers)
576 wantarray ? ($self->headers, $self->days)
577 : [$self->headers, $self->days];
581 # what's the max col of the calendar?
583 $self->head_week ? LDC + 1 : LDC;
586 sub last_day_col { LDC }
589 # last row of the calendar
591 return ($self->coords_of($self->lastday))[0];
594 *last_week_row = \&last_row;
596 sub first_week_row { FWR };
600 my $today = $self->_today;
604 elsif ($today == 0) {
612 my $today = $self->_today;
616 elsif ($today == 0) {
619 return($today .. $self->last_day);
622 # custom glob interfaces
625 # return TD elements containing items
627 @_ || croak "item(s) must be provided";
628 $self->cell(grep(defined $_, map($self->coords_of($_), @_)));
632 # return a glob of the rows of a list of items, including empty cells.
634 $self->row(map { $self->row_of($_) } @_);
638 # same as item_row, but excludes possible week number cells
640 return $self->item_row(@_) unless $self->head_week;
642 for my $r (map { $self->row_of($_) } @_) {
643 next if ++$rows{$r} > 1;
645 push(@coords, ($r, $c));
648 $self->cell(@coords);
652 # glob of all week numbers
654 $self->item($self->week_nums);
658 # return a glob of the cols of a list of items, including empty cells.
660 $self->_item_col(0, $self->last_row, @_);
664 # same as item_col(), but excludes header cells.
666 $self->_item_col(2, $self->last_row, @_);
670 # given row bounds and a list of items, return a glob representing
671 # the cells in the columns occupied by the provided items, including
673 my($self, $rfirst, $rlast) = splice(@_, 0, 3);
674 defined $rfirst && defined $rlast or Carp::confess "No items provided";
676 foreach my $col (map { $self->col_of($_) } @_) {
677 next if ++$seen{$col} > 1;
678 foreach my $row ($rfirst .. $rlast) {
679 push(@coords, $row, $col);
682 $self->cell(@coords);
686 # return a glob of the box defined by two items
687 my($self, $item1, $item2) = splice(@_, 0, 3);
688 defined $item1 && defined $item2 or croak "Two items required";
689 $self->box($self->coords_of($item1), $self->coords_of($item2));
693 # return a glob of all calendar cells, including empty cells.
695 $self->box( 0,0 => $self->last_row, $self->last_col );
699 # return a glob of all cells other than header cells
701 $self->box( 2, 0 => $self->last_row, 6 );
705 # return a glob of all header cells
707 $self->item($self->headers);
710 # transformation Methods
713 # convert an item into grid coordinates
715 croak "undefined value passed to coords_of()" if @_ && ! defined $_[0];
716 my $ref = $self->_itoc(@_);
717 my @pos = ref $ref ? $ref->position : ();
718 @pos ? (@pos[$#pos - 1, $#pos]) : ();
722 # convert grid coords into item
724 $self->_ctoi($self->cell(@_));
729 my($self, $item, $ref) = splice(@_, 0, 3);
730 defined $item or croak "item required";
731 my $itoc = $self->_itoch;
733 croak "Reference required" unless ref $ref;
734 $itoc->{$item} = $ref;
740 # cell reference to item
741 my($self, $refstring, $item) = splice(@_, 0, 3);
742 defined $refstring or croak "cell id required";
743 my $ctoi = $self->_ctoih;
745 $ctoi->{$refstring} = $item;
752 ($self->coords_of(@_))[0];
757 ($self->coords_of(@_))[1];
761 # check/return month...returns name. Accepts month number or string.
763 return $self->month unless @_;
764 my $loc = $self->loc;
767 $m = ($m - 1) % 12 if $m && $m =~ /^\d+$/;
768 $m = $loc->monthname($m) || croak "month not found " . join(', ', @_);
769 return $m if @_ == 1;
776 # check/return month, returns number. Accepts month number or string.
778 my @months = @_ ? @_ : $self->month;
779 my $loc = $self->loc;
781 for my $m (@months) {
782 $m = ($m - 1) % 12 if $m && $m =~ /^\d+$/;
783 $m = $loc->monthnum($m);
784 croak "month not found ", join(', ', @_) unless defined $m;
786 return $m if @_ == 1;
793 # check/return day...returns name. Accepts 1..7, or Su..Sa
795 @_ || croak "day string or num required";
796 my $loc = $self->loc;
800 $d = (($d - 1) % 7) + $self->week_begin - 1;
802 $d = $loc->dayname($d) || croak "day not found ", join(', ', @_);
803 return $d if @_ == 1;
810 # check/return day number 1..7, returns number. Accepts 1..7,
813 @_ || croak "day string or num required";
814 my $loc = $self->loc;
818 $d = (($d - 1) % 7) + $self->week_begin - 1;
820 $d = $loc->daynum($d);
821 croak "day not found ", join(', ', @_) unless defined $d;
823 return $d if @_ == 1;
832 # test day head names
833 my($self, $name) = splice(@_, 0, 2);
834 $name or croak "name missing";
835 return if $name =~ /^\d+$/;
836 $self->daynum($name);
840 # check if an item is a day of the month (1..31)
841 my($self, $item) = splice(@_, 0, 2);
842 croak "item required" unless $item;
843 # can't just invert _headcheck because coords_of() needs _daycheck,
844 # and _headcheck uses coords_of()
845 $item =~ /^\d{1,2}$/ && $item <= 31;
849 # check if an item is a header
853 # constructors/destructors
859 foreach (keys %parms) {
860 if (__PACKAGE__->_is_calmonth_attr($_)) {
861 $attrs{$_} = $parms{$_};
864 $tattrs{$_} = $parms{$_};
868 my $self = CLASS_HET->new(%tattrs);
872 $self->_set_defaults;
874 my $month = delete $attrs{month};
875 my $year = delete $attrs{year};
876 if (!$month || !$year) {
877 my ($nmonth,$nyear) = (localtime(time))[4,5];
878 ++$nmonth; $nyear += 1900;
882 $self->month($month);
886 for my $k (keys %attrs) {
887 $self->$k($attrs{$k}) if defined $attrs{$k};
890 my $loc = CLASS_LOCALE->new(
892 full_days => $self->full_days,
893 full_months => $self->full_months,
894 ) or croak "Problem creating locale " . $self->locale . "\n";
897 my $dt = CLASS_DATETOOL->new(
899 month => $self->month,
900 weeknum => $self->head_week,
901 historic => $self->historic,
902 datetool => $self->datetool,
904 $self->_caltool($dt);
906 $self->week_begin($loc->first_day_of_week + 1)
907 unless defined $attrs{week_begin};
909 my $dom_now = defined $attrs{today} ? $dt->_dom_now(delete $attrs{today})
911 $self->_today($dom_now);
912 $self->today($dom_now) if $dom_now > 0;
914 my $alias = $attrs{alias} || {};
915 if ($self->full_days < 0) {
916 my @full = $self->loc->days;
917 my @narrow = $self->loc->narrow_days;
918 for my $i (0 .. $#narrow) {
919 $alias->{$full[$i]} = $narrow[$i];
922 if ($self->full_months < 0) {
923 my @full = $self->loc->months;
924 my @narrow = $self->loc->narrow_months;
925 for my $i (0 .. $#narrow) {
926 $alias->{$full[$i]} = $narrow[$i];
929 $self->alias($alias) if keys %$alias;
931 # for now, this is the only time this will every happen for this
932 # object. It is now 'initialized'.
933 $self->_date($month, $year);
938 ### overrides (our table is static)
941 sub maxrow { shift->SUPER::maxrow }
942 sub maxcol { shift->SUPER::maxcol }
946 use constant row_offset => 0;
947 use constant col_offset => 0;
948 use constant first_col => 0;
949 use constant first_row => 0;
950 use constant first_week_col => 0;
951 use constant last_week_col => 6;
961 HTML::CalendarMonth - Generate and manipulate HTML calendar months
965 use HTML::CalendarMonth;
967 # Using regular HTML::Element creation
968 my $c = HTML::CalendarMonth->new( month => 8, year => 2010 );
971 # Full locale support via DateTime::Locale
972 my $c2 = HTML::CalendarMonth->new(
979 # Full locale support via DateTime::Locale
980 $c3 = HTML::CalendarMonth->new( month => 8, year => 79, locale => 'fr' );
983 # HTML-Tree integration
984 my $tree = HTML::TreeBuilder->parse_file('cal.html');
985 $tree->find_by_attribute(class => 'hcm-calendar')->replace_with($c);
986 print $tree->as_HTML;
988 # clean up if you're not done, HTML::Element structures must be
990 $c->delete; $c2->delete;
994 HTML::CalendarMonth is a subclass of HTML::ElementTable. See
995 L<HTML::ElementTable(3)> for how that class works, for it affects this
996 module on many levels. Like HTML::ElementTable, HTML::CalendarMonth is
997 an enhanced HTML::Element with methods added to facilitate the
998 manipulation of the calendar table elements as a whole.
1000 The primary interaction with HTML::CalendarMonth is through I<items>
1001 rather than cell coordinates like HTML::ElementTable uses. An I<item> is
1002 merely a string that represents the content of the cell of interest
1003 within the calendar. For instance, the element representing the 14th day
1004 of the month would be returned by C<$c-E<gt>item(14)>. Similarly, the
1005 element representing the header for Monday would be returned by C<$c-
1006 E<gt>item('Mo')>. If the year happened to by 2010, then C<$c-
1007 E<gt>item(2010)> would return the cell representing the year. Since
1008 years and particular months change frequently, it is probably more
1009 useful to take advantage of the C<month()> and C<year()> methods, which
1010 return their respective values. The following is therefore the same as
1011 explicitly referencing the year: C<$c-E<gt>item($c- E<gt>year())>.
1013 Multiple cells of the calendar can be manipulated as if they were a
1014 single element. For instance, C<$c-E<gt>item(15)-E<gt>attr(class =E<gt>
1015 'fancyday')> would alter the class of the cell representing the 15th. By
1016 the same token, C<$c-E<gt>item(15, 16, 17,
1017 23)-E<gt>attr(class =E<gt> 'fancyday')> would do the same thing for all
1018 cells containing the days passed to the C<item()> method.
1020 Underneath, the calendar is still nothing more than a table structure,
1021 the same as provided by the HTML::ElementTable class. In addition to the
1022 I<item> based access methods above, calendar cells can still be accessed
1023 using row and column grid coordinates using the C<cell()> method
1024 provided by the table class. All coordinate-based methods in the table
1025 class are accessible to the calendar class.
1027 The module includes support for week-of-the-year numbering, arbitrary
1028 1st day of the week definitions, and locale support.
1030 Dates that are beyond the range of the built-in time functions of perl
1031 are handled either by the ncal/cal command, Date::Calc, DateTime, or
1032 Date::Manip. The presence of any one of these utilities and modules will
1033 suffice for these far flung date calculations. One of these utilities
1034 (with the exception of 'cal') is also required if you want to use week-of-
1037 Full locale support is offered via DateTime::Locale. For a full list of
1038 supported locale id's, look at HTML::CalendarMonth::Locale->locales().
1042 All arguments appearing in [brackets] are optional, and do not represent
1043 anonymous array references.
1051 With no arguments, the constructor will return a calendar object
1052 representing the current month with a default appearance. The initial
1053 configuration of the calendar is controlled by special attributes. Non-
1054 calendar related attributes are passed along to HTML::ElementTable. Any
1055 non-table related attributes left after that are passed to HTML::Element
1056 while constructing the E<lt>tableE<gt> tag. See L<HTML::ElementTable> if
1057 you are interested in attributes that can be passed along to that class.
1059 Special Attributes for HTML::CalendarMonth:
1065 1-12, or Jan-Dec. Defaults to current month.
1069 Four digit representation. Defaults to current year.
1073 Specifies whether to display the month header. Default 1.
1077 Specifies whether to display the year header. Default 1.
1081 Specifies whether to display days of the week header. Default 1.
1085 Specifies the id of the locale in which to render the calendar. Default
1086 is 'en_US'. By default, this will also control determine which day is
1087 considered to be the first day of the week. See
1088 L<HTML::CalendarMonth::Locale> for more information. If for some reason
1089 you prefer to use different labels than those provided by C<locale>, see
1090 the C<alias> attribute below.
1094 Specifies whether or not to use full day names or their abbreviated
1095 names. Default is 0, use abbreviated names. Use -1 for 'narrow' mode,
1096 the shortest (not guaranteed to be unique) abbreviations.
1100 Specifies whether or not to use full month names or their abbreviated
1101 names. Default is 1, use full names. Use -1 for 'narrow' mode, the
1102 shortest (not guaranteed to be unique) abbreviations.
1106 Takes a hash reference mapping labels provided by C<locale> to any
1107 custom label you prefer. Lookups, such as C<day('Sun')>, will still use
1108 the locale string, but when the calendar is rendered the aliased value
1113 Specifies whether to display the week-of-year numbering. Default 0.
1117 Specify first day of the week, which can be 1..7, starting with Sunday.
1118 In order to specify Monday, set this to 2, and so on. By default, this
1119 is determined based on the locale.
1123 Set some handy CSS class attributes on elements, enabled by default.
1124 Currently the classes are:
1126 hcm-table Set on the <lt>table<gt> tag of the calendar
1127 hcm-day-head Set on the day-of-week <lt>tr<gt> or <lt>td<gt> tags
1128 hcm-year-head Set on the <lt>td<gt> tag for the year
1129 hcm-month-head Set on the <lt>td<gt> tag for the month
1130 hcm-week-head Set on the <lt>td<gt> tags for the week-of-year
1134 Sets some additional CSS class attributes on elements, disabled by
1135 default. The notion of 'today' is taken either from the system clock
1136 (default) or from the 'today' parameter as provided to new(). Currently
1139 hcm-today Set on the <lt>td<gt> tag for today, if present
1140 hcm-past Set on the <lt>td<gt> tags for prior days, if present
1141 hcm-future Set on the <lt>td<gt> tags for subsequent days, if present
1145 Specify the value for 'today' if different from the local time as
1146 reported by the system clock (the default). If specified as two or less
1147 digits, it is assumed to be one of the days of the month in the current
1148 calendar. If more than two digits, it is assumed to be a epoch time in
1149 seconds. Otherwise it must be given as a string of the form 'YYYY-mm-
1150 dd'. Note that the default value as determined by the system clock uses
1151 localtime rather than gmtime.
1155 This option is ignored for dates that do not exceed the range of the built-
1156 in perl time functions. For dates that B<do> exceed these ranges, this
1157 option specifies the default calculation method. When set, if the 'ncal'
1158 or 'cal' command is available on your system, that will be used rather
1159 than the Date::Calc or Date::Manip modules. This can be an issue since
1160 the date modules blindly extrapolate the Gregorian calendar, whereas
1161 ncal/cal will revert to the Julian calendar during September 1752. If
1162 either ncal or cal are not available on your system, this attribute is
1163 meaningless. Defaults to 1.
1169 =head2 Item Query Methods
1171 The following methods return lists of item *symbols* (28, 29, 'Thu',
1172 ...) that are related in some way to the provided list of items. The
1173 returned symbols may then be used as arguments to the glob methods
1174 detailed further below.
1178 =item row_items(item1, [item2, ...])
1180 Returns all item symbols in rows shared by the provided item symbols.
1182 =item col_items(item1, [item2, ...])
1184 Returns all item symbols in columns shared by the provided item symbols.
1186 =item daycol_items(col_item1, [col_item2, ...])
1188 Same as col_items(), but the returned item symbols are limited to those
1189 that are not header items (month, year, day-of-week).
1191 =item row_of(item1, [item2, ...])
1193 Returns the row indices of rows containing the provided item symbols.
1195 =item col_of(item1, [item2, ...])
1197 Returns the column indices of columns containing the provided
1202 Returns the day number (symbol) of the last day of the month.
1206 Returns the column index for the first day of the month.
1210 Returns a list of all days of the month as numbers.
1214 Returns a list of week-of-year numbers for this month.
1218 Returns a list of all day headers (Su..Sa)
1222 Returns a list of all headers (month, year, dayheaders)
1226 Returns a list of all item symbols (day number, header values) in
1231 Returns the index of the last column of the calendar (note that this
1232 could be the week-of-year column if head_week is enabled).
1234 =item last_day_col()
1236 Returns the index of the last column of the calendar containing days of
1237 the month (same as last_col() unless week-of-year is enabled).
1239 =item first_week_row()
1241 Returns the index of the first row of the calendar containing day items
1242 (ie, the first week).
1246 Returns the index of the last row of the calendar.
1250 Returns the day of month for 'today', if present in the current
1255 Returns a list of days prior to 'today'. If 'today' is in a future
1256 month, all days are returned. If 'today' is in a past month, no days
1261 Returns a list of days after 'today'. If 'today' is in a past
1262 month, all days are returned. If 'today' is in a future month, no
1269 Glob methods return references that are functionally equivalent to an
1270 individual calendar cell. Mostly, they provide item based analogues to
1271 the glob methods provided in HTML::ElementTable. In methods dealing with
1272 rows, columns, and boxes, the globs include empty calendar cells (which
1273 would otherwise need to be accessed through native HTML::ElementTable
1274 methods). The row and column numbers returned by the item methods above
1275 are compatible with the grid based methods in HTML::ElementTable.
1277 For details on how these globs work, check out L<HTML::ElementTable> and
1278 L<HTML::ElementGlob>.
1282 =item item(item1, [item2, ...])
1284 Returns all cells containing the provided item symbols.
1286 =item item_row(item1, [item2, ...])
1288 Returns all cells in all rows occupied by the provided item symbols.
1290 =item item_day_row(item1, [item2, ...])
1292 Same as item_row() except excludes week-of-year cells, if present.
1294 =item item_col(item1, [item2, ...])
1296 Returns all cells in all columns occupied by the provided item symbols.
1298 =item item_daycol(item1, [item2, ...])
1300 Same as item_col() except limits the cells to non header cells.
1302 =item item_week_nums()
1304 Returns all week-of-year cells, if present.
1306 =item item_box(item1a, item1b, [item2a, item2b, ...])
1308 Returns all cells in the boxes defined by the item pairs provided.
1312 Returns all header cells.
1316 Returns all non header cells, including empty cells.
1320 Returns all cells in the calendar, including empty cells.
1324 =head2 Transformation Methods
1326 The following methods provide ways of translating between various item
1327 symbols, coordinates, and other representations.
1331 =item coords_of(item)
1333 Returns the row and column coordinates of the provided item symbol, for
1334 use with the grid based methods in HTML::ElementTable.
1336 =item item_at(row,column)
1338 Returns the item symbol of the item at the provided coordinates, for use
1339 with the item based methods of HTML::CalendarMonth.
1341 =item monthname(monthnum)
1343 Returns the name (item symbol) of the month number provided, where
1344 I<monthnum> can be 1..12.
1346 =item monthnum(monthname)
1348 Returns the number (1..12) of the month name provided. Only a minimal
1349 case-insensitive match on the month name is necessary; the proper item
1350 symbol for the month will be determined from this match.
1352 =item dayname(daynum)
1354 Returns the name (item symbol) of the day of week header for a number of
1355 a day of the week, where I<daynum> is 1..7.
1357 =item daynum(dayname)
1359 Returns the number of the day of the week given the symbolic name for
1364 Returns the number in seconds since the epoch for a given day. The day
1365 must be present in the current calendar.
1369 =head2 Other Methods
1375 Returns a simple style sheet as a string that can be used in an HTML
1376 document in conjunction with the classes assigned to elements when css
1387 Date::Calc, DateTime, or Date::Manip (only if you want week-of-
1388 year numbering or non-contemporary dates on a system without the
1393 Matthew P. Sisk, E<lt>F<sisk@mojotoad.com>E<gt>
1397 Copyright (c) 1998-2010 Matthew P. Sisk. All rights reserved. All wrongs
1398 revenged. This program is free software; you can redistribute it and/or
1399 modify it under the same terms as Perl itself.
1403 A useful page of examples can be found at
1404 http://www.mojotoad.com/sisk/projects/HTML-CalendarMonth.
1406 For information on iso639 standards for abbreviations for language
1407 names, see http://www.loc.gov/standards/iso639-2/englangn.html
1409 HTML::ElementTable(3), HTML::Element(3), perl(1)
1411 =for Pod::Coverage col_offset row_offset item_alias item_aliased last_week_row