DHTML Calendar Widget

$Id: reference.tex,v 1.13 2003/11/05 17:30:21 mishoo Exp $

Contents

    1  Overview
        1.1  How does this thing work?
        1.2  Project files
        1.3  License

    2  Quick startup
        2.1  Installing a popup calendar
        2.2  Installing a flat calendar
        2.3  Calendar.setup in detail

    3  The Calendar object overview
        3.1  Creating a calendar
        3.2  Order does matter ;-)
        3.3  Caching the object
        3.4  Callback functions

    4  The Calendar object API reference
        4.1  Calendar constructor
        4.2  Useful member variables (properties)
        4.3  Public methods
            4.3.1  Calendar.create
            4.3.2  Calendar.callHandler
            4.3.3  Calendar.callCloseHandler
            4.3.4  Calendar.hide
            4.3.5  Calendar.setDateFormat
            4.3.6  Calendar.setTtDateFormat
            4.3.7  Calendar.setDisabledHandler
            4.3.8  Calendar.setDateStatusHandler
            4.3.9  Calendar.show
            4.3.10  Calendar.showAt
            4.3.11  Calendar.showAtElement
            4.3.12  Calendar.setDate
            4.3.13  Calendar.setMondayFirst
            4.3.14  Calendar.parseDate
            4.3.15  Calendar.setRange

    5  Side effects

    6  Credits

1  Overview

The DHTML Calendar widget¹ is an (HTML) user interface element that gives end-users a friendly way to select date and time. It works in a web browser. The first versions only provided support for popup calendars, while starting with version 0.9 it also supports “flat” display. A “flat” calendar is a calendar that stays visible in the page all the time. In this mode it could be very useful for “blog” pages and other pages that require the calendar to be always present.

The calendar is compatible with most popular browsers nowadays. While it’s created using web standards and it should generally work with any compliant browser, the following browsers were found to work: Mozilla (the development platform), Netscape 6.0 or better, all other Gecko-based browsers, Internet Explorer 5.0 or better for Windows², Opera 7³ and Konqueror 3.1.2 (with pretty much the same dysfunctions as in Opera).

You can find the latest info and version at the calendar homepage:

1.1  How does this thing work?

DHTML is not “another kind of HTML”. It’s merely a naming convention. DHTML refers to the combination of HTML, CSS, JavaScript and DOM. DOM (Document Object Model) is a set of interfaces that glues the other three together. In other words, DOM allows dynamic modification of an HTML page through a program. JavaScript is our programming language, since that’s what browsers like. CSS is a way to make it look good ;-). So all this soup is generically known as DHTML.

Using DOM calls, the program dynamically creates a <table> element that contains a calendar for the given date and then inserts it in the document body. Then it shows this table at a specified position. Usually the position is related to some element in which the date needs to be displayed/entered, such as an input field.

By assigning a certain CSS class to the table we can control the look of the calendar through an external CSS file; therefore, in order to change the colors, backgrounds, rollover effects and other stuff, you can only change a CSS file—modification of the program itself is not necessary.

1.2  Project files

Here’s a description of the project files, excluding documentation and example files.

• the main program file (calendar.js). This defines all the logic behind the calendar widget.

• the CSS files (calendar-*.css). Loading one of them is necessary in order to see the calendar as intended.

• the language definition files (lang/calendar-*.js). They are plain JavaScript files that contain all texts that are displayed by the calendar. Loading one of them is necessary.

• helper functions for quick setup of the calendar (calendar-setup.js). You can do fine without it, but starting with version 0.9.3 this is the recommended way to setup a calendar.

1.3  License

The calendar is released under the GNU Lesser General Public License. You can read the entire license text here.

2  Quick startup

Installing the calendar used to be quite a task until version 0.9.3. Starting with 0.9.3 I have included the file calendar-setup.js whose goal is to assist you to setup a popup or flat calendar in minutes. You are encouraged to modify this file and not calendar.js if you need extra customization, but you’re on your own.

First you have to include the needed scripts and style-sheet. Make sure you do this in your document’s <head> section, also make sure you put the correct paths to the scripts.

<style type="text/css">@import url(calendar-win2k-1.css)</style>
<script type="text/javascript" src="calendar.js"></script>
<script type="text/javascript" src="lang/calendar-en.js"></script>
<script type="text/javascript" src="calendar-setup.js"></script>

