NAME

HTML::CalendarMonth - Perl extension for generating and manipulating HTML calendar months

SYNOPSIS

use HTML::CalendarMonth;
use HTML::AsSubs;

# Using HTML::AsSubs
$c = HTML::CalendarMonth->new( month => 3, year => 69 );
$c->item($c->year, $c->month)->attr(bgcolor => 'wheat');
$c->item($c->year, $c->month)->wrap_content(font({size => '+2'}));
$c->item(12, 16, 28)->wrap_content(strong());
print $c->as_HTML;

# Using regular HTML::Element creation
$c2 = HTML::CalendarMonth->new( month => 8, year => 79 );
$c2->item($c2->year, $c2->month)->attr(bgcolor => 'wheat');
$f = HTML::Element->new('font', size => '+2');
$c2->item($c2->year, $c2->month)->wrap_content($f);
$c2->item_daycol('Su', 'Sa')->attr(bgcolor => 'cyan');
print $c2->as_HTML;

# Full locale support via DateTime::Locale
$c3 HTML::CalendarMonth->new( month => 8, year => 79, locale => 'fr' );
print $c3->as_HTML

DESCRIPTION

HTML::CalendarMonth is a subclass of HTML::ElementTable. See HTML::ElementTable(3) for how that class works, for it affects this module on many levels. Like HTML::ElementTable, HTML::CalendarMonth behaves as if it were an HTML::ElementSuper, which is a regular HTML::Element with methods added to easily manipulate the appearance of the HTML table containing the calendar.

The primary interaction with HTML::CalendarMonth is through items. An item is merely a symbol 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->item(14). Similarly, the element representing the header for Monday would be returned by $c->item('Mo'). If the year happened to by 1984, then $c->item(1984) would return the cell representing the year. Since years and particular months change frequently, it is probably more useful to take advantage of the month() and year() methods, which return the respective item symbol for the current calendar. In the prior example, using 1984, the following is equivalent: $c->item($c- >year()).

Multiple cells of the calendar can be manipulated as if they were a single element. For instance, $c->item(15)->attr(bgcolor => 'cyan') would alter the background color of the cell representing the 15th. By the same token, $c->item(15, 16, 17, 23)->attr(bgcolor => 'cyan') would do the same thing for all cells containing the item symbols passed to the item() method.

The calendar structure is still nothing more than a table structure; the same table structure provided by the HTML::ElementTable class. In addition to the item based access methods above, calendar cells can still be accessed using row and column grid coordinates using the 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 aliasing so that you can express any element in any language HTML can handle.

Dates that are beyond the range of the built-in time functions of perl are handled either by the 'cal' command, Date::Calc, or Date::Manip. The presence of any one of these utilities and modules will suffice for these far flung date calculations. If you want to use week-of-year numbering, then either one of the date modules is required.

Full locale support is offered via DateTime::Locale. For a full list of supported locale id's, look at HTML::CalendarMonth::Locale->locales() or DateTime::Locale->ids().

METHODS

All arguments appearing in [brackets] are optional, and do not represent anonymous array references.

Constructor

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 <table> tag. See HTML::ElementTable if you are interested in attributes that can be passed along to that class.

Special Attributes for HTML::CalendarMonth:

month

1-12, or Jan-Dec. Defaults to current month.

year

Four digit representation. Defaults to current year.

head_m

Specifies whether to display the month header. Default 1.

head_y

Specifies whether to display the year header. Default 1.

head_dow

Specifies whether to display days of the week header. Default 1.

locale

Specifies a locale in which to render the calendar. Default is 'en_US'. See HTML::CalendarMonth::Locale for more information. If for some reason you prefer to use different labels than those provided by locale, see the alias attribute below.

full_days

Specifies whether or not to use full day names or their abbreviated names. Default is 0, use abbreviated names.

full_months

Specifies whether or not to use full month names or their abbriviated names. Default is 1, use full names.

alias

Takes a hash reference mapping labels provided by locale to any custom label you prefer. Lookups, such as day('Sun'), will still use the locale string, but when the calendar is rendered the aliased value will appear.

head_week

Specifies whether to display the week-of-year numbering. Default 0.

week_begin

Specify first day of the week, which can be 1..7, starting with Sunday. Defaults to 1, or Sunday. In order to specify Monday, set this to 2, and so on.

row_offset

Specifies the offset of the first calendar row within the table containing the calendar. This is 0 by default, making the first row of the table the same as the first row of the calendar.

col_offset

Specifies the offset of the first calendar column within the table containing the calendar. This is 0 by default, making the first column of the table the same as the first row of the calendar.

historic

This option is ignored for dates that do not exceed the range of the built- in perl time functions. For dates that do exceed these ranges, this option specifies the default calculation method. When set, if the 'cal' utility 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 'cal' takes some of these quirks into account. If 'cal' is not available on your system, this attribute is meaningless. Defaults to 1.

Item Query Methods

