/ 
HTML-CalendarMonth-1.03
River stage one • 1 direct dependent • 1 total dependent
/ HTML::CalendarMonth

NAME

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

SYNOPSIS

require HTML::CalendarMonth;
use     HTML::AsSubs;
$c = new HTML::CalendarMonth ( month => 3, year => 69 );
$c->item($c->year,$c->month)->attr(bgcolor => 'wheat');
$c->item($c->year,$c->month)->wrap_content(font({size => '+2'}));
print $c->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, with methods added to easily manipulate the appearance of the HTML table containing the calendar. In addition to the row and column cell based methods provided in HTML::ElementTable, there are analogous methods based on items, or the symbols contained in the calendar cells. For instance, $c->item(15) returns the cell containing the 15th, and $c->item($c->year()) returns the cell containing the year. Groups of item cells can be manipulated as if they were single elements. For example, $c->daycol('Su') would affect all days in the same column as the 'Su' header.

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.

PUBLIC METHODS

All arguments appearing in [brackets] are optional.

Constructor
new([attr1 => val1, attr2 => val2, ...]) HTML::CalendarMonth;

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.

Special Attributes for HTML::CalendarMonth

month      1-12, or Jan-Dec.  Default current.
year       Four digit representation.  Default current.
head_m     0 or 1.  Mode for month header display. Default 1.
head_y     0 or 1.  Mode for year header display. Default 1.
head_dow   0 or 1.  Mode for day-of-week header display. Default 1.
head_week  0 or 1.  Mode for week-of-year header display. Default 0.
week_begin 1..7. Specify first day of the week.  Days of the
           week  are numbered 1..7 
row_offset Row offset within the table containing the calendar.
col_offset Column offset within the table containing the calendar.
historic   0 or 1.  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 Date::Calc. This is and issue
           since Date::Calc blindly extrapolates the Gregorian
           calendar, whereas 'cal' takes some of these quirks into
           account.  If 'cal' is not available on your system,
           this attribute is meaningless. Default 1.

See HTML::ElementTable(3) for the special attributes available to that class.

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 items 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(row1, [row2, ...])

Returns all items in rows shared by the provided items.

col_items(col1, [col2, ...])

Returns all items in columns shared by the provided items.

daycol_items(col1, [col2, ...])

Same as col_items(), but the returned items 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 items.

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

Returns the column numbers of columns containing the provided items.

lastday()

Returns 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 items 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.

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.

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.

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 items.

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

Returns all cells in all rows occupied by the provided items.

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

Returns all cells in all columns occupied by the provided items.

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 symbolic values, coordinates, and representations.

coords_of(item)

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

item_at(row,column)

Returns the symbol of the item at the provided coordinates, for use with the item based methods of HTML::CalendarMonth.

monthname(monthnum)

Returns the name 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.

dayname(daynum)

Returns the name 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". Well, if you are using a default calendar, 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 is always 2, even if you aren't displaying month, year, or day headers. The third friday of every month then becomes $c->cell(2,5). Likewise, the "nth dayname/week of the month" can always be mapped to table coordinates.

This sort of mapping is obviously affected in our example 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, 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, assuming your week begins with Sunday.

REQUIRES

HTML::ElementTable

OPTIONAL

Date::Calc (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-2000 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.

ACKNOWLEDGEMENTS

Thanks to William R. Ward for some conceptual nudging. Thanks to Jarkko Hietaniemi for some suggestions on global calendar customs.

SEE ALSO

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