Zapatec DHTML Calendar Manual

Contents

    1  Get the Zapatec DHTML Calendar files
        1.1  Download the Zip file
        1.2  Unzip zpcal.zip

    2  Create a Calendar with the Wizard
        2.1  What does the Wizard do?
        2.2  How to Start the Wizard
        2.3  Using the Wizard
        2.4  Theme and Language
        2.5  Basic Setup
            2.5.1  First day of week
            2.5.2  Show week numbers
            2.5.3  Show adjacent months
            2.5.4  Show Time
            2.5.5  Time Format
            2.5.6  Year Step
        2.6  Date and time formats
        2.7  Multiple Months
            2.7.1  Number of Months
            2.7.2  Control Month
            2.7.3  Months in a Row
            2.7.4  Vertical Months
        2.8  Test and Generate

    3  Quick Startup (Without Wizard)
        3.1  Project Files
            3.1.1  The zpcal folder
            3.1.2  The src folder
            3.1.3  The demo folder
            3.1.4  The doc folder
            3.1.5  The lang folder
            3.1.6  The themes folder
        3.2  Set Up Your Calendar
            3.2.1  Insert the Headers
            3.2.2  Path Warning
            3.2.3  Upgrade Warning
        3.3  Create a Form with a Calendar
            3.3.1  Insert the Form Code
        3.4  Insert the Calendar Code
        3.5  Copy Files to your Web Server
        3.6  Test the Calendar Application
        3.7  Change Included Files
            3.7.1  Change Theme
            3.7.2  Change Language
        3.8  Events

    4  Configuration Options
        4.1  align (string)
                Vertical alignment
                Horizontal alignment
        4.2  button (string)
        4.3  cache (boolean)
        4.4  closeEventName (string)
        4.5  controlMonth (integer)
        4.6  daFormat (string)
        4.7  date (date)
        4.8  dateStatusFunc (function)
        4.9  disableDrag (boolean)
        4.10  disableFunc (function)
        4.11  disableNavYear (boolean)
        4.12  displayArea (string)
        4.13  electric (boolean)
        4.14  eventName (string)
        4.15  fdowClick (boolean)
        4.16  firstDay (integer)
        4.17  flat (string)
        4.18  flatCallback (function)
        4.19  ifFormat (string)
        4.20  inputField (string)
        4.21  monthsInRow (integer)
        4.22  multiple (date[])
        4.23  noCloseButton (boolean)
        4.24  noHelp (boolean)
        4.25  numberMonths (integer)
        4.26  onClose (function)
        4.27  onSelect (function)
        4.28  onUpdate (function)
        4.29  position (array)
        4.30  range (integer [ ])
        4.31  saveDate(integer)
        4.32  showOthers (boolean)
        4.33  showsTime (boolean or string)
        4.34  singleClick (boolean)
        4.35  sortOrder (string)
        4.36  step (integer)
        4.37  timeFormat (string)
        4.38  timeInterval (integer)
        4.39  titleHtml (string or function)
        4.40  vertical (boolean)
        4.41  weekNumbers (boolean)

    5  Calendar API
        5.1  Public methods
            5.1.1  Calendar.create
            5.1.2  Calendar.callHandler
            5.1.3  Calendar.callCloseHandler
            5.1.4  Calendar.hide
            5.1.5  Calendar.setDateFormat
            5.1.6  Calendar.setTtDateFormat
            5.1.7  Calendar.setDateStatusHandler
            5.1.8  Calendar.setDateStatusHandler
            5.1.9  Calendar.show
            5.1.10  Calendar.showAt
            5.1.11  Calendar.showAtElement
            5.1.12  Calendar.setDate
            5.1.13  Calendar.setFirstDayOfWeek
            5.1.14  Calendar.parseDate
            5.1.15  Calendar.setRange

    6  Sample Calendar Configurations
        6.1  Basic Single Click Calendar
        6.2  Double Click With Time Calendar

    7  Side effects

1  Get the Zapatec DHTML Calendar files

1.1  Download the Zip file

The DHTML Calendar files are bundled in a zip file. Click the download link in the Calendar section of Zapatec’s web site and follow the instructions to download the file.

Save the file (zpcal.zip) to your website’s root folder on your computer or server.