2.1  Installing a popup calendar

Now suppose you have the following HTML:

<form ...>
  <input type="text" id="data" name="data" />
  <button id="trigger">...</button>
</form>

You want the button to popup a calendar widget when clicked? Just insert the following code immediately after the HTML form:

<script type="text/javascript">
  Calendar.setup(
    {
      inputField  : "data",      // ID of the input field
      ifFormat    : "M d, y",    // the date format
      button      : "trigger"    // ID of the button
    }
  );
</script>

The Calendar.setup function, defined in calendar-setup.js takes care of “patching” the button to display a calendar when clicked. The calendar is by default in single-click mode and linked with the given input field, so that when the end-user selects a date it will update the input field with the date in the given format and close the calendar. If you are a long-term user of the calendar you probably remember that for doing this you needed to write a couple functions and add an “onclick” handler for the button by hand.

By looking at the example above we can see that the function Calendar.setup receives only one parameter: a JavaScript object. Further, that object can have lots of properties that tell to the setup function how would we like to have the calendar. For instance, if we would like a calendar that closes at double-click instead of single-click we would also include the following: singleClick:false.

For a list of all supported parameters please see the section 2.3.

2.2  Installing a flat calendar

Here’s how to configure a flat calendar, using the same Calendar.setup function. First, you should have an empty element with an ID. This element will act as a container for the calendar. It can be any block-level element, such as DIV, TABLE, etc. We will use a DIV in this example.

<div id="calendar-container"></div>

Then there is the JavaScript code that sets up the calendar into the “calendar-container” DIV. The code can occur anywhere in HTML after the DIV element.

<script type="text/javascript">
  function dateChanged(calendar) {
    // Beware that this function is called even if the end-user only
    // changed the month/year.  In order to determine if a date was
    // clicked you can use the dateClicked property of the calendar:
    if (calendar.dateClicked) {
      // OK, a date was clicked, redirect to /yyyy/mm/dd/index.php
      var y = calendar.date.getFullYear();
      var m = calendar.date.getMonth();     // integer, 0..11
      var d = calendar.date.getDate();      // integer, 1..31
      // redirect...
      window.location = "/" + y + "/" + m + "/" + d + "/index.php";
    }
  };

  Calendar.setup(
    {
      flat         : "calendar-container", // ID of the parent element
      flatCallback : dateChanged           // our callback function
    }
  );
</script>

2.3  Calendar.setup in detail

Following there is the complete list of properties interpreted by Calendar.setup. All of them have default values, so you can pass only those which you would like to customize. Anyway, you must pass at least one of inputField, displayArea or button, for a popup calendar, or flat for a flat calendar. Otherwise you will get a warning message saying that there’s nothing to setup.

3  The Calendar object overview

Basically you should be able to setup the calendar with the function presented in the previous section. However, if for some reason Calendar.setup doesn’t provide all the functionality that you need and you want to tweak into the process of creating and configuring the calendar “by hand”, then this section is the way to go.

The file calendar.js implements the functionality of the calendar. All (well, almost all) functions and variables are embedded in the JavaScript object “Calendar”.

You can instantiate a Calendar object by calling the constructor, like this: var cal = new Calendar(...). We will discuss the parameters later. After creating the object, the variable cal will contain a reference to it. You can use this reference to access further options of the calendar, for instance:

cal.weekNumbers = false; // do not display week numbers
cal.showsTime = true;    // include a time selector
cal.setDateFormat("%Y.%m.%d %H:%M"); // set this format: 2003.12.31 23:59
cal.setDisabledHandler(function(date, year, month, day) {
  // verify date and return true if it has to be disabled
  // ``date'' is a JS Date object, but if you only need the
  // year, month and/or day you can get them separately as
  // next 3 parameters, as you can see in the declaration
  if (year == 2004) {
    // disable all dates from 2004
    return true;
  }
  return false;
});

etc. Prior to version 0.9.3 this was the only way to configure it. The Calendar.setup function, documented in section 2, basically does the same things (actually more) in order to setup the calendar, based on the parameters that you provided.

3.1  Creating a calendar

The calendar is created by following some steps (even the function Calendar.setup, described in section 2, does the same). While you can skip optional (marked “opt”) steps if you’re happy with the defaults, please respect the order below.

