affordable web development services

Tigra Calendar v4.0 - Documentation

Description
Features
Files
Initialization
Calendar Settings
Troubleshooting
License
Links and References

Description

Tigra Calendar is a free cross-browser JavaScript Calendar control, it improves the user experience by enabling a drop-down calendar for date fields in HTML forms.

Features

Uses document layers - no problems with pop-up blockers
Easy customization via CSS file
Simple localization
Attaches to existing form fields
Can be created dynamically - perfect for AJAX applications
Multiple popular date formats are supported (American, European, Database)
Efficient, well formatted code - great learning source for students
Easy setup - no programming skills required
Works in all modern browsers
Can be used in any kind of web applications (PHP/ASP/CGI etc.)
Public domain software - FREE for any use

Files

Tigra Calendar script consists of several files:

calendar_??.js - Calendar script file for a specific format. Following files are included:

calendar_us.js - for American format (mm/dd/yyyy)
calendar_eu.js - for European format (dd-mm-yyyy)
calendar_db.js - for Database Format (yyyy-mm-dd)

calendar.css - Calendar style file
img/*.* - Calendar images

Every page utilizing the calendar should have one of the calendar script files and the style file linked to it. The recommended location for links it the document's header:

<html>
<head>
	<title>Document's Title</title>
	<script language="JavaScript" src="calendar_us.js"></script>
	<link rel="stylesheet" href="calendar.css">
</head>
<body>
...

Notes:

The suggested layout is ideal for most cases, but if needed, the content of calendar's JS and CSS files can be merged into the main HTML document.
Calendar files can be renamed or moved anywhere in the file structure of the website. Calendar will still work as long as files are accessible and paths to them are correct.

Initialization

Tigra Calendar creates the calendar icon and attaches to the existing text input box. In most cases the calendar is initialized right after the assigned form field:

<form name="testform">
	<input type="text" name="testinput" />
	<script language="JavaScript">
	new tcal ({
		'formname': 'testform',
		'controlname': 'testinput'
	});
	</script>
</form>

Calendar initialization accepts two parameters:

Settings used to initialize and preset the calendar in the form (required)
Template override settings for localization and paths (optional)

See next section for more information.

Notes:

An instance of the component can be initialized at any time, however assigned input box must exist in the document by the time user invokes the calendar
Calendar can use the existing icon instead of creating new. This feature should be used when initializing the calendars dynamically in loaded pages. See included sample4.html and Calendar Settings below
The initialization call returns the reference to the calendar object which can later be used for accessing calendar's individual properties and methods. See first calendar instance in included sample2.html

Calendar Settings

Both configuration variables accepted by the calendar initialization are JavaScript associative arrays. They can be defined as variables and passed by name (see A_CALTPL in sample2.html) or they can be defined inline (anonymously) directly in the calendar's initialization call (see first parameter in most samples).

Configuration keys in calendar settings (first parameter):

key	description	accepted values
formname	Name of the form as it appear inside the name attribute of the form tag. If forms don't have assigned names then zero-based numeric indexes can be used (i.e. 0 for first form, 1 for next etc.). This setting is required when input field is referenced by name, optional if referenced by ID. Form names must be unique within the page.	string or number
controlname	Name or ID of the assigned input element as it appears in name or id attribute of the input tag. Always required. Name must be unique within the form. ID must be unique within the page.	string
id	ID for the calendar instance. Optional. If not assigned zero-based numeric ID is generated for each calender instance. This ID is used to identify the calendar icon. If image with id=tcalico_<id> already exists in the document then calendar will use it instead of creating its own. This feature should be used when creating calendar dynamically in loaded page. See included sample4.html	string
today	Date to be displayed as today. Optional. If not assigned then the date from the client system is used	string
selected	Date to be displayed as selected if assigned input field is blank. Optional. If not assigned then the today's date is used	string

Template defaults are defined at the beginning of the calendar's script file. They can be redefined individually after the calendar's initialization by accessing the properties of the object (see first calendar instance in sample2.html) or they can be overridden by passing new template variable as second parameter to the initialization (see second calendar instance in sample2.html).

Configuration keys in calendar template (optional second parameter):

key	description	accepted values	default
months	months as they appear in the calendar's title	array of strings	["January", "February", "March", "April", "May", "June","July", "August", "September", "October", "November", "December"]
weekdays	week day titles as they appear in the calendar	array of strings	["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"]
yearscroll	icons for navigating the years	true or false	true
weekstart	first day of week: 0-Su or 1-Mo	0 - 6	0 in US and DB, 1 in EU
centyear	2 digit years less than 'centyear' are in 20xx, otherwise in 19xx	0 - 99	70
imgpath	path to the directory where calendar images are stored (trailing slash required). Path can be absolute or relative to the directory containing the document with the calendar	string	'img/'

Troubleshooting

symptoms	problem
Calendar icon doesn't appear, no javascript errors	Error reporting is not enabled in browser (most likely)
	Calendar was not initialized in the page
	Calendar initialized inside invisible element
	Calendar attached to existing element (very unlikely by incident)
"tcal is undefined" error	Calendar script file is not linked to the document
	Path to calendar script file is incorrect
	calendar script file is corrupted
Calendar is plain, no colors, default font	Calendar style file is not linked to the document
	Path to calendar style file is incorrect
	Settings from another style sheet affecting the calendar
Broken image icon appears instead of calendar icon, still opens the calendar. No icons in the calendar	Path to the image directory (imgpath) in template configuration is incorrect
	Image files are missing
	File permissions for image files or containing directory are incorrect
"TC: form 'formname' can not be found" error	The form with specified name doesn't exist in the document
"TC: form 'formname' can not be found" error	Form name is not unique, multiple forms use it within the same document
"TC: element 'controlname' does not exist in this document" error	Element with this ID doesn't exist in the document
	Element ID is not unique, multiple elements use it within the same document
	Element is not an Input
	Input's name is used as ID (without specifying form name)
"TC: element 'controlname' does not exist in form 'formname'" error	Element with this ID doesn't exist in the document
	Input name is not unique, multiple inputs use it within the same form
	Input with the specified name exists in the page but in another form
	Element is not an Input

Tigra Calendar v4.0 License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.