Using the `dates` array in Epoch Prime

The dates array forms the core of Epoch Prime, containing all important dates, holidays, and events.

Users familiar with older Epoch versions (1.0.6 and below) may wonder what to do with the selectedDates array. The dates array in Epoch Prime replaces the function of selectedDates. selectedDates, like before, contains all currently selected dates in the calendar. However, it is now secondary to the dates array, and must be updated if you make any changes to dates. If you use Epoch Prime's date handling routines, you won't have to worry about this at all.

Overview

dates is an array contains all dates of importance for Epoch Prime. Dates of importance include any date that is not the default standard, non-selected date. Use dates to specify dates that are holidays, have custom HTML/titles, are not selectable, or are otherwise important to the user.

selectedDates is an array containing all dates that are currently selected in Epoch Prime. It is a simple pointer array; each element is a pointer to a date in the dates array—it is updated automatically whenever a date is selected/deselected.

Because of the complex nature of date handling in Epoch Prime, we strongly recommend you do not add or remove dates from dates or selectedDates using the push(), pop(), or any other array methods. Instead, use Epoch Prime's XML date features, or the addDates(), selectDates(), removeDates(), and resetSelections() methods.

A few additions to the dates stored in `dates`

In order to enable the extra features in Epoch Prime, a few modifications have been made to the dates that reside in the dates array, namely the addition of several extra properties. These are:

canSelect

A boolean (true/false) value – whether this date's calendar cell may be selected.

selected

A boolean (true/false) value – whether this date's calendar cell is currently selected.

type

A string (can be 'normal', or 'holiday') value – if a date is a 'holiday', its calendar cell will have a different color (which you can specify in epoch_styles.css).

title

A string (can be any text) value – contains the HTML title (or tooltip) that displays when the user hovers their mouse cursor over this date's calendar cell. You can use this to give hints or brief information about this date to the user.

href

A string (can be any text) value containing a URL for this date. A cell that has a date with a URL will have a hyperlink over the day of the month—you can choose to make it a traditional link (i.e. when the user clicks on the day number only), or a JavaScript link (user clicks anywhere in the cell). See the setURL() entry in the CalCell Object entry for more details.

cellHTML

A string (can be any text) value – contains any HTML you want to display under the date number in this date's calendar cell. Since by default Epoch's caledar cells are quite small, we recommend you change the default size of the calendar cells by modifying epoch_styles.css.

Adding/Removing Dates Using XML

Using `importXML()` to add Dates

With Epoch Prime you can initialize and update the calendar on both page load and at run-time using XML.

On Page-Load

This is the easiest way to get started with the XML importation.

First, you must insert an XML string somewhere on your page, so that Epoch Prime can access it. The easiest way to do this is to declare a JavaScript variable containing the XML in the page <HEAD> or <BODY>.

<html>
<head>
<title>My Hotel's XML test page</title>
...
...
<script type="text/javascript">
/*Remove ALL line breaks in the XML string below to prevent "unterminated string literal/constant" errors.
The line breaks below are simply to make the example easier to read.*/
var myXML = '<?xml version="1.0" encoding="UTF-8"?>
<importdata>
 <datesadd>
  <date value="2006-01-01"></date>
  <date type="holiday" value="2006-07-04"><![CDATA[<p>July 4th spectacular!</p>]]></date>
  <date type="normal" value="2006-09-03" selected="disabled"><![CDATA[<p>Closed for Labor Day</p>]]></date>
 </datesadd>
</importdata>
</script>
...
...
</head>

Next, use the importXML() method to import your XML into Epoch Prime
mycalendar.importXML(myXML); //load the dates into the calendar
For a more detailed explanation of using XML with the Epoch Prime AJAX Calendar, view our Using XML How-to Guide with Demos

After Page Load

You can update the dates in the calendar at any time using XML, either created client-side (in your user's browser), or server-side (via AJAX and the XMLHttpRequest object) – either way, the XML format is the same.

Getting the XML data via AJAX:

Below is a simplified example of an AJAX query to fetch dates from the server. We strongly recommend that you are familiar with general AJAX methods before trying this.

Send a query to your server

/*i.e. get the dates you want to add for the August 2006*/
var url = 'fetchdatexml.php?month=8&year=2006';
myXMLHttp.onreadystatechange = handleStateChange;
myXMLHttp.open('GET',url,true);
myXMLHttp.send(null);

Pass the XML returned from your query into importXML()
mycalendar.importXML(myXMLHttp.responseXML);

Using `importXML()` to remove Dates

The format of the datesrem section is very similar to datesadd – however, date tags in datesrem only requires a value attribute.

First, create the XML containing the dates you want to remove:

<html>
<head>
<title>My Hotel's XML test page</title>
...
...
<script type="text/javascript">
/*Remove ALL line breaks in the XML string below to prevent "unterminated string literal/constant" errors.
The line breaks below are simply to make the example easier to read.*/
var myXML = '<?xml version="1.0" encoding="UTF-8"?>
<importdata>
 <datesrem>
  <date value="2006-01-01"></date>
  <date value="2006-07-04"></date>
  <date value="2006-09-03"></date>
 </datesrem>
</importdata>';
</script>
...
...
</head>

Next, use the importXML() method to import your XML into Epoch Prime
mycalendar.importXML(myXML); //remove the dates from the calendar

Tip: You can add and remove dates simultaneously by using both <datesadd> and <datesrem> in the same XML string.

Using `addDates()` and `removeDates()` Methods

Epoch Prime maintains the addDates() and removeDates() from the Epoch JavaScript Calendar. However, using addDates() is a bit tedious compared to adding dates via XML (due to the additional date properties), but may be advantageous if you just need to add 1 or 2 dates after you've initialized the calendar.

Using `addDates()`

Declare and initialize the dates
var date1 = new Date(2006,0,1) //Jan 1, 2006 var date2 = new Date(2006,3,1) //Apr 1, 2006

Add any custom attributes, such as type, cellHTML, etc.

//set the attribute values for date1 - if you don't set an attribute value, it will simply default to blank.
date1.title = "New Year's day bash at Stevo's house!";
date1.cellHTML = "<img src="/images/steveo.jpg"/> 123 Main St.<br/>B.Y.O.B";
//set attribute values for date2
date2.type = "holiday";
date2.title = "April Fool's day!";

Create an array and fill it with the newly-created dates.
```
var myArray = new Array(date1,date2);
```

Pass the array to Epoch's addDates() method.

mycalendar1.addDates(myArray); //add the dates and display them on the calendar!

Epoch Prime will process the dates and add them to the dates array, then redraw itself to show the new dates.

Using `removeDates()`

Create an array containing the dates you want to remove:

var date1 = new Date(2006,0,1); //Jan 1, 2006
var date2 = new Date(2006,3,1); //Apr 1, 2006
var removeArray = new Array(date1,date2);

Call the removeDates() method
mycalendar.removeDates(removeArray);

Resetting the `dates` Array

Resetting the dates array is easy; simply call the resetSelections() method. This will remove all normal selected dates, keeping holidays and blackout dates intact.

mycalendar.resetSelections(); //clear all dates, rows, and columns
mycalendar.resetSelections(true); //same as above, but returns calendar to default month/year

Using the dates array in Epoch Prime