.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::CalendarMonth 3pm"
.TH HTML::CalendarMonth 3pm "2018-11-25" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::CalendarMonth \- Generate and manipulate HTML calendar months
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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 => \*(Aqzu\-ZA\*(Aq
\& );
\& print $c2\->as_HTML;
\&
\& # HTML\-Tree integration
\& my $tree = HTML::TreeBuilder\->parse_file(\*(Aqcal.html\*(Aq);
\& $tree\->find_by_attribute(class => \*(Aqhcm\-calendar\*(Aq)\->replace_with($c);
\& print $tree\->as_HTML;
\&
\& # clean up if you\*(Aqre not done, HTML::Element structures must be
\& # manually destroyed
\& $c\->delete; $c2\->delete;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
HTML::CalendarMonth is a subclass of HTML::ElementTable. See
\&\fBHTML::ElementTable\fR\|(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.
.PP
The primary interaction with HTML::CalendarMonth is through \fIitems\fR
rather than cell coordinates like HTML::ElementTable uses. An \fIitem\fR 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 \f(CW\*(C`$c\->item(14)\*(C'\fR. Similarly, the
element representing the header for Monday would be returned by \f(CW\*(C`$c\-
>item(\*(AqMo\*(Aq)\*(C'\fR. If the year happened to by 2010, then \f(CW\*(C`$c\-
>item(2010)\*(C'\fR would return the cell representing the year. Since
years and particular months change frequently, it is probably more
useful to take advantage of the \f(CW\*(C`month()\*(C'\fR and \f(CW\*(C`year()\*(C'\fR methods, which
return their respective values. The following is therefore the same as
explicitely referencing the year: \f(CW\*(C`$c\->item($c\- >year())\*(C'\fR.
.PP
Multiple cells of the calendar can be manipulated as if they were a
single element. For instance, \f(CW\*(C`$c\->item(15)\->attr(class =>
\&\*(Aqfancyday\*(Aq)\*(C'\fR would alter the class of the cell representing the 15th. By
the same token, \f(CW\*(C`$c\->item(15, 16, 17,
23)\->attr(class => \*(Aqfancyday\*(Aq)\*(C'\fR would do the same thing for all
cells containing the days passed to the \f(CW\*(C`item()\*(C'\fR method.
.PP
Underneath, the calendar is still nothing more than a table structure,
the same as provided by the HTML::ElementTable class. In addition to the
\&\fIitem\fR based access methods above, calendar cells can still be accessed
using row and column grid coordinates using the \f(CW\*(C`cell()\*(C'\fR method
provided by the table class. All coordinate-based methods in the table
class are accessible to the calendar class.
.PP
The module includes support for week-of-the-year numbering, arbitrary
1st day of the week definitions, and locale support.
.PP
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.
.PP
Full locale support is offered via DateTime::Locale. For a full list of
supported locale id's, look at HTML::CalendarMonth::Locale\->\fBlocales()\fR.
.SH "METHODS"
.IX Header "METHODS"
All arguments appearing in [brackets] are optional, and do not represent
anonymous array references.
.SS "Constructor"
.IX Subsection "Constructor"
.IP "\fBnew()\fR" 4
.IX 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
tag. See HTML::ElementTable if
you are interested in attributes that can be passed along to that class.
.Sp
Special Attributes for HTML::CalendarMonth:
.RS 4
.IP "month" 4
.IX Item "month"
1\-12, or Jan-Dec. Defaults to current month.
.IP "year" 4
.IX Item "year"
Four digit representation. Defaults to current year.
.IP "head_m" 4
.IX Item "head_m"
Specifies whether to display the month header. Default 1.
.IP "head_y" 4
.IX Item "head_y"
Specifies whether to display the year header. Default 1.
.IP "head_dow" 4
.IX Item "head_dow"
Specifies whether to display days of the week header. Default 1.
.IP "head_week" 4
.IX Item "head_week"
Specifies whether to display the week-of-year numbering. Default 0.
.IP "locale" 4
.IX 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
HTML::CalendarMonth::Locale for more information. If for some reason
you prefer to use different labels than those provided by \f(CW\*(C`locale\*(C'\fR, see
the \f(CW\*(C`alias\*(C'\fR attribute below. \s-1NOTE:\s0 DateTime::Locale versions 0.92 and
earlier use underscores rather than dashes, e.g. 'en_US'.
.IP "full_days" 4
.IX Item "full_days"
Specifies whether or not to use full day names or their abbreviated
names. Default is 0, use abbreviated names. Use \-1 for 'narrow' mode,
the shortest (not guaranteed to be unique) abbreviations.
.IP "full_months" 4
.IX 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.
.IP "alias" 4
.IX Item "alias"
Takes a hash reference mapping labels provided by \f(CW\*(C`locale\*(C'\fR to any
custom label you prefer. Lookups, such as \f(CW\*(C`day(\*(AqSun\*(Aq)\*(C'\fR, will still use
the locale string, but when the calendar is rendered the aliased value
will appear.
.IP "week_begin" 4
.IX 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.
.IP "enable_css" 4
.IX Item "enable_css"
Set some handy \s-1CSS\s0 class attributes on elements, enabled by default.
Currently the classes are:
.Sp
.Vb 5
\& hcm\-table Set on the EtableE tag of the calendar
\& hcm\-day\-head Set on the day\-of\-week EtrE or EtdE tags
\& hcm\-year\-head Set on the EtdE tag for the year
\& hcm\-month\-head Set on the EtdE tag for the month
\& hcm\-week\-head Set on the EtdE tags for the week\-of\-year
.Ve
.IP "semantic_css" 4
.IX Item "semantic_css"
Sets some additional \s-1CSS\s0 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 \fBnew()\fR. Currently
these classes are:
.Sp
.Vb 3
\& hcm\-today Set on the EtdE tag for today, if present
\& hcm\-past Set on the EtdE tags for prior days, if present
\& hcm\-future Set on the EtdE tags for subsequent days, if present
.Ve
.IP "today" 4
.IX 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.
.IP "historic" 4
.IX Item "historic"
This option is ignored for dates that do not exceed the range of the built\-
in perl time functions. For dates that \fBdo\fR 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.
.RE
.RS 4
.RE
.SS "Item Query Methods"
.IX Subsection "Item Query Methods"
The following methods return lists of item *symbols* (28, 29, 'Thu',
\&...) that are related in some way to the provided list of items. The
returned symbols may then be used as arguments to the glob methods
detailed further below.
.IP "row_items(item1, [item2, ...])" 4
.IX Item "row_items(item1, [item2, ...])"
Returns all item symbols in rows shared by the provided item symbols.
.IP "col_items(item1, [item2, ...])" 4
.IX Item "col_items(item1, [item2, ...])"
Returns all item symbols in columns shared by the provided item symbols.
.IP "daycol_items(col_item1, [col_item2, ...])" 4
.IX Item "daycol_items(col_item1, [col_item2, ...])"
Same as \fBcol_items()\fR, but the returned item symbols are limited to those
that are not header items (month, year, day-of-week).
.IP "row_of(item1, [item2, ...])" 4
.IX Item "row_of(item1, [item2, ...])"
Returns the row indices of rows containing the provided item symbols.
.IP "col_of(item1, [item2, ...])" 4
.IX Item "col_of(item1, [item2, ...])"
Returns the column indices of columns containing the provided
item symbols.
.IP "\fBlastday()\fR" 4
.IX Item "lastday()"
Returns the day number (symbol) of the last day of the month.
.IP "\fBdow1st()\fR" 4
.IX Item "dow1st()"
Returns the column index for the first day of the month.
.IP "\fBdays()\fR" 4
.IX Item "days()"
Returns a list of all days of the month as numbers.
.IP "\fBweek_nums()\fR" 4
.IX Item "week_nums()"
Returns a list of week-of-year numbers for this month.
.IP "\fBdayheaders()\fR" 4
.IX Item "dayheaders()"
Returns a list of all day headers (Su..Sa)
.IP "\fBheaders()\fR" 4
.IX Item "headers()"
Returns a list of all headers (month, year, dayheaders)
.IP "\fBitems()\fR" 4
.IX Item "items()"
Returns a list of all item symbols (day number, header values) in
the calendar.
.IP "\fBlast_col()\fR" 4
.IX 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).
.IP "\fBlast_day_col()\fR" 4
.IX Item "last_day_col()"
Returns the index of the last column of the calendar containing days of
the month (same as \fBlast_col()\fR unless week-of-year is enabled).
.IP "\fBfirst_week_row()\fR" 4
.IX Item "first_week_row()"
Returns the index of the first row of the calendar containing day items
(ie, the first week).
.IP "\fBlast_row()\fR" 4
.IX Item "last_row()"
Returns the index of the last row of the calendar.
.IP "\fBtoday()\fR" 4
.IX Item "today()"
Returns the day of month for 'today', if present in the current
calendar.
.IP "\fBpast_days()\fR" 4
.IX 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.
.IP "\fBfuture_days()\fR" 4
.IX 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.
.SS "Glob Methods"
.IX Subsection "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.
.PP
For details on how these globs work, check out HTML::ElementTable and
HTML::ElementGlob.
.IP "item(item1, [item2, ...])" 4
.IX Item "item(item1, [item2, ...])"
Returns all cells containing the provided item symbols.
.IP "item_row(item1, [item2, ...])" 4
.IX Item "item_row(item1, [item2, ...])"
Returns all cells in all rows occupied by the provided item symbols.
.IP "item_day_row(item1, [item2, ...])" 4
.IX Item "item_day_row(item1, [item2, ...])"
Same as \fBitem_row()\fR except excludes week-of-year cells, if present.
.IP "item_col(item1, [item2, ...])" 4
.IX Item "item_col(item1, [item2, ...])"
Returns all cells in all columns occupied by the provided item symbols.
.IP "item_daycol(item1, [item2, ...])" 4
.IX Item "item_daycol(item1, [item2, ...])"
Same as \fBitem_col()\fR except limits the cells to non header cells.
.IP "\fBitem_week_nums()\fR" 4
.IX Item "item_week_nums()"
Returns all week-of-year cells, if present.
.IP "item_box(item1a, item1b, [item2a, item2b, ...])" 4
.IX Item "item_box(item1a, item1b, [item2a, item2b, ...])"
Returns all cells in the boxes defined by the item pairs provided.
.IP "\fBallheaders()\fR" 4
.IX Item "allheaders()"
Returns all header cells.
.IP "\fBalldays()\fR" 4
.IX Item "alldays()"
Returns all non header cells, including empty cells.
.IP "\fBall()\fR" 4
.IX Item "all()"
Returns all cells in the calendar, including empty cells.
.SS "Transformation Methods"
.IX Subsection "Transformation Methods"
The following methods provide ways of translating between various item
symbols, coordinates, and other representations.
.IP "coords_of(item)" 4
.IX Item "coords_of(item)"
Returns the row and column coordinates of the provided item symbol, for
use with the grid based methods in HTML::ElementTable.
.IP "item_at(row,column)" 4
.IX Item "item_at(row,column)"
Returns the item symbol of the item at the provided coordinates, for use
with the item based methods of HTML::CalendarMonth.
.IP "monthname(monthnum)" 4
.IX Item "monthname(monthnum)"
Returns the name (item symbol) of the month number provided, where
\&\fImonthnum\fR can be 1..12.
.IP "monthnum(monthname)" 4
.IX Item "monthnum(monthname)"
Returns the number (1..12) of the month name provided. Only a minimal
case-insensitive match on the month name is necessary; the proper item
symbol for the month will be determined from this match.
.IP "dayname(daynum)" 4
.IX Item "dayname(daynum)"
Returns the name (item symbol) of the day of week header for a number of
a day of the week, where \fIdaynum\fR is 1..7.
.IP "daynum(dayname)" 4
.IX Item "daynum(dayname)"
Returns the number of the day of the week given the symbolic name for
that day (Su..Sa).
.IP "daytime(day)" 4
.IX Item "daytime(day)"
Returns the number in seconds since the epoch for a given day. The day
must be present in the current calendar.
.SS "Other Methods"
.IX Subsection "Other Methods"
.IP "\fBdefault_css()\fR" 4
.IX Item "default_css()"
Returns a simple style sheet as a string that can be used in an \s-1HTML\s0
document in conjunction with the classes assigned to elements when css
is enabled.
.SH "REQUIRES"
.IX Header "REQUIRES"
HTML::ElementTable
.SH "OPTIONAL"
.IX Header "OPTIONAL"
Date::Calc, DateTime, or Date::Manip (only if you want week\-of\-
year numbering or non-contemporary dates on a system without the
\&\fIcal\fR command)
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthew P. Sisk, <\fIsisk@mojotoad.com\fR>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1998\-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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
A useful page of examples can be found at
http://www.mojotoad.com/sisk/projects/HTML\-CalendarMonth.
.PP
For information on iso639 standards for abbreviations for language
names, see http://www.loc.gov/standards/iso639\-2/englangn.html
.PP
\&\fBHTML::ElementTable\fR\|(3), \fBHTML::Element\fR\|(3), \fBperl\fR\|(1)