How It Works

Some people get confused about how to deploy this calendar tool on their website. After reading the description here, I suggest that you look at the samples on the Demos page (which are also included with the download). Each sample illustrates different features and the instructions used are described in the annotated text below the calendar display.

Basically you add a few lines of instructions to your web page telling the web browser where to find calendar script, where to find your event data, and where to display the calendar on the page. If you want to enable additional features or modify the calendar display, then you add some further instructions to your page. The rest of the "magic" is hidden in the calendar script which you should not need to change.

You may find more details on Kevin Ilsen's calendar web page, but these are the 3 basic components to deploy to your web site:

The calendar JavaScript (layercalendar.js or crunched.js in the samples) which tells the visitor's browser how to render the calendar on their screen. [Note: This script should generally should not be changed. It includes default settings for variables which control the display of various calendar elements which you can override by setting new values elsewhere.]
An event JavaScript which defines your events and any associated attributes such as images and hyperlinks. This is the file that gets changed most often and I usually include "events" as part of the file name to identify it.
An HTML page which sources the above mentioned JavaScripts and calls the "Calendar()" function of the calendar script to tell the browser to render the calendar on the web page.

You may choose to override the variables that control the display of various calendar elements or to source additional JavaScripts. While you could combine all the JavaScripts together or even add them in-line into the HTML page, separating them into separate files allows for easier maintenance and probably better performance.

I prefer to set configuration variables in a separate "common" JavaScript so they can be shared with a print-friendly view page if you enable that feature. Then I only in-line into the HTML pages those settings that are different from the common values.

A simple example of what goes in the HTML page is shown below. The directives to include external JavaScripts can go anywhere in the HTML file BEFORE the point where you want to display the calendar. They do NOT even need to be between the <html> and </html> tags.

<script src="crunched.js"></script> <script src="events.js"></script> <script language="JavaScript">  </script>

The contents of the "events.js" file look like this. The event dates are specified in the first argument to DefineEvent in YYYYMMDD format. [Note: There is no specification of event times except as you include in the event description. If multiple events occur on the same day, the calendar will render them in the order that they appear in the event script.]

DefineEvent(20040305,"Kelly","","coffee_donut.gif",45,45); DefineEvent(20040307,"School Night @Lock Monsters","","hockey.gif",32,39); DefineEvent(20040312,"No Coffee","","no_coffee.gif",45,45); DefineEvent(20040314,"Potluck @ Mariann","","grill.gif",35,37); DefineEvent(20040317,"","","irish.gif",39,33); DefineEvent(20040319,"Elizabeth","","coffee_donut.gif",45,45); DefineEvent(20040321,"Potluck @Sue","","grill.gif",35,37); DefineEvent(20040326,"Nancy","","coffee_donut.gif",45,45); DefineEvent(20040328,"Potluck @Amy","","grill.gif",35,37);

The event description goes in the second argument and may contain embedded HTML tags to customize the format. It can be blank if you just want to show an image on that date with no associated text. The target URL for a hyperlink (if present) goes in the third argument. It may point to a web page, an anchor within a web page, or even a document such as a Microsoft Word or Adobe Acrobat document. The last three arguments can specify an associated image file and display size.

TIP

One strategy using hyperlinks to organize detailed information on your events beyond what you can fit in the calendar cells is to create a page or file for each month named using the "YYYYMM" convention and put the details in there. If you insert anchors in these detail files, you can then hyperlink the event description in the calendar to the corresponding anchor on the details page.

TIP

For good rendering performance it is important to minimize the size of image files. You can do this by resizing the images down to their intended displayed size instead of making your visitors download larger images and then instructing their browser to scale them down for display using the width and height attributes. You can also reduce image file sizes by reducing the color depth; 256 color mode is sufficient for something displayed thumbnail size such as event images. Some useful tools for modifying your image files are IrfanView, which is FREE for non-commercial use, and the FREE ImageMagick which is a collection of powerful tools for manipulating images from the command line.

TIP

If you have many repeat events (same link or same image - maybe even the same description), one way to simplify the entry of events in your event script file is to define a convenience function with the repetitive information. For example:

function Coffee(date, place) { DefineEvent(date,place,"link.html","image.jpg",45,45) }

Then you can call the simpler "Coffee" function instead of the full "DefineEvent" function. For example:

Coffee(20011021,"Alice's house"); Coffee(20011028,"Betty's house");

If you want to use the category layers feature in my enhancements, instead of "DefineEvent", you will use "AddEvent" which adds four additional arguments: two additional event attributes inserted after the event description and two additional event image attributes inserted after the existing event image attributes. The two additional event image attributes are Align and Alt. Align is the alignment of the image in relation to the event description such as "left" or "right" when you want to override the standard setting as determined based on the global values of imageAlign and altAlign. Alt is the alternate text of the image (for mouseover or non-graphic browser).

The two additional event attributes are Layer and Format. Layer is the name of the event category for which you can globally define a standard format (such as color) and whose display on the calendar can be toggled on/off by the user. Format specifies the source of the format info for the event description and there are four recognized settings. If set to "layer", it will apply the format defined for that category layer. If set to "custom", it will ignore the layer format and use only tags embedded in the event description for formatting. If blank (the most common setting), it will act as either "custom" or "layer" depending on the value of "LayerFormat". Finally, you can specify before and after format tags separated by a "|" character to wrap around the event description instead of the category layer format.

[Note: regardless of the value of Layer, any embedded formats in the event description still take precedence; this is primarily intended to provide a more convenient way to override globally defined category formats and I rarely use it.]

When using the category layers feature, there is an additional "DefineLayer(Name,Format)" command which can be used to define the category names and assign their formats. There is also an optional 3rd parameter if you wanted an event category hidden by default. If you do not include these commands to define your categories, it will build up a list automatically as it encounters them in events and use a default format. Any event not assigned to a category is automatically assigned to the default category which is always displayed and has no corresponding checkbox for hiding it.

TIP

As with the "coffee" example above, if you have several layer definitions that have somewhat complex but similar formats (maybe just different colors), you can simplify the entry of layer definitions and reduce the chace of error by defining a convenience function with the repetitive information. For example:

function myLayer(name, color, size) { DefineLayer(name, "<font" + (size ? " size="+size : "") + " color="+color+"><b>|</b></font>"); }

Then you can call the clearer "myLayer" function instead of the full "DefineLayer" function. For example:

myLayer("default","black"); myLayer("youth","red"); myLayer("adult","blue");