The Epoch Object Reference

The Epoch Object is the main calendar class that forms the core of the Epoch DHTML JavaScript Calendar. It comprises all the calendar properties that you would access from your own JavaScript code (i.e. in a page that contains Epoch). If you want to customize Epoch, this is the place to start.

Constructor

This function runs when a new instance of Epoch is created (i.e. mycalendar = new Epoch(...)). It initializes the internal calendar variables and initializes the calendar in the DOM so it may be displayed to the user.

Arguments

  • string name
  • string {'flat', 'popup'} mode
  • HTMLElement targetelement
  • bool multiselect

Return Values

(none)

Usage

This function runs whenever a new instance of Epoch is created. The name string is used to prepend all id attributes of the calendar in the DOM — each calendar should have a unique name. multiselect determines whether the user can select one or multiple dates simultaneously — it defaults to false.

AJAX developers can leave targetelement blank if the calendar will be assigned to an element that is created after the page loads. In the meantime, the calendar will be appended to document.body until setTarget() is called.

Public Properties

The most commonly-used properties. These can be accessed in your JavaScript code like any other object's properties, i.e. mycalendar.name='abcd'.

state

int {0, 1, 2} Epoch::state

The draw state of the calendar, can be 0 (initializing), 1 (redrawing), or 2 (ready).

name

string Epoch::name

The base name of the character – used in the DOM to prepend all calendar id attributes. Does not have to be the same as the JavaScript variable name for the calendar, but is recommended.

curDate

Date Epoch::curDate

The date to display as the current date in the calendar—defaults to the current date. Note: the current date is not highlighted by default in Epoch. You must set the CSS declaration for table.calcells td.curdate in Epoch_styles.css yourself.

mode

string {'popup', 'flat'} Epoch::mode

Whether the calendar will pop up when a control is entered ('popup'), or if displayed inline with the page's HTML ('flat'). mode should NOT be set after calendar initialiation.

selectMultiple

bool Epoch::selectMultiple

Whether the user is allowed to highlight multiple dates in the calendar. selectMultiple should not be used in popup/datepicker mode – multi-select is only available in flat mode.

dates

Array(Date) Epoch::dates

Contains all dates of importance in the calendar, including selected dates, holidays, and non-selectable dates.

Usage

We strongly recommend you do not set the dates array elements manually. Use the addDates(), selectDates(), or removeDates() methods instead.

selectedDates

Array(Date) Epoch::selectedDates

Points to all selected dates in the calendar's dates array.

Usage

We strongly recommend you do not set the selectedDates array elements manually. Use the addDates(), selectDates(), or removeDates() methods instead. Call the private method updateSelectedDates() to refresh the selectedDates array.

calendar

HTMLTableElement Epoch::calendar

The master table that contains all of the HTML elements belonging to Epoch.

calHeading

HTMLDivElement Epoch::calHeading

Contains the top portion of the calendar, including the year and month <SELECT> elements.

calCells

HTMLTableElement Epoch::calCells

Table containing all dates and week headings(in the TBODY), as well as the day headings (in the THEAD)

rows

Array(bool) Epoch::rows

Array of boolean values indicating whether an entire week (row) is selected/deselected for the current month. Currently these values are not saved when changing months; instead all values are reset to false.

cols

Array(bool) Epoch::cols

Array of boolean values indicating whether all instances of a certain day of week (column) are selected/deselected for the current month. Currently these values are not saved when changing months; instead all values are reset to false.

cells

Array(CalCell) Epoch::cells

Array containing all of the calendar's CalCell objects, i.e. each table cell in calCells has an attached CalCell object that is pointed to in cells.

monthSelect

HTMLSelectElement Epoch::monthSelect

Pointer to the month list <SELECT> element.

yearSelect

HTMLSelectElement Epoch::yearSelect

Pointer to the year list <SELECT> element.

mousein

bool Epoch::mousein

Indicates whether the user's mouse cursor lies within the calendar's calendar table, i.e. is inside Epoch.

Public Methods

The most commonly-used methods. These can be accessed in your JavaScript code like any other object's methods, i.e. mycalendar.setTarget(element).

dateInArray(arr,searchVal,startIndex)

Find a date in the given array, returning its index if found, -1 if not.

Arguments

  • Array arr
  • Date searchval
  • int startIndex

Return Values

int

setTarget(HTMLInputElement targetelement, bool focus)

Changes the target element of this calendar to another input. Can be used in either flat or popup mode.

Arguments

  • HTMLInputElement targetelement
  • bool focus

Return Values

(none)

Usage

setTarget() can be called at any time to change the location of the calendar within the page. This can save memory and increase speed, as opposed to initializing a new calendar. For example, in popup mode, setTarget() can be used to assign a single calendar to multiple <input> boxes. The calendar will seamlessly pop up when a user focuses on any of the boxes, while remembering the date selected in each box if the user goes back to a box they already filled in. This is particularly useful if the page you're developing allows the user to add new calendar-containing elements dynamically.

setTarget() can also be used in flat mode. For aesthetic reasons you will probably not want to do this, though AJAX developers will find this feature useful if they initialize the calendar without a target element—see the entry for the Epoch Constructor.

nextMonth()

Go to the next month - if the current month is December, go to January of the next year instead. Checks if the next month is within the minimum and maximum allowed dates allowed to be accessed by the user, and if so, returns true if the month will be incremented.

Arguments

(none)

Return Values

bool

prevMonth()

Go to the previous month - if the current month is January, go to December of the previous year. Checks if the previous month is within the minimum and maximum allowed dates allowed to be accessed by the user, and if so, returns true if the month will be decremented.

Arguments

(none)

Return Values

bool