1. Instantiate a Calendar object. Details about this in section 4.1.

2. opt   Set the weekNumbers property to false if you don’t want the calendar to display week numbers.

3. opt   Set the showsTime property to true if you want the calendar to also provide a time selector.

4. opt   Set the time24 property to false if you want the time selector to be in 12-hour format. Default is 24-hour format. This property only has effect if you also set showsTime to true.

5. opt   Set the range of years available for selection (see section 4.3.15). The default range is [1970..2050].

6. opt   Set the getDateStatus property. You should pass here a function that receives a JavaScript Date object and returns true if the given date should be disabled, false otherwise (details in section 4.3.7).

7. opt   Set a date format. Your handler function, passed to the calendar constructor, will be called when a date is selected with a reference to the calendar and a date string in this format.

8. Create the HTML elements related to the calendar. This step practically puts the calendar in your HTML page. You simply call Calendar.create(). You can give an optional parameter if you wanna create a flat calendar (details in section 4.3.1).

9. opt   Initialize the calendar to a certain date, for instance from the input field.

10. Show the calendar (details in section 4.3.9).

3.2  Order does matter ;-)

As you could see in the previous section, there are more steps to be followed in order to setup the calendar. This happens because there are two different things that need to be accomplished: first there is the JavaScript object, that is created with new Calendar(...). Secondly there are the HTML elements that actually lets you see and manipulate the calendar.

By instantiating the calendar we create the JavaScript object. It lets us configure some properties and it also knows how to create the UI element (the HTML elements actually) that will eventually be what the end-user sees on screen. Creation of the HTML element is accomplished by the function Calendar.create. It knows how to create popup or flat calendars. This function is described in section 4.3.1.

Some properties need to be set prior to creating the HTML elements, because otherwise they wouldn’t have any effect. Such a property is weekNumbers—it has the default value “true”, and if you don’t want the calendar to display the week numbers you have to set it to false. If, however, you do that after calling Calendar.create the calendar would still display the week numbers, because the HTML elements are already created (including the <td>-s in the <table> element that should contain the week numbers). For this reason the order of the steps above is important.

Another example is when you want to show the calendar. The “create” function does create the HTML elements, but they are initially hidden (have the style “display: none”) unless the calendar is a flat calendar that should be always visible in the page. Obviously, the Calendar.show function should be called after calling Calendar.create.

3.3  Caching the object

Suppose the end-user has popped up a calendar and selects a date. The calendar then closes. What really happens now?

There are two approaches. The first (used in very old versions of the calendar) was to drop completely the Calendar object and when the end-user pops up the calendar again to create another one. This approach is bad for more reasons:

• creating the JavaScript object and HTML elements is time-consuming

• we may loose some end-user preferences (i.e. he might prefer to have Monday for the first day of week and probably already clicked it the first time when the calendar was opened, but now he has to do it again)

The second approach, implemented by the Calendar.setup function, is to cache the JavaScript object. It does this by checking the global variable window.calendar and if it is not null it assumes it is the created Calendar object. When the end-user closes the calendar, our code will only call “hide” on it, therefore keeping the JavaScript object and the HTML elements in place.

CAVEAT:     Since time selection support was introduced, this “object caching” mechanism has the following drawback: if you once created the calendar with the time selection support, then other items that may not require this functionality will still get a calendar with the time selection support enabled. And reciprocal. ;-) Hopefully this will be corrected in a later version, but for now it doesn’t seem such a big problem.

3.4  Callback functions

You might rightfully wonder how is the calendar related to the input field? Who tells it that it has to update that input field when a date is selected, or that it has to jump to that URL when a date is clicked in flat mode?

All this magic is done through callback functions. The calendar doesn’t know anything about the existence of an input field, nor does it know where to redirect the browser when a date is clicked in flat mode. It just calls your callback when a particular event is happening, and you’re responsible to handle it from there. For a general purpose library I think this is the best model of making a truly reusable thing.

The calendar supports the following user callbacks:

• onSelect   — this gets called when the end-user changes the date in the calendar. Documented in section 4.1.

• onClose   — this gets called when the calendar should close. It’s user’s responsibility to close the calendar. Details in section 4.1.