The following methods return lists of item symbols 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. When these methods deal with 'rows' and 'columns', they are only concerned with the cells in the calendar -- not the cells that might be present in the surrounding table if you have extended it. If you have not set row or column offsets, or extended the span of the containing table, then these rows and columns are functionally equivalent to the table rows and columns.

row_items(item1, [item2, ...])

Returns all item symbols in rows shared by the provided item symbols.

col_items(item1, [item2, ...])

Returns all item symbols in columns shared by the provided item symbols.

daycol_items(col_item1, [col_item2, ...])

Same as col_items(), but the returned item symbols are limited to those that are not header items (month, year, day-of-week).

row_of(item1, [item2, ...])

Returns the row numbers of rows containing the provided item symbols.

col_of(item1, [item2, ...])

Returns the column numbers of columns containing the provided item symbols.

lastday()

Returns the number of the last day of the month.

dow1st()

Returns the column number for the first day of the month.

days()

Returns a list of all days of the month.

dayheaders()

Returns a list of all day headers (Su..Sa)

headers()

Returns a list of all headers (month, year, dayheaders)

items()

Returns a list of all item symbols in the calendar.

first_col()

Returns the number of the first column of the calendar. This could be different from that of the surrounding table if the table was extended, but otherwise should be identical.

last_col()

Returns the number of the last column of the calendar. This could be different from that of the surrounding table if the table was extended, but should otherwise be identical.

first_row()

Returns the number of the first row of the calendar. This could be different from that of the surrounding table if offsets were made.

first_week_row()

Returns the number of the first row of the calendar containing day items (ie, the first week). This could vary depending on table offsets and header modes.

last_row()

Returns the number of the last row of the calendar. This could be different from that of the surrounding table if the table was extended, but should otherwise be identical.

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 HTML::ElementTable and HTML::ElementGlob.

item(item1, [item2, ...])

Returns all cells containing the provided item symbols.

item_row(item1, [item2, ...])

Returns all cells in all rows occupied by the provided item symbols.

item_col(item1, [item2, ...])

Returns all cells in all columns occupied by the provided item symbols.

item_daycol(item1, [item2, ...])

Same as item_col(), except limits the cells to non header cells.

item_box(item1a, item1b, [item2a, item2b, ...])

Returns all cells in the boxes defined by the item pairs provided.

allheaders()

Returns all header cells.

alldays()

Returns all non header cells, including empty cells.

all()

Returns all cells in the calendar, including empty cells.

Transformation Methods

The following methods provide ways of translating between various item symbols, coordinates, and other representations.

coords_of(item)

Returns the row and column of the provided item symbol, for use with the grid based methods in HTML::ElementTable.

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.

monthname(monthnum)

Returns the name (item symbol) of the month number provided, where monthnum can be 1..12.

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.

dayname(daynum)

Returns the name (item symbol) of the day of week header for a number of a day of the week, where daynum is 1..7.

daynum(dayname)

Returns the number of the day of the week given the symbolic name for that day (Su..Sa).

daytime(day)

Returns the number in seconds since the epoch for a given day. The day must be present in the current calendar.

Notes On Dates And Spatial Relationships

One of the nice things about having a calendar represented as a table accessible with grid coordinates is that some of the trickier date calculations become trivial. You can use packages such as Date::Manip or Date::Calc for these sort of things, but the algorithms are often derived from a common human activity: looking at a calendar on a wall. Say, for instance, that you are interested in "the third Friday of every month". If you are using a calendar with Sunday as the first day of the week, then Fridays will always be in column 5, starting from 0. Likewise, due to the fact that supressed headers are merely masked in the actual table, the first row with dates in a calendar structure will always be 2, even if the month, year, or day headers are disabled. The third friday of every month therefore becomes $c->cell(2,5), regardless of the particular month. Likewise, the "nth dayname/week of the month" can always be mapped to table coordinates.

The particulars of this grid mapping are affected if you have redefined what the first day of the week is, or if you have tweaked the table beyond the bounds of the calendar itself. There are methods that can help under these circumstances, though. For instance, in our example where we are interested in the 3rd Friday of the month, the row number is accessed with $c->first_week_row + 2, whereas the column number could be derived with $c->last_col - 1.

REQUIRES

HTML::ElementTable

OPTIONAL

Date::Calc or Date::Manip (only if you want week-of-year numbering or non-contemporary dates on a system without the cal command)

AUTHOR

Matthew P. Sisk, <sisk@mojotoad.com>

COPYRIGHT

Copyright (c) 1998-2008 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.

SEE ALSO

A useful page of examples can be found at http://www.mojotoad.com/sisk/projects/HTML-CalendarMonth.

For information on iso639 standards for abbreviations for language names, see http://www.loc.gov/standards/iso639-2/englangn.html

HTML::ElementTable(3), HTML::Element(3), perl(1)

cpanm HTML::CalendarMonth

perl -MCPAN -e shell
install HTML::CalendarMonth