How to Use the JavaScript Event Calendar

The JavaScript Event Calendar is designed to permit maximum control over the look and feel of the displayed calendar, while still making it easy to specify events that should be displayed. The look of the calendar is almost entirely controlled by a Cascading Style Sheet (either a linked CSS file, or styles embedded in the page). Basically, you’ll follow these steps:

  1. Download the latest .JS file to your own web site, and reference it on the page where you want to display the calendar.
  2. (optional but recommended) Define CSS settings to customize the look of the calendar.
  3. Put a <div> on your page where you want the calendar to appear, with a unique id.
  4. Create a new JEC object, indicating the id of the div (and any optional settings).
  5. Define one or more events (the .defineEvents() function can be invoked multiple times, and each invocation can define multiple events).
  6. Show the calendar (by calling the .showCalendar() function).

Each of these steps is described in detail below.

The .JS File

The code for the calendar is contained in a single JavaScript file, which you can get on the Downloads page. Please do NOT link directly to the file on this web server; use a copy on your own server. You’ll add a line to the <head> section of your web page, similar to the following:

  • <html>
  • <head>
  •   .
  •   .
  • <script type="text/javascript" src="{path-to-local-js-files}/calendar-2.2.js"></script>
  •   .
  •   .
  • </head>
  •   .
  •   .

CSS Styling

The calendar may be styled in a variety of ways; to do this, it is important to understand how the calendar is marked up as an HTML table.

The <table> will have a class of “JEC” (unless this has been overridden prior to showing the calendar). Thus, “table.JEC” can be used as a selector to style individual table elements.

The <table> will have a <thead> that includes one row, with a single <th> spanning 7 columns and containing the month and year. Think of this as the “heading” of the entire calendar. You can style it like this, for example:

  1. table.JEC thead th {
  2.   background-color: #696969;
  3.   color: white;
  4.   font-size: 16px;
  5.   font-weight: bold;
  6.   margin: 5px;
  7. }

The <table> will have a <tfoot> that includes one row, containing three <th> elements. The first, spanning 2 columns, will contain a link to the previous month. The second, spanning 3 columns, will contain a drop-down select box for jumping directly to any month. The third, spanning 2 columns, will contain a link to the next month.

The <table> will have a <tbody> that includes all of the actual dates. The first row in the <tbody> will contain 7 <th> elements, each containing the (abbreviated) name of a day of the week (Sun - Sat). Subsequent rows will each contain 7 <td> elements. Each <td> in the <tbody> will display a date. Some will be empty because they represent blank squares in the calendar grid; these will be defined as <td class='dayBlank'>. The others will have a <div class='date'> element that contains only the day of the month. If there are events for a day, they will be displayed in a <div class='events'> that immediately follows the date. The text of each event description will be enclosed in a <span> element (unless there is a URL associated with the event, in which case the text will be enclosed in an <a> element). When there are multiple events on the same day, a <br/> element will appear BETWEEN the events (but NOT after the last event). If an event has an image, it will precede the event's <span> or <a> element.