• getDateStatus   — this function gets called for any day in a month, just before displaying the month. It is called with a JavaScript Date object and should return true if that date should be disabled, false if it’s an ordinary date and no action should be taken, or it can return a string in which case the returned value will be appended to the element’s CSS class (this way it provides a powerful way to make some dates “special”, i.e. highlight them differently). Details in section 4.3.8.

4  The Calendar object API reference

4.1  Calendar constructor

Synopsis:

var calendar = Calendar(mondayFirst, date, onSelect, onClose);

Parameters are as follows:

• mondayFirst   — boolean, if it’s true the calendar will have Monday as first day of week, if false weeks start on Sunday.

• date   — a JavaScript Date object or null. If null is passed then the calendar will default to today date. Otherwise it will initialize on the given date.

• onSelect   — your callback for the “onChange” event. See above.

• onClose   — your callback for the “onClose” event. See above.

The onSelect event

Here is a typical implementation of this function:

function onSelect(calendar, date) {
  var input_field = document.getElementById("date");
  input_field.value = date;
};

date is in the format selected with calendar.setDateFormat (see section 4.3.5). This code simply updates the input field. If you want the calendar to be in single-click mode then you should also close the calendar after you updated the input field, so we come to the following version:

function onSelect(calendar, date) {
  var input_field = document.getElementById("date");
  input_field.value = date;
  if (calendar.dateClicked) {
    calendar.callCloseHandler(); // this calls "onClose" (see above)
  }
};

Note that we checked the member variable dateClicked and only hide the calendar if it’s true. If this variable is false it means that no date was actually selected, but the user only changed the month/year using the navigation buttons or the menus. We don’t want to hide the calendar in that case.

The onClose event

This event is triggered when the calendar should close. It should hide or destroy the calendar object—the calendar itself just triggers the event, but it won’t close itself.

A typical implementation of this function is the following:

function onClose(calendar) {
  calendar.hide();
  // or calendar.destroy();
};

4.2  Useful member variables (properties)

After creating the Calendar object you can access the following properties:

• date — is a JavaScript Date object. It will always reflect the date shown in the calendar (yes, even if the calendar is hidden).

• isPopup — if this is true then the current Calendar object is a popup calendar. Otherwise (false) we have a flat calendar. This variable is set from Calendar.create and has no meaning before this function was called.

• dateClicked — particularly useful in the onSelect handler, this variable tells us if a date was really clicked. That’s because the onSelect handler is called even if the end-user only changed the month/year but did not select a date. We don’t want to close the calendar in that case.

• weekNumbers — if true (default) then the calendar displays week numbers. If you don’t want week numbers you have to set this variable to false before calling Calendar.create.

• showsTime – if you set this to true (it is false by default) then the calendar will also include a time selector.

• time24 – if you set this to false then the time selector will be in 12-hour format. It is in 24-hour format by default.

• mondayFirst — if true then the calendar uses Monday as first day of week, otherwise Sunday. This variable is set from constructor, but you still have a chance to modify it before calling Calendar.create.

There are lots of other member variables, but one should access them only through member functions so I won’t document them here.

4.3  Public methods

4.3.1  Calendar.create

This function creates the afferent HTML elements that are needed to display the calendar. You should call it after setting the calendar properties. Synopsis:

calendar.create(); // creates a popup calendar
  // -- or --
calendar.create(document.getElementById(parent_id)); // makes a flat calendar

It can create a popup calendar or a flat calendar. If the “parent” argument is present (it should be a reference—not ID—to an HTML element) then a flat calendar is created and it is inserted in the given element.

At any moment, given a reference to a calendar object, we can inspect if it’s a popup or a flat calendar by checking the boolean member variable isPopup:

if (calendar.isPopup) {
   // this is a popup calendar
} else {
   // this is a flat calendar
}

4.3.2  Calendar.callHandler

This function calls the first user callback (the onSelect handler) with the required parameters.

4.3.3  Calendar.callCloseHandler

This function calls the second user callback (the onClose handler). It’s useful when you want to have a “single-click” calendar—just call this in your onSelect handler, if a date was clicked.

4.3.4  Calendar.hide

Call this function to hide the calendar. The calendar object and HTML elements will not be destroyed, thus you can later call one of the show functions on the same element.

4.3.5  Calendar.setDateFormat

This function configures the format in which the calendar reports the date to your “onSelect” handler. Call it like this:

