Epoch Prime XML Specification & Tag Definitions

One of Epoch Prime's most exciting features is the power to import XML data into the calendar at will – both at initialization and run-time. This page discusses the proper format of the XML you will use to transfer data into Epoch Prime.

Configuration Variables: <configs>

Initialization Variables: <initcfg>

These variables control the look and features of Epoch Prime. They can only be set on calendar initialization.

string <name>

The name prepended to any id attributes created in the calendar's DOM representation (i.e. what you see). Should be unique for each calendar.

string {'popup', 'flat'} <mode>

The mode the calendar will run in; can be 'popup', or 'flat'.

int {'yes','no'} <multiselect>

Whether the user can select multiple dates, or just one. Can be 'yes' or 'no'. Multiselect cannot be enabled in popup mode.

int {0:6} <startday>

The day the weeks will start on. Can be 0 (Sunday) through 6 (Saturday).

string {'yes','no'} <showweeks>

Whether the week numbers will be displayed to the left of the calendar. Can be 'yes' or 'no'.

string {'yes','no'} <selcurmonthonly>

Whether dates will be selected outside of the current month when the user clicks a week or day heading. User can still select individual cells outside the current month.

State Variables: <statecfg>

Control the initial state of the calendar, specifically dealing with the default month/year to show and allowable date ranges. These config values can be set at any time; either on calendar initialization, or after.

int <displayyearinitial>

The year to return to when the user clicks the Clear button on the calendar.

int <displaymonthinitial>

The month to return to when the user clicks the Clear button on the calendar.

int <displayyear>

The year to display to the user.

string <displaymonth>

The month to display to the user.

string <mindate>

The minimum allowed date the use may click on the calendar. Must be in ISO 8601 standard date notation ('yyyy-mm-dd').

string <maxdate>

The maximum allowed date the use may click on the calendar. Must be in ISO 8601 standard date notation ('yyyy-mm-dd').

string <dateformat>

The default date format to use in popup mode – i.e. the date format of the date that is placed in the target text box. Follows the conventions of the PHP date() function. See our dateFormat() reference for more details on formatting.

Language Variables: <lang>

Control the text displayed to the user in the calendar. May be set at any time, with the exception of the week and month names.

Abbreviated Day List: <daylist_sh>

A 7-unit long list of the Abbreviated Day Names to use (i.e. Sun, Mon,... in English; Dom, Lun,... in Spanish)

Day List: <daylist_ln>

A 7-unit long list of the Full Day Names to use (i.e. Sunday, Monday,... in English; Domingo, Lunes,... in Spanish)

Abbreviated Month List: <months_sh>

A 12-unit long list of the Abbreviated Month Names to use (i.e. Jan, Feb,... in English; Ene, Feb,... in Spanish)

Month List: <months_ln>

A 12-unit long list of the Full Month Names to use (i.e. January, February,... in English; Enero, Febrero,... in Spanish)

Language Text Variables: <langtexts>

string <monthup_title>

The tooltip text for the Previous Month button

string <monthdn_title>

The tooltip text for the Next Month button

string <clearbtn_caption>

The caption text for the Clear Button

string <clearbtn_title>

The tooltip text for the Clear Button

string <maxrange_caption>

The message to display when the user exceeds the limits of the minimum/maximum dates

string <closebtn_caption>

The caption text for the Close Button

string <closebtn_title>

The tooltip text for the Close Button

Dates to Add: <datesadd>

<datesadd> contains all the dates you want to add to the calendar. You can add dates at any time; at calendar initialization, and after initialization. Epoch Prime processes and removes the dates in <datesrem> before adding the dates in the <datesadd> section.

string <date>

Contains all the data needed to add a date to the calendar's dates array. Date parameters, such as the type, value, and whether it can be selected are stored in the tag attributes, while any HTML for the cell is placed between the <date> tags.

Attributes

string {'normal', 'holiday'} type

type specifies the type of date the calendar cell for this date will display as. This does not affect the behavior of the calendar cell in any way, other than changing the CSS class of it. type is optional and may be omitted from the data tag's attributes; defaults to 'normal'.

string title

title is the text that will display as a tooltip when the user's mouse cursor hovers over this date's calendar cell. It is equivalent to the HTML title attribute. title is optional and may be omitted; no default.

string value

The value of the date (i.e. 2006-01-01). Must be in ISO 8601 standard date notation ('yyyy-mm-dd').

string href

The URL to overlay on the date on the calendar. By default, this appears as a standard URL under the date in the calendar cell — you can make the entire cell a clickable link by modifying the CalCell::setURL() function.

string{'yes','no','disabled'} selected

Determines the status of the cell – is it going to be selected by default ('yes'), not selected ('no'), or is the user prevented from selecting it at all ('disabled')?

Dates to Remove: <datesrem>

<datesrem> contains all the dates you want to remove from the calendar. Dates may be removed at any time. Epoch Prime processes this section and removes the dates in <datesrem> before adding the dates in <datesadd>.

string <date>

Contains all the data needed to remove a date from the calendar's dates array. The only required attribute for a <date> under the <datesrem> section is value—other attributes will be ignored.

Attributes

string value

The value of the date (i.e. 2006-01-01). Must be in ISO 8601 standard date notation ('yyyy-mm-dd').

Useful Hints

  1. It is not necessary to include every configuration value in the XML. Those left out will default to the values set in the calConfig() and setLang() functions defined in epoch_classes.js.
    1. You can leave out entire sub-sections, the <?xml?> tag, and the <importdata> document element (as long as you're setting only one of <configs>, <datesadd>, or <datesrem>). For example, <configs><name>mycalendar</name><mode>popup</mode></initcfg></configs>, or <datesadd><date value="2006-01-01"></date><date value="2006-02-04"></date></datesadd> are perfectly good configuration strings.
    2. Do Not leave out the major sections (<configs>, <datesadd>, or <datesrem>) if you plan to use any of their subsections.
  2. Enclose your cells' HTML in XML CDATA tags. This will prevent parse errors if the tag contents aren't valid XML/XHTML. For example, 
    <datesadd>
 <date value="2006-01-01"> <p>New year's bash! </date>
</datesadd>
    will cause a parse error because the <p> element isn't closed. Try this instead: 
    <datesadd>
 <date value="2006-01-01"> <![CDATA[<p>New year's bash!]]> </date>
</datesadd>

    The XML parser will skip over the <date> tag's contents, allowing Epoch Prime to place the contents in one of its cells.

Sample XML

Here is a FULL sample xml string you can use to create your own XML with. Note: if you want to place the XML in your page as a JavaScript string (see the Using XML for more details), use our free Code Compactor – it will strip out line breaks and excessive spaces/tabs from the XML.