Table cells (<td>'s) may have one or more of the following classes:

dayBlank
for a cell that is a blank square in the calendar
dayToday
for the cell corresponding to the current date
daySpecial
for special days of the week (Sunday, for example)
dayHasEvent
if there is at least one event on the day

Using these classes, it is possible to render the date cell(s) differently by adjusting the cell background, the color of the date (by styling div.date), etc. For example:

  1. table.JEC td.dayToday {
  2.   background-color: #eee;
  3.   border: 3px solid black;
  4. }

At your option, there are two ways you can specify the styling of the elements in the calendar table. Either you can include an embedded style sheet within your HTML page, or you can link to an external style sheet. The Examples page makes use of two different external linked style sheets, as follows:

  • <html>
  • <head>
  •   .
  •   .
  • <link rel="stylesheet" href="css/jec-grey.css" type="text/css" />
  • <link rel="stylesheet" href="css/jec-styled.css" type="text/css" />
  •   .
  •   .
  • </head>
  •   .
  •   .

TWO different style sheets are linked, because the Examples page includes multiple calendars, each styled differently. (Both of these style sheets are available on the Downloads page.)

As previously noted, the calendar’s <table> is created with a class=“JEC” by default, but this class can be overridden (as described later). If you are planning to have multiple calendars on the page, styled differently, you will NEED to override the class name.

Place Your Calendar

Decide where, in the overall layout of your page, you’d like your calendar to appear. Create a <div> element with a unique id attribute, and no content. For example:

  •   .
  •   .
  • <div id='myCalendarContainer'></div>
  •   .
  •   .

Create the JEC Object

For the remaining steps, you’ll need to add a small bit of JavaScript code, where you’ll create the object, set options, define events, and show the calendar. The first step is to create an instance of the JEC "class” as follows:

  1. <script type="text/javascript">
  2.   var myCalendar = new JEC('myCalendarContainer');
  3. </script>

In the code above, the string that you pass to the JEC( ) constructor must match the id attribute of the <div> where you want the calendar to appear.

The line above will create the JEC object, but nothing will be displayed. To display the calendar, invoke the .showCalendar( ) function on the object that you created:

  1. <script type="text/javascript">
  2.   var myCalendar = new JEC('myCalendarContainer');
  3.   myCalendar.showCalendar();
  4. </script>

Now, the calendar will appear at the desired place on your page. It will display the current month, and the links and drop-down list will permit the user to select any month within the current year. The definition of events (see below) or the explicit inclusion of options will change that default behavior.

The JEC( ) constructor accepts a second parameter (in addition to the id of the <div> that will contain the calendar). The optional second parameter is an object that can contain a set of name/value pairs, specifying options that will alter the generated calendar. The name/value pairs are specified in JavaScript Object Notation (i.e., “JSON” format). The supported options include:

tableClass
the name of the class that will be applied to the calendar <table> element (if not specified, the class name will be “JEC”)
firstDayOfWeek
the day of the week that should be displayed in the left-most column of the calendar; 1=Sunday, 2-Monday, . . . 7=Saturday (default is Sunday)
specialDay
the day of the week that should receive a special class (“daySpecial”) so that it can be styled differently than the other days; 1=Sunday, 2=Monday, . . . 7=Saturday (if not specified, then no days will receive the special class)
specialDays
array of special day numbers, if you need multiple days to receive the special class; for example [ 1, 7 ] for Sunday and Saturday (if this option is specified, it will supersede the single specialDay option)
linkNewWindow
if true, links (when present for events) will open in a new window; if false, links will open in the current browser window (default=true)
dateLinkNewWindow
if true, date links (when present) will open in a new window; if false, date links will open in the current browser window (default=false)
months
array of month names for the months January through February
weekdays
array of weekday names, from Sunday (“Sun”) through Saturday (“Sat”)
firstMonth
the first month to make available for display, specified in YYYYMM format (the presence of events will take precedence; you cannot make the calendar range “smaller” than the defined events determine)
lastMonth
the last month to make available for display, specified in YYYYMM format (the presence of events will take precedence; you cannot make the calendar range “smaller” than the defined events determine)

Below is an example of how a calendar can be created with various options:

  1. var myCal = new JEC('myCalendarContainer', {
  2.   tableClass: 'styledCalendar',
  3.   firstMonth: 201003,
  4.   lastMonth: 201010,
  5.   firstDayOfWeek: 2,
  6.   specialDays: [ 1, 7 ],
  7.   linkNewWindow: false,
  8.   weekdays: [
  9.     "Sunday",
  10.     "Monday",
  11.     "Tuesday",
  12.     "Wednesday",
  13.     "Thursday",
  14.     "Friday",
  15.     "Saturday"
  16.   ]
  17. });

Define Events

This is, after all, a JavaScript EVENT Calendar, and so the definition of the events is perhaps the most important aspect of the tool. The JEC object includes a .defineEvents( ) function, which allows you to specify a list of one or more events, each with its own unique properties. As in the case of the optional parameter to the JEC( ) constructor, the events are specified using JSON. The .defineEvents( ) function accepts an array, and each element in the array is an object that can include the following name/value pairs:

eventDate
the date of the event, in the format YYYYMMDD (this is a REQUIRED value)
eventDescription
the description of the event, which will appear in the calendar on the indicated date (this is a REQUIRED value)
eventLink
if specified, this optional value is the URL of a page to which the event will be linked
image
if specified, this optional value is the path of an image (relative to the current page on the web server) that will be displayed with the event description on the indicated date
imageWidth
if specified (and if an image is specified), this optional value is the width of the image in pixels (specifying a width is generally not necessary)
imageHeight
if specified (and if an image is specified), this optional value is the height of the image in lines (specifying a height is generally not necessary)

Below is an example of a call to the .defineEvents( ) function, to define 4 different events:

  1. myCal.defineEvents(
  2.   [
  3.     {
  4.       eventDate: 20100407,
  5.       eventDescription: 'JEC 2.0 Released',
  6.       eventLink: 'http://calendar.ilsen.net'
  7.     },
  8.     {
  9.       eventDate: 20090101,
  10.       eventDescription: 'MonkeysTapping Launched!',
  11.       eventLink: 'http://monkeystapping.com'
  12.     },
  13.     { eventDate: 20100705, eventDescription: 'Kevin\'s Birthday' },
  14.     { eventDate: 20090705, eventDescription: 'Kevin\'s BIG Birthday!' }
  15.   ]
  16. );

To provide some degree of “backward-compatibility” with the original version of the JavaScript Event Calendar, there’s an additional function: .defineEvent( ). This function allows you to define a single event, by specifying the event’s properties as individual parameters. You would invoke this event once for each individual event. It can accept between 2 and 6 parameters (unused parameters at the end can be omitted). The full format is shown below, followed by several examples:

.defineEvent(eventDate, eventDescription, eventLink, image, imageWidth, imageHeight);
  1. myCal.defineEvent(20100407, 'JEC 2.0 Released', 'http://calendar.ilsen.net');
  2. myCal.defineEvent(20090101, 'MonkeysTapping Launched', 'http://monkeystapping.com', 'img/monkey.gif');
  3. myCal.defineEvent(20100705, 'Kevin\'s Birthday');

Date Links

In addition to the hyperlinks that can be included with defined events, it is also possible to associate hyperlinks with specific dates. The date number will be “clickable” and can be styled in any way that you like. The JEC object includes a .linkDates( ) function, which accepts an array, and each element in the array is an object that includes the following name/value pairs:

linkedDate
the date of the event, in the format YYYYMMDD
dateLink
the URL of a page to which the date will be linked

Below is an example of a call to the .linkDates( ) function, to define 2 different date links:

  1. myCal.linkDates(
  2.   [
  3.     {
  4.       linkedDate: 20100407,
  5.       dateLink: 'http://calendar.ilsen.net'
  6.     },
  7.     {
  8.       linkedDate: 20090101,
  9.       dateLink: 'http://monkeystapping.com'
  10.     }
  11.   ]
  12. );

Date Classes

There is sometimes a need to apply a particular style to a single date or a group of dates. For example, consider the need to highlight a certain holiday weekend with a background color. The JEC object includes a .styleDates( ) function, which accepts an array, and each element in the array is an object that includes the following name/value pairs:

styledDate
the date which should be styled with the class, in the format YYYYMMDD
dateClass
the class to apply to the date

Then, you would use your stylesheet to define whatever specific styles should be applied for that class. Below is an example of a call to the .styleDates( ) function:

  1. myCal.styleDates(
  2.   [
  3.     {
  4.       styledDate: 20110528,
  5.       dateClass: 'memorialDayWeekend'
  6.     },
  7.     {
  8.       styledDate: 20110529,
  9.       dateClass: 'memorialDayWeekend'
  10.     },
  11.     {
  12.       styledDate: 20110530,
  13.       dateClass: 'memorialDayWeekend'
  14.     }
  15.   ]
  16. );

Show the Calendar

As previously noted (above), you can display your calendar by invoking the .showCalendar( ) function of your calendar object. This will display the current month and year. You can also specify a particular month and year, in the format YYYYMM, as a parameter. For example, the following series of lines defines a calendar with some options, creates a couple of events, and displays the calendar for July 2010:

  1. var myCal = new JEC('myCalendarContainer', {
  2.   tableClass: 'styledCalendar',
  3.   firstMonth: 201003,
  4.   lastMonth: 201010
  5. });
  6. myCal.defineEvents(
  7.   [
  8.     {
  9.       eventDate: 20100407,
  10.       eventDescription: 'JEC 2.0 Released',
  11.       eventLink: 'http://calendar.ilsen.net'
  12.     },
  13.     { eventDate: 20100705, eventDescription: 'Kevin\'s Birthday' }
  14.   ]
  15. );
  16. myCal.showCalendar(201007);