goToMonth(year,month)

Sets the calendar to display the requested month/year, returning true if the requested month/year is within the minimum and maximum allowed dates.

Arguments

  • int year
  • int month

Return Values

bool

updatePos(target)

Moves the calendar's position in the page to the target element's position (popup mode only).

Arguments

  • HTMLElement target

Return Values

show()

Displays the calendar by setting the CSS:display property for the calendar table element to 'block'. Ideally should be set to 'table', but Internet Explorer 6.0 and below do not support this.

Arguments

(none)

Return Values

(none)

hide()

Hides the calendar by setting the CSS:display property for the calendar table element to 'none'.

Arguments

(none)

Return Values

(none)

toggle()

Toggles (shows/hides) the calendar depending on the current display state of the calendar element.

Arguments

(none)

Return Values

(none)

addDates(dates,redraw)

Adds the input array dates to the calendar's dates array, removing duplicate dates, then redraws the calendar if redraw is true.

Arguments

  • Array(Date) dates
  • bool redraw

Return Values

(none)

removeDates(dates,redraw)

Removes the dates in the input array dates from the calendar's dates array, then redraws the calendar if redraw is true.

Arguments

  • Array(Date) dates
  • bool redraw

Return Values

(none)

selectDates(inpdates,selectVal,redraw,removeothers)

Selects or Deselects an array of dates.

Arguments

  • Array(Date) inpdates
  • bool selectVal
  • bool redraw
  • bool removeothers

Return Values

(none)

sendForm(formid,inputname)

Adds the dates in the calendar's dates array as hidden inputs in a form identified by id formid. inputname is the name of each hidden element.

Arguments

  • string formid
  • string inputname

Return Values

(none)

Usage

sendForm() is a quick and easy way to send the calendar's selected dates to the server via standard form submission. It uses the DOM to add hidden <INPUT> elements to the form when the user clicks the sbumit button. The calendar does not need to be inside the form, as it uses the id provided in formid to get a handle on the form you want to use.

<form id="myform" onsubmit="mycalendar.sendForm('myform','calendardates);">

resetSelections(retMonth)

Reset the calender. =Erases the dates array and resets the calendar's selection variables to defaults. If retMonth is true, the calendar will return to the initial default month/year.

Arguments

  • bool retMonth

Return Values

(none)

reDraw(index)

Reapplies all the CSS classes for the calendar cells – usually called after changing their state. If index is specified, it will redraw that cell only.

Arguments

  • int index

Return Values

(none)

getCellIndex(date)

Returns the index of the cell whose date value matches "date", or -1 if not found

Arguments

  • Date date

Return Values

int

Private Properties

These variables can only be accessed and set from within the Epoch class – trying to do this from your page's JavaScript code will cause an error. Your only need to modify these if you're modifying the internal workings of Epoch.

self

Epoch Epoch::self

A workaround due to JavaScript's varying definitions of this in variable scopes (see explanation in below paragraph). Basically, using self is exactly the same as using this – it always points to the main Epoch class prototype and is equivalent to using this in other object-oriented languages such as C++ and PHP. For consistency, we have replaced all references to this with self.

In explicit function declarations (function myfunc() {....}), this refers to the current function prototype—this is fine until you nest functions (as we do to in Epoch Prime to achieve private methods. Then this refers to the nested function's prototype – meaning you cannot easily access the parent function's prototype. Hence self was born.

QuirksMode has a good overview of the JavaScript this keyword here.

Private Methods

These functions can only be accessed and set from within the Epoch class – trying to do this from your page's JavaScript code will cause an error. Your only need to modify these if you're modifying the internal workings of Epoch.

calConfig()

Usage:

void calConfig()

Declares and initializes the calendar variables. All the variables here can be safely changed by the developer

Arguments

(none)

Return Values

(none)

setLang()

All language settings for Epoch are made in this function. Check Date.dateFormat() for the Date object's language settings.

Arguments

(none)

Return Values

(none)

setDays()

Initializes the standard Gregorian Calendar parameters

Arguments

(none)

Return Values

(none)

createCalendar()

Creates the full DOM implementation of the calendar

Arguments

(none)

Return Values

(none)

createMainHeading()

Creates the primary calendar heading, with months & years

Arguments

(none)

Return Values

HTMLDivElement

createFooter()

Creates the footer of the calendar – goes under the calendar cells

Arguments

(none)

Return Values

HTMLDivElement

createDayHeading()

Creates the heading containing the day names

Arguments

(none)

Return Values

HTMLTheadElement

createCalCells()

Creates the table containing the calendar day cells

Arguments

(none)

Return Values

HTMLTbodyElement

setMode(targetelement)

Runs all the operations necessary to change the mode of the calendar

Arguments

  • HTMLInputElement targetelement

Return Values

(none)

deleteCells()

Removes the calendar table cells from the DOM (does not delete the cell objects associated with them)

Arguments

(none)

Return Values

(none)

setClass(element,className)

Sets the CSS class of the element, W3C & IE

Arguments

  • HTMLElement element
  • string className

Return Values

(none)

setCellProperties(cellindex)

Updates a cell's data, including CSS class and selection properties

Arguments

  • int cellindex

Return Values

(none)

updateSelectedDates()

Updates the selectedDates pointer array to point to all selected dates in dates.

Arguments

(none)

Return Values

(none)

cal_onmouseover()

Updates the mousein variable to true. This function is pointed to by the Epoch::calendar.onmouseover() event handler.

Arguments

(none)

Return Values

(none)

cal_onmouseout()

Updates the mousein variable to false. This function is pointed to by the Epoch::calendar.onmouseout() event handler.

Arguments

(none)

Return Values

(none)