1.2  Unzip zpcal.zip

  1. On your computer, go to the folder where you saved the zpcal.zip file.

  2. zpcal.zip contains a folder called zpcal that holds all of the files you need to create your calendar.

  3. Open or double-click zpcal.zip to unzip or unpack it.

2  Create a Calendar with the Wizard

You can create a Zapatec calendar with or without using the wizard.

2.1  What does the Wizard do?

The wizard generates the code for exactly the kind of calendar you want! It’s a Graphic User Interface (GUI) that allows you to select the language, theme, size, style, etc. for the calendar visually. After you have made your selections, the wizard generates the code you need to place the calendar in your HTML document, form, or application with the click of a button.

2.2  How to Start the Wizard

If you haven’t done so, follow the instructions in section 1.1. to download the Calendar files.

  1. Navigate to your DHTML Calendar folder (zpcal).

  2. Open the Wizard directory (folder).

  3. Open index.html in your Web browser.

2.3  Using the Wizard

The wizard page displays the calendar you are creating as you make your selections. It updates as you choose the features you want so that you can see what the end result will be.

Click the Next and Previous buttons to move through the panes, or choose a specific pane from the menu on the left side of the screen.

Click Next to move to the Theme and Language page and start creating your calendar.

2.4  Theme and Language

  1. Choose the language in which you want to present your calendar.

  2. Select the theme you want for your calendar.

  3. If you want a smaller calendar, check the box labeled "Use the small version." Keep in mind that certain options, such as showOthers, may affect the calendar size.

Watch the calendar on the screen as it changes with your selections. You can change your selections to view different themes and languages.

2.5  Basic Setup

2.5.1  First day of week

Select the first day of week from the drop-down menu.

2.5.2  Show week numbers

Check this box if you want the calendar to display week numbers. The calendar can calculate and display week numbers using the ISO 8601 standard.

2.5.3  Show adjacent months

Check this box if you want the calendar to display days from adjacent months to the current month. Calendars that display days from adjacent months are fixed-size. They always display six weeks. Calendars that do not display days from adjacent months sometimes display five weeks and sometimes six.

2.5.4  Show Time

Check this box to prompt users to enter a time as well as a date.

2.5.5  Time Format

If you checked "Show Time", you can choose a 12-hour or 24-hour clock.

2.5.6  Year Step

The years can be displayed with a certain interval the next or previous years. The next or previous year is always the first one displayed, no matter how many steps you choose between years. This is useful for drop-down year menus.

2.6  Date and time formats

To further customize your calendar, choose a date and time formats. Some examples of date formats are:

January 1, 2007
01-01-07
1/1/2007
01-Jan-07

2.7  Multiple Months

You can configure a calendar to display multiple months simultaneously.

2.7.1  Number of Months

Enter a number between one and twelve for the number of months of display in the calendar.

2.7.2  Control Month

In a calendar that displays multiple months, the control month is the month in which the default date (usually today’s date) is highlighted.

2.7.3  Months in a Row

This controls the layout of a calendar displaying multiple months. This value is the number of months to display in a single row. For example, for a calendar displaying six months, choosing three Months in a Row generates a calendar with two rows, three months in each row. However, choosing two Months in a Row generates a calendar with three rows, two months in each row.

2.7.4  Vertical Months

This box applies only to calendars with more than one row and more than one column. If the box is checked, the months are incremented vertically (February appears below January). If the box is clear, the months are incremented horizontally (February appears to the right of January).

2.8  Test and Generate

You can test the calendar until you are happy with its appearance and behavior. Click the Next button to generate the HTML for the calendar. Then copy and paste this code into your HTML document for a quick-and-easy calendar setup!

3  Quick Startup (Without Wizard)

This section describes how to create a calendar using HTML and Javascript.

If you have not done so follow the instructions in section 1.1. to download and unzip the Calendar files.

3.1  Project Files

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

3.1.1  The zpcal folder

This is the main directory containing all of the other directories and files.

3.1.2  The src folder

The src folder contains the JavaScript that makes the program work.

3.1.3  The demo folder

The calendar demos contain examples of different types of calendars. The demos are a great resource for examples of usage and the underlying code.

3.1.4  The doc folder

The doc folder contains documentation to assist you with the Calendar.

3.1.5  The lang folder

