mirror of
https://github.com/EGroupware/egroupware.git
synced 2024-11-17 13:33:19 +01:00
1125 lines
50 KiB
HTML
1125 lines
50 KiB
HTML
|
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!--
|
||
|
|
|
||
|
|
Generated from TeX source by tex2page, v 4r8f
|
||
|
|
(running on MzScheme 204, unix),
|
||
|
|
(c) Dorai Sitaram,
|
||
|
|
http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html
|
||
|
|
|
||
|
|
-->
|
||
|
|
<head>
|
||
|
|
<title>
|
||
|
|
DHTML Calendar Widget
|
||
|
|
</title>
|
||
|
|
<link rel="stylesheet" type="text/css" href="reference.css" title=default>
|
||
|
|
<link rel="stylesheet" type="text/css" href="reference-Z-S.css" title=default>
|
||
|
|
<meta name=robots content="index,follow">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<h1 class=title align=center><br><br>DHTML Calendar Widget</h1>
|
||
|
|
<p></p>
|
||
|
|
<div align=center>
|
||
|
|
Mihai Bazon, <tt><mishoo@infoiasi.ro></tt><p>July 9, 2003<br></p>
|
||
|
|
<p></p>
|
||
|
|
<p>
|
||
|
|
<span class=small>calendar version: 0.9.3<br>
|
||
|
|
document version: 0.1
|
||
|
|
</span>
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<span class=small><blockquote>
|
||
|
|
<div align=right><table><tr><td>
|
||
|
|
|
||
|
|
“Though a program be but three lines of code, someday it will have to be
|
||
|
|
maintained.”<br>
|
||
|
|
— <em>The Tao of Programming</em>
|
||
|
|
</td></tr></table></div>
|
||
|
|
|
||
|
|
</blockquote></span>
|
||
|
|
<a name="node_sec_Temp_1"></a>
|
||
|
|
<h1>Contents</h1><p><a name="node_toc_start"></a></p>
|
||
|
|
<p><b>
|
||
|
|
<a name="node_toc_node_sec_1"></a><a href="#node_sec_1">1 Overview</a></b><br>
|
||
|
|
<a name="node_toc_node_sec_1.1"></a><a href="#node_sec_1.1">1.1 How does this thing work?</a><br>
|
||
|
|
<a name="node_toc_node_sec_1.2"></a><a href="#node_sec_1.2">1.2 Project files</a><br>
|
||
|
|
<a name="node_toc_node_sec_1.3"></a><a href="#node_sec_1.3">1.3 License</a><br>
|
||
|
|
</p>
|
||
|
|
<p><b>
|
||
|
|
<a name="node_toc_node_sec_2"></a><a href="#node_sec_2">2 Quick startup</a></b><br>
|
||
|
|
<a name="node_toc_node_sec_2.1"></a><a href="#node_sec_2.1">2.1 Installing a popup calendar</a><br>
|
||
|
|
<a name="node_toc_node_sec_2.2"></a><a href="#node_sec_2.2">2.2 Installing a flat calendar</a><br>
|
||
|
|
<a name="node_toc_node_sec_2.3"></a><a href="#node_sec_2.3">2.3 <tt>Calendar.setup</tt> in detail</a><br>
|
||
|
|
</p>
|
||
|
|
<p><b>
|
||
|
|
<a name="node_toc_node_sec_3"></a><a href="#node_sec_3">3 The Calendar object overview</a></b><br>
|
||
|
|
<a name="node_toc_node_sec_3.1"></a><a href="#node_sec_3.1">3.1 Creating a calendar</a><br>
|
||
|
|
<a name="node_toc_node_sec_3.2"></a><a href="#node_sec_3.2">3.2 Order does matter ;-)</a><br>
|
||
|
|
<a name="node_toc_node_sec_3.3"></a><a href="#node_sec_3.3">3.3 Caching the object</a><br>
|
||
|
|
<a name="node_toc_node_sec_3.4"></a><a href="#node_sec_3.4">3.4 Callback functions</a><br>
|
||
|
|
</p>
|
||
|
|
<p><b>
|
||
|
|
<a name="node_toc_node_sec_4"></a><a href="#node_sec_4">4 The Calendar object API reference</a></b><br>
|
||
|
|
<a name="node_toc_node_sec_4.1"></a><a href="#node_sec_4.1">4.1 <tt>Calendar</tt> constructor</a><br>
|
||
|
|
<a name="node_toc_node_sec_4.2"></a><a href="#node_sec_4.2">4.2 Useful member variables (properties)</a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3"></a><a href="#node_sec_4.3">4.3 Public methods</a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.1"></a><a href="#node_sec_4.3.1">4.3.1 <tt>Calendar.create</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.2"></a><a href="#node_sec_4.3.2">4.3.2 <tt>Calendar.callHandler</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.3"></a><a href="#node_sec_4.3.3">4.3.3 <tt>Calendar.callCloseHandler</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.4"></a><a href="#node_sec_4.3.4">4.3.4 <tt>Calendar.hide</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.5"></a><a href="#node_sec_4.3.5">4.3.5 <tt>Calendar.setDateFormat</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.6"></a><a href="#node_sec_4.3.6">4.3.6 <tt>Calendar.setTtDateFormat</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.7"></a><a href="#node_sec_4.3.7">4.3.7 <tt>Calendar.setDisabledHandler</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.8"></a><a href="#node_sec_4.3.8">4.3.8 <tt>Calendar.show</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.9"></a><a href="#node_sec_4.3.9">4.3.9 <tt>Calendar.showAt</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.10"></a><a href="#node_sec_4.3.10">4.3.10 <tt>Calendar.showAtElement</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.11"></a><a href="#node_sec_4.3.11">4.3.11 <tt>Calendar.setDate</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.12"></a><a href="#node_sec_4.3.12">4.3.12 <tt>Calendar.setMondayFirst</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.13"></a><a href="#node_sec_4.3.13">4.3.13 <tt>Calendar.parseDate</tt></a><br>
|
||
|
|
<a name="node_toc_node_sec_4.3.14"></a><a href="#node_sec_4.3.14">4.3.14 <tt>Calendar.setRange</tt></a><br>
|
||
|
|
</p>
|
||
|
|
<p><b>
|
||
|
|
<a name="node_toc_node_sec_5"></a><a href="#node_sec_5">5 Side effects</a></b><br>
|
||
|
|
</p>
|
||
|
|
<p><b>
|
||
|
|
<a name="node_toc_node_sec_6"></a><a href="#node_sec_6">6 Sponsors</a></b><br>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_1"></a>
|
||
|
|
<h1><a href="#node_toc_node_sec_1">1 Overview</a></h1><p>The DHTML Calendar widget<a name="call_footnote_Temp_2"></a><a href="#footnote_Temp_2"><sup><small>1</small></sup></a>
|
||
|
|
is an (HTML) user interface element that gives end-users a friendly way to
|
||
|
|
input dates. 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.</p>
|
||
|
|
<p>
|
||
|
|
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 main
|
||
|
|
development platform), Netscape 6.0 or better, all other Gecko-based browsers,
|
||
|
|
Internet Explorer 5.0 or better <em>for Windows</em><a name="call_footnote_Temp_3"></a><a href="#footnote_Temp_3"><sup><small>2</small></sup></a>, Opera 7<a name="call_footnote_Temp_4"></a><a href="#footnote_Temp_4"><sup><small>3</small></sup></a>.</p>
|
||
|
|
<p>
|
||
|
|
You can find the latest info and version at the calendar homepage:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<div align=center><table><tr><td>
|
||
|
|
|
||
|
|
<a href="http://students.infoiasi.ro/~mishoo/site/calendar.epl"><tt>http://students.infoiasi.ro/~mishoo/site/calendar.epl</tt></a>
|
||
|
|
</td></tr></table></div>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_1.1"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_1.1">1.1 How does this thing work?</a></h2><p>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 ;-).</p>
|
||
|
|
<p>
|
||
|
|
Using DOM calls, the program dynamically creates a <tt><table></tt> 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.</p>
|
||
|
|
<p>
|
||
|
|
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.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_1.2"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_1.2">1.2 Project files</a></h2><p>Here’s a description of the project files, excluding documentation and example
|
||
|
|
files.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p>the main program file (<tt>calendar.js</tt>). This defines all the logic
|
||
|
|
behind the calendar widget.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>the CSS files (<tt>calendar-*.css</tt>). Loading one of them is
|
||
|
|
necessary in order to see the calendar as intended.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>the language definition files (<tt>lang/calendar-*.js</tt>). They are
|
||
|
|
plain JavaScript files that contain all texts that are displayed by the
|
||
|
|
calendar. Loading one of them is necessary.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>helper functions for quick setup of the calendar
|
||
|
|
(<tt>calendar-setup.js</tt>). You can do fine without it, but starting with
|
||
|
|
version 0.9.3 this is the recommended way to setup a calendar.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_1.3"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_1.3">1.3 License</a></h2><p></p>
|
||
|
|
<div align=center><table><tr><td>
|
||
|
|
|
||
|
|
© Mihai Bazon, 2002 – 2003, <tt><mishoo@infoiasi.ro></tt><br>
|
||
|
|
<a href="http://students.infoiasi.ro/~mishoo"><tt>http://students.infoiasi.ro/~mishoo</tt></a>
|
||
|
|
</td></tr></table></div>
|
||
|
|
<p>
|
||
|
|
The calendar is released under the
|
||
|
|
<a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public
|
||
|
|
License</a>. This basically means that you are allowed to use it for anything you
|
||
|
|
like, except selling it for profit or claiming it’s authorship. You can read
|
||
|
|
the entire license text <a href="http://www.gnu.org/licenses/lgpl.html">here</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_2"></a>
|
||
|
|
<h1><a href="#node_toc_node_sec_2">2 Quick startup</a></h1><p></p>
|
||
|
|
<p>
|
||
|
|
Installing the calendar used to be quite a task until version 0.9.3. Starting
|
||
|
|
with 0.9.3 I have included the file <tt>calendar-setup.js</tt> whose goal is to
|
||
|
|
assist you to setup a popup or flat calendar within minutes.</p>
|
||
|
|
<p>
|
||
|
|
First you have to include the needed scripts and style-sheet. Make sure you do
|
||
|
|
this in your document’s <tt><head></tt> section, also make sure you put the
|
||
|
|
correct paths to the scripts.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim><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>
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_2.1"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_2.1">2.1 Installing a popup calendar</a></h2><p></p>
|
||
|
|
<p>
|
||
|
|
Now suppose you have the following HTML:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim><form ...>
|
||
|
|
<input type="text" id="data" name="data" />
|
||
|
|
<button id="trigger">...</button>
|
||
|
|
</form>
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
You want the button to popup a calendar widget when clicked? Just
|
||
|
|
insert the following code immediately <em>after</em> the HTML form:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim><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>
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
The <tt>Calendar.setup</tt> function, defined in <tt>calendar-setup.js</tt>
|
||
|
|
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.</p>
|
||
|
|
<p>
|
||
|
|
By looking at the example above we can see that the function
|
||
|
|
<tt>Calendar.setup</tt> 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: <tt>singleClick:false</tt>.</p>
|
||
|
|
<p>
|
||
|
|
For a list of all supported parameters please see the section
|
||
|
|
<a href="#node_sec_2.3">2.3</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_2.2"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_2.2">2.2 Installing a flat calendar</a></h2><p></p>
|
||
|
|
<p>
|
||
|
|
Here’s how to configure a flat calendar, using the same <tt>Calendar.setup</tt>
|
||
|
|
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.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim><div id="calendar-container"></div>
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
Then there is the JavaScript code that sets up the calendar into the
|
||
|
|
“calendar-container” DIV. The code can occur anywhere in HTML
|
||
|
|
<em>after</em> the DIV element.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim><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>
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_2.3"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_2.3">2.3 <tt>Calendar.setup</tt> in detail</a></h2><p></p>
|
||
|
|
<p>
|
||
|
|
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 <em>must</em> pass at least one
|
||
|
|
of <tt>inputField</tt>, <tt>displayArea</tt> or <tt>button</tt>, for a popup
|
||
|
|
calendar, or <tt>flat</tt> for a flat calendar. Otherwise you will get a
|
||
|
|
warning message saying that there’s nothing to setup.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<span class=small><table border=0><tr><td valign=top ><b>property</b> </td><td valign=top ><b>type</b> </td><td valign=top ><b>description</b> </td><td valign=top ><b>default</b>
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>inputField</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >The ID of your input field.
|
||
|
|
</td><td valign=top >null
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>displayArea</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >This is the ID of a <span>, <div>, or any other element that you would like to use to display the current date. This is generally useful only if the input field is hidden, as an area to display the date.
|
||
|
|
</td><td valign=top >null
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>button</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >The ID of the calendar “trigger”. This is an element (ordinarily a button or an image) that will dispatch a certain event (usually “click”) to the function that creates and displays the calendar.
|
||
|
|
</td><td valign=top >null
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>eventName</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >The name of the event that will trigger the calendar. The name should be without the “on” prefix, such as “click” instead of “onclick”. Virtually all users will want to let this have the default value (“click”). Anyway, it could be useful if, say, 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).
|
||
|
|
</td><td valign=top >“click”
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>ifFormat</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >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.
|
||
|
|
</td><td valign=top >“y/mm/dd”
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>daFormat</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >Format of the date displayed in the displayArea (if specified).
|
||
|
|
</td><td valign=top >“y/mm/dd”
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>singleClick</tt>
|
||
|
|
</td><td valign=top >boolean </td><td valign=top >Wether the calendar is in “single-click mode” or “double-click mode”. If true (the default) the calendar will be created in single-click mode.
|
||
|
|
</td><td valign=top >true
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>disableFunc</tt>
|
||
|
|
</td><td valign=top >function </td><td valign=top >A function that receives a JS Date object. It should return
|
||
|
|
<tt>true</tt> if that date has to be disabled, <tt>false</tt> otherwise.
|
||
|
|
</td><td valign=top >null
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>mondayFirst</tt>
|
||
|
|
</td><td valign=top >boolean </td><td valign=top >If “true” then the calendar will display with Monday being the first day of week.
|
||
|
|
</td><td valign=top >false
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>weekNumbers</tt>
|
||
|
|
</td><td valign=top >boolean </td><td valign=top >If “true” then the calendar will display week numbers.
|
||
|
|
</td><td valign=top >true
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>align</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >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 <a href="#node_sec_4.3.10">4.3.10</a>.
|
||
|
|
</td><td valign=top >“Bl”
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>range</tt>
|
||
|
|
</td><td valign=top >array </td><td valign=top >An array having exactly 2 elements, integers. (!) The first [0] element is the minimum year that is available, and the second [1] element is the maximum year that the calendar will allow.
|
||
|
|
</td><td valign=top >[1900, 2999]
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>flat</tt>
|
||
|
|
</td><td valign=top >string </td><td valign=top >If you want a flat calendar, pass the ID of the parent object in
|
||
|
|
this property. If not, pass <tt>null</tt> here (or nothing at all as
|
||
|
|
<tt>null</tt> is the default value.
|
||
|
|
</td><td valign=top >null
|
||
|
|
</td></tr>
|
||
|
|
<tr><td valign=top ><tt>flatCallback</tt>
|
||
|
|
</td><td valign=top >function </td><td valign=top >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 <a href="#node_sec_2.2">2.2</a> for an example
|
||
|
|
of how to setup a flat calendar.
|
||
|
|
</td><td valign=top >null
|
||
|
|
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
</span><p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_3"></a>
|
||
|
|
<h1><a href="#node_toc_node_sec_3">3 The Calendar object overview</a></h1><p></p>
|
||
|
|
<p>
|
||
|
|
Basically you should be able to setup the calendar with the function presented
|
||
|
|
in the last section. However, if for some reason <tt>Calendar.setup</tt>
|
||
|
|
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.</p>
|
||
|
|
<p>
|
||
|
|
The file <tt>calendar.js</tt> implements the functionality of the calendar.
|
||
|
|
All (well, almost all) functions and variables are embedded in the JavaScript
|
||
|
|
object “Calendar”.</p>
|
||
|
|
<p>
|
||
|
|
You can instantiate a <tt>Calendar</tt> object by calling the constructor, like
|
||
|
|
this: <tt>var cal = new Calendar(<tt>...</tt>)</tt>. We will discuss the parameters
|
||
|
|
later. After creating the object, the variable <tt>cal</tt> will contain a
|
||
|
|
reference to it. You can use this reference to access further options of the
|
||
|
|
calendar, for instance:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>cal.weekNumbers = false; // do not display week numbers
|
||
|
|
cal.setDateFormat("y.mm.dd"); // set this format: 2003.12.31
|
||
|
|
cal.setDisabledHandler(function(date) {
|
||
|
|
// verify date and return true if it has to be disabled
|
||
|
|
if (date.getFullYear() == 2004) {
|
||
|
|
// disable all dates from 2004
|
||
|
|
return false;
|
||
|
|
}
|
||
|
|
});
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
etc. Prior to version
|
||
|
|
0.9.3 this was the only way to configure it. The <tt>Calendar.setup</tt>
|
||
|
|
function, documented in section <a href="#node_sec_2">2</a>, basically does the same
|
||
|
|
things (actually more) in order to setup the calendar, based on the parameters
|
||
|
|
that you provided.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_3.1"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_3.1">3.1 Creating a calendar</a></h2><p>The calendar is created by following some steps (even the function
|
||
|
|
<tt>Calendar.setup</tt>, described in section <a href="#node_sec_2">2</a>, does the
|
||
|
|
same):</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ol><p>
|
||
|
|
</p>
|
||
|
|
<li><p><em>Instantiate</em> a <tt>Calendar</tt> object. Details about this in
|
||
|
|
section <a href="#node_sec_4.1">4.1</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>optional</b> Set the <tt>weekNumbers</tt> property to <tt>false</tt> if you don’t want
|
||
|
|
the calendar to display week numbers. This step must take place <em>before</em>
|
||
|
|
calling <tt>Calendar.create</tt>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>optional</b> Set the range of years available for selection (see section
|
||
|
|
<a href="#node_sec_4.3.14">4.3.14</a>). The default range is [1970..2050].</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>optional</b> Set the <tt>disabledHandler</tt> property. You should pass
|
||
|
|
here a function that receives a JavaScript <tt>Date</tt> object and returns
|
||
|
|
<tt>true</tt> if the given date should be disabled, false otherwise (details in
|
||
|
|
section <a href="#node_sec_4.3.7">4.3.7</a>).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>optional</b> 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.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><em>Create</em> the HTML elements related to the calendar. This step
|
||
|
|
practically puts the calendar in your HTML page. You simply call
|
||
|
|
<tt>Calendar.create()</tt>. You can give an optional parameter if you wanna
|
||
|
|
create a flat calendar (details in section <a href="#node_sec_4.3.1">4.3.1</a>).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>optional</b> Initialize the calendar to a certain date, for instance from
|
||
|
|
the input field.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>Show the calendar (details in section <a href="#node_sec_4.3.8">4.3.8</a>).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ol><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_3.2"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_3.2">3.2 Order does matter ;-)</a></h2><p>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 <tt>new Calendar(<tt>...</tt>)</tt>. Secondly there are the HTML
|
||
|
|
elements that actually lets you see and manipulate the calendar.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<span class=small>[ Those that did UI<a name="call_footnote_Temp_5"></a><a href="#footnote_Temp_5"><sup><small>4</small></sup></a> programming, no matter in what
|
||
|
|
language and on what platform, may be familiar with this concept. First there
|
||
|
|
is the object in memory that lets you manipulate the UI element, and secondly
|
||
|
|
there is the UI element (known as “control”, “window”, “widget”, etc.),
|
||
|
|
also in memory but you don’t usually access it directly. ]
|
||
|
|
</span><p>
|
||
|
|
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
|
||
|
|
<tt>Calendar.create</tt>. It knows how to create popup or flat calendars.
|
||
|
|
This function is described in section <a href="#node_sec_4.3.1">4.3.1</a>.</p>
|
||
|
|
<p>
|
||
|
|
Some properties need to be set prior to creating the HTML elements, because
|
||
|
|
otherwise they wouldn’t have any effect. Such a property is
|
||
|
|
<tt>weekNumbers</tt>—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 <em>after</em> calling <tt>Calendar.create</tt> the calendar
|
||
|
|
would still display the week numbers, because the HTML elements are already
|
||
|
|
created (including the <tt><td></tt>-s in the <tt><table></tt> element that
|
||
|
|
should contain the week numbers). For this reason the order of the steps above
|
||
|
|
is important.</p>
|
||
|
|
<p>
|
||
|
|
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 <tt>Calendar.show</tt> function should be
|
||
|
|
called <em>after</em> calling <tt>Calendar.create</tt>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_3.3"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_3.3">3.3 Caching the object</a></h2><p>Suppose the end-user has popped up a calendar and selects a date. The calendar
|
||
|
|
then closes. What really happens now?</p>
|
||
|
|
<p>
|
||
|
|
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:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p>creating the JavaScript object and HTML elements is time-consuming</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>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)</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
The second approach, implemented by the <tt>Calendar.setup</tt> function, is to
|
||
|
|
cache the JavaScript object. It does this by checking the global variable
|
||
|
|
<tt>window.calendar</tt> 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 “<tt>hide</tt>” on it, therefore keeping the JavaScript object and the
|
||
|
|
HTML elements in place.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_3.4"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_3.4">3.4 Callback functions</a></h2><p>You might rightfully wonder how is the calendar related to the input field?
|
||
|
|
Who tells it that it has to update <em>that</em> input field when a date is
|
||
|
|
selected, or that it has to jump to <em>that</em> URL when a date is clicked in
|
||
|
|
flat mode?</p>
|
||
|
|
<p>
|
||
|
|
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.</p>
|
||
|
|
<p>
|
||
|
|
The calendar supports the following user callbacks:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>onSelect</b> — this gets called when the end-user changes the date in the
|
||
|
|
calendar. Documented in section <a href="#node_sec_4.1">4.1</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>onClose</b> — this gets called when the calendar should close. It’s
|
||
|
|
user’s responsibility to close the calendar. Details in section
|
||
|
|
<a href="#node_sec_4.1">4.1</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>disabledHandler</b> — this function gets called for any day in a month,
|
||
|
|
just before displaying the month. It is called with a JavaScript <tt>Date</tt>
|
||
|
|
object and should return <tt>true</tt> if that date should be disabled
|
||
|
|
or false otherwise. Details in section <a href="#node_sec_4.3.7">4.3.7</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4"></a>
|
||
|
|
<h1><a href="#node_toc_node_sec_4">4 The Calendar object API reference</a></h1><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.1"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_4.1">4.1 <tt>Calendar</tt> constructor</a></h2><p></p>
|
||
|
|
<p>
|
||
|
|
Synopsis:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>var calendar = Calendar(mondayFirst, date, onSelect, onClose);
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
Parameters are as follows:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>mondayFirst</b> — boolean, if it’s <tt>true</tt> the calendar will have
|
||
|
|
Monday as first day of week, if false weeks start on Sunday.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>date</b> — a JavaScript Date object or <tt>null</tt>. If <tt>null</tt>
|
||
|
|
is passed then the calendar will default to today date. Otherwise it will
|
||
|
|
initialize on the given date.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>onSelect</b> — your callback for the “onChange” event. See above.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><b>onClose</b> — your callback for the “onClose” event. See above.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_Temp_6"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_Temp_6">The <tt>onSelect</tt> event</a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Here is a typical implementation of this function:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>function onSelect(calendar, date) {
|
||
|
|
var input_field = document.getElementById("date");
|
||
|
|
input_field.value = date;
|
||
|
|
};
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
<tt>date</tt> is in the format selected with <tt>calendar.setDateFormat</tt>
|
||
|
|
(see section <a href="#node_sec_4.3.5">4.3.5</a>). 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:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>function onSelect(calendar, date) {
|
||
|
|
var input_field = document.getElementById("date");
|
||
|
|
input_field.value = date;
|
||
|
|
if (calendar.dateClicked) {
|
||
|
|
calendar.callCloseHandler(); // this calls "onClose" (see above)
|
||
|
|
}
|
||
|
|
};
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
Note that we checked the member variable <tt>dateClicked</tt> and
|
||
|
|
only hide the calendar if it’s <tt>true</tt>. If this variable is <tt>false</tt> 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.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_Temp_7"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_Temp_7">The <tt>onClose</tt> event</a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
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.</p>
|
||
|
|
<p>
|
||
|
|
A typical implementation of this function is the following:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>function onClose(calendar) {
|
||
|
|
calendar.hide();
|
||
|
|
// or calendar.destroy();
|
||
|
|
};
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.2"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_4.2">4.2 Useful member variables (properties)</a></h2><p></p>
|
||
|
|
<p>
|
||
|
|
After creating the Calendar object you can access the following properties:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>date</tt> — is a JavaScript <tt>Date</tt> object. It will always
|
||
|
|
reflect the date shown in the calendar (yes, even if the calendar is hidden).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>isPopup</tt> — 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 <tt>Calendar.create</tt> and has no meaning before this function was
|
||
|
|
called.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>dateClicked</tt> — particularly useful in the <tt>onSelect</tt>
|
||
|
|
handler, this variable tells us if a date was really clicked. That’s because
|
||
|
|
the <tt>onSelect</tt> 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.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>weekNumbers</tt> — if <tt>true</tt> (default) then the calendar
|
||
|
|
displays week numbers. If you don’t want week numbers you have to set this
|
||
|
|
variable to <tt>false</tt> <em>before</em> calling <tt>Calendar.create</tt>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>mondayFirst</tt> — if <tt>true</tt> 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 <em>before</em> calling
|
||
|
|
<tt>Calendar.create</tt>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
There are lots of other member variables, but one should access them only
|
||
|
|
through member functions so I won’t document them here.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3"></a>
|
||
|
|
<h2><a href="#node_toc_node_sec_4.3">4.3 Public methods</a></h2><p></p>
|
||
|
|
<a name="node_sec_4.3.1"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.1">4.3.1 <tt>Calendar.create</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
This function creates the afferent HTML elements that are needed to display the
|
||
|
|
calendar. You should call it after setting the calendar properties. Synopsis:
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.create(); // creates a popup calendar
|
||
|
|
// -- or --
|
||
|
|
calendar.create(document.getElementById(parent_id)); // makes a flat calendar
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
It can create a popup calendar or a flat calendar. If the “parent” argument
|
||
|
|
is present (it should be a <em>reference</em>—not ID—to an HTML element) then
|
||
|
|
a flat calendar is created and it is inserted in the given element.</p>
|
||
|
|
<p>
|
||
|
|
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
|
||
|
|
<tt>isPopup</tt>:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>if (calendar.isPopup) {
|
||
|
|
// this is a popup calendar
|
||
|
|
} else {
|
||
|
|
// this is a flat calendar
|
||
|
|
}
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.2"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.2">4.3.2 <tt>Calendar.callHandler</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
This function calls the first user callback (the
|
||
|
|
<tt>onSelect</tt> handler) with the required parameters.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.3"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.3">4.3.3 <tt>Calendar.callCloseHandler</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
This function calls the second user callback (the
|
||
|
|
<tt>onClose</tt> handler). It’s useful when you want to have a
|
||
|
|
“single-click” calendar—just call this in your <tt>onSelect</tt> handler,
|
||
|
|
if a date was clicked.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.4"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.4">4.3.4 <tt>Calendar.hide</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
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 <tt>show</tt>
|
||
|
|
functions on the same element.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.5"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.5">4.3.5 <tt>Calendar.setDateFormat</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
This function configures the format in which the calendar reports the date to
|
||
|
|
your “onSelect” handler. Call it like this:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.setDateFormat("y/mm/dd");
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
As you can see, it receives only one parameter, the required format. The magic
|
||
|
|
characters are the following:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<table border=0><tr><td valign=top ></td></tr>
|
||
|
|
<tr><td valign=top >d </td><td valign=top >the date ( ex: 1 .. 31 ) </td></tr>
|
||
|
|
<tr><td valign=top >dd </td><td valign=top >the date, zero padded ( ex: 01 .. 31 ) </td></tr>
|
||
|
|
<tr><td valign=top >m </td><td valign=top >month as a number ( ex: 1 .. 12 ) </td></tr>
|
||
|
|
<tr><td valign=top >mm </td><td valign=top >month, zero padded ( ex: 01 .. 12 ) </td></tr>
|
||
|
|
<tr><td valign=top >y </td><td valign=top >4 digit year ( ex: 1979 ) </td></tr>
|
||
|
|
<tr><td valign=top >yy </td><td valign=top >2 digit year, yy - 1900 ( ex: 79 ) (USING THIS IS NOT RECOMMENDED) </td></tr>
|
||
|
|
<tr><td valign=top >w </td><td valign=top >the number of the week in the year (1 or 2 digits) </td></tr>
|
||
|
|
<tr><td valign=top >ww </td><td valign=top >the number of the week, zero padded (2 digits) </td></tr>
|
||
|
|
<tr><td valign=top >D </td><td valign=top >short weekday name ( ex: Sun, Wed, Fri ) </td></tr>
|
||
|
|
<tr><td valign=top >DD </td><td valign=top >long weekday name ( ex: Sunday, Wednesday, Friday ) </td></tr>
|
||
|
|
<tr><td valign=top >M </td><td valign=top >short month name ( ex: Mar, Jan, Oct ) </td></tr>
|
||
|
|
<tr><td valign=top >MM </td><td valign=top >long month name ( ex: March, January, October )</td></tr>
|
||
|
|
<tr><td valign=top ></td></tr>
|
||
|
|
<tr><td valign=top ></td></tr></table><p>
|
||
|
|
<font color="red"><b>WARNING!</b></font> The format specifiers are likely to change.
|
||
|
|
The current is a complete mess, in that that, for instance, you can’t have a
|
||
|
|
format like this: “ymmdd”—you have to separate them through non-word
|
||
|
|
characters, like for example “y-mm-dd”. In next versions of calendar the
|
||
|
|
format will probably use a “%” prefix, like in <tt>strftime</tt> from
|
||
|
|
ANSI-C, so the format above will be possible to write like this:
|
||
|
|
“%y%mm%dd”.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.6"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.6">4.3.6 <tt>Calendar.setTtDateFormat</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Has the same prototype as <tt>Calendar.setDateFormat</tt>, but refers to the
|
||
|
|
format of the date displayed in the “status bar” when the mouse is over some
|
||
|
|
date.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.7"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.7">4.3.7 <tt>Calendar.setDisabledHandler</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
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:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>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);
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
If you change this function in “real-time”, meaning, without creating a new
|
||
|
|
calendar, then you have to call <tt>calendar.refresh()</tt> to make it
|
||
|
|
redisplay the month and take into account the new disabledHandler.
|
||
|
|
<tt>Calendar.setup</tt> does this, so you have no such trouble with it.</p>
|
||
|
|
<p>
|
||
|
|
Note that <tt>disallowDate</tt> 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).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.8"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.8">4.3.8 <tt>Calendar.show</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Call this function do show the calendar. It basically sets the CSS “display”
|
||
|
|
property to “block”. It doesn’t modify the calendar position.</p>
|
||
|
|
<p>
|
||
|
|
This function only makes sense when the calendar is in popup mode.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.9"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.9">4.3.9 <tt>Calendar.showAt</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Call this to show the calendar at a certain (x, y) position. Prototype:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.showAt(x, y);
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
The parameters are absolute coordinates relative to the top left
|
||
|
|
corner <em>of the page</em>, thus they are <em>page</em> coordinates not screen
|
||
|
|
coordinates.</p>
|
||
|
|
<p>
|
||
|
|
After setting the given coordinates it calls Calendar.show. This function only
|
||
|
|
makes sense when the calendar is in popup mode.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.10"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.10">4.3.10 <tt>Calendar.showAtElement</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
This function is useful if you want to display the calendar near some element.
|
||
|
|
You call it like this:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.showAtElement(element, align);
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
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 <tt>"Br"</tt> as
|
||
|
|
align, the calendar will appear <em>below</em> the element and with its right
|
||
|
|
margin continuing the element’s right margin.</p>
|
||
|
|
<p>
|
||
|
|
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 <tt>"l"</tt> (the left margin of the calendar will
|
||
|
|
be at the same horizontal position as the left margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
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 <tt>Calendar.showAt</tt> to display the calendar there.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_Temp_8"></a>
|
||
|
|
<h4><a href="#node_toc_node_sec_Temp_8">Vertical alignment</a></h4><p>The first character in “<tt>align</tt>” can take one of the following values:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>T</tt> — completely above the reference element (bottom margin of
|
||
|
|
the calendar aligned to the top margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>t</tt> — above the element but may overlap it (bottom margin of the calendar aligned to
|
||
|
|
the bottom margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>c</tt> — the calendar displays vertically centered to the reference
|
||
|
|
element. It might overlap it (that depends on the horizontal alignment).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>b</tt> — below the element but may overlap it (top margin of the calendar aligned to
|
||
|
|
the top margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>B</tt> — completely below the element (top margin of the calendar
|
||
|
|
aligned to the bottom margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_Temp_9"></a>
|
||
|
|
<h4><a href="#node_toc_node_sec_Temp_9">Horizontal alignment</a></h4><p>The second character in “<tt>align</tt>” can take one of the following values:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>L</tt> — completely to the left of the reference element (right
|
||
|
|
margin of the calendar aligned to the left margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>l</tt> — to the left of the element but may overlap it (left margin
|
||
|
|
of the calendar aligned to the left margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>c</tt> — horizontally centered to the element. Might overlap it,
|
||
|
|
depending on the vertical alignment.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>r</tt> — to the right of the element but may overlap it (right
|
||
|
|
margin of the calendar aligned to the right margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>R</tt> — completely to the right of the element (left margin of the
|
||
|
|
calendar aligned to the right margin of the element).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_Temp_10"></a>
|
||
|
|
<h4><a href="#node_toc_node_sec_Temp_10">Default values</a></h4><p>If the “<tt>align</tt>” parameter is missing the calendar will choose
|
||
|
|
“<tt>Bl</tt>”. This resembles the behavior of older versions (prior to
|
||
|
|
0.9.3) which did not support custom alignment.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.11"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.11">4.3.11 <tt>Calendar.setDate</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Receives a JavaScript <tt>Date</tt> object. Sets the given date in the
|
||
|
|
calendar. If the calendar is visible the new date is displayed immediately.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.setDate(new Date()); // go today
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.12"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.12">4.3.12 <tt>Calendar.setMondayFirst</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Changes the first day of week. If the parameter is <tt>true</tt> then Monday
|
||
|
|
will be the first day of week, otherwise Sunday.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.setMondayFirst(false); // use Sunday
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.13"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.13">4.3.13 <tt>Calendar.parseDate</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Use this function to parse a date given as string and to move the calendar to
|
||
|
|
that date.</p>
|
||
|
|
<p>
|
||
|
|
The algorithm tries to parse the date according to the format that was
|
||
|
|
previously set with <tt>Calendar.setDateFormat</tt>; if that fails, it still
|
||
|
|
tries to get some valid date out of it (it doesn’t read your thoughts, though).</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.parseDate("2003/07/06");
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_4.3.14"></a>
|
||
|
|
<h3><a href="#node_toc_node_sec_4.3.14">4.3.14 <tt>Calendar.setRange</tt></a></h3><p></p>
|
||
|
|
<p>
|
||
|
|
Sets the range of years that are allowed in the calendar. Synopsis:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<pre class=verbatim>calendar.setRange(1970, 2050);
|
||
|
|
</pre><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_5"></a>
|
||
|
|
<h1><a href="#node_toc_node_sec_5">5 Side effects</a></h1><p>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
|
||
|
|
<tt>calendar.js</tt> was loaded.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ol><p>
|
||
|
|
</p>
|
||
|
|
<li><p>The global variable <tt>window.calendar</tt> 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.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>The JavaScript <tt>Date</tt> 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 <tt>Date</tt> object than to the calendar itself.
|
||
|
|
Complete list:</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ol><p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date._MD = new Array(31,28,31,30,31,30,31,31,30,31,30,31);</tt>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.SECOND = 1000 /* milliseconds */;</tt>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.MINUTE = 60 * Date.SECOND;</tt>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.HOUR = 60 * Date.MINUTE;</tt>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.DAY = 24 * Date.HOUR;</tt>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.WEEK = 7 * Date.DAY;</tt></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.prototype.getMonthDays</tt>(month) — returns the number of days
|
||
|
|
of the given month, or of the current date object if no month was given.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.prototype.getWeekNumber</tt>() — returns the week number of the
|
||
|
|
date in the current object.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.prototype.equalsTo</tt>(other_date) — compare the current date
|
||
|
|
object with <tt>other_date</tt> and returns <tt>true</tt> if the dates are
|
||
|
|
equal. <em>It ignores time</em>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p><tt>Date.prototype.print</tt>(format) — returns a string with the
|
||
|
|
current date object represented in the given format. It implements the format
|
||
|
|
specified in section <a href="#node_sec_4.3.5">4.3.5</a>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ol><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ol><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<a name="node_sec_6"></a>
|
||
|
|
<h1><a href="#node_toc_node_sec_6">6 Sponsors</a></h1><p>The following people either sponsored, donated money to the project or bought
|
||
|
|
developer 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
|
||
|
|
<em>please</em> contact me at <tt><a href="mailto:mishoo@infoiasi.ro">mishoo@infoiasi.ro</a></tt>.</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<ul><p>
|
||
|
|
</p>
|
||
|
|
<li><p>Seyhan Ersoy (<a href="http://www.oocgi.com">http://www.oocgi.com</a>)</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<li><p>Jon Stokkeland (<a href="http://www.sauen.com">http://www.sauen.com</a>)</p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
</ul><p></p>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<div align=right><table><tr><td>
|
||
|
|
|
||
|
|
<b>Thank you!</b><br>
|
||
|
|
— <tt>mishoo@infoiasi.ro</tt>
|
||
|
|
</td></tr></table></div>
|
||
|
|
<p>
|
||
|
|
</p>
|
||
|
|
<div class=footnoterule><hr></div><p></p>
|
||
|
|
<div class=footnote><p><a name="footnote_Temp_2"></a><a href="#call_footnote_Temp_2"><sup><small>1</small></sup></a>
|
||
|
|
by the term “widget” I understand a single element of user interface.
|
||
|
|
But that’s in Linux world. For those that did lots of Windows
|
||
|
|
programming the term “control” might be more familiar
|
||
|
|
</p>
|
||
|
|
<p><a name="footnote_Temp_3"></a><a href="#call_footnote_Temp_3"><sup><small>2</small></sup></a> people report that the calendar does
|
||
|
|
not work with IE5/Mac. I don’t have access to a Macintosh,
|
||
|
|
therefore—sorry—I can’t fix it.</p>
|
||
|
|
<p><a name="footnote_Temp_4"></a><a href="#call_footnote_Temp_4"><sup><small>3</small></sup></a> under Opera 7 the calendar still lacks some functionality, such as
|
||
|
|
keyboard navigation; also Opera doesn’t seem to allow disabling text
|
||
|
|
selection when one drags the mouse on the page; despite all that, the
|
||
|
|
calendar is still highly functional under Opera 7 and looks as good as
|
||
|
|
in other supported browsers. </p>
|
||
|
|
<p><a name="footnote_Temp_5"></a><a href="#call_footnote_Temp_5"><sup><small>4</small></sup></a> user interface</p>
|
||
|
|
</div>
|
||
|
|
<div align=right class=colophon>
|
||
|
|
<i>Last modified: Mon, July 7, 2003, 5:18 pm<br>
|
||
|
|
HTML conversion by <a href="http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html">TeX2page 4r8f</a></i>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|