calendar.setDateFormat("%y/%m/%d");

As you can see, it receives only one parameter, the required format. The magic characters are the following:

There are more algorithms for computing the week number. All three specifiers currently implement the same one, as defined by ISO 8601: “the week 01 is the week that has the Thursday in the current year, which is equivalent to the week that contains the fourth day of January. Weeks start on Monday.

4.3.6  Calendar.setTtDateFormat

Has the same prototype as Calendar.setDateFormat, but refers to the format of the date displayed in the “status bar” when the mouse is over some date.

4.3.7  Calendar.setDisabledHandler

This function allows you to specify a callback function that checks if a certain date must be disabled by the calendar. You are responsible to write the callback function. Synopsis:

function disallowDate(date) {
  // date is a JS Date object
  if (  date.getFullYear() == 2003 &&
        date.getMonth()    == 6 /* July, it's zero-based */ &&
        date.getDate()     == 5  ) {
    return true; // disable July 5 2003
  }
  return false; // enable other dates
};

calendar.setDisabledHandler(disallowDate);

If you change this function in “real-time”, meaning, without creating a new calendar, then you have to call calendar.refresh() to make it redisplay the month and take into account the new disabledHandler. Calendar.setup does this, so you have no such trouble with it.

Note that disallowDate should be very fast, as it is called for each date in the month. Thus, it gets called, say, 30 times before displaying the calendar, and 30 times when the month is changed. Tests I’ve done so far show that it’s still good, but in the future I might switch it to a different design (for instance, to call it once per month and to return an array of dates that must be disabled).

This function should be considered deprecated in the favor of Calendar.setDateStatusHandler, described below.

4.3.8  Calendar.setDateStatusHandler

This function obsoletes Calendar.setDisabledHandler. You call it with a function parameter, but this function can return a boolean or a string. If the return value is a boolean (true or false) then it behaves just like setDisabledHandler, therefore disabling the date if the return value is true.

If the returned value is a string then the given date will gain an additional CSS class, namely the returned value. You can use this to highlight some dates in some way. Note that you are responsible for defining the CSS class that you return. If you return the string “disabled” then that date will be disabled, just as if you returned true.

Here is a simple scenario that shows what you can do with this function. The following should be present in some of your styles, or in the document head in a STYLE tag (but put it after the place where the calendar styles were loaded):