The language folder contains up all our supported languages to provide the greatest possible versatility and ease of use for your end-users. Supported languages include English, French, Spanish, Italian,Afrikaans, German, Finnish, Croatian, Hungarian, Italian, Romanian, Slovenian, and Turkish.

3.1.6  The themes folder

The themes folder contains the CSS files that control the aesthetics of your calendar.

3.2  Set Up Your Calendar

3.2.1  Insert the Headers

In your web editor (Dreamweaver, UltraEdit, etc.), open the web page in which you want to place the calendar. Insert your cursor before the ending </head> tag. Paste the following style path and script paths before the ending </head> tag:

<!-- Javascript Zapatec utilities file -->  
<script type="text/javascript" src="utils/zapatec.js"></script>
<!-- Javascript files to support calendar -->
<script type="text/javascript" src="src/calendar.js"></script>
<!-- Javascript files to set the language for the calendar --> 
<script type="text/javascript" src="lang/calendar-en.js"/></script>
<!-- CSS file for specifiying the theme -->
<link rel="stylesheet" type="text/css" href="themes/winxp.css"/> 

You can substitute a different language for the calendar by choosing a different language file from the lang folder.

You can substitute a different theme for the calendar by choosing a different CSS file from the themes folder. Specifying a CSS file int he headers is mandatory to support the Calendar.

3.2.2  Path Warning

If your web page containing the calendar is saved in the calendar folder, these lines work without any changes. If, however, you save your web page in another location (such as directly under your website’s root folder), you need to add the folder information to the front of the file path so that your web page can read these files.

3.2.3  Upgrade Warning

If you have been using a version of Zapatec calendar that is older than version 2.0 and are now migrating to the current version, you need to adjust the header files.

The older utils.js is no longer supported; it has been replaced by zapatec.js. In addition, calendar-setup.js is no longer required. To upgrade, replace the old lines:

<script type="text/javascript" src="src/utils.js"/> 
<script type="text/javascript" src="src/calendar.js"/> 
<script type="text/javascript" src="lang/calendar-en.js"/> 
<script type="text/javascript" src="src/calendar-setup.js"/>
<link rel="stylesheet" type="text/css" href="themes/winxp.css"/>

with

<script type="text/javascript" src="utils/zapatec.js"></script>
<script type="text/javascript" src="src/calendar.js"></script>
<script type="text/javascript" src="lang/calendar-en.js"/></script>
<link rel="stylesheet" type="text/css" href="themes/winxp.css"/> 

3.3  Create a Form with a Calendar

Most web developers use the Zapatec HTML Calendar with forms. You can create a small form with a text box and a button to build a simple calendar application.

3.3.1  Insert the Form Code

Name the text box "data" and give the button an id of "trigger".

<form action="#" method="get">
<input type="text" name="date" id="f_date_b" />
<button type="reset" id="trigger">...</button>
</form>

Paste this code into the body of your document.

3.4  Insert the Calendar Code

Insert the following code to make a calendar pop up when your form is used. Paste it directly after </form> and before </body>.

<script type="text/javascript">
Zapatec.Calendar.setup(
inputField  : "data", // This is the ID of your form's text field
ifFormat    : "%m %d, %Y", // Format in which you want the date returned
button      : "trigger" // "trigger" is the ID of the form's button
}
</script>
<noscript>
<br/>
This page uses a 
<a href='http://www.zapatec.com/products/prod1'> Javascript Calendar </a>, 
but your browser does not support Javascript. 
<br/>
Either enable Javascript in your Browser or upgrade to a newer version.
</noscript>

3.5  Copy Files to your Web Server

Using your editing or FTP program, copy your web page and the entire calendar folder to the root of your website.

3.6  Test the Calendar Application

Using your web browser, navigate to the web page that you created to include the Zapatec HTML Calendar. Click the "trigger" button to see if the calendar pops up. Click a date to select it and make sure that the date displays in the empty box. Congratulations! You have set up the most basic version of the Zapatec HTML Calendar! Now, on to the fun and exciting features you can change with this highly adaptable application!

3.7  Change Included Files

You can change the theme or language of the calendar by including a different file in the header.

3.7.1  Change Theme

One of the lines you inserted in Section 3.2.1 includes the winxp.css file in the themes folder. WinXP is one of the themes that comes with the Zapatec DHTML Calendar. You can choose among several themes by changing the file called by the path. Look in the themes folder for more options.

