1 package HTML::CalendarMonth;
3 $HTML::CalendarMonth::VERSION = '2.04';
10 use HTML::ElementTable 1.18;
11 use HTML::CalendarMonth::Locale;
12 use HTML::CalendarMonth::DateTool;
14 use base qw( Class::Accessor HTML::ElementTable );
18 # default complex attributes
19 my %Calmonth_Attrs = (
20 head_m => 1, # month heading mode
21 head_y => 1, # year heading mode
22 head_dow => 1, # DOW heading mode
23 head_week => 0, # weak of year
24 year_span => 2, # default col span of year
26 today => undef, # DOM, if not now
27 week_begin => 1, # what DOW (1-7) is the 1st DOW?
29 historic => 1, # if able to choose, use ncal/cal
30 # rather than Date::Calc, which
31 # blindly extrapolates Gregorian
33 alias => {}, # what gets displayed if not
36 month => undef, # these will get initialized
48 # internal muckety muck
64 __PACKAGE__->mk_accessors(keys %Calmonth_Attrs);
66 # Class::Accessor overrides
69 my($self, $key) = splice(@_, 0, 2);
71 $Objects{$self}{$key} = $_[0];
74 $Objects{$self}{$key} = [@_];
77 Carp::confess("wrong number of arguments received");
84 return $Objects{$self}{$_[0]};
87 return @{$Objects{$self}{@_}};
90 Carp::confess("wrong number of arguments received.");
94 sub _is_calmonth_attr { shift; exists $Calmonth_Attrs{shift()} }
98 foreach (keys %Calmonth_Attrs) {
99 $self->$_($Calmonth_Attrs{$_});
104 sub DESTROY { delete $Objects{shift()} }
106 # last dow col, first week row
108 use constant LDC => 6;
109 use constant FWR => 2;
114 my($self, $item) = splice(@_, 0, 2);
115 defined $item or croak "item name required";
116 $self->alias->{$item} = shift if @_;
117 $self->alias->{$item} || $item;
121 my($self, $item) = splice(@_, 0, 2);
122 defined $item or croak "item name required.\n";
123 defined $self->alias->{$item};
129 # Set/test entire heading (month,year,and dow headers) (does not
130 # affect week number column). Return true if either heading active.
132 $self->head_m(@_) && $self->head_dow(@_) if @_;
133 $self->_head_my || $self->head_dow;
137 # Set/test month and year header mode
138 my($self, $mode) = splice(@_, 0, 2);
139 $self->head_m($mode) && $self->head_y($mode) if defined $mode;
140 $self->head_m || $self->head_y;
145 @_ ? $self->{_initialized} = shift : $self->{_initialized};
151 # set target month, year
154 my ($month, $year) = @_;
155 $month && defined $year || croak "date method requires month and year";
156 croak "Date already set" if $self->_initialized();
158 # get rid of possible leading 0's
162 $month <= 12 && $month >= 1 or croak "Month $month out of range (1-12)\n";
163 $year > 0 or croak "Negative years are unacceptable\n";
165 $self->month($self->monthname($month));
167 $month = $self->monthnum($month);
169 # trigger _gencal...this should be the only place where this occurs
172 return($self->month, $self->year);
175 # class factory access
177 use constant CLASS_HET => 'HTML::ElementTable';
178 use constant CLASS_DATETOOL => 'HTML::CalendarMonth::DateTool';
179 use constant CLASS_LOCALE => 'HTML::CalendarMonth::Locale';
182 # generate internal calendar representation
185 # new calendar...clobber day-specific settings
186 my $itoc = $self->_itoch({});
187 my $ctoi = $self->_ctoih({});
189 # figure out dow of 1st day of the month as well as last day of the
190 # month (uses date calculator backends)
191 $self->_anchor_month();
193 # row count for weeks in grid
196 my ($dowc) = $self->dow1st;
197 my $skips = $self->_caltool->_skips;
200 foreach (1 .. $self->lastday) {
201 next if $skips->{$_};
204 # this is a bootstrap until we know the number of rows in the month.
205 $itoc->{$_} = [$r, $c];
207 ++$wcnt unless $dowc || $_ == $self->lastday;
210 $self->{_week_rows} = $wcnt;
212 my $row_extent = $wcnt + FWR;
213 my $col_extent = LDC;
214 $col_extent += 1 if $self->head_week;
216 $self->SUPER::extent($row_extent, $col_extent);
218 # table can contain the days now, so replace our bootstrap coordinates
219 # with references to the actual elements.
220 foreach (keys %$itoc) {
221 my $cellref = $self->cell(@{$itoc->{$_}});
222 $self->_itoc($_, $cellref);
223 $self->_ctoi($cellref, $_);
226 # week num affects month/year spans
227 my $width = $self->head_week ? 8 : 7;
230 my $cellref = $self->cell(0, 0);
231 $self->_itoc($self->month, $cellref);
232 $self->_ctoi($cellref, $self->month);
233 $cellref = $self->cell(0, $width - $self->year_span);
234 $self->_itoc($self->year, $cellref);
235 $self->_ctoi($cellref, $self->year);
237 $self->item($self->month)->replace_content($self->item_alias($self->month));
238 $self->item($self->year)->replace_content($self->item_alias($self->year));
240 if ($self->_head_my) {
241 if ($self->head_m && $self->head_y) {
242 $self->item($self->year) ->attr('colspan', $self->year_span);
243 $self->item($self->month)->attr('colspan', $width - $self->year_span);
245 elsif ($self->head_y) {
246 $self->item($self->month)->mask(1);
247 $self->item($self->year)->attr('colspan', $width);
249 elsif ($self->head_m) {
250 $self->item($self->year)->mask(1);
251 $self->item($self->month)->attr('colspan', $width);
255 $self->row(0)->mask(1);
260 my $days = $self->loc->days;
261 foreach (0..$#$days) {
262 # Transform for week_begin 1..7
263 $trans = ($_ + $self->week_begin - 1) % 7;
264 my $cellref = $self->cell(1, $_);
265 $self->_itoc($days->[$trans], $cellref);
266 $self->_ctoi($cellref, $days->[$trans]);
268 if ($self->head_dow) {
269 grep($self->item($_)->replace_content($self->item_alias($_)), @$days);
272 $self->row(1)->mask(1);
276 if ($self->head_week) {
277 # week nums can collide with days. Use "w" in front of the number
278 # for uniqueness, and automatically alias to just the number (unless
279 # already aliased, of course).
280 $self->_gen_week_nums();
283 foreach ($self->_numeric_week_nums) {
285 $self->item_alias($ws, $_) unless $self->item_aliased($ws);
286 my $cellref = $self->cell($row_count, $self->last_col);
287 $self->_itoc($ws, $cellref);
288 $self->_ctoi($cellref, $ws);
289 $self->item($ws)->replace_content($self->item_alias($ws));
294 # fill in days of the month
296 foreach my $r (FWR .. $self->last_row) {
297 foreach my $c (0 .. LDC) {
298 $self->cell($r,$c)->replace_content($self->item_alias($i))
299 if ($i = $self->item_at($r,$c));
304 if ($self->enable_css) {
305 $self->push_attr(class => 'hcm-table');
306 $self->item_row($self->dayheaders)->push_attr(class => 'hcm-day-head')
308 $self->item($self->year)->push_attr(class => 'hcm-year-head')
310 $self->item($self->month)->push_attr(class => 'hcm-month-head')
312 $self->item($self->week_nums) ->push_attr(class => 'hcm-week-head')
316 if ($self->semantic_css) {
317 my $today = $self->today;
319 $self->item($self->days)->push_attr(class => 'hcm-past');
321 elsif ($today == 0) {
322 $self->item($self->days)->push_attr(class => 'hcm-future');
325 for my $d ($self->days) {
327 $self->item($d)->push_attr(class => 'hcm-past');
329 elsif ($d > $today) {
330 $self->item($d)->push_attr(class => 'hcm-future');
333 $self->item($d)->push_attr(class => 'hcm-today');
343 my $hbgc = '#DDDDDD';
347 <style type="text/css">
351 border: thin solid $bc;
352 border-collapse: collapse;
363 background-color: $hbgc;
368 background-color: $hbgc;
373 background-color: $hbgc;
374 border-bottom: thin solid $bc;
379 background-color: $hbgc;
380 border-left: thin solid $bc;
392 if (! ($ct = $self->_caltool)) {
393 $ct = $self->_caltool(CLASS_DATETOOL->new(
395 month => $self->month,
396 weeknum => $self->head_week,
397 historic => $self->historic,
398 datetool => $self->datetool,
405 # Figure out what our month grid looks like.
406 # Let HTML::CalendarMonth::DateTool determine which method is
410 my $month = $self->monthnum($self->month);
411 my $year = $self->year;
413 my $tool = $self->_datetool;
415 my $dow1st = $tool->dow1st; # 0..6, starting with Sun
416 my $lastday = $tool->lastday;
418 # week_begin given as 1..7 starting with Sun
419 $dow1st = ($dow1st - ($self->week_begin - 1)) % 7;
421 $self->dow1st($dow1st);
422 $self->lastday($lastday);
428 # Generate week-of-the-year numbers. The first week is generally
429 # agreed upon to be the week that contains the 4th of January.
431 # For purposes of shenanigans with 'week_begin', we anchor the week
432 # number off of Thursday in each row.
436 my($year, $month, $lastday) = ($self->year, $self->monthnum, $self->lastday);
438 my $tool = $self->_caltool;
439 croak "Oops. " . ref $tool . " not set up for week of year calculations.\n"
440 unless $tool->can('week_of_year');
442 my $fdow = $self->dow1st;
443 my $delta = 4 - $fdow;
447 my @ft = $tool->add_days($delta, 1);
449 my $ldow = $tool->dow($lastday);
454 my @lt = $tool->add_days($delta, $lastday);
456 my $fweek = $tool->week_of_year(@ft);
457 my $lweek = $tool->week_of_year(@lt);
458 my @wnums = $fweek > $lweek ? ($fweek, 1 .. $lweek) : ($fweek .. $lweek);
460 # do we have days above our first Thursday?
461 if ($self->row_of($ft[0]) != FWR) {
462 unshift(@wnums, $wnums[0] -1);
465 # do we have days below our last Thursday?
466 if ($self->row_of($lt[0]) != $self->last_row) {
467 push(@wnums, $wnums[-1] + 1);
470 # first visible week is from last year
471 if ($wnums[0] == 0) {
472 $wnums[0] = $tool->week_of_year($tool->add_days(-7, $ft[0]));
475 # last visible week is from subsequent year
476 if ($wnums[-1] > $lweek) {
477 $wnums[-1] = $tool->week_of_year($tool->add_days(7, $lt[0]));
480 $self->_weeknums(\@wnums);
486 # given a list of items, return all items in rows shared by the
490 foreach my $item (@_) {
491 my $row = ($self->coords_of($item))[0];
492 foreach my $col (0 .. $self->last_col) {
493 my $i = $self->item_at($row, $col) || next;
497 keys %items > 1 ? keys %items : (keys %items)[0];
501 # return all item cells in the columns occupied by the provided list
504 $self->_col_items(0, $self->last_row, @_);
508 # same as col_items(), but excludes header cells.
510 $self->_col_items(FWR, $self->last_row, @_);
514 # given row bounds and a list of items, return all item elements
515 # in the columns occupied by the provided items. Does not return
517 my($self, $rfirst, $rlast) = splice(@_, 0, 3);
519 my($item, $row, $col, %i);
520 foreach my $item (@_) {
521 my $col = ($self->coords_of($item))[1];
522 foreach my $row ($rfirst .. $rlast) {
523 my $i = $self->item_at($row,$col) || next;
527 keys %items > 1 ? keys %items : (keys %items)[0];
531 # return seconds since epoch for a given day
532 my($self, $day) = splice(@_, 0, 2);
533 $day or croak "must specify day of month";
534 croak "day does not exist" unless $self->_daycheck($day);
535 $self->_caltool->day_epoch($day);
539 # return list of all week number labels
540 my @wnums = map("w$_", shift->_numeric_week_nums);
541 wantarray ? @wnums : \@wnums;
544 sub _numeric_week_nums {
545 # return list of all week numbers as numbers
547 return unless $self->head_week;
548 wantarray ? @{$self->_weeknums} : $self->_weeknums;
552 # return list of all days of the month (1..$c->lastday).
554 my $skips = $self->_caltool->_skips;
555 my @days = grep { !$skips->{$_} } (1 .. $self->lastday);
556 wantarray ? @days : \@days;
560 # return list of all day headers (Su..Sa).
565 # return list of all headers (month,year,dayheaders)
567 wantarray ? ($self->year, $self->month, $self->dayheaders)
568 : [$self->year, $self->month, $self->dayheaders];
572 # return list of all items (days, headers)
574 wantarray ? ($self->headers, $self->days)
575 : [$self->headers, $self->days];
579 # what's the max col of the calendar?
581 $self->head_week ? LDC + 1 : LDC;
584 sub last_day_col { LDC }
587 # last row of the calendar
589 return ($self->coords_of($self->lastday))[0];
592 *last_week_row = \&last_row;
594 sub first_week_row { FWR };
598 my $today = $self->today;
602 elsif ($today == 0) {
610 my $today = $self->today;
614 elsif ($today == 0) {
617 return($today .. $self->last_day);
620 # custom glob interfaces
623 # return TD elements containing items
625 @_ || croak "item(s) must be provided";
626 $self->cell(grep(defined $_, map($self->coords_of($_), @_)));
630 # return a glob of the rows of a list of items, including empty cells.
632 $self->row(map { $self->row_of($_) } @_);
636 # same as item_row, but excludes possible week number cells
638 return $self->item_row(@_) unless $self->head_week;
640 for my $r (map { $self->row_of($_) } @_) {
641 next if ++$rows{$r} > 1;
643 push(@coords, ($r, $c));
646 $self->cell(@coords);
650 # glob of all week numbers
652 $self->item($self->week_nums);
656 # return a glob of the cols of a list of items, including empty cells.
658 $self->_item_col(0, $self->last_row, @_);
662 # same as item_col(), but excludes header cells.
664 $self->_item_col(2, $self->last_row, @_);
668 # given row bounds and a list of items, return a glob representing
669 # the cells in the columns occupied by the provided items, including
671 my($self, $rfirst, $rlast) = splice(@_, 0, 3);
672 defined $rfirst && defined $rlast or Carp::confess "No items provided";
674 foreach my $col (map { $self->col_of($_) } @_) {
675 next if ++$seen{$col} > 1;
676 foreach my $row ($rfirst .. $rlast) {
677 push(@coords, $row, $col);
680 $self->cell(@coords);
684 # return a glob of the box defined by two items
685 my($self, $item1, $item2) = splice(@_, 0, 3);
686 defined $item1 && defined $item2 or croak "Two items required";
687 $self->box($self->coords_of($item1), $self->coords_of($item2));
691 # return a glob of all calendar cells, including empty cells.
693 $self->box( 0,0 => $self->last_row, $self->last_col );
697 # return a glob of all cells other than header cells
699 $self->box( 2, 0 => $self->last_row, 6 );
703 # return a glob of all header cells
705 $self->item($self->headers);
708 # transformation Methods
711 # convert an item into grid coordinates
713 croak "undefined value passed to coords_of()" if @_ && ! defined $_[0];
714 my $ref = $self->_itoc(@_);
715 my @pos = ref $ref ? $ref->position : ();
716 @pos ? (@pos[$#pos - 1, $#pos]) : ();
720 # convert grid coords into item
722 $self->_ctoi($self->cell(@_));
727 my($self, $item, $ref) = splice(@_, 0, 3);
728 defined $item or croak "item required";
729 my $itoc = $self->_itoch;
731 croak "Reference required" unless ref $ref;
732 $itoc->{$item} = $ref;
738 # cell reference to item
739 my($self, $refstring, $item) = splice(@_, 0, 3);
740 defined $refstring or croak "cell id required";
741 my $ctoi = $self->_ctoih;
743 $ctoi->{$refstring} = $item;
750 ($self->coords_of(@_))[0];
755 ($self->coords_of(@_))[1];
759 # check/return month...returns name. Accepts month number or string.
761 return $self->month unless @_;
762 my $loc = $self->loc;
765 $m = ($m - 1) % 12 if $m && $m =~ /^\d+$/;
766 $m = $loc->monthname($m) || croak "month not found " . join(', ', @_);
767 return $m if @_ == 1;
774 # check/return month, returns number. Accepts month number or string.
776 my @months = @_ ? @_ : $self->month;
777 my $loc = $self->loc;
779 for my $m (@months) {
780 $m = ($m - 1) % 12 if $m && $m =~ /^\d+$/;
781 $m = $loc->monthnum($m);
782 croak "month not found ", join(', ', @_) unless defined $m;
784 return $m if @_ == 1;
791 # check/return day...returns name. Accepts 1..7, or Su..Sa
793 @_ || croak "day string or num required";
794 my $loc = $self->loc;
798 $d = (($d - 1) % 7) + $self->week_begin - 1;
800 $d = $loc->dayname($d) || croak "day not found ", join(', ', @_);
801 return $d if @_ == 1;
808 # check/return day number 1..7, returns number. Accepts 1..7,
811 @_ || croak "day string or num required";
812 my $loc = $self->loc;
816 $d = (($d - 1) % 7) + $self->week_begin - 1;
818 $d = $loc->daynum($d);
819 croak "day not found ", join(', ', @_) unless defined $d;
821 return $d if @_ == 1;
830 # test day head names
831 my($self, $name) = splice(@_, 0, 2);
832 $name or croak "name missing";
833 return if $name =~ /^\d+$/;
834 $self->daynum($name);
838 # check if an item is a day of the month (1..31)
839 my($self, $item) = splice(@_, 0, 2);
840 croak "item required" unless $item;
841 # can't just invert _headcheck because coords_of() needs _daycheck,
842 # and _headcheck uses coords_of()
843 $item =~ /^\d{1,2}$/ && $item <= 31;
847 # check if an item is a header
851 # constructors/destructors
857 foreach (keys %parms) {
858 if (__PACKAGE__->_is_calmonth_attr($_)) {
859 $attrs{$_} = $parms{$_};
862 $tattrs{$_} = $parms{$_};
866 my $self = CLASS_HET->new(%tattrs);
870 $self->_set_defaults;
872 my $month = delete $attrs{month};
873 my $year = delete $attrs{year};
874 if (!$month || !$year) {
875 my ($nmonth,$nyear) = (localtime(time))[4,5];
876 ++$nmonth; $nyear += 1900;
880 $self->month($month);
884 for my $k (keys %attrs) {
885 $self->$k($attrs{$k}) if defined $attrs{$k};
888 my $loc = CLASS_LOCALE->new(
890 full_days => $self->full_days,
891 full_months => $self->full_months,
892 ) or croak "Problem creating locale " . $self->locale . "\n";
895 my $dt = CLASS_DATETOOL->new(
897 month => $self->month,
898 weeknum => $self->head_week,
899 historic => $self->historic,
900 datetool => $self->datetool,
902 $self->_caltool($dt);
904 $self->week_begin($loc->first_day_of_week + 1)
905 unless defined $attrs{week_begin};
907 my $dom_now = defined $attrs{today} ? $dt->_dom_now(delete $attrs{today})
909 $self->today($dom_now);
911 my $alias = $attrs{alias} || {};
912 if ($self->full_days < 0) {
913 my @full = $self->loc->days;
914 my @narrow = $self->loc->narrow_days;
915 for my $i (0 .. $#narrow) {
916 $alias->{$full[$i]} = $narrow[$i];
919 if ($self->full_months < 0) {
920 my @full = $self->loc->months;
921 my @narrow = $self->loc->narrow_months;
922 for my $i (0 .. $#narrow) {
923 $alias->{$full[$i]} = $narrow[$i];
926 $self->alias($alias) if keys %$alias;
928 # for now, this is the only time this will every happen for this
929 # object. It is now 'initialized'.
930 $self->_date($month, $year);
935 ### overrides (our table is static)
938 sub maxrow { shift->SUPER::maxrow }
939 sub maxcol { shift->SUPER::maxcol }
943 use constant row_offset => 0;
944 use constant col_offset => 0;
945 use constant first_col => 0;
946 use constant first_row => 0;
947 use constant first_week_col => 0;
948 use constant last_week_col => 6;
958 HTML::CalendarMonth - Generate and manipulate HTML calendar months
962 use HTML::CalendarMonth;
964 # Using regular HTML::Element creation
965 my $c = HTML::CalendarMonth->new( month => 8, year => 2010 );
968 # Full locale support via DateTime::Locale
969 my $c2 = HTML::CalendarMonth->new(
976 # HTML-Tree integration
977 my $tree = HTML::TreeBuilder->parse_file('cal.html');
978 $tree->find_by_attribute(class => 'hcm-calendar')->replace_with($c);
979 print $tree->as_HTML;
981 # clean up if you're not done, HTML::Element structures must be
983 $c->delete; $c2->delete;
987 HTML::CalendarMonth is a subclass of HTML::ElementTable. See
988 L<HTML::ElementTable(3)> for how that class works, for it affects this
989 module on many levels. Like HTML::ElementTable, HTML::CalendarMonth is
990 an enhanced HTML::Element with methods added to facilitate the
991 manipulation of the calendar table elements as a whole.
993 The primary interaction with HTML::CalendarMonth is through I<items>
994 rather than cell coordinates like HTML::ElementTable uses. An I<item> is
995 merely a string that represents the content of the cell of interest
996 within the calendar. For instance, the element representing the 14th day
997 of the month would be returned by C<$c-E<gt>item(14)>. Similarly, the
998 element representing the header for Monday would be returned by C<$c-
999 E<gt>item('Mo')>. If the year happened to by 2010, then C<$c-
1000 E<gt>item(2010)> would return the cell representing the year. Since
1001 years and particular months change frequently, it is probably more
1002 useful to take advantage of the C<month()> and C<year()> methods, which
1003 return their respective values. The following is therefore the same as
1004 explicitely referencing the year: C<$c-E<gt>item($c- E<gt>year())>.
1006 Multiple cells of the calendar can be manipulated as if they were a
1007 single element. For instance, C<$c-E<gt>item(15)-E<gt>attr(class =E<gt>
1008 'fancyday')> would alter the class of the cell representing the 15th. By
1009 the same token, C<$c-E<gt>item(15, 16, 17,
1010 23)-E<gt>attr(class =E<gt> 'fancyday')> would do the same thing for all
1011 cells containing the days passed to the C<item()> method.
1013 Underneath, the calendar is still nothing more than a table structure,
1014 the same as provided by the HTML::ElementTable class. In addition to the
1015 I<item> based access methods above, calendar cells can still be accessed
1016 using row and column grid coordinates using the C<cell()> method
1017 provided by the table class. All coordinate-based methods in the table
1018 class are accessible to the calendar class.
1020 The module includes support for week-of-the-year numbering, arbitrary
1021 1st day of the week definitions, and locale support.
1023 Dates that are beyond the range of the built-in time functions of perl
1024 are handled either by the ncal/cal command, Date::Calc, DateTime, or
1025 Date::Manip. The presence of any one of these utilities and modules will
1026 suffice for these far flung date calculations. One of these utilities
1027 (with the exception of 'cal') is also required if you want to use week-of-
1030 Full locale support is offered via DateTime::Locale. For a full list of
1031 supported locale id's, look at HTML::CalendarMonth::Locale->locales().
1035 All arguments appearing in [brackets] are optional, and do not represent
1036 anonymous array references.
1044 With no arguments, the constructor will return a calendar object
1045 representing the current month with a default appearance. The initial
1046 configuration of the calendar is controlled by special attributes. Non-
1047 calendar related attributes are passed along to HTML::ElementTable. Any
1048 non-table related attributes left after that are passed to HTML::Element
1049 while constructing the E<lt>tableE<gt> tag. See L<HTML::ElementTable> if
1050 you are interested in attributes that can be passed along to that class.
1052 Special Attributes for HTML::CalendarMonth:
1058 1-12, or Jan-Dec. Defaults to current month.
1062 Four digit representation. Defaults to current year.
1066 Specifies whether to display the month header. Default 1.
1070 Specifies whether to display the year header. Default 1.
1074 Specifies whether to display days of the week header. Default 1.
1078 Specifies whether to display the week-of-year numbering. Default 0.
1082 Specifies the id of the locale in which to render the calendar. Default
1083 is 'en-US'. By default, this will also control determine which day is
1084 considered to be the first day of the week. See
1085 L<HTML::CalendarMonth::Locale> for more information. If for some reason
1086 you prefer to use different labels than those provided by C<locale>, see
1087 the C<alias> attribute below. NOTE: DateTime::Locale versions 0.92 and
1088 earlier use underscores rather than dashes, e.g. 'en_US'.
1092 Specifies whether or not to use full day names or their abbreviated
1093 names. Default is 0, use abbreviated names. Use -1 for 'narrow' mode,
1094 the shortest (not guaranteed to be unique) abbreviations.
1098 Specifies whether or not to use full month names or their abbreviated
1099 names. Default is 1, use full names. Use -1 for 'narrow' mode, the
1100 shortest (not guaranteed to be unique) abbreviations.
1104 Takes a hash reference mapping labels provided by C<locale> to any
1105 custom label you prefer. Lookups, such as C<day('Sun')>, will still use
1106 the locale string, but when the calendar is rendered the aliased value
1111 Specify first day of the week, which can be 1..7, starting with Sunday.
1112 In order to specify Monday, set this to 2, and so on. By default, this
1113 is determined based on the locale.
1117 Set some handy CSS class attributes on elements, enabled by default.
1118 Currently the classes are:
1120 hcm-table Set on the E<lt>tableE<gt> tag of the calendar
1121 hcm-day-head Set on the day-of-week E<lt>trE<gt> or E<lt>tdE<gt> tags
1122 hcm-year-head Set on the E<lt>tdE<gt> tag for the year
1123 hcm-month-head Set on the E<lt>tdE<gt> tag for the month
1124 hcm-week-head Set on the E<lt>tdE<gt> tags for the week-of-year
1128 Sets some additional CSS class attributes on elements, disabled by
1129 default. The notion of 'today' is taken either from the system clock
1130 (default) or from the 'today' parameter as provided to new(). Currently
1133 hcm-today Set on the E<lt>tdE<gt> tag for today, if present
1134 hcm-past Set on the E<lt>tdE<gt> tags for prior days, if present
1135 hcm-future Set on the E<lt>tdE<gt> tags for subsequent days, if present
1139 Specify the value for 'today' if different from the local time as
1140 reported by the system clock (the default). If specified as two or less
1141 digits, it is assumed to be one of the days of the month in the current
1142 calendar. If more than two digits, it is assumed to be a epoch time in
1143 seconds. Otherwise it must be given as a string of the form 'YYYY-mm-
1144 dd'. Note that the default value as determined by the system clock uses
1145 localtime rather than gmtime.
1149 This option is ignored for dates that do not exceed the range of the built-
1150 in perl time functions. For dates that B<do> exceed these ranges, this
1151 option specifies the default calculation method. When set, if the 'ncal'
1152 or 'cal' command is available on your system, that will be used rather
1153 than the Date::Calc or Date::Manip modules. This can be an issue since
1154 the date modules blindly extrapolate the Gregorian calendar, whereas
1155 ncal/cal will revert to the Julian calendar during September 1752. If
1156 either ncal or cal are not available on your system, this attribute is
1157 meaningless. Defaults to 1.
1163 =head2 Item Query Methods
1165 The following methods return lists of item *symbols* (28, 29, 'Thu',
1166 ...) that are related in some way to the provided list of items. The
1167 returned symbols may then be used as arguments to the glob methods
1168 detailed further below.
1172 =item row_items(item1, [item2, ...])
1174 Returns all item symbols in rows shared by the provided item symbols.
1176 =item col_items(item1, [item2, ...])
1178 Returns all item symbols in columns shared by the provided item symbols.
1180 =item daycol_items(col_item1, [col_item2, ...])
1182 Same as col_items(), but the returned item symbols are limited to those
1183 that are not header items (month, year, day-of-week).
1185 =item row_of(item1, [item2, ...])
1187 Returns the row indices of rows containing the provided item symbols.
1189 =item col_of(item1, [item2, ...])
1191 Returns the column indices of columns containing the provided
1196 Returns the day number (symbol) of the last day of the month.
1200 Returns the column index for the first day of the month.
1204 Returns a list of all days of the month as numbers.
1208 Returns a list of week-of-year numbers for this month.
1212 Returns a list of all day headers (Su..Sa)
1216 Returns a list of all headers (month, year, dayheaders)
1220 Returns a list of all item symbols (day number, header values) in
1225 Returns the index of the last column of the calendar (note that this
1226 could be the week-of-year column if head_week is enabled).
1228 =item last_day_col()
1230 Returns the index of the last column of the calendar containing days of
1231 the month (same as last_col() unless week-of-year is enabled).
1233 =item first_week_row()
1235 Returns the index of the first row of the calendar containing day items
1236 (ie, the first week).
1240 Returns the index of the last row of the calendar.
1244 Returns the day of month for 'today', if present in the current
1249 Returns a list of days prior to 'today'. If 'today' is in a future
1250 month, all days are returned. If 'today' is in a past month, no days
1255 Returns a list of days after 'today'. If 'today' is in a past
1256 month, all days are returned. If 'today' is in a future month, no
1263 Glob methods return references that are functionally equivalent to an
1264 individual calendar cell. Mostly, they provide item based analogues to
1265 the glob methods provided in HTML::ElementTable. In methods dealing with
1266 rows, columns, and boxes, the globs include empty calendar cells (which
1267 would otherwise need to be accessed through native HTML::ElementTable
1268 methods). The row and column numbers returned by the item methods above
1269 are compatible with the grid based methods in HTML::ElementTable.
1271 For details on how these globs work, check out L<HTML::ElementTable> and
1272 L<HTML::ElementGlob>.
1276 =item item(item1, [item2, ...])
1278 Returns all cells containing the provided item symbols.
1280 =item item_row(item1, [item2, ...])
1282 Returns all cells in all rows occupied by the provided item symbols.
1284 =item item_day_row(item1, [item2, ...])
1286 Same as item_row() except excludes week-of-year cells, if present.
1288 =item item_col(item1, [item2, ...])
1290 Returns all cells in all columns occupied by the provided item symbols.
1292 =item item_daycol(item1, [item2, ...])
1294 Same as item_col() except limits the cells to non header cells.
1296 =item item_week_nums()
1298 Returns all week-of-year cells, if present.
1300 =item item_box(item1a, item1b, [item2a, item2b, ...])
1302 Returns all cells in the boxes defined by the item pairs provided.
1306 Returns all header cells.
1310 Returns all non header cells, including empty cells.
1314 Returns all cells in the calendar, including empty cells.
1318 =head2 Transformation Methods
1320 The following methods provide ways of translating between various item
1321 symbols, coordinates, and other representations.
1325 =item coords_of(item)
1327 Returns the row and column coordinates of the provided item symbol, for
1328 use with the grid based methods in HTML::ElementTable.
1330 =item item_at(row,column)
1332 Returns the item symbol of the item at the provided coordinates, for use
1333 with the item based methods of HTML::CalendarMonth.
1335 =item monthname(monthnum)
1337 Returns the name (item symbol) of the month number provided, where
1338 I<monthnum> can be 1..12.
1340 =item monthnum(monthname)
1342 Returns the number (1..12) of the month name provided. Only a minimal
1343 case-insensitive match on the month name is necessary; the proper item
1344 symbol for the month will be determined from this match.
1346 =item dayname(daynum)
1348 Returns the name (item symbol) of the day of week header for a number of
1349 a day of the week, where I<daynum> is 1..7.
1351 =item daynum(dayname)
1353 Returns the number of the day of the week given the symbolic name for
1358 Returns the number in seconds since the epoch for a given day. The day
1359 must be present in the current calendar.
1363 =head2 Other Methods
1369 Returns a simple style sheet as a string that can be used in an HTML
1370 document in conjunction with the classes assigned to elements when css
1381 Date::Calc, DateTime, or Date::Manip (only if you want week-of-
1382 year numbering or non-contemporary dates on a system without the
1387 Matthew P. Sisk, E<lt>F<sisk@mojotoad.com>E<gt>
1391 Copyright (c) 1998-2015 Matthew P. Sisk. All rights reserved. All wrongs
1392 revenged. This program is free software; you can redistribute it and/or
1393 modify it under the same terms as Perl itself.
1397 A useful page of examples can be found at
1398 http://www.mojotoad.com/sisk/projects/HTML-CalendarMonth.
1400 For information on iso639 standards for abbreviations for language
1401 names, see http://www.loc.gov/standards/iso639-2/englangn.html
1403 HTML::ElementTable(3), HTML::Element(3), perl(1)
1405 =for Pod::Coverage col_offset row_offset item_alias item_aliased last_week_row