.special { background-color: #000; color: #fff; }

And you would use the following code before calling Calendar.create():

// this table holds your special days, so that we can automatize
// things a bit:
var SPECIAL_DAYS = {
    0 : [ 13, 24 ],             // special days in January
    2 : [ 1, 6, 8, 12, 18 ],    // special days in March
    8 : [ 21, 11 ],             // special days in September
   11 : [ 25, 28 ]              // special days in December
};

// this function returns true if the passed date is special
function dateIsSpecial(year, month, day) {
    var m = SPECIAL_DAYS[month];
    if (!m) return false;
    for (var i in m) if (m[i] == day) return true;
    return false;
}

// this is the actual date status handler.  Note that it receives the
// date object as well as separate values of year, month and date, for
// your confort.
function dateStatusHandler(date, y, m, d) {
    if (dateIsSpecial(y, m, d)) return ``special'';
    else return false;
    // return true above if you want to disable other dates
}

// configure it to the calendar
calendar.setDateStatusHandler(dateStatusHandler);

The above code adds the “special” class name to some dates that are defined in the SPECIAL_DAYS table. Other dates will simply be displayed as default, enabled.

4.3.9  Calendar.show

Call this function do show the calendar. It basically sets the CSS “display” property to “block”. It doesn’t modify the calendar position.

This function only makes sense when the calendar is in popup mode.

4.3.10  Calendar.showAt

Call this to show the calendar at a certain (x, y) position. Prototype:

calendar.showAt(x, y);

The parameters are absolute coordinates relative to the top left corner of the page, thus they are page coordinates not screen coordinates.

After setting the given coordinates it calls Calendar.show. This function only makes sense when the calendar is in popup mode.

4.3.11  Calendar.showAtElement

This function is useful if you want to display the calendar near some element. You call it like this:

calendar.showAtElement(element, align);

where element is a reference to your element (for instance it can be the input field that displays the date) and align is an optional parameter, of type string, containing one or two characters. For instance, if you pass "Br" as align, the calendar will appear below the element and with its right margin continuing the element’s right margin.

As stated above, align may contain one or two characters. The first character dictates the vertical alignment, relative to the element, and the second character dictates the horizontal alignment. If the second character is missing it will be assumed "l" (the left margin of the calendar will be at the same horizontal position as the left margin of the element).

The characters given for the align parameters are case sensitive. This function only makes sense when the calendar is in popup mode. After computing the position it uses Calendar.showAt to display the calendar there.

Vertical alignment

The first character in “align” can take one of the following values:

• T — completely above the reference element (bottom margin of the calendar aligned to the top margin of the element).

• t — above the element but may overlap it (bottom margin of the calendar aligned to the bottom margin of the element).

• c — the calendar displays vertically centered to the reference element. It might overlap it (that depends on the horizontal alignment).

• b — below the element but may overlap it (top margin of the calendar aligned to the top margin of the element).

• B — completely below the element (top margin of the calendar aligned to the bottom margin of the element).

Horizontal alignment

The second character in “align” can take one of the following values:

• L — completely to the left of the reference element (right margin of the calendar aligned to the left margin of the element).

• l — to the left of the element but may overlap it (left margin of the calendar aligned to the left margin of the element).

• c — horizontally centered to the element. Might overlap it, depending on the vertical alignment.

• r — to the right of the element but may overlap it (right margin of the calendar aligned to the right margin of the element).

• R — completely to the right of the element (left margin of the calendar aligned to the right margin of the element).

Default values

If the “align” parameter is missing the calendar will choose “Bl”. This resembles the behavior of older versions (prior to 0.9.3) which did not support custom alignment.

4.3.12  Calendar.setDate

Receives a JavaScript Date object. Sets the given date in the calendar. If the calendar is visible the new date is displayed immediately.

calendar.setDate(new Date()); // go today

4.3.13  Calendar.setMondayFirst

Changes the first day of week. If the parameter is true then Monday will be the first day of week, otherwise Sunday.

calendar.setMondayFirst(false); // use Sunday

4.3.14  Calendar.parseDate

Use this function to parse a date given as string and to move the calendar to that date.

The algorithm tries to parse the date according to the format that was previously set with Calendar.setDateFormat; if that fails, it still tries to get some valid date out of it (it doesn’t read your thoughts, though).

calendar.parseDate("2003/07/06");

4.3.15  Calendar.setRange

Sets the range of years that are allowed in the calendar. Synopsis:

calendar.setRange(1970, 2050);

5  Side effects

The calendar code was intentionally embedded in an object to make it have as less as possible side effects. However, there are some—not harmful, after all. Here is a list of side effects; you can count they already happened after calendar.js was loaded.

1. The global variable window.calendar will be set to null. This variable is used by the calendar code, especially when doing drag & drop for moving the calendar. In the future I might get rid of it, but for now it didn’t harm anyone.

2. The JavaScript Date object is modified. We add some properties and functions that are very useful to our calendar. It made more sense to add them directly to the Date object than to the calendar itself. Complete list:

   1. Date._MD = new Array(31,28,31,30,31,30,31,31,30,31,30,31);

   2. Date.SECOND = 1000 /* milliseconds */;

   3. Date.MINUTE = 60 * Date.SECOND;

   4. Date.HOUR = 60 * Date.MINUTE;

   5. Date.DAY = 24 * Date.HOUR;

   6. Date.WEEK = 7 * Date.DAY;

   7. Date.prototype.getMonthDays(month) — returns the number of days of the given month, or of the current date object if no month was given.

   8. Date.prototype.getWeekNumber() — returns the week number of the date in the current object.

   9. Date.prototype.equalsTo(other_date) — compare the current date object with other_date and returns true if the dates are equal. It ignores time.

   10. Date.prototype.print(format) — returns a string with the current date object represented in the given format. It implements the format specified in section 4.3.5.

6  Credits

The following people either sponsored, donated money to the project or bought commercial licenses (listed in reverse chronological order). Your name could be here too! If you wish to sponsor the project (for instance request a feature and pay me for implementing it) or donate some money please please contact me at mishoo@infoiasi.ro.

• Himanshukumar Shah

• Seyhan Ersoy (http://www.oocgi.com)

• Jon Stokkeland (http://www.sauen.com)