For example, to use the WinXP theme, insert this line:

<link rel="stylesheet" type="text/css" href="themes/winxp.css"/>

This produces a calendar with the WinXP theme, like the one in the Saving Dates in Cookies Demo.

Or to use the Green theme, insert:

<link rel="stylesheet" type="text/css" href="themes/green.css"/>

for a calendar with the Green theme like the one in the Flat Calendar, Different Look for Special Days Demo.

3.7.2  Change Language

One of the lines you inserted in Section 3.2.1 was

<script type="text/javascript" src="lang/calendar-en.js"/>

This line controls the language in which your calendar is displayed. The file called here is calendar-en.js, the English file. You can choose among several languages by changing the file called by the path. For example, for French use

<script type="text/javascript" src="lang/calendar-fr.js"></script>

or for Italian:

<script type="text/javascript" src="lang/calendar-it.js"></script>

Look in the lang folder for more language files.

3.8  Events

Events cause the calendar perform a specific action based on the user’s actions. For example, you can have the calendar display a tip of the day tool tip when the user first clicks it. In this case, the event would be the onClick event.

The following example sets up a handler called "cal_submit_days" for the onClick event:

<input type='button' value='Submit Days' onclick='cal_submit_days()' 
	title='Submit Button'>

4  Configuration Options

In Section 3.4, you saw how to create a calendar by inserting the Calendar.setup javascript code. You can customize the calendar by setting various options in the setup code.

This section describes the calendar configuration options.

One of the following options is required: inputField, displayArea or button.

4.1  align (string)

This is the alignment of the calendar relative to its containing element. The string consists of two characters. The first specifies the veritcal alignment and the second the horizontal alignment.

For example,

align : "BR";

positions the calendar completely below and to the right of its containing element.

The default is "Bl".

below are the letters used to specify alignment.

Vertical alignment

The first character in the align string is one of the following:

Horizontal alignment

The second character in the align string is one of the following:

4.2  button (string)

This is the ID of or DOM element reference to the button, image, or other element that triggers a popup calendar.

4.3  cache (boolean)

If this option is true, the calendar object is re-used whenever possible. The default is false.

4.4  closeEventName (string)

This is the name of the event that closes a calendar.

By default, a calendar will close if one of the following happens:

4.5  controlMonth (integer)

In a calendar that displays multiple months, the control month is the month against which all controls are applied. Thus the default date (usually today’s date) is highlighted in the control month and the current year is the year of the control month.

The argument is a value between one and twelve specfiying the control month. The default is 1.

This option is used with the numberMonths option.

4.6  daFormat (string)

This is the date format of a date stored in a display area. See the displayArea option.

The characters used to define the format are the same as those listed for the ifFormat option.

The default is "%Y/%m/%d".

4.7  date (date)

This is the date that the calendar displays initially. The default is today’s date.

4.8  dateStatusFunc (function)

This is an optional function that can be used to change the appearacnce of a specific date.

The function takes as input a Javascript date object and returns a boolean or a string. The returned value is interpreted as follows:

4.9  disableDrag (boolean)

If set to true, the user cannot drag the calendar. The default is false.

4.10  disableFunc (function)

This is an optional function used to disable a date. It takes as input a Javascript data object and returns true if the date should be disabled.

4.11  disableNavYear (boolean)

This option disables the calendar’s year navigation buttons. The default is false.

4.12  displayArea (string)

This is the ID of or DOM element reference to the area, such as <span> or <div>, that contains the date.

4.13  electric (boolean)

If this option is true, when the singleClick option is false, date displays are updated for each click. Otherwise they are updated only on close. This setting is not valid if singleClick is true.

The default is true.

4.14  eventName (string)

This is the name of the event that triggers a popup calendar. The default is "click".

4.15  fdowClick (boolean)

If this option is true, the user can select any day of the week, including the first. If this option is false, the first day of the week is not selectable.

4.16  firstDay (integer)

This option specifies the day that the calendar displays as the first day of the week. The argument is a number between zero and six. Zero indicates Sunday, 1 Monday, etc. The default is zero.

4.17  flat (string)

A flat calendar is one that is visible when the page loads, in contrast to the default popup calendar, which appears in response to a click event.

The string passed to this option is the ID of the flat calendar’s container. The default is null.

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

