Epoch DHTML JavaScript Calendar – Getting Started

For those who want to dive in, check out the minimum code required page to see the bare minimum you need to run Epoch.

Introduction

Events and Holidays via Epoch Epoch is a fast, low-footprint, high-powered JavaScript Calendar for use on websites which demand high interactivity from their users. Epoch can be used as a datepicker or inline calendar. Epoch is fully standards-compliant, with minimal allotments for obsolete browsers like IE4/Netscape 4, and commonly-used browsers that deviate from web standards. As a result, Epoch will work for virtually all users with JavaScript enabled – the dominant browsers out there all support it! More importantly, because of its standards-compliance, Epoch is future-compatible (confirmed with Internet Explorer 7!) and its use of many of the object-oriented features of JavaScript makes it easier for the developer to maintain and extend.

Thanks for your interest in Epoch!
Nick Baicoianu
Epoch Lead Developer

License

Epoch is free for non-commercial use. If you are using Epoch for a commercial website (e-commerce, corporate site, intranet, etc), please purchase a license. – you'll get free upgrades, full access to the Epoch source code, as well as email support in setting up your calendar. We think you'll find it's worth the time you saved implementing Epoch versus other solutions.

Who Epoch is For

Website Owners

Epoch's ease of deployment and maintenance makes it a prime choice for any website. Hoteliers and events websites will find the holiday and blackout date features of Epoch incredibly useful in detailing their offerings. Bloggers can use Epoch to navigate their archives with ease. High-traffic sites will appreciate the low bandwidth footprint (24k for all files - compressed) of Epoch when upgrading their user's experiences.

Never has it been so simple and inexpensive to upgrade your site than with Epoch.

Developers

Epoch is designed to be as easy for the developer to deploy as it is for the user to interact with it. 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.

Your Site's Visitors

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 entirely, they won't be left out in the cold.

The Basics

More information on setting up Epoch is available at the Epoch Setup Page.

For those who 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 web-accessible directory 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).

The links to both files should go in the <HEAD> section of any 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 a few options on where to put the Epoch initializations – all will work the same.

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 initializations-->
</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.

Tools

The code in epoch_classes.js is heavily commented to make modification easier – developers for more highly-trafficked sites should compress their JavaScript and CSS files using MeanFreePath's Free JavaScript and CSS code compactor. The code compactor reduces your files sizes by up to 50% by removing comments and unecessary whitespace from your files. The results are faster loading times for your users, and JavaScript code that is extremely difficult for humans to read. We recommend you keep a non-compacted version of epoch_classes.js for your own reference.

Support and Other Resources

We at MeanFreePath want your development experience with Epoch to go as smoothly as possible. Here are some resources to help make installation and customization easier: