Epoch DHTML Javascript Calendar – Getting Started

For those who've never heard the term 'RTFM' and want to dive in, check out the minimum code required page to see the bare minimum you need to run Epoch.

Introduction

I developed Epoch as a free alternative to the existing Javascript calendars I found on the web—each one had some great features but none had everything I wanted. Those that did have features charged exorbitant licensing fees, and even then the code was poorly organized and written using tons of hacks, poorly-organized 1999-era methods, and unneccessary <iframes> or popup windows.

Epoch is designed to be fully standards-compliant, with minimal allotments for obsolete browsers like IE4/Netscape 4. Despite this so called "lack" of backwards-compatibility, Epoch will work for over 98% of users with Javascript enabled – the dominant browsers out there all support it! More importantly, because of its standards-compliance, Epoch is future-compatible and its use of many of the object-oriented features of Javascript makes it easier to maintain. We've also have a nice list of features and upgrades for future versions on Epoch, including:

Improved Customization
Improved Styles
AJAX & XML Support

If you have any questions or feedback on Epoch, or wish to contribute an add-on or skin for the calendar, let us know!

Thanks for your interest in Epoch!
Nick Baicoianu
Epoch Lead Developer
nick@meanfreepath.com

If you liked Epoch, please rate it on the major JavaScript directories:

License

Creative Commons LGPL Epoch is licensed under the Creative Commons GNU Lesser Public License—this means you may copy and modify it as you please provided you keep the copyright notice (in the .js files) intact. This applies to you only if you plan to distribute Epoch or any code based on Epoch.

Who Epoch is For

Epoch is designed to be easy for the webmaster as well as the user. Integrating Epoch into your web pages doesn't require any hacks or complicated code because of its object-oriented structure. If you aren't familiar with object-oriented programming in Javascript (or any other language, for that matter), don't fret! Using Epoch's features requires no special knowledge outside of basic Javascript and HTML. Everything you need to get Epoch running on your web pages is included in this file and the example file.

Before you add Epoch to your web pages, consider your audience: are they advanced users who use the latest technology, or less-experienced users who may not be using "modern browsers" (i.e. Internet Explorer 4 and below, Netscape 4 and below, IE for Mac)? You can easily check your users' browsers if your webserver has a web stats program installed – if you use cPanel you have several options available. If you think your users are the less-experienced type, we recommend you use Epoch only for non-critical applications or in popup mode—that way if your users' browsers can't run Epoch, or have switched off Javascript, they won't be left out in the cold.

The Basics

For those who've never heard the term 'RTFM' and want to dive in, check out the minimum code required page to see the bare minimum you need to run Epoch.

1. Uploading Epoch

Before you can do anything, you must upload the Epoch files (via FTP or SCP/SFTP) to a publicly-accessible folder on your webserver. For example, if you site's root directory is /var/www/mysite/ (UNIX/Linux), or C:\inetpub\mysite\ (for Windows), you can place them in any subdirectory, i.e. /var/www/mysite/javascript/, or C:\inetpub\mysite\css\.

2. Linking to the Epoch files

Before you can begin using Epoch in your page, you need to include the files necessary for Epoch to function and look good. There are two files: a javascript file (epoch_classes.js), and a css file(epoch_styles.css). You can rename these to whatever you want—just make sure that the file names match with what you're putting on your page.

Both files should go in the <HEAD> section of eny webpage that uses Epoch – make sure they point to the correct subdirectory!

<html>
<head>
<title>My Cool Calendar Page</title>
<link rel="stylesheet" type="text/css" href="/path_to_css/epoch_styles.css" /> <!--Epoch's styles-->
<script type="text/javascript" src="/path_to_javascript/epoch_classes.js"></script> <!--Epoch's Code-->
</head>

3. Initializing and using Epoch in your Page

Once you've added the 2 files in the page head, you can start using Epoch! To add an Epoch calendar to you page you will first need to create an empty HTML element in the page body to physically hold the calendar; <div>, <input>, <td>, <p> are all acceptable elements. The containing element should be placed at the exact location you want Epoch to appear.

Syntax

When you've created the container element, you need to initialize an Epoch calendar for each one. You can do this using a line of code like this:

calendar1 = new Epoch(name,mode,container,multiselect);

The Initialization Variables

name: A unique name for the calendar – this will become the base for the calendar's id attribute.
mode: The mode the calendar will run in – can be flat or popup
container: A Javascript resource pointing to the HTML element that will hold the calendar. Usually accessed through the Javascript method document.getElementById('container_id').
multiselect: Whether you can select multiple dates – true for yes, false for no.

This code must lie inside a <SCRIPT> tag.

Where to put it

You have several options on where to put the Epoch declarations

In the Page <HEAD>

<head>
<title>My Cool Calendar Page</title>
<link rel="stylesheet" type="text/css" href="/path_to_css/epoch_styles.css" />   <!--Epoch's styles-->
<script type="text/javascript" src="/path_to_javascript/epoch_classes.js"></script>   <!--Epoch's Code-->
<script type="text/javascript">
var calendar1, calendar2, calendar3; /*must be declared in global scope*/
/*put the calendar initializations in the window's onload() method*/
window.onload = function() {
	calendar1 = new Epoch('cal1','flat',document.getElementById('calendar1_container'),false);
	calendar2 = new Epoch('cal2','popup',document.getElementById('calendar2_container'),false);
	calendar3 = new Epoch('cal3','flat',document.getElementById('calendar3_container'),true);
	...
};
</script>
</head>

In a separate .js file (using the code in blue above)

<head>
<title>My Cool Calendar Page</title>
<link rel="stylesheet" type="text/css" href="/path_to_css/epoch_styles.css" />   <!--Epoch's styles-->
<script type="text/javascript" src="/path_to_javascript/epoch_classes.js"></script>   <!--Epoch's Code-->
<script type="text/javascript" src="/path_to_javascript/my_declarations.js"></script>   <!--Epoch Declarations-->
</head>

Inside the containing HTML element (flat mode only)—not recommended

<body>
<h1>My cool calendars</h1>
<p>Check out our great events calendars!</p>
<div id="calendar1_container">
  <script type="text/javascript">new Epoch('cal1','flat',document.getElementById('calendar1_container'),false);</script>
</div>
<!--No "appropriate" way of associating a calendar with an inline script-->
<input id="calendar2_container" type="text" name="date" />
<div id="calendar3_container">
  <script type="text/javascript">new Epoch('cal3','flat',document.getElementById('calendar3_container'),true);</script>
</div>
</body>

Summary

In short, integrating Epoch into your webpage requires only 4 basic steps:

Copy epoch_classes.js and epoch_styles.css to your web server's Javascript and CSS directories.
Include the Epoch files in your page's head—be sure to include the correct path to the files!
Add containing elements in your page's body where you want Epoch to appear. Each element should have a unique id attribute.
Initialize a calendar for each containing element.

For a demo that shows the minimum required code to use Epoch, click here.