Zapatec DHTML Calendar Quick Guide

Contents

[Table of contents not generated; rerun TeX2page]

1  Get the Zapatec DHTML Calendar files

1.1  Download the Zip file

The DHTML Calendar files are bundled in a zip file. Click on 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 file zpcal.zip.

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

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

2  Create a Calendar with 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 visually select the Language, Theme, Size, Style, and more. Once you have made your selections, the Wizard will create the code you need to place 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 will update as you choose the features you want so that you can see what the end result will be. This is a case of "What You See is What You Get" (WYSIWYG). Click on Next and Previous to move through the panes, or choose a specific pane from the menu on the left hand side.

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 your calendar to display smaller, check the box that says "Use the small version." Keep in mind that later selections, such as show other months, will affect calendar size.

Watch the DHTML Calendar on the screen as it changes with your selections. You can change your selections to view different themes and languages. Keep in mind that later selections, such as show other months, will affect calendar size.

2.5  Basic Setup

2.5.1  First day of week

Select the first day of week by using the drop-down box.

2.5.2  Show week numbers

Check if you want the Calendar to display week numbers. The Calendar can calculate and display week numbers using the ISO 8601 standard. This can be very handy for someone who needs to know which week of the year they are working with.

2.5.3  Show other months

Check Show other months if you want the calendar to display days from adjacent months. Note that calendars that display days from other months are fixed size – they always display six weeks. Calendars that don’t display days from other months will sometime display five weeks and other times six.

2.5.4  Show Time

Check to have your users prompted to enter a time as well as a date.

2.5.5  Time Format

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

2.5.6  Year Step

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

2.5.7  Date and time formats

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

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

2.6  Events

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

2.7  Generate

When you click "Generate" the code for your calendar will display in a window on this screen. You can copy this code and paste it into your HTML document for a quick-and-easy calendar setup!

3  Quick Startup (Without Wizard)

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’s a description of the project files, excluding documentation and example files.

3.1.1  The zpcal folder

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 demo folder holds examples of many of the types of calendars you can use. It is a great resource for examples of usage and the HTML code needed to make it happen.

3.1.4  The doc folder

The doc folder contains all of the help and support files to assist you with the Calendar. Help is provided in HTML, and PDF formats with and without screenshots for ease of use and display.

3.1.5  The lang folder

The language folder contains up to twenty different languages - from English to French, Spanish, Italian and more - to provide you with the greatest possible versatility and ease of use for you and your end-users. Afrikaans, English, French, German, Spanish, Finnish, Croatian, Hungarian, Italian, Romanian, Slovenian, and Turkish are currently available.

3.1.6  The themes folder

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

3.2  Set Up Your Calendar

3.2.1  insert the headers

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

<link rel="stylesheet" type="text/css" href="themes/winxp.css"/>
<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"/>

The five lines point to five different files located in the calendar folder. The files are:

3.2.2  Path Warning

If your web page containing the Calendar is saved in the calendar folder, the above lines will work without any changes. If, however, you save your web page in another location (like directly under your website’s root folder), you will need to add the folder information to the front of the file path so that your web page can read these files. For instance if you keep the files in the zpcal folder you should include the following lines:

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

3.3  Create the Calendar Form

Most web developers use the Zapatec HTML Calendar with forms. The most basic form of setup is to create a small form with a text box and a button.

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="f_trigger_b">...</button>
</form>

Quick Start: paste this code into the body of your document.

3.4  Insert the Calendar configuration code

Now, insert the code that makes the calendar pop up when your form is used. The following code should be pasted 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>

Quick Start: paste this code into the body of your document AFTER the </form> tag.

3.5  Copy your files to your web server

Using your editing or FTP program, copy or "put" 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 choosing to include a different file in your header.

3.7.1  Use a Different Themes

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 between several themes by changing the file called by the path. Look in the themes folder for more options.

1. Theme 1 - Windows XP Use this line:

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

Get this result: Windows XP Theme:

Winxp Calendar

2. Theme 2 - Green Use this line:

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

Get this result: Green Theme

Green Calendar

3.7.2  Use a Different 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, and it is being called from the lang folder. To change the language, change the file name to one of those in the lang directory. Examples are:

English: <script type="text/javascript" src="lang/calendar-en.js"></script>
French: <script type="text/javascript" src="lang/calendar-fr.js"></script>
Italian: <script type="text/javascript" src="lang/calendar-it.js"></script>

3.8  Customize Setup 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 section. For readability the options are displayed one on a line. Javascript syntax requires that there be a comma after each option except for the last one.

3.8.1  Change to Flat Calendar

The flat version of the Zapatec DHTML Calendar is simply one that displays on the page all the time instead of popping up when clicked. To make the Zapatec DHTML Calendar flat, you need to put it in a placeholder like a table or a div on your web page. Here is an example using a div to hold the calendar:

Paste this code into the body of your html file:

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

The div is the container that holds your calendar.

