Class xbCalendar — a JavaScript object for creating dynamic calendar widgets using the W3C DOM. Contributed by Jeremy Hoppe.
extends Class xbObject
class xbCalendar : xbObject
{
public:
xbCalendar(String id,
Date dateObj,
String classprefix,
String dayNameFormat,
Number firstDayOfWeek,
Window windowRef);
// properties
HTMLElement caption;
Array cells;
String classprefix;
Date date;
String dayNameFormat;
Number firstDayOfWeek;
Array headers;
String id;
Date maxDate;
Date minDate;
String name;
HTMLElement table;
Boolean showStatusInfo;
Boolean useTitles;
Window window;
// methods
Date dateFromIndex(Number index);
void destroy();
Date getDate();
Number getMonthLength(Number month, Number year);
HTMLElement getNode();
Number indexFromDate(Date dateObj);
void nextMonth();
void nextYear();
void prevMonth();
void prevYear();
void refresh(Boolean doRepaintOnly);
void setBorder(Number i);
void setCellPadding(Number i);
void setCellSpacing(Number i);
void setDate(Date dateObj);
// events
Boolean ondatechange(Date dateObj);
// static Class properties
Array dayNames;
Array monthNames;
// internal use only
Number _name;
String SPACE_CHAR;
protected:
// methods
String _getCaptionFormat(Number month, Number year);
String _getDateFormat(Date dateObj);
private:
// internal state properties
Boolean _needsLinkRefocus;
Number _nextIndex;
Number _prevIndex;
Number _selectedIndex;
}
xbCalendar is a JavaScript object which implements a flexible calendar widget for browsers which support the W3C DOM and JavaScript 1.3+ (ECMAScript Edition 3), including Gecko-based browsers (such as Netscape 6.x, Netscape 7.x, CompuServe 7.0) and Internet Explorer 5.5+ for Windows. Support for Internet Explorer 5+ for the Macintosh has yet to be determined.
Built using the W3C DOM, the calendar widget can be inserted into any block-level element in the body of a document, without having to be contained in an absolute-positioned <div> container.
Script Location/Invocation. Whenever a new instance of xbCalendar is created, it immediately begins constructing the HTML objects necessary for the display of the calendar. Since this may take a moment or two, it is best to defer creating new instances of xbCalendar until after the document has loaded and the window.onload event has been fired.
Limiting the dates an xbCalendar widget can display. You can easily define a 'range' of dates that an xbCalendar widget can display by setting it's maxDate and minDate properties. Any dates which fall outside of the specified range will not be displayed by xbCalendar, and users will not be allowed to navigate to those dates. See the examples section for an example of how to define 'date ranges'.
Localization. xbCalendar can easily be localized for other languages. See the examples section for a example of how to localize xbCalendar.
In order to provide the greatest level of control over the look and feel of a calendar, the display of xbCalendar widgets are controlled through the use of several CSS classes. These class names can be customized by specifying the classprefix argument when creating an instance of xbCalendar. If not otherwise specified, classprefix defaults to 'cal-'.
Below is a reference list showing which CSS class selectors style which elements of xbCalendar.
Name of CSS class for the calendar table. HTML tag: TABLE
Name of CSS class for the calendar's caption. HTML tag: CAPTION
Name of CSS class for the day-name headers. HTML tag: TH
Name of CSS class for cells that belong to the current month, but are not currently selected. HTML tag: TD
Name of CSS class for the currently selected cell. HTML tag: TD
Name of CSS class for cells that belong to the previous or next months. HTML tag: TD
Name of CSS class for links inside cells that belong to the current month, but are not currently selected. HTML tag: A
Name of CSS class for the link inside the currently selected cell. HTML tag: A
Name of CSS class for links that are in cells that belong to the previous or next month. HTML tag: A
Example 1. Example 01
This example illustrates the basics of a working xbCalendar widget using minimal CSS styling.
Example 3. Example 03
This example expands on Example 02 by displaying all calendar links as block-level elements and creating rollover effects using the CSS :hover pseudo-selector.
Example 4. Example 04
This example demonstrates how to use xbCalendar's ondatechange event to filter/restrict the dates a user may choose from an xbCalendar widget.
Example 5. Example 05
This example demonstrates how to localize the strings and date-formatting used by xbCalendar.
Example 6. Example 06
This example demonstrates how to specify a range of dates (a 'date range') that an xbCalendar widget can display.
readonly HTMLElement - a reference to the calendar's caption.
readonly Array - a 41-slot array that holds instances of xbCalendarCellNodeMap, a private class for creating and managing calendar cells and their contents.
readonly String - the prefix of CSS classnames to be used to style xbCalendar. If not set elsewhere, this property will default to 'cal-'.
readonly Date - a Date object describing the calendar's currently selected date.
readonly String - specifies how day-names should be displayed in the calendar. See the constructor reference for accepted values and their meanings.
Number - specifies the day of the week that will be displayed as the first-day-of-the-week in the xbCalendar widget. See the constructor reference for accepted values and their meanings.
readonly Array - a 7-slot array that holds references to the calendar's 7 day-name headers.
readonly String - the value of the ID attribute given to the calendar TABLE tag.
Date - specifies the maximum date that the calendar should display. All dates that fall after this date will not be displayed. If not set elsewhere, this property will default to 31 Dec, 2099 23:59:59.
Date - specifies the minimum date that the calendar should display. All dates that fall before this date will not be displayed. If not set elsewhere, this property will default to 01 Jan, 1970 00:00:00.
readonly String - name of the global variable created during construction which holds a reference to the newly created xbCalendar object. This is used internally to handle events which occur on the links inside the calendar table.
readonly HTMLTableElement - a reference to the table used to display the calendar.
Boolean - specifies whether or not to show contextual information in the browser's status line, such as a formatted date string when the user's mouse hovers over a calendar link. If not set elsewhere, this property defaults to true.
Boolean - specifies whether or not to present additional information regarding a link or other element inside the calendar by setting the TITLE attribute on those links. Most modern browsers present information stored in the TITLE attribute to users in the form of tooltips.
readonly Window - reference to the window where the xbCalendar widget resides. This is used for cross-frame or similar environments where the xbCalendar widget resides in a different window than the xb APIs.
Constructs an instance of xbCalendar.
Arguments: String id - the id to be assigned to the calendar.
Date dateObj - the initial date that the calendar should display. If omitted, this defaults to the current date.
String classprefix - the prefix of CSS classnames to be used to style xbCalendar. By specifying different classprefixes for different xbCalendar widgets on the same page you can customize the appearance of each calendar independently of the others. If omitted, the default value 'cal-' will be used.
String dayNameFormat - specifies how to represent day-names in the calendar. Possible values are: 'short' (one-letter abbreviation), 'medium' (three-letter abbreviation), 'long' (entire day-name). If omitted, the default value 'short' will be used.
Number firstDayOfWeek - specifies which day of the week should appear as the first-day-of-the-week in the xbCalendar widget. Valid values are numbers 0-6, where 0 is Monday, 1 is Tuesday, etc. If omitted, this defaults to 6 (Sunday).
Window windowRef - the window that the xbCalendar widget resides in. If the xbCalendar widget does not live in the same window as the xbCalendar.js and xbObjects.js APIs, the windowRef argument must be specified.
Allows you to query the calendar to determine what date is being displayed at a given cell-index (0-41).
Arguments: Number index - a number in the range of 0-41.
Returns. Date the date currently being displayed at the specified cell-index.
Exceptions
Destroys this instance of xbCalendar.
Returns. Nothing
Returns. Date - a Date object describing the calendar's currently selected date.
Arguments:
Number month - the desired month, represented as a number 0-11.
Number year - the desired year, expressed in 4-digit format.
Returns. Number - the length of the specified month in the given year.
Returns the HTMLElement for this widget that should be inserted into the document tree.
Returns. HTMLElement - this calendar's root HTMLElement to be inserted into the DOM document tree.
Allows you to query the calendar to obtain the cell-index of the table-cell currently displaying the date represented by dateObj.
Arguments: Date dateObj - a Date object.
Returns. Number - the cell-index of the table-cell currently displaying the date represented by dateObj, or -1 if the specified date is not currently being displayed by the calendar.
Instructs the calendar to jump to the next month.
Returns. Nothing
Instructs the calendar to jump to the current month in the next year.
Returns. Nothing
Instructs the calendar to jump to the previous month.
Returns. Nothing
Instructs the calendar to jump to the current month in the previous year.
Returns. Nothing
Refreshes the calendar with the latest date information and repaints the calendar.
Arguments: Boolean doRepaintOnly - if true, repaints only the currently selected and previously selected cells. This argument is usually only specified when this method is called internally, and may be omitted in general use.
Returns. Nothing
Sets the date that the calendar should display.
If the date represented by dateObj is not within the range specified by the minDate and maxDate properties, this method will return without refreshing the calendar.
Arguments: Date dateObj - the date that the calendar should display.
Returns. Nothing
Sets the value of the calendar table's BORDER attribute.
Arguments: Number i - the desired border size, in pixels.
Returns. Nothing
Sets the value of the calendar table's CELLPADDING attribute.
Arguments: Number i - the desired amount of cell-padding, in pixels.
Returns. Nothing
Sets the value of the calendar table's CELLSPACING attribute.
Arguments: Number i - the desired amount of cell-spacing, in pixels.
Returns. Nothing
Formats the string that is to be displayed in the calendar's caption area.
Arguments:
Number month - the month, expressed as a number 0-11.
Number year - the year, expressed in 4-digit format.
Returns. String - the string to be displayed in the calendar's caption.
Used to obtain a String containing general-purpose formatted date information to be used in a variety of ways, such as being shown in the browser's status line, or used as a tooltip for links in the calendar.
Arguments: Date dateObj - the date information to format.
Returns. String - a string containing formatted date information.
Fired when the calendar's currently displayed date is about to change. Event handlers may return false to cancel the change.
Supplied parameters: Date dateObj - the date that is about to be displayed by the calendar.
Event return values:
These properties are used internally by xbCalendar, and should not be modified or relied upon by outside code.
readonly Boolean - true if the calendar has just been refreshed due to the user clicking on a date (a hyperlink) outside of the 'current' month, and the user-focus needs to be moved to the correct link.
readonly Number - the index in the cells array of the cell which contains the first day of the next month.
readonly Number - the index in the cells array of the cell which contains the last day of the previous month (that is, cells 0 through _prevIndex belong to the previous month).
readonly Number - contains the cell-index of the currently selected cell. Used internally for in-month repaints.
readonly Array - a 7-slot array containing the full names of the days-of-the-week, starting with Monday and ending with Sunday.
readonly Array - a 12-slot array containing the full names of the twelve months of the year.
readonly Number - an instance counter used to give each instance of xbCalendar created a unique global identifier by which it can reference itself internally.
readonly String - a string containing the non-breaking space character.