Zapatec.Calendar.setup( {
flat         : "calendar-container" 
});

4.18  flatCallback (function)

This is the optional callback function for a flat calendar. It is invoked when the date in the calendar is changed with a reference to the calendar object.

The callback takes as input a Javascript date object and returns a URL.

4.19  ifFormat (string)

This is the date format of a date stored in an input field. See the inputField option. Combine the characters in the string passed to ifFormat to describe the date format.

For example,

ifFormat : "%a, %b %e, %Y";

formats the date as Mon, Apr 24, 2006.

The following table lists the characters used to define a date format.

%a abbreviated weekday name
%A full weekday name
%b abbreviated month name
%B full month name
%C century number
%d the day of the month ( 00 .. 31 )
%e the day of the month ( 0 .. 31 )
%H hour ( 00 .. 23 )
%I hour ( 01 .. 12 )
%j day of the year ( 000 .. 366 )
%k hour ( 0 .. 23 )
%l hour ( 1 .. 12 )
%m month ( 01 .. 12 )
%M minute ( 00 .. 59 )
%n a newline character
%p "PM" or "AM"
%P "pm" or "am"
%S second ( 00 .. 59 )
%s number of seconds since Epoch (since Jan 01 1970 00:00:00 UTC)
%t a tab character
%U, %W, %V the week number
%u the day of the week ( 1 .. 7, 1 = MON )
%w the day of the week ( 0 .. 6, 0 = SUN )
%y year without the century ( 00 .. 99 )
%Y year including the century ( ex. 1979 )
%% a literal % character

The am/pm and AM/PM formats designated by %p and %P are provided automatically only when the the English language file (calendar-en.js) is used. For other languages they are ignored by default. However, if you want to include this functionality for another language, add the following line to the language file you are using:

Zapatec.Calendar._TT._AMPM = {am : "am", pm : "pm"};

You can also customize the string that is displayed for am and pm by editing the string; for example:

Zapatec.Calendar._TT._AMPM = {am : "morning", pm : "afternoon"};

4.20  inputField (string)

This is the ID of or DOM element reference to the input field that contains the selected date.

4.21  monthsInRow (integer)

In a calendar that displays multiple months, monthsInRow controls the calendar’s layout. This argument is the number of months to display in a single row. For example, for a calendar displaying six months, choosing three generates a calendar with two rows, three months in each row. However, choosing two generates a calendar with three rows, two months in each row.

4.22  multiple (date[])

This option allows users to select multiple days in a calendar. It also permits multiple dates to be selected programatically. The array of dates stores the selected dates.

When a calendar is created with the multiple option, the user must explicitly close it by clicking its close button.

The array of dates can be sorted. See the sortOrder option.

4.23  noCloseButton (boolean)

This option hides the calendar’s close button. The default is false.

4.24  noHelp (boolean)

This option turns off the Help question mark (?) that normally appears in the top left corner of a calendar. If noHelp is true, the question mark is not displayed. The default is false.

4.25  numberMonths (integer)

This option specifies a calendar that displays multiple months. The argument is a value between one and twelve specfiying the number of months to display.

See also the vertical option.

4.26  onClose (function)

This is an optional function to invoke when the calendar is closed.

4.27  onSelect (function)

This is an optional function to invoke when a date is selected. If this option is defined, the function must handle the "click-on-date" event.

Usually the default handler works for most applications.

4.28  onUpdate (function)

This is an optional function to invoke when the date is updated in the input field.

As input, the function takes a reference to the calendar after the target field has been updated with a new date.

This feature is useful for chaining two calendars. For example, you can set up a default date in the second calendar based on the date selected in the first.

4.29  position (array)

This option specifies the [x, y] coordinates of the calendar’s position relative to the top-left corner of the page. If not used, the calendar is positioned based on the align option.

4.30  range (integer [ ])

This option specifies the range of years covered by the calendar.

The argument is an array of two integers. The first [0] is the first year allowed in the calendar, and the second [1] is the last year allowed. The default is [1900, 2999].

4.31  saveDate(integer)

This option saves the current date in a cookie. The argument is the number of days that the date will be saved.

When users return to the web site, this option allows the calendar to populate the date field with the saved date.

4.32  showOthers (boolean)

If this option is true, the calendar displays days from months adjacent to the current month. Calendars that display days from other months always display six weeks. Calendars that do not display days from other months sometimes display five weeks and at other times six.