Now, we will use JavaScript to put the calendar inside the DIV. Important: the JavaScript code must be placed after the div code. Paste the following code after your div container code:

<script type="text/javascript">
Zapatec.Calendar.setup( {
flat         : "calendar-container" // ID of the parent element
});

3.8.2  Change date and time format

ifFormat":       "%Y/%m/%d";

The "%Y/%m/%d" tells the calendar to display the date as year/month/day. You can change this in many ways. For example, "%B %d, %Y " tells the calendar to display the date as month day, year (capital B is for month, lower-case d for day, and capital Y for a four-digit year.

Some common abbreviations you can use are as follows. In the case of capital letters, you can often set an abbreviated version by using lower-case. For example, if you want January spelled out, use capital B. If you want January displayed as Jan, use lower-case b.

%A full weekday name (user lower-case for abbreviated)

%B full month name (user lower-case for abbreviated)

%d the day of the month ( 00 .. 31 )

%Y year including the century ( ex. 1979 ) (user lower-case for a two-digit year)

For a full list of the formatting abbreviations, see the Date Parameters section of the programmer’s manual.

3.8.3  Show time

showsTime:true,

When true will prompt for time as well as date.

3.8.4  Time Format

timeFormat: "24",

Changing the "24" to "12" will change the time display on your calendar from a 24-hour to a 12-hour clock.

4  Sample Calendar Configurations

The following are a few of the many different ways in which you can use and present the Calendar.

4.1  Basic Single click

(example: 2004-11-02 [45] 15:11)

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: label, text box, and button

Display the calendar by clicking on the "..." button You can select the Year, Month, and Date using your mouse button or keyboard commands (listed above). Click the date you want with your mouse button or press the <Enter> key to select.

4.2  Double click, with time

(example: 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: text box and button Set the showsTime parameter to true and singleClick to false.

4.3  Multiple Months

(example: Tue, Sep 2, 2005 [03:12 PM])

Zapatec.Calendar.setup({
inputField     :    "sel2",     // id of the input field
button         :    "button2",  // trigger button 
showsTime      :     true,      // show time as well as date
timeInterval   :     15,        // allow minutes to change at intervals of 15
numberMonths   :     6,         // show 6 months in this calendar
controlMonth   :     2,         // month 2 (row 1, col 2) is current, notice how month 1 is previous month
monthsInRow    :     3          // show 3 months in a row
});

Form elements: text box and button Shows 6 calendars, 3 on each row. The second calendar (row 1, col 2) is the Control month, which is current month

You can have a maximum of 12 months.
monthsInRow:  You can have a maximum of 6 months in a row.
controlMonth: Which month contains the start date?  Default is 1.
vertical:     You can have the months displayed horizontally (default) or vertical.

Ex: I want to show the full year starting January 1, 2005.  There should be 3 months in each row.

numberMonths   : 12,        // show 6 months in this calendar
monthsInRow    : 3,         // show 3 months in a row
date           : new Date("January 1, 2005")  // Set Control month to January

           Horizontal           Vertical
         Jan  Feb  Mar        Jan  May  Sep
         Apr  May  Jun        Feb  Jun  Oct
         Jul  Aug  Sep        Mar  Jul  Nov
         Oct  Nov  Dec        Apr  Aug  Dec

Notice how Horizontal shows the next month horizontally (next column) and Vertical shows the next month 
vertically (next row).  Again, the default is Horizontal (vertical:false).

Ex: I want to show Previous, Current, and Next month

numberMonths   : 12,        // show 6 months in this calendar
controlMonth   : 2

If the current month is Sep then the calendar will display

          Aug  Sep  Oct
                |____________Control Month

Green Calendar

5  DHTML Calendar Setup Detailed Parameters

Here is the complete list or properties that can be interpreted by calendar.setup. All of them have default values, so you can pass only those which you would like to customize.

You must pass at least one of the following: inputField, displayArea or button to set up a popup or flat DHTML calendar. If you do not, you will get a error message indicating that there’s nothing to set up.

property type description default

align

string Alignment of the calendar, relative to the reference element. The reference element is dynamically chosen like this: if a displayArea is specified then it will be the reference element. Otherwise, the input field is the reference element. For the meaning of the alignment characters please section sec:Calendar.showAtElement. Bl

button

string The ID of the button, image, or other element that triggers the calendar. null

cache

boolean Set this to “true” if you want to cache the calendar object. This means that a single calendar object will be used for all fields that require a popup calendar false

closeEventName

string Name of the event that triggers the closing of the calendar without the “on” prefix. There’s no default event, but the calendar will close if one of the following happens: the user clicks (in single-click mode), or clicks a second time (in double-click mode) on a date, clicks on the "X" or clicks outside the calendar area. None.

controlMonth

integer Use with numberMonths. Which month in the Multiple Month calendar is the start date? For example, if the current month is Sep and I have numberMonths=3 and controlMonth=2 then my calendar will have Aug,Sep,Oct. 1

daFormat

string Format of the date displayed in the displayArea (if specified). %Y/%m/%d

date

date This allows you to setup an the default date for the calendar. positioned to. If absent then the calendar will open to the today date. today

dateStatusFunc

function A function that receives a JS Date object and returns a boolean or a string. This function allows one to set a certain CSS class to some date, therefore making it look different. If it returns true then the date will be disabled. If it returns false nothing special happens with the given date. If it returns a string then that will be taken as a CSS class and appended to the date element. If this string contains “disabled” then the date is also disabled (therefore is like returning true) but with your own custom style. For more information please refer to section sec:Calendar.setDateStatusHandler. null

displayArea

string This is the ID of a <span>, <div>, or any other element that you would like to use to display the current date. Useful in flat calendars or if the input field is hidden, as an area to display the date. null

electric

boolean Not applicable with single-click. With double-click setting to true (default) fields/date areas are updated for each click; otherwise they are updated only on close. true

eventName

string Name of the event that triggers the calendar without the “on” prefix (default click). For instance use“click” instead of “onclick”. Virtually all users will want to let this have the default value (“click”). But, it could be useful if, for example, you want the calendar to appear when the input field is focused and have no trigger button (in this case use “focus” as the event name). click

firstDay

integer Specifies which day is to be displayed as the first day of week. Possible values are 0 to 6; 0 means Sunday, 1 means Monday, ..., 6 means Saturday. The end user can easily change this too, by clicking on the day name in the calendar header. 0

flat

string To create a flat calendar pass the ID of the object where the calendar will be created. null is the default value). null

flatCallback

function You should provide this function if the calendar is flat. It will be called when the date in the calendar is changed with a reference to the calendar object. See section sec:quick-start-flat for an example of how to set up a flat calendar. null

ifFormat

string The format string that will be used to enter the date in the input field. This format will be honored even if the input field is hidden. %Y/%m/%d

inputField

string The ID of your input field. This is where the date/time users chose goes. null

multiple

array of dates Allow choosing multiple days in the calendar. The javascript array that you pass as the argument contains the array of dates initially chosen. The user can than click to select or deselect dates in the calendar. Single-click or double-click don’t apply in here. The user needs to explicitly close the calendar by clicking on the "X" button. null

monthsInRow

integer Use with numberMonths. How many months do you want in a row? You can have a maximum of 6 in a row. 1

numberMonths

integer How many months do you want the calendar to display? You can have a maximum of 12 months. 1

onClose

function This handler will be called when the calendar needs to close. If you set a handler here, it is your responsibility to hide/destroy the calendar. Check the calendar-setup.js file for an example. null

onSelect

function Function that gets called when a date is selected. You don’t have to supply this (the default is generally OK). If you do provide a handler, you will have to manage the “click-on-date” event by yourself. Look in the file calendar-setup.js and use the onSelect handler that you can see in it as an example. null

onUpdate

function function that gets called after the date is updated in the input field. Receives a reference to the calendar. after the target field is updated with a new date. You can use this to chain two calendars. For example you can setup a default date in the second calendar after a date was selected in the first. null

position

array Specifies the [x, y] position, relative to page’s top-left corner, where the calendar will be displayed. If not passed then the position will be computed based on the “align” parameter. Defaults to “null” (not used). null

range

array An array having exactly 2 integers. The first [0] element is the first year allowed, and the second [1] element is the last year allowed. [1900, 2999]

saveDate

integer Will save the date in a cookie for the number of days set in the parameter. Will then populate the textbox as a default with the saved date so that when users come back to the web site, the last date they chose is the default. null

showOthers

boolean If set to “true” if you want the calendar to display days from adjacent months. Note that calendars that display days from other months are fixed size – they always display six weeks. Calendars that do not display days from other months will sometimes display five weeks and at other times six. false

showsTime

boolean When set to true the calendar lets users select the time as well as the date. false

singleClick

boolean Whether the calendar is in single click mode or not (default: true). Notice that double-click is somewhat a misnomer. It’s not the quick double click that often used when opening a program. It means that rather than submitting the data right away when the user clicks on a date, the calendar will stay open. Only when the user clicks on the same date a second time will the data be submitted. true

sortOrder

string For multiple flat calendar. Can be set to "asc", "desc", or "none" for ascending, descending or no sorting of the dates the user chose. See the multiple option above and section sec:quick-start-flat for an example of a flat calendar. none

step

integer Configures the step in the year drop-down menus. So setting it to 5 will display 1900, 1905, 1910, ... 2

timeFormat

string The time format; can be "12" or "24". “24”

timeInterval

integer How do you want to allow the user to change the time? Allowed number of minutes:1, 2, 3, 4, 5, 6, 10, 15, 30, 60, 120, 180, 240, 300, 360 null

vertical

boolean Use with numberMonths. If “true” the calendar will display the next consecutive month on the next row, instead of the next column. false

weekNumbers

boolean If “true” the calendar will display week numbers. Week numbers are displayed using the ISO 8601 standard. true

Last modified: Thursday, May 4th, 2006 4:09:20pm