4.33  showsTime (boolean or string)

Valid parameters are true, false, or "seconds".

If this option is true, the calendar displays the date and time to the nearest minute.

If it is "seconds", the calendar displays the date and time to the nearest second.

If it is false, the calendar displays only the date.

4.34  singleClick (boolean)

If this option is true, a single click submits an action in a calendar.

If it is false, two clicks are required to submit. In this case, rather than submitting the data as soon as the user clicks a date, data is not submitted until the user clicks the same date a second time.

The default is true.

4.35  sortOrder (string)

This option determines the order in which multiple selected dates are stored. It is valid only for a flat calendar in which the multiple option is true. See the multiple option.

Valid values are "asc" for ascending order, "desc" for decending order, and "none" for no sorting..

4.36  step (integer)

This is the interval between years that are displayed in the year drop-down menus. For example, a setting of 5 offers 1900, 1905, 1910, etc. The default is 2.

4.37  timeFormat (string)

This is the time format. Valid values are "12" and "24". The default is "24".

4.38  timeInterval (integer)

This option sets the interval, in minutes, by which the user can change the time. Allowed values are: 1, 2, 3, 4, 5, 6, 10, 15, 30, 60, 120, 180, 240, 300, 360.

4.39  titleHtml (string or function)

This option displays a title in a single-month or multi-month calendar. The title can be a simple string or a function to allow the title to be set dynamically.

The following example sets the title based on the current control month in a multi-month calendar.

titleHtml     : function(strTitle, month, year) {
	return "Control Month is " +  Zapatec.Calendar.i18n(month, "mn")

4.40  vertical (boolean)

If this option is true and multiple months are displayed, the calendar displays the next consecutive month in the next row, instead of in the next column Use with the numberMonths option.

The default is false.

4.41  weekNumbers (boolean)

If this option is true, the calendar displays the week numbers. The default is true.

5  Calendar API

5.1  Public methods

5.1.1  Calendar.create

This function creates the HTML elements that are needed to display the calendar. Call it after setting the calendar properties.

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

The function creates a popup or a flat calendar. If the parent argument is present (it should be a reference, not an ID, to an HTML element), a flat calendar is created and it is inserted in the specified element.

Given a reference to a calendar object, you can use the boolean member variable isPopup to see if it is a popup or a flat calendar:

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

5.1.2  Calendar.callHandler

This function calls the user-defined onSelect callback with the required parameters.

5.1.3  Calendar.callCloseHandler

This function calls the user-defined onClose callback. It is useful for creating a "single-click" calendar that closes if a date is clicked.

5.1.4  Calendar.hide

Call this function to hide the calendar. It does not destroy the calendar object and HTML elements. You can later call one of the show functions on the same element.

5.1.5  Calendar.setDateFormat

This function configures the format in which the calendar reports the date to the "onSelect" handler.

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

See the table in Section 4.19 for details about specifying a date format.

5.1.6  Calendar.setTtDateFormat

This function sets the format of the date displayed in the status bar when the mouse is hovering over a date. The format specification is similar to that of Calendar.setDateFormat.

5.1.7  Calendar.setDateStatusHandler

This function sets the callback for disabling and customizing specific dates and times. The callback returns a boolean or a string. If the return value is true, the date is disabled and the user cannot click it. If it is false, the date is enabled.

If the returned value is a string, the date gets an additional CSS class, which is the returned value. You can use this feature to highlight some dates. You are responsible for defining the CSS class that you return. If you return a string that contains "disabled", the date will be disabled, just as if you returned true. This feature provides a way to display disabled dates in a customized way.

For example, you could define .special in some of your styles or in the document header in a STYLE tag. Place this definition after the the calendar styles are loaded:

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

Then you would insert the following code before calling Calendar.create(). It adds the "special" class name to dates that are defined in the SPECIAL_DAYS table. Other dates will simply be displayed as default, enabled.

// 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);

5.1.8  Calendar.setDateStatusHandler

You can disable specific times as well as dates using the setDateStatusHandler.

In the following example, the calendar calls the timeOutOfRange callback on two events: when the date changes and when the time changes. To see which event it is, check if the hours variable is defined. Here the user is limited to 11AM - 5PM on Saturdays and 8AM to 9:45 PM on Fridays.

function timeOutOfRange(date, year, month, day, hours, minutes) {
	if (date.getDay() == 0) { //No Sunday
		return true;
	}
	if (typeof(hours) != "undefined") {
		if (date.getDay() == 6) {
			//only allow 11AM to 5PM on Saturday
			if (hours < 17 && hours >= 11) {
				return false;
			} else {
				return true;
			}
		}

		//on saturdays allow
		if (date.getDay() == 5) {
			//only allow 8AM to 9:45PM on Friday
			if (hours > 21 || hours < 8) {
				return true; //not within the hours
			}

			if (hours != 21) {
				return false; //within the hours
			}

			//hours = 21
			if (minutes <= 45) {
				return false;
			} else {
				return true;
			}
		}

	}
	return false;
}

Zapatec.Calendar.setup({
inputField     :    "sel9",     // id of the input field
singleClick    :     false,     // require two clicks to submit
ifFormat       :    '%a, %b %e, %Y [%H:%M]',     // format of the input field
ampm           :     false,
showsTime      :     true,     // show time as well as date
button         :    "button9",  // trigger button
dateStatusFunc :    timeOutOfRange,
floating       :    true
});

5.1.9  Calendar.show

Call this function to show the calendar. It sets the CSS display property to "block". It does not modify the calendar position.

This function is valid only for popup calendars.

5.1.10  Calendar.showAt

Call this function to show the calendar at the position specified by the passed [x, y] coordinates.

calendar.showAt(x, y);

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

After setting the given coordinates the function calls Calendar.show.

This function is valid only for popup calendars.

5.1.11  Calendar.showAtElement

This function is used to display the calendar near a specific element.

calendar.showAtElement(element, align);

where element is a reference to your element, such as the input field that displays the date. Align is an optional parameter, of type string, containing one or two characters.

Align can contain one or two characters. The first character dictates the vertical alignment relative to the element, and the second character dictates the horizontal alignment. See the description of the align option at 4.1 for details about the valid values and defaults for this parameter.

5.1.12  Calendar.setDate

Sets the Calendar to the date passed in the parameter. This parameter needs to be a JavaScript Date object. If the calendar is visible the new date is displayed immediately.

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

5.1.13  Calendar.setFirstDayOfWeek

This function changes the first day of week. The parameter is a numeric value ranging from 0 to 6. Pass 0 for Sunday, 1 for Monday, ..., 6 for Saturday.

calendar.setFirstDayOfWeek(5); // start weeks on Friday

5.1.14  Calendar.parseDate

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

The algorithm first tries to parse the date according to the format previously set with Calendar.setDateFormat. If that fails, it uses other methods to get a valid date.

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

5.1.15  Calendar.setRange

This function sets the range of years allowed in the calendar.

calendar.setRange(1970, 2050);

6  Sample Calendar Configurations

Here are two of the many different ways in which you can present a calendar.

6.1  Basic Single Click Calendar

Format: 2004-11-02 [45]

Zapatec.Calendar.setup({
inputField     :    "sel1",     // id of the input field
ifFormat       :    "%Y-%m-%d [%W] %H:%M",     // format of the input field
button         :    "button1",  // What will trigger popup of the calendar
showsTime      :     false      //don't show time, only date
});

Form elements include a label, text box, and button.

In the Basic Calendar, Single Click Demo, you can display the calendar by clicking the "..." button. You can select the year, month, and date with mouse button or keyboard commands. Click the date you want to display with your mouse button or press the <Enter> key to select it.

6.2  Double Click With Time Calendar

Format: Tue, Nov 2, 2004 [03:12 PM])

Zapatec.Calendar.setup({
inputField     :    "sel2",     // id of the input field
singleClick    :     false,     // require two clicks to submit
ifFormat       :    '%a, %b %e, %Y [%I:%M %p]', // format of input field
showsTime      :     true,     // show time as well as date
button         :    "button2"  // trigger button 
});

Form elements a text box and button set.

See the Double Click, with Time Demo.

7  Side effects

Here are some side effects that you may experience when the DHTML calendar code in embedded in an object:

  1. The global variable window.calendar is initially set to null. This variable is used by the calendar code, especially when doing drag & drop for moving the calendar.

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

    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 5.1.5.

Last modified: Wednesday, November 29th, 2006 11:18:35am