pub/TWiki/JSCalendarContrib/doc/html/reference.html
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
colas@0
     2
<html>
colas@0
     3
<!--
colas@0
     4
colas@0
     5
Generated from ../reference.tex by tex2page, v 2004-09-11
colas@0
     6
(running on MzScheme 209, unix), 
colas@0
     7
(c) Dorai Sitaram, 
colas@0
     8
http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html
colas@0
     9
colas@0
    10
-->
colas@0
    11
<head>
colas@0
    12
<title>
colas@0
    13
DHTML Calendar Widget
colas@0
    14
</title>
colas@0
    15
<link rel="stylesheet" type="text/css" href="reference.css" title=default>
colas@0
    16
<link rel="stylesheet" type="text/css" href="reference-Z-S.css" title=default>
colas@0
    17
<meta name=robots content="index,follow">
colas@0
    18
</head>
colas@0
    19
<body>
colas@0
    20
<p>
colas@0
    21
</p>
colas@0
    22
<p>
colas@0
    23
</p>
colas@0
    24
<p>
colas@0
    25
</p>
colas@0
    26
<p>
colas@0
    27
</p>
colas@0
    28
<p>
colas@0
    29
</p>
colas@0
    30
<p>
colas@0
    31
</p>
colas@0
    32
<p>
colas@0
    33
colas@0
    34
colas@0
    35
colas@0
    36
colas@0
    37
</p>
colas@0
    38
<p>
colas@0
    39
colas@0
    40
colas@0
    41
</p>
colas@0
    42
<p>
colas@0
    43
</p>
colas@0
    44
<p>
colas@0
    45
</p>
colas@0
    46
<h1 class=title align=center><br><br>DHTML Calendar Widget</h1>
colas@0
    47
<p></p>
colas@0
    48
<div align=center>
colas@0
    49
Mihai Bazon, <tt>&lt;mihai_bazon@yahoo.com&gt;</tt><br>
colas@0
    50
&copy; Dynarch.com 2002-2005, <a href="http://www.dynarch.com/"><tt>www.dynarch.com</tt></a><p>March 7, 2005<br></p>
colas@0
    51
<p></p>
colas@0
    52
<p>
colas@0
    53
<span class=small>calendar version: 1.0 ``It is happening again''</span>
colas@0
    54
</p>
colas@0
    55
</div>
colas@0
    56
<p></p>
colas@0
    57
<p>
colas@0
    58
<span class=small><code class=verbatim>$Id: reference.html 7997 2005-12-27 20:23:39Z AndreUlrich $</code></span>
colas@0
    59
</p>
colas@0
    60
<span class=small><blockquote>
colas@0
    61
<div align=right><table><tr><td>
colas@0
    62
colas@0
    63
</td></tr></table></div>
colas@0
    64
colas@0
    65
</blockquote></span>
colas@0
    66
<a name="node_sec_Temp_1"></a>
colas@0
    67
<h1><a href="#node_toc_node_sec_Temp_1">Contents</a></h1>
colas@0
    68
<p><a name="node_toc_start"></a></p>
colas@0
    69
<p><b>
colas@0
    70
&nbsp; &nbsp; <a name="node_toc_node_sec_1"></a><a href="#node_sec_1">1&nbsp;&nbsp;Overview</a></b><br>
colas@0
    71
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_1.1"></a><a href="#node_sec_1.1">1.1&nbsp;&nbsp;How does this thing work?</a><br>
colas@0
    72
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_1.2"></a><a href="#node_sec_1.2">1.2&nbsp;&nbsp;Project files</a><br>
colas@0
    73
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_1.3"></a><a href="#node_sec_1.3">1.3&nbsp;&nbsp;License</a><br>
colas@0
    74
</p>
colas@0
    75
<p><b>
colas@0
    76
&nbsp; &nbsp; <a name="node_toc_node_sec_2"></a><a href="#node_sec_2">2&nbsp;&nbsp;Quick startup</a></b><br>
colas@0
    77
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_2.1"></a><a href="#node_sec_2.1">2.1&nbsp;&nbsp;Installing a popup calendar</a><br>
colas@0
    78
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_2.2"></a><a href="#node_sec_2.2">2.2&nbsp;&nbsp;Installing a flat calendar</a><br>
colas@0
    79
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_2.3"></a><a href="#node_sec_2.3">2.3&nbsp;&nbsp;<tt>Calendar.setup</tt> in detail</a><br>
colas@0
    80
</p>
colas@0
    81
<p><b>
colas@0
    82
&nbsp; &nbsp; <a name="node_toc_node_sec_3"></a><a href="#node_sec_3">3&nbsp;&nbsp;Recipes</a></b><br>
colas@0
    83
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.1"></a><a href="#node_sec_3.1">3.1&nbsp;&nbsp;Popup calendars</a><br>
colas@0
    84
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.1.1"></a><a href="#node_sec_3.1.1">3.1.1&nbsp;&nbsp;Simple text field with calendar attached to a button</a><br>
colas@0
    85
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.1.2"></a><a href="#node_sec_3.1.2">3.1.2&nbsp;&nbsp;Simple field with calendar attached to an image</a><br>
colas@0
    86
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.1.3"></a><a href="#node_sec_3.1.3">3.1.3&nbsp;&nbsp;Hidden field, plain text triggers</a><br>
colas@0
    87
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.1.4"></a><a href="#node_sec_3.1.4">3.1.4&nbsp;&nbsp;2 Linked fields, no trigger buttons</a><br>
colas@0
    88
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.2"></a><a href="#node_sec_3.2">3.2&nbsp;&nbsp;Flat calendars</a><br>
colas@0
    89
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.3"></a><a href="#node_sec_3.3">3.3&nbsp;&nbsp;Highlight special dates</a><br>
colas@0
    90
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_3.4"></a><a href="#node_sec_3.4">3.4&nbsp;&nbsp;Select multiple dates</a><br>
colas@0
    91
</p>
colas@0
    92
<p><b>
colas@0
    93
&nbsp; &nbsp; <a name="node_toc_node_sec_4"></a><a href="#node_sec_4">4&nbsp;&nbsp;The Calendar object overview</a></b><br>
colas@0
    94
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_4.1"></a><a href="#node_sec_4.1">4.1&nbsp;&nbsp;Creating a calendar</a><br>
colas@0
    95
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_4.2"></a><a href="#node_sec_4.2">4.2&nbsp;&nbsp;Order does matter ;-)</a><br>
colas@0
    96
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_4.3"></a><a href="#node_sec_4.3">4.3&nbsp;&nbsp;Caching the object</a><br>
colas@0
    97
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_4.4"></a><a href="#node_sec_4.4">4.4&nbsp;&nbsp;Callback functions</a><br>
colas@0
    98
</p>
colas@0
    99
<p><b>
colas@0
   100
&nbsp; &nbsp; <a name="node_toc_node_sec_5"></a><a href="#node_sec_5">5&nbsp;&nbsp;The Calendar object API reference</a></b><br>
colas@0
   101
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.1"></a><a href="#node_sec_5.1">5.1&nbsp;&nbsp;<tt>Calendar</tt> constructor</a><br>
colas@0
   102
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.2"></a><a href="#node_sec_5.2">5.2&nbsp;&nbsp;Useful member variables (properties)</a><br>
colas@0
   103
&nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3"></a><a href="#node_sec_5.3">5.3&nbsp;&nbsp;Public methods</a><br>
colas@0
   104
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.1"></a><a href="#node_sec_5.3.1">5.3.1&nbsp;&nbsp;<tt>Calendar.create</tt></a><br>
colas@0
   105
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.2"></a><a href="#node_sec_5.3.2">5.3.2&nbsp;&nbsp;<tt>Calendar.callHandler</tt></a><br>
colas@0
   106
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.3"></a><a href="#node_sec_5.3.3">5.3.3&nbsp;&nbsp;<tt>Calendar.callCloseHandler</tt></a><br>
colas@0
   107
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.4"></a><a href="#node_sec_5.3.4">5.3.4&nbsp;&nbsp;<tt>Calendar.hide</tt></a><br>
colas@0
   108
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.5"></a><a href="#node_sec_5.3.5">5.3.5&nbsp;&nbsp;<tt>Calendar.setDateFormat</tt></a><br>
colas@0
   109
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.6"></a><a href="#node_sec_5.3.6">5.3.6&nbsp;&nbsp;<tt>Calendar.setTtDateFormat</tt></a><br>
colas@0
   110
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.7"></a><a href="#node_sec_5.3.7">5.3.7&nbsp;&nbsp;<tt>Calendar.setDisabledHandler</tt></a><br>
colas@0
   111
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.8"></a><a href="#node_sec_5.3.8">5.3.8&nbsp;&nbsp;<tt>Calendar.setDateStatusHandler</tt></a><br>
colas@0
   112
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.9"></a><a href="#node_sec_5.3.9">5.3.9&nbsp;&nbsp;<tt>Calendar.show</tt></a><br>
colas@0
   113
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.10"></a><a href="#node_sec_5.3.10">5.3.10&nbsp;&nbsp;<tt>Calendar.showAt</tt></a><br>
colas@0
   114
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.11"></a><a href="#node_sec_5.3.11">5.3.11&nbsp;&nbsp;<tt>Calendar.showAtElement</tt></a><br>
colas@0
   115
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.12"></a><a href="#node_sec_5.3.12">5.3.12&nbsp;&nbsp;<tt>Calendar.setDate</tt></a><br>
colas@0
   116
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.13"></a><a href="#node_sec_5.3.13">5.3.13&nbsp;&nbsp;<tt>Calendar.setFirstDayOfWeek</tt></a><br>
colas@0
   117
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.14"></a><a href="#node_sec_5.3.14">5.3.14&nbsp;&nbsp;<tt>Calendar.parseDate</tt></a><br>
colas@0
   118
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; <a name="node_toc_node_sec_5.3.15"></a><a href="#node_sec_5.3.15">5.3.15&nbsp;&nbsp;<tt>Calendar.setRange</tt></a><br>
colas@0
   119
</p>
colas@0
   120
<p><b>
colas@0
   121
&nbsp; &nbsp; <a name="node_toc_node_sec_6"></a><a href="#node_sec_6">6&nbsp;&nbsp;Side effects</a></b><br>
colas@0
   122
</p>
colas@0
   123
<p><b>
colas@0
   124
&nbsp; &nbsp; <a name="node_toc_node_sec_7"></a><a href="#node_sec_7">7&nbsp;&nbsp;Credits</a></b><br>
colas@0
   125
</p>
colas@0
   126
<p>
colas@0
   127
</p>
colas@0
   128
<p>
colas@0
   129
</p>
colas@0
   130
<a name="node_sec_1"></a>
colas@0
   131
<h1><a href="#node_toc_node_sec_1">1&nbsp;&nbsp;Overview</a></h1>
colas@0
   132
<p>The DHTML Calendar widget<a name="call_footnote_Temp_2"></a><a href="#footnote_Temp_2"><sup><small>1</small></sup></a>
colas@0
   133
is an (HTML) user interface element that gives end-users a friendly way to
colas@0
   134
select date and time.  It works in a web browser.  The first versions only provided
colas@0
   135
support for popup calendars, while starting with version 0.9 it also supports
colas@0
   136
``flat'' display.  A ``flat'' calendar is a calendar that stays visible in the
colas@0
   137
page all the time.  In this mode it could be very useful for ``blog'' pages and
colas@0
   138
other pages that require the calendar to be always present.</p>
colas@0
   139
<p>
colas@0
   140
The calendar is compatible with most popular browsers nowadays.  While it's
colas@0
   141
created using web standards and it should generally work with any compliant
colas@0
   142
browser, the following browsers were found to work: Mozilla/Firefox (the
colas@0
   143
development platform), Netscape&nbsp;6.0 or better, all other Gecko-based browsers,
colas@0
   144
Internet Explorer&nbsp;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&nbsp;7<a name="call_footnote_Temp_4"></a><a href="#footnote_Temp_4"><sup><small>3</small></sup></a>, Konqueror 3.1.2 and Apple Safari for
colas@0
   145
MacOSX.</p>
colas@0
   146
<p>
colas@0
   147
You can find the latest info and version at the calendar homepage:</p>
colas@0
   148
<p>
colas@0
   149
</p>
colas@0
   150
<div align=center><table><tr><td>
colas@0
   151
colas@0
   152
<a href="http://www.dynarch.com/projects/calendar/"><tt>www.dynarch.com/projects/calendar</tt></a>
colas@0
   153
</td></tr></table></div>
colas@0
   154
<p>
colas@0
   155
</p>
colas@0
   156
<a name="node_sec_1.1"></a>
colas@0
   157
<h2><a href="#node_toc_node_sec_1.1">1.1&nbsp;&nbsp;How does this thing work?</a></h2>
colas@0
   158
<p>DHTML is not ``another kind of HTML''.  It's merely a naming convention.  DHTML
colas@0
   159
refers to the combination of HTML, CSS, JavaScript and DOM.  DOM (Document
colas@0
   160
Object Model) is a set of interfaces that glues the other three together.  In
colas@0
   161
other words, DOM allows dynamic modification of an HTML page through a program.
colas@0
   162
JavaScript is our programming language, since that's what browsers like.  CSS
colas@0
   163
is a way to make it look good ;-).  So all this soup is generically known as
colas@0
   164
DHTML.</p>
colas@0
   165
<p>
colas@0
   166
Using DOM calls, the program dynamically creates a <tt>&lt;table&gt;</tt> element
colas@0
   167
that contains a calendar for the given date and then inserts it in the document
colas@0
   168
body.  Then it shows this table at a specified position.  Usually the position
colas@0
   169
is related to some element in which the date needs to be displayed/entered,
colas@0
   170
such as an input field.</p>
colas@0
   171
<p>
colas@0
   172
By assigning a certain CSS class to the table we can control the look of the
colas@0
   173
calendar through an external CSS file; therefore, in order to change the
colas@0
   174
colors, backgrounds, rollover effects and other stuff, you can only change a
colas@0
   175
CSS file -- modification of the program itself is not necessary.</p>
colas@0
   176
<p>
colas@0
   177
</p>
colas@0
   178
<a name="node_sec_1.2"></a>
colas@0
   179
<h2><a href="#node_toc_node_sec_1.2">1.2&nbsp;&nbsp;Project files</a></h2>
colas@0
   180
<p>Here's a description of the project files, excluding documentation and example
colas@0
   181
files.</p>
colas@0
   182
<p>
colas@0
   183
</p>
colas@0
   184
<ul><p>
colas@0
   185
</p>
colas@0
   186
<li><p>the main program file (<tt>calendar.js</tt>).  This defines all the logic
colas@0
   187
behind the calendar widget.</p>
colas@0
   188
<p>
colas@0
   189
</p>
colas@0
   190
<li><p>the CSS files (<tt>calendar-*.css</tt>).  Loading one of them is
colas@0
   191
necessary in order to see the calendar as intended.</p>
colas@0
   192
<p>
colas@0
   193
</p>
colas@0
   194
<li><p>the language definition files (<tt>lang/calendar-*.js</tt>).  They are
colas@0
   195
plain JavaScript files that contain all texts that are displayed by the
colas@0
   196
calendar.  Loading one of them is necessary.</p>
colas@0
   197
<p>
colas@0
   198
</p>
colas@0
   199
<li><p>helper functions for quick setup of the calendar
colas@0
   200
(<tt>calendar-setup.js</tt>).  You can do fine without it, but starting with
colas@0
   201
version 0.9.3 this is the recommended way to setup a calendar.</p>
colas@0
   202
<p>
colas@0
   203
</p>
colas@0
   204
</ul><p></p>
colas@0
   205
<p>
colas@0
   206
</p>
colas@0
   207
<a name="node_sec_1.3"></a>
colas@0
   208
<h2><a href="#node_toc_node_sec_1.3">1.3&nbsp;&nbsp;License</a></h2>
colas@0
   209
<p></p>
colas@0
   210
<div align=center><table><tr><td>
colas@0
   211
colas@0
   212
&copy; Dynarch.com 2002-2005,
colas@0
   213
<a href="http://www.dynarch.com/"><tt>www.dynarch.com</tt></a>
colas@0
   214
Author: Mihai Bazon
colas@0
   215
</td></tr></table></div>
colas@0
   216
<p>
colas@0
   217
The calendar is released under the
colas@0
   218
<a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License</a>.</p>
colas@0
   219
<p>
colas@0
   220
</p>
colas@0
   221
<a name="node_sec_2"></a>
colas@0
   222
<h1><a href="#node_toc_node_sec_2">2&nbsp;&nbsp;Quick startup</a></h1>
colas@0
   223
<p></p>
colas@0
   224
<p>
colas@0
   225
Installing the calendar used to be quite a task until version 0.9.3.  Starting
colas@0
   226
with 0.9.3 I have included the file <tt>calendar-setup.js</tt> whose goal is to
colas@0
   227
assist you to setup a popup or flat calendar in minutes.  You are
colas@0
   228
encouraged to modify this file and <em>not</em> calendar.js if you need
colas@0
   229
extra customization, but you're on your own.</p>
colas@0
   230
<p>
colas@0
   231
First you have to include the needed scripts and style-sheet.  Make sure you do
colas@0
   232
this in your document's <tt>&lt;head&gt;</tt> section, also make sure you put the
colas@0
   233
correct paths to the scripts.</p>
colas@0
   234
<p>
colas@0
   235
</p>
colas@0
   236
<pre class=verbatim>&lt;style type=&quot;text/css&quot;&gt;@import url(calendar-win2k-1.css);&lt;/style&gt;
colas@0
   237
&lt;script type=&quot;text/javascript&quot; src=&quot;calendar.js&quot;&gt;&lt;/script&gt;
colas@0
   238
&lt;script type=&quot;text/javascript&quot; src=&quot;lang/calendar-en.js&quot;&gt;&lt;/script&gt;
colas@0
   239
&lt;script type=&quot;text/javascript&quot; src=&quot;calendar-setup.js&quot;&gt;&lt;/script&gt;
colas@0
   240
</pre><p></p>
colas@0
   241
<p>
colas@0
   242
</p>
colas@0
   243
<a name="node_sec_2.1"></a>
colas@0
   244
<h2><a href="#node_toc_node_sec_2.1">2.1&nbsp;&nbsp;Installing a popup calendar</a></h2>
colas@0
   245
<p></p>
colas@0
   246
<p>
colas@0
   247
Now suppose you have the following HTML:</p>
colas@0
   248
<p>
colas@0
   249
</p>
colas@0
   250
<pre class=verbatim>&lt;form ...&gt;
colas@0
   251
  &lt;input type=&quot;text&quot; id=&quot;data&quot; name=&quot;data&quot; /&gt;
colas@0
   252
  &lt;button id=&quot;trigger&quot;&gt;...&lt;/button&gt;
colas@0
   253
&lt;/form&gt;
colas@0
   254
</pre><p></p>
colas@0
   255
<p>
colas@0
   256
You want the button to popup a calendar widget when clicked?  Just
colas@0
   257
insert the following code immediately <em>after</em> the HTML form:</p>
colas@0
   258
<p>
colas@0
   259
</p>
colas@0
   260
<pre class=verbatim>&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   261
  Calendar.setup(
colas@0
   262
    {
colas@0
   263
      inputField  : &quot;data&quot;,         // ID of the input field
colas@0
   264
      ifFormat    : &quot;%m %d, %Y&quot;,    // the date format
colas@0
   265
      button      : &quot;trigger&quot;       // ID of the button
colas@0
   266
    }
colas@0
   267
  );
colas@0
   268
&lt;/script&gt;
colas@0
   269
</pre><p></p>
colas@0
   270
<p>
colas@0
   271
The <tt>Calendar.setup</tt> function, defined in <tt>calendar-setup.js</tt>
colas@0
   272
takes care of ``patching'' the button to display a calendar when clicked.  The
colas@0
   273
calendar is by default in single-click mode and linked with the given input
colas@0
   274
field, so that when the end-user selects a date it will update the input field
colas@0
   275
with the date in the given format and close the calendar.  If you are a
colas@0
   276
long-term user of the calendar you probably remember that for doing this you
colas@0
   277
needed to write a couple functions and add an ``onclick'' handler for the
colas@0
   278
button by hand.</p>
colas@0
   279
<p>
colas@0
   280
By looking at the example above we can see that the function
colas@0
   281
<tt>Calendar.setup</tt> receives only one parameter: a JavaScript object.
colas@0
   282
Further, that object can have lots of properties that tell to the setup
colas@0
   283
function how would we like to have the calendar.  For instance, if we would
colas@0
   284
like a calendar that closes at double-click instead of single-click we would
colas@0
   285
also include the following: <tt>singleClick:false</tt>.</p>
colas@0
   286
<p>
colas@0
   287
For a list of all supported parameters please see the section
colas@0
   288
<a href="#node_sec_2.3">2.3</a>.</p>
colas@0
   289
<p>
colas@0
   290
</p>
colas@0
   291
<a name="node_sec_2.2"></a>
colas@0
   292
<h2><a href="#node_toc_node_sec_2.2">2.2&nbsp;&nbsp;Installing a flat calendar</a></h2>
colas@0
   293
<p></p>
colas@0
   294
<p>
colas@0
   295
Here's how to configure a flat calendar, using the same <tt>Calendar.setup</tt>
colas@0
   296
function.  First, you should have an empty element with an ID.  This element
colas@0
   297
will act as a container for the calendar.  It can be any block-level element,
colas@0
   298
such as DIV, TABLE, etc.  We will use a DIV in this example.</p>
colas@0
   299
<p>
colas@0
   300
</p>
colas@0
   301
<pre class=verbatim>&lt;div id=&quot;calendar-container&quot;&gt;&lt;/div&gt;
colas@0
   302
</pre><p></p>
colas@0
   303
<p>
colas@0
   304
Then there is the JavaScript code that sets up the calendar into the
colas@0
   305
``calendar-container'' DIV.  The code can occur anywhere in HTML
colas@0
   306
<em>after</em> the DIV element.</p>
colas@0
   307
<p>
colas@0
   308
</p>
colas@0
   309
<pre class=verbatim>&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   310
  function dateChanged(calendar) {
colas@0
   311
    // Beware that this function is called even if the end-user only
colas@0
   312
    // changed the month/year.  In order to determine if a date was
colas@0
   313
    // clicked you can use the dateClicked property of the calendar:
colas@0
   314
    if (calendar.dateClicked) {
colas@0
   315
      // OK, a date was clicked, redirect to /yyyy/mm/dd/index.php
colas@0
   316
      var y = calendar.date.getFullYear();
colas@0
   317
      var m = calendar.date.getMonth();     // integer, 0..11
colas@0
   318
      var d = calendar.date.getDate();      // integer, 1..31
colas@0
   319
      // redirect...
colas@0
   320
      window.location = &quot;/&quot; + y + &quot;/&quot; + m + &quot;/&quot; + d + &quot;/index.php&quot;;
colas@0
   321
    }
colas@0
   322
  };
colas@0
   323
colas@0
   324
  Calendar.setup(
colas@0
   325
    {
colas@0
   326
      flat         : &quot;calendar-container&quot;, // ID of the parent element
colas@0
   327
      flatCallback : dateChanged           // our callback function
colas@0
   328
    }
colas@0
   329
  );
colas@0
   330
&lt;/script&gt;
colas@0
   331
</pre><p></p>
colas@0
   332
<p>
colas@0
   333
</p>
colas@0
   334
<a name="node_sec_2.3"></a>
colas@0
   335
<h2><a href="#node_toc_node_sec_2.3">2.3&nbsp;&nbsp;<tt>Calendar.setup</tt> in detail</a></h2>
colas@0
   336
<p></p>
colas@0
   337
<p>
colas@0
   338
Following there is the complete list of properties interpreted by
colas@0
   339
Calendar.setup.  All of them have default values, so you can pass only those
colas@0
   340
which you would like to customize.  Anyway, you <em>must</em> pass at least one
colas@0
   341
of <tt>inputField</tt>, <tt>displayArea</tt> or <tt>button</tt>, for a popup
colas@0
   342
calendar, or <tt>flat</tt> for a flat calendar.  Otherwise you will get a
colas@0
   343
warning message saying that there's nothing to setup.</p>
colas@0
   344
<p>
colas@0
   345
</p>
colas@0
   346
<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>
colas@0
   347
</td></tr>
colas@0
   348
<tr><td valign=top ><tt>inputField</tt>
colas@0
   349
</td><td valign=top >string </td><td valign=top >The ID of your input field.
colas@0
   350
</td><td valign=top >null
colas@0
   351
</td></tr>
colas@0
   352
<tr><td valign=top ><tt>displayArea</tt>
colas@0
   353
</td><td valign=top >string </td><td valign=top >This is the ID of a &lt;span&gt;, &lt;div&gt;, 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.
colas@0
   354
</td><td valign=top >null
colas@0
   355
</td></tr>
colas@0
   356
<tr><td valign=top ><tt>button</tt>
colas@0
   357
</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.
colas@0
   358
</td><td valign=top >null
colas@0
   359
</td></tr>
colas@0
   360
<tr><td valign=top ><tt>eventName</tt>
colas@0
   361
</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).
colas@0
   362
</td><td valign=top >``click''
colas@0
   363
</td></tr>
colas@0
   364
<tr><td valign=top ><tt>ifFormat</tt>
colas@0
   365
</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.
colas@0
   366
</td><td valign=top >``%Y/%m/%d''
colas@0
   367
</td></tr>
colas@0
   368
<tr><td valign=top ><tt>daFormat</tt>
colas@0
   369
</td><td valign=top >string </td><td valign=top >Format of the date displayed in the displayArea (if specified).
colas@0
   370
</td><td valign=top >``%Y/%m/%d''
colas@0
   371
</td></tr>
colas@0
   372
<tr><td valign=top ><tt>singleClick</tt>
colas@0
   373
</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.
colas@0
   374
</td><td valign=top >true
colas@0
   375
</td></tr>
colas@0
   376
<tr><td valign=top ><tt>disableFunc</tt>
colas@0
   377
</td><td valign=top >function </td><td valign=top >A function that receives a JS Date object.  It should return
colas@0
   378
<tt>true</tt> if that date has to be disabled, <tt>false</tt> otherwise.
colas@0
   379
<font color="red">DEPRECATED (see below).</font>
colas@0
   380
</td><td valign=top >null
colas@0
   381
</td></tr>
colas@0
   382
<tr><td valign=top ><tt>dateStatusFunc</tt>
colas@0
   383
</td><td valign=top >function </td><td valign=top >A function that receives a JS Date object and returns a boolean
colas@0
   384
or a string.  This function allows one to set a certain CSS class to some
colas@0
   385
date, therefore making it look different.  If it returns <tt>true</tt> then
colas@0
   386
the date will be disabled.  If it returns <tt>false</tt> nothing special
colas@0
   387
happens with the given date.  If it returns a string then that will be taken
colas@0
   388
as a CSS class and appended to the date element.  If this string is
colas@0
   389
``disabled'' then the date is also disabled (therefore is like returning
colas@0
   390
<tt>true</tt>).  For more information please also refer to section
colas@0
   391
<a href="#node_sec_5.3.8">5.3.8</a>.
colas@0
   392
</td><td valign=top >null
colas@0
   393
</td></tr>
colas@0
   394
<tr><td valign=top ><tt>firstDay</tt>
colas@0
   395
</td><td valign=top >integer </td><td valign=top >Specifies which day is to be displayed as the first day of
colas@0
   396
week.  Possible values are 0 to 6; 0 means Sunday, 1 means Monday, ..., 6
colas@0
   397
means Saturday.  The end user can easily change this too, by clicking on the
colas@0
   398
day name in the calendar header.
colas@0
   399
</td><td valign=top >0
colas@0
   400
</td></tr>
colas@0
   401
<tr><td valign=top ><tt>weekNumbers</tt>
colas@0
   402
</td><td valign=top >boolean </td><td valign=top >If ``true'' then the calendar will display week numbers.
colas@0
   403
</td><td valign=top >true
colas@0
   404
</td></tr>
colas@0
   405
<tr><td valign=top ><tt>align</tt>
colas@0
   406
</td><td valign=top >string </td><td valign=top >Alignment of the calendar, relative to the reference element. The
colas@0
   407
reference element is dynamically chosen like this: if a displayArea is
colas@0
   408
specified then it will be the reference element. Otherwise, the input field
colas@0
   409
is the reference element.  For the meaning of the alignment characters
colas@0
   410
please section <a href="#node_sec_5.3.11">5.3.11</a>.
colas@0
   411
</td><td valign=top >``Bl''
colas@0
   412
</td></tr>
colas@0
   413
<tr><td valign=top ><tt>range</tt>
colas@0
   414
</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.
colas@0
   415
</td><td valign=top >[1900, 2999]
colas@0
   416
</td></tr>
colas@0
   417
<tr><td valign=top ><tt>flat</tt>
colas@0
   418
</td><td valign=top >string </td><td valign=top >If you want a flat calendar, pass the ID of the parent object in
colas@0
   419
this property.  If not, pass <tt>null</tt> here (or nothing at all as
colas@0
   420
<tt>null</tt> is the default value).
colas@0
   421
</td><td valign=top >null
colas@0
   422
</td></tr>
colas@0
   423
<tr><td valign=top ><tt>flatCallback</tt>
colas@0
   424
</td><td valign=top >function </td><td valign=top >You should provide this function if the calendar is flat.  It
colas@0
   425
will be called when the date in the calendar is changed with a reference to
colas@0
   426
the calendar object.  See section <a href="#node_sec_2.2">2.2</a> for an example
colas@0
   427
of how to setup a flat calendar.
colas@0
   428
</td><td valign=top >null
colas@0
   429
</td></tr>
colas@0
   430
<tr><td valign=top ><tt>onSelect</tt>
colas@0
   431
</td><td valign=top >function </td><td valign=top >If you provide a function handler here then you have to manage
colas@0
   432
the ``click-on-date'' event by yourself.  Look in the calendar-setup.js and
colas@0
   433
take as an example the onSelect handler that you can see there.
colas@0
   434
</td><td valign=top >null
colas@0
   435
</td></tr>
colas@0
   436
<tr><td valign=top ><tt>onClose</tt>
colas@0
   437
</td><td valign=top >function </td><td valign=top >This handler will be called when the calendar needs to close.
colas@0
   438
You don't need to provide one, but if you do it's your responsibility to
colas@0
   439
hide/destroy the calendar.  You're on your own.  Check the calendar-setup.js
colas@0
   440
file for an example.
colas@0
   441
</td><td valign=top >null
colas@0
   442
</td></tr>
colas@0
   443
<tr><td valign=top ><tt>onUpdate</tt>
colas@0
   444
</td><td valign=top >function </td><td valign=top >If you supply a function handler here, it will be called right
colas@0
   445
after the target field is updated with a new date.  You can use this to
colas@0
   446
chain 2 calendars, for instance to setup a default date in the second just
colas@0
   447
after a date was selected in the first.
colas@0
   448
</td><td valign=top >null
colas@0
   449
</td></tr>
colas@0
   450
<tr><td valign=top ><tt>date</tt>
colas@0
   451
</td><td valign=top >date </td><td valign=top >This allows you to setup an initial date where the calendar will be
colas@0
   452
positioned to.  If absent then the calendar will open to the today date.
colas@0
   453
</td><td valign=top >null
colas@0
   454
</td></tr>
colas@0
   455
<tr><td valign=top ><tt>showsTime</tt>
colas@0
   456
</td><td valign=top >boolean </td><td valign=top >If this is set to <tt>true</tt> then the calendar will also
colas@0
   457
allow time selection.
colas@0
   458
</td><td valign=top >false
colas@0
   459
</td></tr>
colas@0
   460
<tr><td valign=top ><tt>timeFormat</tt>
colas@0
   461
</td><td valign=top >string </td><td valign=top >Set this to ``12'' or ``24'' to configure the way that the
colas@0
   462
calendar will display time.
colas@0
   463
</td><td valign=top >``24''
colas@0
   464
</td></tr>
colas@0
   465
<tr><td valign=top ><tt>electric</tt>
colas@0
   466
</td><td valign=top >boolean </td><td valign=top >Set this to ``false'' if you want the calendar to update the
colas@0
   467
field only when closed (by default it updates the field at each date change,
colas@0
   468
even if the calendar is not closed) </td><td valign=top >true
colas@0
   469
</td></tr>
colas@0
   470
<tr><td valign=top ><tt>position</tt>
colas@0
   471
</td><td valign=top >array </td><td valign=top >Specifies the [x, y] position, relative to page's top-left corner,
colas@0
   472
where the calendar will be displayed.  If not passed then the position will
colas@0
   473
be computed based on the ``align'' parameter.  Defaults to ``null'' (not
colas@0
   474
used). </td><td valign=top >null
colas@0
   475
</td></tr>
colas@0
   476
<tr><td valign=top ><tt>cache</tt>
colas@0
   477
</td><td valign=top >boolean </td><td valign=top >Set this to ``true'' if you want to cache the calendar object.
colas@0
   478
This means that a single calendar object will be used for all fields that
colas@0
   479
require a popup calendar </td><td valign=top >false
colas@0
   480
</td></tr>
colas@0
   481
<tr><td valign=top ><tt>showOthers</tt>
colas@0
   482
</td><td valign=top >boolean </td><td valign=top >If set to ``true'' then days belonging to months overlapping
colas@0
   483
with the currently displayed month will also be displayed in the calendar
colas@0
   484
(but in a ``faded-out'' color) </td><td valign=top >false
colas@0
   485
colas@0
   486
</td></tr></table>
colas@0
   487
colas@0
   488
</span><p>
colas@0
   489
</p>
colas@0
   490
<a name="node_sec_3"></a>
colas@0
   491
<h1><a href="#node_toc_node_sec_3">3&nbsp;&nbsp;Recipes</a></h1>
colas@0
   492
<p>This section presents some common ways to setup a calendar using the
colas@0
   493
<tt>Calendar.setup</tt> function detailed in the previous section.</p>
colas@0
   494
<p>
colas@0
   495
We don't discuss here about loading the JS or CSS code -- so make sure you
colas@0
   496
add the proper &lt;script&gt; and &lt;style&gt; or &lt;link&gt; elements in your
colas@0
   497
HTML code.  Also, when we present input fields, please note that they should
colas@0
   498
be embedded in some form in order for data to be actually sent to server; we
colas@0
   499
don't discuss these things here because they are not related to our
colas@0
   500
calendar.</p>
colas@0
   501
<p>
colas@0
   502
</p>
colas@0
   503
<a name="node_sec_3.1"></a>
colas@0
   504
<h2><a href="#node_toc_node_sec_3.1">3.1&nbsp;&nbsp;Popup calendars</a></h2>
colas@0
   505
<p>These samples can be found in the file “<tt>simple-1.html</tt>” from the
colas@0
   506
calendar package.</p>
colas@0
   507
<p>
colas@0
   508
</p>
colas@0
   509
<a name="node_sec_3.1.1"></a>
colas@0
   510
<h3><a href="#node_toc_node_sec_3.1.1">3.1.1&nbsp;&nbsp;Simple text field with calendar attached to a button</a></h3>
colas@0
   511
<p></p>
colas@0
   512
<p>
colas@0
   513
This piece of code will create a calendar for a simple input field with a
colas@0
   514
button that will open the calendar when clicked.</p>
colas@0
   515
<p>
colas@0
   516
</p>
colas@0
   517
<pre class=verbatim>&lt;input type=&quot;text&quot; name=&quot;date&quot; id=&quot;f_date_b&quot;
colas@0
   518
       /&gt;&lt;button type=&quot;reset&quot; id=&quot;f_trigger_b&quot;
colas@0
   519
       &gt;...&lt;/button&gt;
colas@0
   520
&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   521
    Calendar.setup({
colas@0
   522
        inputField     :    &quot;f_date_b&quot;,           //*
colas@0
   523
        ifFormat       :    &quot;%m/%d/%Y %I:%M %p&quot;,
colas@0
   524
        showsTime      :    true,
colas@0
   525
        button         :    &quot;f_trigger_b&quot;,        //*
colas@0
   526
        step           :    1
colas@0
   527
    });
colas@0
   528
&lt;/script&gt;
colas@0
   529
</pre><p></p>
colas@0
   530
<p>
colas@0
   531
Note that this code does more actually; the only <em>required</em> fields are
colas@0
   532
those marked with “//*” -- that is, the ID of the input field and the ID of
colas@0
   533
the button need to be passed to <tt>Calendar.setup</tt> in order for the
colas@0
   534
calendar to be properly assigned to this input field.  As one can easily
colas@0
   535
guess from the argument names, the other arguments configure a certain date
colas@0
   536
format, instruct the calendar to also include a time selector and display
colas@0
   537
every year in the drop-down boxes (the “step” parameter) -- instead of showing
colas@0
   538
every other year as the default calendar does.</p>
colas@0
   539
<p>
colas@0
   540
</p>
colas@0
   541
<a name="node_sec_3.1.2"></a>
colas@0
   542
<h3><a href="#node_toc_node_sec_3.1.2">3.1.2&nbsp;&nbsp;Simple field with calendar attached to an image</a></h3>
colas@0
   543
<p>Same as the above, but the element that triggers the calendar is this time
colas@0
   544
an image, not a button.</p>
colas@0
   545
<p>
colas@0
   546
</p>
colas@0
   547
<pre class=verbatim>&lt;input type=&quot;text&quot; name=&quot;date&quot; id=&quot;f_date_c&quot; readonly=&quot;1&quot; /&gt;
colas@0
   548
&lt;img src=&quot;img.gif&quot; id=&quot;f_trigger_c&quot;
colas@0
   549
     style=&quot;cursor: pointer; border: 1px solid red;&quot;
colas@0
   550
     title=&quot;Date selector&quot;
colas@0
   551
     onmouseover=&quot;this.style.background='red';&quot;
colas@0
   552
     onmouseout=&quot;this.style.background=''&quot; /&gt;
colas@0
   553
&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   554
    Calendar.setup({
colas@0
   555
        inputField     :    &quot;f_date_c&quot;,
colas@0
   556
        ifFormat       :    &quot;%B %e, %Y&quot;,
colas@0
   557
        button         :    &quot;f_trigger_c&quot;,
colas@0
   558
        align          :    &quot;Tl&quot;,
colas@0
   559
        singleClick    :    false
colas@0
   560
    });
colas@0
   561
&lt;/script&gt;
colas@0
   562
</pre><p></p>
colas@0
   563
<p>
colas@0
   564
Note that the same 2 parameters are required as in the previous case; the
colas@0
   565
difference is that the 'button' parameter now gets the ID of the image
colas@0
   566
instead of the ID of the button.  But the event is the same: at 'onclick' on
colas@0
   567
the element that is passed as 'button', the calendar will be shown.</p>
colas@0
   568
<p>
colas@0
   569
The above code additionally sets an alignment mode -- the parameters are
colas@0
   570
described in <a href="#node_sec_5.3.11">5.3.11</a>.</p>
colas@0
   571
<p>
colas@0
   572
</p>
colas@0
   573
<a name="node_sec_3.1.3"></a>
colas@0
   574
<h3><a href="#node_toc_node_sec_3.1.3">3.1.3&nbsp;&nbsp;Hidden field, plain text triggers</a></h3>
colas@0
   575
<p>Sometimes, to assure that the date is well formatted, you might want not to
colas@0
   576
allow the end user to write a date manually.  This can easily be achieved
colas@0
   577
with an input field by setting its <tt>readonly</tt> attribute, which is
colas@0
   578
defined by the HTML4 standard; however, here's an even nicer approach: our
colas@0
   579
calendar widget allows you to use a hidden field as the way to pass data to
colas@0
   580
server, and a “display area” to show the end user the selected date.  The
colas@0
   581
“display area” can be any HTML element, such as a DIV or a SPAN or
colas@0
   582
whatever -- we will use a SPAN in our sample.</p>
colas@0
   583
<p>
colas@0
   584
</p>
colas@0
   585
<pre class=verbatim>&lt;input type=&quot;hidden&quot; name=&quot;date&quot; id=&quot;f_date_d&quot; /&gt;
colas@0
   586
colas@0
   587
&lt;p&gt;Your birthday:
colas@0
   588
   &lt;span style=&quot;background-color: #ff8; cursor: default;&quot;
colas@0
   589
         onmouseover=&quot;this.style.backgroundColor='#ff0';&quot;
colas@0
   590
         onmouseout=&quot;this.style.backgroundColor='#ff8';&quot;
colas@0
   591
         id=&quot;show_d&quot;
colas@0
   592
   &gt;Click to open date selector&lt;/span&gt;.&lt;/p&gt;
colas@0
   593
colas@0
   594
&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   595
    Calendar.setup({
colas@0
   596
        inputField     :    &quot;f_date_d&quot;,
colas@0
   597
        ifFormat       :    &quot;%Y/%d/%m&quot;,
colas@0
   598
        displayArea    :    &quot;show_d&quot;,
colas@0
   599
        daFormat       :    &quot;%A, %B %d, %Y&quot;,
colas@0
   600
    });
colas@0
   601
&lt;/script&gt;
colas@0
   602
</pre><p></p>
colas@0
   603
<p>
colas@0
   604
The above code will configure a calendar attached to the hidden field and to
colas@0
   605
the SPAN having the id=“show_d”.  When the SPAN element is clicked, the
colas@0
   606
calendar opens and allows the end user to chose a date.  When the date is
colas@0
   607
chosen, the input field will be updated with the value in the format
colas@0
   608
“<tt>%Y/%d/%m</tt>”, and the SPAN element will display the date in a
colas@0
   609
friendlier format (defined by “<tt>daFormat</tt>”).</p>
colas@0
   610
<p>
colas@0
   611
Beware that using this approach will make your page unfunctional in browsers
colas@0
   612
that do not support JavaScript or our calendar.</p>
colas@0
   613
<p>
colas@0
   614
</p>
colas@0
   615
<a name="node_sec_3.1.4"></a>
colas@0
   616
<h3><a href="#node_toc_node_sec_3.1.4">3.1.4&nbsp;&nbsp;2 Linked fields, no trigger buttons</a></h3>
colas@0
   617
<p>Supposing you want to create 2 fields that hold an interval of exactly one
colas@0
   618
week.  The first is the starting date, and the second is the ending date.
colas@0
   619
You want the fields to be automatically updated when some date is clicked in
colas@0
   620
one or the other, in order to keep exactly one week difference between them.</p>
colas@0
   621
<p>
colas@0
   622
</p>
colas@0
   623
<pre class=verbatim>&lt;input type=&quot;text&quot; name=&quot;date&quot; id=&quot;f_date_a&quot; /&gt;
colas@0
   624
&lt;input type=&quot;text&quot; name=&quot;date&quot; id=&quot;f_calcdate&quot; /&gt;
colas@0
   625
colas@0
   626
&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   627
    function catcalc(cal) {
colas@0
   628
        var date = cal.date;
colas@0
   629
        var time = date.getTime()
colas@0
   630
        // use the _other_ field
colas@0
   631
        var field = document.getElementById(&quot;f_calcdate&quot;);
colas@0
   632
        if (field == cal.params.inputField) {
colas@0
   633
            field = document.getElementById(&quot;f_date_a&quot;);
colas@0
   634
            time -= Date.WEEK; // substract one week
colas@0
   635
        } else {
colas@0
   636
            time += Date.WEEK; // add one week
colas@0
   637
        }
colas@0
   638
        var date2 = new Date(time);
colas@0
   639
        field.value = date2.print(&quot;%Y-%m-%d %H:%M&quot;);
colas@0
   640
    }
colas@0
   641
    Calendar.setup({
colas@0
   642
        inputField     :    &quot;f_date_a&quot;,
colas@0
   643
        ifFormat       :    &quot;%Y-%m-%d %H:%M&quot;,
colas@0
   644
        showsTime      :    true,
colas@0
   645
        timeFormat     :    &quot;24&quot;,
colas@0
   646
        onUpdate       :    catcalc
colas@0
   647
    });
colas@0
   648
    Calendar.setup({
colas@0
   649
        inputField     :    &quot;f_calcdate&quot;,
colas@0
   650
        ifFormat       :    &quot;%Y-%m-%d %H:%M&quot;,
colas@0
   651
        showsTime      :    true,
colas@0
   652
        timeFormat     :    &quot;24&quot;,
colas@0
   653
        onUpdate       :    catcalc
colas@0
   654
    });
colas@0
   655
&lt;/script&gt;
colas@0
   656
</pre><p></p>
colas@0
   657
<p>
colas@0
   658
The above code will configure 2 input fields with calendars attached, as
colas@0
   659
usual.  The first thing to note is that there's no trigger button -- in such
colas@0
   660
case, the calendar will popup when one clicks into the input field.  Using
colas@0
   661
the <tt>onUpdate</tt> parameter, we pass a reference to a function of ours
colas@0
   662
that will get called after a date was selected.  In that function we
colas@0
   663
determine what field was updated and we compute the date in the other input
colas@0
   664
field such that it keeps a one week difference between the two.  Enjoy! :-)</p>
colas@0
   665
<p>
colas@0
   666
</p>
colas@0
   667
<a name="node_sec_3.2"></a>
colas@0
   668
<h2><a href="#node_toc_node_sec_3.2">3.2&nbsp;&nbsp;Flat calendars</a></h2>
colas@0
   669
<p>This sample can be found in “<tt>simple-2.html</tt>”.  It will configure a
colas@0
   670
flat calendar that is always displayed in the page, in the DIV having the
colas@0
   671
id=“calendar-container”.  When a date is clicked our function hander gets
colas@0
   672
called (<tt>dateChanged</tt>) and it will compute an URL to jump to based on
colas@0
   673
the selected date, then use <tt>window.location</tt> to visit the new link.</p>
colas@0
   674
<p>
colas@0
   675
</p>
colas@0
   676
<pre class=verbatim>&lt;div style=&quot;float: right; margin-left: 1em; margin-bottom: 1em;&quot;
colas@0
   677
id=&quot;calendar-container&quot;&gt;&lt;/div&gt;
colas@0
   678
colas@0
   679
&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   680
  function dateChanged(calendar) {
colas@0
   681
    // Beware that this function is called even if the end-user only
colas@0
   682
    // changed the month/year.  In order to determine if a date was
colas@0
   683
    // clicked you can use the dateClicked property of the calendar:
colas@0
   684
    if (calendar.dateClicked) {
colas@0
   685
      // OK, a date was clicked, redirect to /yyyy/mm/dd/index.php
colas@0
   686
      var y = calendar.date.getFullYear();
colas@0
   687
      var m = calendar.date.getMonth();     // integer, 0..11
colas@0
   688
      var d = calendar.date.getDate();      // integer, 1..31
colas@0
   689
      // redirect...
colas@0
   690
      window.location = &quot;/&quot; + y + &quot;/&quot; + m + &quot;/&quot; + d + &quot;/index.php&quot;;
colas@0
   691
    }
colas@0
   692
  };
colas@0
   693
colas@0
   694
  Calendar.setup(
colas@0
   695
    {
colas@0
   696
      flat         : &quot;calendar-container&quot;, // ID of the parent element
colas@0
   697
      flatCallback : dateChanged           // our callback function
colas@0
   698
    }
colas@0
   699
  );
colas@0
   700
&lt;/script&gt;
colas@0
   701
</pre><p></p>
colas@0
   702
<p>
colas@0
   703
</p>
colas@0
   704
<a name="node_sec_3.3"></a>
colas@0
   705
<h2><a href="#node_toc_node_sec_3.3">3.3&nbsp;&nbsp;Highlight special dates</a></h2>
colas@0
   706
<p>So you want to display certain dates in a different color, or with bold
colas@0
   707
font, or whatever, right?  Well, no problem -- our calendar can do this as
colas@0
   708
well.  It doesn't matter if it's a flat or popup calendar -- we'll use a flat
colas@0
   709
one for this sample.  The idea, however, is that you need to have the dates
colas@0
   710
in an array or a JavaScript object -- whatever is suitable for your way of
colas@0
   711
thinking -- and use it from a function that returns a value, telling the
colas@0
   712
calendar what kind of date is the passed one.</p>
colas@0
   713
<p>
colas@0
   714
Too much talking, here's the code ;-)</p>
colas@0
   715
<p>
colas@0
   716
</p>
colas@0
   717
<pre class=verbatim>&lt;!-- this goes into the &lt;head&gt; tag --&gt;
colas@0
   718
&lt;style type=&quot;text/css&quot;&gt;
colas@0
   719
  .special { background-color: #000; color: #fff; }
colas@0
   720
&lt;/style&gt;
colas@0
   721
colas@0
   722
&lt;!-- and the rest inside the &lt;body&gt; --&gt;
colas@0
   723
&lt;div style=&quot;float: right; margin-left: 1em; margin-bottom: 1em;&quot;
colas@0
   724
id=&quot;calendar-container&quot;&gt;&lt;/div&gt;
colas@0
   725
colas@0
   726
&lt;script type=&quot;text/javascript&quot;&gt;
colas@0
   727
  var SPECIAL_DAYS = {
colas@0
   728
    0 : [ 13, 24 ],		// special days in January
colas@0
   729
    2 : [ 1, 6, 8, 12, 18 ],	// special days in March
colas@0
   730
    8 : [ 21, 11 ]		// special days in September
colas@0
   731
  };
colas@0
   732
colas@0
   733
  function dateIsSpecial(year, month, day) {
colas@0
   734
    var m = SPECIAL_DAYS[month];
colas@0
   735
    if (!m) return false;
colas@0
   736
    for (var i in m) if (m[i] == day) return true;
colas@0
   737
    return false;
colas@0
   738
  };
colas@0
   739
colas@0
   740
  function dateChanged(calendar) {
colas@0
   741
    // Beware that this function is called even if the end-user only
colas@0
   742
    // changed the month/year.  In order to determine if a date was
colas@0
   743
    // clicked you can use the dateClicked property of the calendar:
colas@0
   744
    if (calendar.dateClicked) {
colas@0
   745
      // OK, a date was clicked, redirect to /yyyy/mm/dd/index.php
colas@0
   746
      var y = calendar.date.getFullYear();
colas@0
   747
      var m = calendar.date.getMonth();     // integer, 0..11
colas@0
   748
      var d = calendar.date.getDate();      // integer, 1..31
colas@0
   749
      // redirect...
colas@0
   750
      window.location = &quot;/&quot; + y + &quot;/&quot; + m + &quot;/&quot; + d + &quot;/index.php&quot;;
colas@0
   751
    }
colas@0
   752
  };
colas@0
   753
colas@0
   754
  function ourDateStatusFunc(date, y, m, d) {
colas@0
   755
    if (dateIsSpecial(y, m, d))
colas@0
   756
      return &quot;special&quot;;
colas@0
   757
    else
colas@0
   758
      return false; // other dates are enabled
colas@0
   759
      // return true if you want to disable other dates
colas@0
   760
  };
colas@0
   761
colas@0
   762
  Calendar.setup(
colas@0
   763
    {
colas@0
   764
      flat         : &quot;calendar-container&quot;, // ID of the parent element
colas@0
   765
      flatCallback : dateChanged,          // our callback function
colas@0
   766
      dateStatusFunc : ourDateStatusFunc
colas@0
   767
    }
colas@0
   768
  );
colas@0
   769
&lt;/script&gt;
colas@0
   770
</pre><p></p>
colas@0
   771
<p>
colas@0
   772
So the above code creates a normal flat calendar, like in the previous
colas@0
   773
sample.  We hook into it with the function “<tt>ourDateStatusFunc</tt>”,
colas@0
   774
which receives a date object as the first argument, and also the year,
colas@0
   775
month, date as the next 3 arguments (normally, you can extract year, month,
colas@0
   776
date from the first parameter too, but we pass them separately for
colas@0
   777
convenience, as it's very likely that they are going to be used in this
colas@0
   778
function).</p>
colas@0
   779
<p>
colas@0
   780
So, this function receives a date.  It can return <tt>false</tt> if you want
colas@0
   781
no special action to be taken on that date, <tt>true</tt> if that date
colas@0
   782
should be disabled (unselectable), or a string if you want to assign a
colas@0
   783
special CSS class to that date.  We return “special” for the dates that we
colas@0
   784
want to highlight -- and note that we defined a “special” look for them in
colas@0
   785
the CSS section.</p>
colas@0
   786
<p>
colas@0
   787
I used a simple approach here to define what dates are special.  There's a
colas@0
   788
JavaScript object (the SPECIAL_DAYS global variable) which holds an array
colas@0
   789
of dates for each month.  Month numbers start at zero (January).  Months
colas@0
   790
that don't contain special dates can be absent from this object.  Note that
colas@0
   791
the way to implement this is completely separated from the calendar
colas@0
   792
code -- therefore, feel free to use your imagination if you have better
colas@0
   793
ideas. :-)</p>
colas@0
   794
<p>
colas@0
   795
</p>
colas@0
   796
<a name="node_sec_3.4"></a>
colas@0
   797
<h2><a href="#node_toc_node_sec_3.4">3.4&nbsp;&nbsp;Select multiple dates</a></h2>
colas@0
   798
<p>Starting version 1.0, the calendar is able to handle multiple dates
colas@0
   799
selection.  You just need to pass the “<tt>multiple</tt>” parameter to
colas@0
   800
<tt>Calendar.setup</tt> and add some special code that interprets the
colas@0
   801
selection once the calendar is closed.</p>
colas@0
   802
<p>
colas@0
   803
</p>
colas@0
   804
<pre class=verbatim>&lt;a id=&quot;trigger&quot; href=&quot;#&quot;&gt;[open calendar...]&lt;/a&gt;
colas@0
   805
&lt;div id=&quot;output&quot;&gt;&lt;/div&gt;
colas@0
   806
&lt;script type=&quot;text/javascript&quot;&gt;//&lt;![CDATA[
colas@0
   807
    // the default multiple dates selected,
colas@0
   808
    // first time the calendar is displayed
colas@0
   809
    var MA = [];
colas@0
   810
colas@0
   811
    function closed(cal) {
colas@0
   812
colas@0
   813
      // here we'll write the output; this is only for example.  You
colas@0
   814
      // will normally fill an input field or something with the dates.
colas@0
   815
      var el = document.getElementById(&quot;output&quot;);
colas@0
   816
colas@0
   817
      // reset initial content.
colas@0
   818
      el.innerHTML = &quot;&quot;;
colas@0
   819
colas@0
   820
      // Reset the &quot;MA&quot;, in case one triggers the calendar again.
colas@0
   821
      // CAREFUL!  You don't want to do &quot;MA = [];&quot;.  We need to modify
colas@0
   822
      // the value of the current array, instead of creating a new one.
colas@0
   823
      // Calendar.setup is called only once! :-)  So be careful.
colas@0
   824
      MA.length = 0;
colas@0
   825
colas@0
   826
      // walk the calendar's multiple dates selection hash
colas@0
   827
      for (var i in cal.multiple) {
colas@0
   828
        var d = cal.multiple[i];
colas@0
   829
        // sometimes the date is not actually selected,
colas@0
   830
        // so let's check
colas@0
   831
        if (d) {
colas@0
   832
          // OK, selected.  Fill an input field or something.
colas@0
   833
          el.innerHTML += d.print(&quot;%A, %Y %B %d&quot;) + &quot;&lt;br /&gt;&quot;;
colas@0
   834
          // and push it in the &quot;MA&quot;, in case one triggers the calendar again.
colas@0
   835
          MA[MA.length] = d;
colas@0
   836
        }
colas@0
   837
      }
colas@0
   838
      cal.hide();
colas@0
   839
      return true;
colas@0
   840
    };
colas@0
   841
colas@0
   842
    Calendar.setup({
colas@0
   843
      align      : &quot;BR&quot;,
colas@0
   844
      showOthers : true,
colas@0
   845
      multiple   : MA, // pass the initial or computed array of multiple dates
colas@0
   846
      onClose    : closed,
colas@0
   847
      button     : &quot;trigger&quot;
colas@0
   848
    });
colas@0
   849
//]]&gt;&lt;/script&gt;
colas@0
   850
</pre><p></p>
colas@0
   851
<p>
colas@0
   852
The above code creates a popup calendar and passes to it an array of dates,
colas@0
   853
which is initially empty, in the “multiple” argument.  When the calendar is
colas@0
   854
closed it will call our “<tt>closed</tt>” function handler; in this handler
colas@0
   855
we determine what dates were actually selected, inspecting the
colas@0
   856
“<tt>cal.multiple</tt>” property, we display them in a DIV element right
colas@0
   857
next to the &lt;a&gt; element that opens the calendar, and we reinitialize the
colas@0
   858
global array of selected dates (which will be used if the end user opens the
colas@0
   859
calendar again).  I guess the code speaks for itself, right? :-)</p>
colas@0
   860
<p>
colas@0
   861
</p>
colas@0
   862
<a name="node_sec_4"></a>
colas@0
   863
<h1><a href="#node_toc_node_sec_4">4&nbsp;&nbsp;The Calendar object overview</a></h1>
colas@0
   864
<p></p>
colas@0
   865
<p>
colas@0
   866
Basically you should be able to setup the calendar with the function presented
colas@0
   867
in the previous section.  However, if for some reason <tt>Calendar.setup</tt>
colas@0
   868
doesn't provide all the functionality that you need and you want to tweak into
colas@0
   869
the process of creating and configuring the calendar ``by hand'', then this
colas@0
   870
section is the way to go.</p>
colas@0
   871
<p>
colas@0
   872
The file <tt>calendar.js</tt> implements the functionality of the calendar.
colas@0
   873
All (well, almost all) functions and variables are embedded in the JavaScript
colas@0
   874
object ``Calendar''.</p>
colas@0
   875
<p>
colas@0
   876
You can instantiate a <tt>Calendar</tt> object by calling the constructor, like
colas@0
   877
this: <tt>var cal = new Calendar(<tt>...</tt>)</tt>.  We will discuss the parameters
colas@0
   878
later.  After creating the object, the variable <tt>cal</tt> will contain a
colas@0
   879
reference to it.  You can use this reference to access further options of the
colas@0
   880
calendar, for instance:</p>
colas@0
   881
<p>
colas@0
   882
</p>
colas@0
   883
<pre class=verbatim>cal.weekNumbers = false; // do not display week numbers
colas@0
   884
cal.showsTime = true;    // include a time selector
colas@0
   885
cal.setDateFormat(&quot;%Y.%m.%d %H:%M&quot;); // set this format: 2003.12.31 23:59
colas@0
   886
cal.setDisabledHandler(function(date, year, month, day) {
colas@0
   887
  // verify date and return true if it has to be disabled
colas@0
   888
  // ``date'' is a JS Date object, but if you only need the
colas@0
   889
  // year, month and/or day you can get them separately as
colas@0
   890
  // next 3 parameters, as you can see in the declaration
colas@0
   891
  if (year == 2004) {
colas@0
   892
    // disable all dates from 2004
colas@0
   893
    return true;
colas@0
   894
  }
colas@0
   895
  return false;
colas@0
   896
});
colas@0
   897
</pre><p></p>
colas@0
   898
<p>
colas@0
   899
etc.  Prior to version
colas@0
   900
0.9.3 this was the only way to configure it.  The <tt>Calendar.setup</tt>
colas@0
   901
function, documented in section <a href="#node_sec_2">2</a>, basically does the same
colas@0
   902
things (actually more) in order to setup the calendar, based on the parameters
colas@0
   903
that you provided.</p>
colas@0
   904
<p>
colas@0
   905
</p>
colas@0
   906
<a name="node_sec_4.1"></a>
colas@0
   907
<h2><a href="#node_toc_node_sec_4.1">4.1&nbsp;&nbsp;Creating a calendar</a></h2>
colas@0
   908
<p>The calendar is created by following some steps (even the function
colas@0
   909
<tt>Calendar.setup</tt>, described in section <a href="#node_sec_2">2</a>, does the
colas@0
   910
same).  While you can skip optional (marked ``opt'') steps if you're happy with
colas@0
   911
the defaults, please respect the order below.</p>
colas@0
   912
<p>
colas@0
   913
</p>
colas@0
   914
<ol><p>
colas@0
   915
</p>
colas@0
   916
<li><p><em>Instantiate</em> a <tt>Calendar</tt> object.  Details about this in
colas@0
   917
section <a href="#node_sec_5.1">5.1</a>.</p>
colas@0
   918
<p>
colas@0
   919
</p>
colas@0
   920
<li><p><b>opt</b>&nbsp;&nbsp; Set the <tt>weekNumbers</tt> property to <tt>false</tt> if you don't want
colas@0
   921
the calendar to display week numbers.</p>
colas@0
   922
<p>
colas@0
   923
</p>
colas@0
   924
<li><p><b>opt</b>&nbsp;&nbsp; Set the <tt>showsTime</tt> property to <tt>true</tt> if you
colas@0
   925
want the calendar to also provide a time selector.</p>
colas@0
   926
<p>
colas@0
   927
</p>
colas@0
   928
<li><p><b>opt</b>&nbsp;&nbsp; Set the <tt>time24</tt> property to <tt>false</tt> if you want
colas@0
   929
the time selector to be in 12-hour format.  Default is 24-hour format.  This
colas@0
   930
property only has effect if you also set <tt>showsTime</tt> to
colas@0
   931
<tt>true</tt>.</p>
colas@0
   932
<p>
colas@0
   933
</p>
colas@0
   934
<li><p><b>opt</b>&nbsp;&nbsp; Set the range of years available for selection (see section
colas@0
   935
<a href="#node_sec_5.3.15">5.3.15</a>).  The default range is [1970..2050].</p>
colas@0
   936
<p>
colas@0
   937
</p>
colas@0
   938
<li><p><b>opt</b>&nbsp;&nbsp; Set the <tt>getDateStatus</tt> property.  You should pass
colas@0
   939
here a function that receives a JavaScript <tt>Date</tt> object and returns
colas@0
   940
<tt>true</tt> if the given date should be disabled, false otherwise (details in
colas@0
   941
section <a href="#node_sec_5.3.7">5.3.7</a>).</p>
colas@0
   942
<p>
colas@0
   943
</p>
colas@0
   944
<li><p><b>opt</b>&nbsp;&nbsp; Set a date format.  Your handler function, passed to the
colas@0
   945
calendar constructor, will be called when a date is selected with a reference
colas@0
   946
to the calendar and a date string in this format.</p>
colas@0
   947
<p>
colas@0
   948
</p>
colas@0
   949
<li><p><em>Create</em> the HTML elements related to the calendar.  This step
colas@0
   950
practically puts the calendar in your HTML page.  You simply call
colas@0
   951
<tt>Calendar.create()</tt>.  You can give an optional parameter if you wanna
colas@0
   952
create a flat calendar (details in section <a href="#node_sec_5.3.1">5.3.1</a>).</p>
colas@0
   953
<p>
colas@0
   954
</p>
colas@0
   955
<li><p><b>opt</b>&nbsp;&nbsp; Initialize the calendar to a certain date, for instance from
colas@0
   956
the input field.</p>
colas@0
   957
<p>
colas@0
   958
</p>
colas@0
   959
<li><p>Show the calendar (details in section <a href="#node_sec_5.3.9">5.3.9</a>).</p>
colas@0
   960
<p>
colas@0
   961
</p>
colas@0
   962
</ol><p></p>
colas@0
   963
<p>
colas@0
   964
</p>
colas@0
   965
<a name="node_sec_4.2"></a>
colas@0
   966
<h2><a href="#node_toc_node_sec_4.2">4.2&nbsp;&nbsp;Order does matter ;-)</a></h2>
colas@0
   967
<p>As you could see in the previous section, there are more steps to be followed
colas@0
   968
in order to setup the calendar.  This happens because there are two different
colas@0
   969
things that need to be accomplished: first there is the JavaScript object, that
colas@0
   970
is created with <tt>new Calendar(<tt>...</tt>)</tt>.  Secondly there are the HTML
colas@0
   971
elements that actually lets you see and manipulate the calendar.</p>
colas@0
   972
<p>
colas@0
   973
</p>
colas@0
   974
<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
colas@0
   975
language and on what platform, may be familiar with this concept.  First there
colas@0
   976
is the object in memory that lets you manipulate the UI element, and secondly
colas@0
   977
there is the UI element (known as ``control'', ``window'', ``widget'', etc.),
colas@0
   978
also in memory but you don't usually access it directly. ]
colas@0
   979
</span><p>
colas@0
   980
By instantiating the calendar we create the JavaScript object.  It lets us
colas@0
   981
configure some properties and it also knows how to create the UI element (the
colas@0
   982
HTML elements actually) that will eventually be what the end-user sees on
colas@0
   983
screen.  Creation of the HTML element is accomplished by the function
colas@0
   984
<tt>Calendar.create</tt>.  It knows how to create popup or flat calendars.
colas@0
   985
This function is described in section <a href="#node_sec_5.3.1">5.3.1</a>.</p>
colas@0
   986
<p>
colas@0
   987
Some properties need to be set prior to creating the HTML elements, because
colas@0
   988
otherwise they wouldn't have any effect.  Such a property is
colas@0
   989
<tt>weekNumbers</tt> -- it has the default value ``true'', and if you don't
colas@0
   990
want the calendar to display the week numbers you have to set it to false.  If,
colas@0
   991
however, you do that <em>after</em> calling <tt>Calendar.create</tt> the calendar
colas@0
   992
would still display the week numbers, because the HTML elements are already
colas@0
   993
created (including the <tt>&lt;td&gt;</tt>-s in the <tt>&lt;table&gt;</tt> element that
colas@0
   994
should contain the week numbers).  For this reason the order of the steps above
colas@0
   995
is important.</p>
colas@0
   996
<p>
colas@0
   997
Another example is when you want to show the calendar.  The ``create'' function
colas@0
   998
does create the HTML elements, but they are initially hidden (have the style
colas@0
   999
``display: none'') unless the calendar is a flat calendar that should be always
colas@0
  1000
visible in the page.  Obviously, the <tt>Calendar.show</tt> function should be
colas@0
  1001
called <em>after</em> calling <tt>Calendar.create</tt>.</p>
colas@0
  1002
<p>
colas@0
  1003
</p>
colas@0
  1004
<a name="node_sec_4.3"></a>
colas@0
  1005
<h2><a href="#node_toc_node_sec_4.3">4.3&nbsp;&nbsp;Caching the object</a></h2>
colas@0
  1006
<p>Suppose the end-user has popped up a calendar and selects a date.  The calendar
colas@0
  1007
then closes.  What really happens now?</p>
colas@0
  1008
<p>
colas@0
  1009
There are two approaches.  The first (used in very old versions of the
colas@0
  1010
calendar) was to drop completely the Calendar object and when the end-user pops
colas@0
  1011
up the calendar again to create another one.  This approach is bad for more
colas@0
  1012
reasons:</p>
colas@0
  1013
<p>
colas@0
  1014
</p>
colas@0
  1015
<ul><p>
colas@0
  1016
</p>
colas@0
  1017
<li><p>creating the JavaScript object and HTML elements is time-consuming</p>
colas@0
  1018
<p>
colas@0
  1019
</p>
colas@0
  1020
<li><p>we may loose some end-user preferences (i.e. he might prefer to have
colas@0
  1021
Monday for the first day of week and probably already clicked it the first time
colas@0
  1022
when the calendar was opened, but now he has to do it again)</p>
colas@0
  1023
<p>
colas@0
  1024
</p>
colas@0
  1025
</ul><p></p>
colas@0
  1026
<p>
colas@0
  1027
The second approach, implemented by the <tt>Calendar.setup</tt> function, is to
colas@0
  1028
cache the JavaScript object.  It does this by checking the global variable
colas@0
  1029
<tt>window.calendar</tt> and if it is not null it assumes it is the created
colas@0
  1030
Calendar object.  When the end-user closes the calendar, our code will only
colas@0
  1031
call ``<tt>hide</tt>'' on it, therefore keeping the JavaScript object and the
colas@0
  1032
HTML elements in place.</p>
colas@0
  1033
<p>
colas@0
  1034
<font color="red">CAVEAT:</font> &nbsp;&nbsp;&nbsp;&nbsp;Since time selection support was introduced, this
colas@0
  1035
``object caching'' mechanism has the following drawback: if you once created
colas@0
  1036
the calendar with the time selection support, then other items that may not
colas@0
  1037
require this functionality will still get a calendar with the time selection
colas@0
  1038
support enabled.  And reciprocal. ;-)  Hopefully this will be corrected in a
colas@0
  1039
later version, but for now it doesn't seem such a big problem.</p>
colas@0
  1040
<p>
colas@0
  1041
</p>
colas@0
  1042
<a name="node_sec_4.4"></a>
colas@0
  1043
<h2><a href="#node_toc_node_sec_4.4">4.4&nbsp;&nbsp;Callback functions</a></h2>
colas@0
  1044
<p>You might rightfully wonder how is the calendar related to the input field?
colas@0
  1045
Who tells it that it has to update <em>that</em> input field when a date is
colas@0
  1046
selected, or that it has to jump to <em>that</em> URL when a date is clicked in
colas@0
  1047
flat mode?</p>
colas@0
  1048
<p>
colas@0
  1049
All this magic is done through callback functions.  The calendar doesn't know
colas@0
  1050
anything about the existence of an input field, nor does it know where to
colas@0
  1051
redirect the browser when a date is clicked in flat mode.  It just calls your
colas@0
  1052
callback when a particular event is happening, and you're responsible to handle
colas@0
  1053
it from there.  For a general purpose library I think this is the best model of
colas@0
  1054
making a truly reusable thing.</p>
colas@0
  1055
<p>
colas@0
  1056
The calendar supports the following user callbacks:</p>
colas@0
  1057
<p>
colas@0
  1058
</p>
colas@0
  1059
<ul><p>
colas@0
  1060
</p>
colas@0
  1061
<li><p><b>onSelect</b>&nbsp;&nbsp;  --  this gets called when the end-user changes the date in the
colas@0
  1062
calendar.  Documented in section <a href="#node_sec_5.1">5.1</a>.</p>
colas@0
  1063
<p>
colas@0
  1064
</p>
colas@0
  1065
<li><p><b>onClose</b>&nbsp;&nbsp;  --  this gets called when the calendar should close.  It's
colas@0
  1066
user's responsibility to close the calendar.  Details in section
colas@0
  1067
<a href="#node_sec_5.1">5.1</a>.</p>
colas@0
  1068
<p>
colas@0
  1069
</p>
colas@0
  1070
<li><p><b>getDateStatus</b>&nbsp;&nbsp;  --  this function gets called for any day in a month,
colas@0
  1071
just before displaying the month.  It is called with a JavaScript <tt>Date</tt>
colas@0
  1072
object and should return <tt>true</tt> if that date should be disabled, false
colas@0
  1073
if it's an ordinary date and no action should be taken, or it can return a
colas@0
  1074
string in which case the returned value will be appended to the element's CSS
colas@0
  1075
class (this way it provides a powerful way to make some dates ``special'',
colas@0
  1076
i.e. highlight them differently).  Details in section
colas@0
  1077
<a href="#node_sec_5.3.8">5.3.8</a>.</p>
colas@0
  1078
<p>
colas@0
  1079
</p>
colas@0
  1080
</ul><p></p>
colas@0
  1081
<p>
colas@0
  1082
</p>
colas@0
  1083
<a name="node_sec_5"></a>
colas@0
  1084
<h1><a href="#node_toc_node_sec_5">5&nbsp;&nbsp;The Calendar object API reference</a></h1>
colas@0
  1085
<p></p>
colas@0
  1086
<p>
colas@0
  1087
</p>
colas@0
  1088
<a name="node_sec_5.1"></a>
colas@0
  1089
<h2><a href="#node_toc_node_sec_5.1">5.1&nbsp;&nbsp;<tt>Calendar</tt> constructor</a></h2>
colas@0
  1090
<p></p>
colas@0
  1091
<p>
colas@0
  1092
Synopsis:</p>
colas@0
  1093
<p>
colas@0
  1094
</p>
colas@0
  1095
<pre class=verbatim>var calendar = Calendar(firstDayOfWeek, date, onSelect, onClose);
colas@0
  1096
</pre><p></p>
colas@0
  1097
<p>
colas@0
  1098
Parameters are as follows:</p>
colas@0
  1099
<p>
colas@0
  1100
</p>
colas@0
  1101
<ul><p>
colas@0
  1102
</p>
colas@0
  1103
<li><p><b>firstDayOfWeek</b>&nbsp;&nbsp;  --  specifies which day is to be displayed as the first
colas@0
  1104
day of week.  Possible values are 0 to 6; 0 means Sunday, 1 means Monday,
colas@0
  1105
..., 6 means Saturday.</p>
colas@0
  1106
<p>
colas@0
  1107
</p>
colas@0
  1108
<li><p><b>date</b>&nbsp;&nbsp;  --  a JavaScript Date object or <tt>null</tt>.  If <tt>null</tt>
colas@0
  1109
is passed then the calendar will default to today date.  Otherwise it will
colas@0
  1110
initialize on the given date.</p>
colas@0
  1111
<p>
colas@0
  1112
</p>
colas@0
  1113
<li><p><b>onSelect</b>&nbsp;&nbsp;  --  your callback for the ``onChange'' event.  See above.</p>
colas@0
  1114
<p>
colas@0
  1115
</p>
colas@0
  1116
<li><p><b>onClose</b>&nbsp;&nbsp;  --  your callback for the ``onClose'' event.  See above.</p>
colas@0
  1117
<p>
colas@0
  1118
</p>
colas@0
  1119
</ul><p></p>
colas@0
  1120
<p>
colas@0
  1121
</p>
colas@0
  1122
<a name="node_sec_Temp_6"></a>
colas@0
  1123
<h3><a href="#node_toc_node_sec_Temp_6">The <tt>onSelect</tt> event</a></h3>
colas@0
  1124
<p></p>
colas@0
  1125
<p>
colas@0
  1126
Here is a typical implementation of this function:</p>
colas@0
  1127
<p>
colas@0
  1128
</p>
colas@0
  1129
<pre class=verbatim>function onSelect(calendar, date) {
colas@0
  1130
  var input_field = document.getElementById(&quot;date&quot;);
colas@0
  1131
  input_field.value = date;
colas@0
  1132
};
colas@0
  1133
</pre><p></p>
colas@0
  1134
<p>
colas@0
  1135
<tt>date</tt> is in the format selected with <tt>calendar.setDateFormat</tt>
colas@0
  1136
(see section <a href="#node_sec_5.3.5">5.3.5</a>).  This code simply updates the
colas@0
  1137
input field.  If you want the calendar to be in single-click mode then you
colas@0
  1138
should also close the calendar after you updated the input field, so we come to
colas@0
  1139
the following version:</p>
colas@0
  1140
<p>
colas@0
  1141
</p>
colas@0
  1142
<pre class=verbatim>function onSelect(calendar, date) {
colas@0
  1143
  var input_field = document.getElementById(&quot;date&quot;);
colas@0
  1144
  input_field.value = date;
colas@0
  1145
  if (calendar.dateClicked) {
colas@0
  1146
    calendar.callCloseHandler(); // this calls &quot;onClose&quot; (see above)
colas@0
  1147
  }
colas@0
  1148
};
colas@0
  1149
</pre><p></p>
colas@0
  1150
<p>
colas@0
  1151
Note that we checked the member variable <tt>dateClicked</tt> and
colas@0
  1152
only hide the calendar if it's <tt>true</tt>.  If this variable is <tt>false</tt> it
colas@0
  1153
means that no date was actually selected, but the user only changed the
colas@0
  1154
month/year using the navigation buttons or the menus.  We don't want to hide
colas@0
  1155
the calendar in that case.</p>
colas@0
  1156
<p>
colas@0
  1157
</p>
colas@0
  1158
<a name="node_sec_Temp_7"></a>
colas@0
  1159
<h3><a href="#node_toc_node_sec_Temp_7">The <tt>onClose</tt> event</a></h3>
colas@0
  1160
<p></p>
colas@0
  1161
<p>
colas@0
  1162
This event is triggered when the calendar should close.  It should hide or
colas@0
  1163
destroy the calendar object -- the calendar itself just triggers the event, but
colas@0
  1164
it won't close itself.</p>
colas@0
  1165
<p>
colas@0
  1166
A typical implementation of this function is the following:</p>
colas@0
  1167
<p>
colas@0
  1168
</p>
colas@0
  1169
<pre class=verbatim>function onClose(calendar) {
colas@0
  1170
  calendar.hide();
colas@0
  1171
  // or calendar.destroy();
colas@0
  1172
};
colas@0
  1173
</pre><p></p>
colas@0
  1174
<p>
colas@0
  1175
</p>
colas@0
  1176
<a name="node_sec_5.2"></a>
colas@0
  1177
<h2><a href="#node_toc_node_sec_5.2">5.2&nbsp;&nbsp;Useful member variables (properties)</a></h2>
colas@0
  1178
<p></p>
colas@0
  1179
<p>
colas@0
  1180
After creating the Calendar object you can access the following properties:</p>
colas@0
  1181
<p>
colas@0
  1182
</p>
colas@0
  1183
<ul><p>
colas@0
  1184
</p>
colas@0
  1185
<li><p><tt>date</tt>  --  is a JavaScript <tt>Date</tt> object.  It will always
colas@0
  1186
reflect the date shown in the calendar (yes, even if the calendar is hidden).</p>
colas@0
  1187
<p>
colas@0
  1188
</p>
colas@0
  1189
<li><p><tt>isPopup</tt>  --  if this is true then the current Calendar object is
colas@0
  1190
a popup calendar.  Otherwise (false) we have a flat calendar.  This variable is
colas@0
  1191
set from <tt>Calendar.create</tt> and has no meaning before this function was
colas@0
  1192
called.</p>
colas@0
  1193
<p>
colas@0
  1194
</p>
colas@0
  1195
<li><p><tt>dateClicked</tt>  --  particularly useful in the <tt>onSelect</tt>
colas@0
  1196
handler, this variable tells us if a date was really clicked.  That's because
colas@0
  1197
the <tt>onSelect</tt> handler is called even if the end-user only changed the
colas@0
  1198
month/year but did not select a date.  We don't want to close the calendar in
colas@0
  1199
that case.</p>
colas@0
  1200
<p>
colas@0
  1201
</p>
colas@0
  1202
<li><p><tt>weekNumbers</tt>  --  if <tt>true</tt> (default) then the calendar
colas@0
  1203
displays week numbers.  If you don't want week numbers you have to set this
colas@0
  1204
variable to <tt>false</tt> <em>before</em> calling <tt>Calendar.create</tt>.</p>
colas@0
  1205
<p>
colas@0
  1206
</p>
colas@0
  1207
<li><p><tt>showsTime</tt> - if you set this to <tt>true</tt> (it is
colas@0
  1208
<tt>false</tt> by default) then the calendar will also include a time selector.</p>
colas@0
  1209
<p>
colas@0
  1210
</p>
colas@0
  1211
<li><p><tt>time24</tt> - if you set this to <tt>false</tt> then the time
colas@0
  1212
selector will be in 12-hour format.  It is in 24-hour format by default.</p>
colas@0
  1213
<p>
colas@0
  1214
</p>
colas@0
  1215
<li><p><tt>firstDayOfWeek</tt>  --  specifies the first day of week (0 to 6, pass
colas@0
  1216
0 for Sunday, 1 for Monday, ..., 6 for Saturday).  This variable is set from
colas@0
  1217
constructor, but you still have a chance to modify it <em>before</em> calling
colas@0
  1218
<tt>Calendar.create</tt>.</p>
colas@0
  1219
<p>
colas@0
  1220
</p>
colas@0
  1221
</ul><p></p>
colas@0
  1222
<p>
colas@0
  1223
There are lots of other member variables, but one should access them only
colas@0
  1224
through member functions so I won't document them here.</p>
colas@0
  1225
<p>
colas@0
  1226
</p>
colas@0
  1227
<a name="node_sec_5.3"></a>
colas@0
  1228
<h2><a href="#node_toc_node_sec_5.3">5.3&nbsp;&nbsp;Public methods</a></h2>
colas@0
  1229
<p></p>
colas@0
  1230
<a name="node_sec_5.3.1"></a>
colas@0
  1231
<h3><a href="#node_toc_node_sec_5.3.1">5.3.1&nbsp;&nbsp;<tt>Calendar.create</tt></a></h3>
colas@0
  1232
<p></p>
colas@0
  1233
<p>
colas@0
  1234
This function creates the afferent HTML elements that are needed to display the
colas@0
  1235
calendar.  You should call it after setting the calendar properties.  Synopsis:
colas@0
  1236
</p>
colas@0
  1237
<pre class=verbatim>calendar.create(); // creates a popup calendar
colas@0
  1238
  // -- or --
colas@0
  1239
calendar.create(document.getElementById(parent_id)); // makes a flat calendar
colas@0
  1240
</pre><p></p>
colas@0
  1241
<p>
colas@0
  1242
It can create a popup calendar or a flat calendar.  If the ``parent'' argument
colas@0
  1243
is present (it should be a <em>reference</em> -- not ID -- to an HTML element) then
colas@0
  1244
a flat calendar is created and it is inserted in the given element.</p>
colas@0
  1245
<p>
colas@0
  1246
At any moment, given a reference to a calendar object, we can inspect if it's a
colas@0
  1247
popup or a flat calendar by checking the boolean member variable
colas@0
  1248
<tt>isPopup</tt>:</p>
colas@0
  1249
<p>
colas@0
  1250
</p>
colas@0
  1251
<pre class=verbatim>if (calendar.isPopup) {
colas@0
  1252
   // this is a popup calendar
colas@0
  1253
} else {
colas@0
  1254
   // this is a flat calendar
colas@0
  1255
}
colas@0
  1256
</pre><p></p>
colas@0
  1257
<p>
colas@0
  1258
</p>
colas@0
  1259
<a name="node_sec_5.3.2"></a>
colas@0
  1260
<h3><a href="#node_toc_node_sec_5.3.2">5.3.2&nbsp;&nbsp;<tt>Calendar.callHandler</tt></a></h3>
colas@0
  1261
<p></p>
colas@0
  1262
<p>
colas@0
  1263
This function calls the first user callback (the
colas@0
  1264
<tt>onSelect</tt> handler) with the required parameters.</p>
colas@0
  1265
<p>
colas@0
  1266
</p>
colas@0
  1267
<a name="node_sec_5.3.3"></a>
colas@0
  1268
<h3><a href="#node_toc_node_sec_5.3.3">5.3.3&nbsp;&nbsp;<tt>Calendar.callCloseHandler</tt></a></h3>
colas@0
  1269
<p></p>
colas@0
  1270
<p>
colas@0
  1271
This function calls the second user callback (the
colas@0
  1272
<tt>onClose</tt> handler).  It's useful when you want to have a
colas@0
  1273
``single-click'' calendar -- just call this in your <tt>onSelect</tt> handler,
colas@0
  1274
if a date was clicked.</p>
colas@0
  1275
<p>
colas@0
  1276
</p>
colas@0
  1277
<a name="node_sec_5.3.4"></a>
colas@0
  1278
<h3><a href="#node_toc_node_sec_5.3.4">5.3.4&nbsp;&nbsp;<tt>Calendar.hide</tt></a></h3>
colas@0
  1279
<p></p>
colas@0
  1280
<p>
colas@0
  1281
Call this function to hide the calendar.  The calendar object and HTML elements
colas@0
  1282
will not be destroyed, thus you can later call one of the <tt>show</tt>
colas@0
  1283
functions on the same element.</p>
colas@0
  1284
<p>
colas@0
  1285
</p>
colas@0
  1286
<a name="node_sec_5.3.5"></a>
colas@0
  1287
<h3><a href="#node_toc_node_sec_5.3.5">5.3.5&nbsp;&nbsp;<tt>Calendar.setDateFormat</tt></a></h3>
colas@0
  1288
<p></p>
colas@0
  1289
<p>
colas@0
  1290
This function configures the format in which the calendar reports the date to
colas@0
  1291
your ``onSelect'' handler.  Call it like this:</p>
colas@0
  1292
<p>
colas@0
  1293
</p>
colas@0
  1294
<pre class=verbatim>calendar.setDateFormat(&quot;%y/%m/%d&quot;);
colas@0
  1295
</pre><p></p>
colas@0
  1296
<p>
colas@0
  1297
As you can see, it receives only one parameter, the required format.  The magic
colas@0
  1298
characters are the following:</p>
colas@0
  1299
<p>
colas@0
  1300
</p>
colas@0
  1301
<table border=0><tr><td valign=top ></td></tr>
colas@0
  1302
<tr><td valign=top ><tt>%a</tt> </td><td valign=top >abbreviated weekday name </td></tr>
colas@0
  1303
<tr><td valign=top ><tt>%A</tt> </td><td valign=top >full weekday name </td></tr>
colas@0
  1304
<tr><td valign=top ><tt>%b</tt> </td><td valign=top >abbreviated month name </td></tr>
colas@0
  1305
<tr><td valign=top ><tt>%B</tt> </td><td valign=top >full month name </td></tr>
colas@0
  1306
<tr><td valign=top ><tt>%C</tt> </td><td valign=top >century number </td></tr>
colas@0
  1307
<tr><td valign=top ><tt>%d</tt> </td><td valign=top >the day of the month ( 00 .. 31 ) </td></tr>
colas@0
  1308
<tr><td valign=top ><tt>%e</tt> </td><td valign=top >the day of the month ( 0 .. 31 ) </td></tr>
colas@0
  1309
<tr><td valign=top ><tt>%H</tt> </td><td valign=top >hour ( 00 .. 23 ) </td></tr>
colas@0
  1310
<tr><td valign=top ><tt>%I</tt> </td><td valign=top >hour ( 01 .. 12 ) </td></tr>
colas@0
  1311
<tr><td valign=top ><tt>%j</tt> </td><td valign=top >day of the year ( 000 .. 366 ) </td></tr>
colas@0
  1312
<tr><td valign=top ><tt>%k</tt> </td><td valign=top >hour ( 0 .. 23 ) </td></tr>
colas@0
  1313
<tr><td valign=top ><tt>%l</tt> </td><td valign=top >hour ( 1 .. 12 ) </td></tr>
colas@0
  1314
<tr><td valign=top ><tt>%m</tt> </td><td valign=top >month ( 01 .. 12 ) </td></tr>
colas@0
  1315
<tr><td valign=top ><tt>%M</tt> </td><td valign=top >minute ( 00 .. 59 ) </td></tr>
colas@0
  1316
<tr><td valign=top ><tt>%n</tt> </td><td valign=top >a newline character </td></tr>
colas@0
  1317
<tr><td valign=top ><tt>%p</tt> </td><td valign=top >``PM'' or ``AM'' </td></tr>
colas@0
  1318
<tr><td valign=top ><tt>%P</tt> </td><td valign=top >``pm'' or ``am'' </td></tr>
colas@0
  1319
<tr><td valign=top ><tt>%S</tt> </td><td valign=top >second ( 00 .. 59 ) </td></tr>
colas@0
  1320
<tr><td valign=top ><tt>%s</tt> </td><td valign=top >number of seconds since Epoch (since Jan 01 1970 00:00:00 UTC) </td></tr>
colas@0
  1321
<tr><td valign=top ><tt>%t</tt> </td><td valign=top >a tab character </td></tr>
colas@0
  1322
<tr><td valign=top ><tt>%U, %W, %V</tt> </td><td valign=top >the week number</td></tr>
colas@0
  1323
<tr><td valign=top ><tt>%u</tt> </td><td valign=top >the day of the week ( 1 .. 7, 1 = MON )</td></tr>
colas@0
  1324
<tr><td valign=top ><tt>%w</tt> </td><td valign=top >the day of the week ( 0 .. 6, 0 = SUN )</td></tr>
colas@0
  1325
<tr><td valign=top ><tt>%y</tt> </td><td valign=top >year without the century ( 00 .. 99 )</td></tr>
colas@0
  1326
<tr><td valign=top ><tt>%Y</tt> </td><td valign=top >year including the century ( ex. 1979 )</td></tr>
colas@0
  1327
<tr><td valign=top ><tt>%%</tt> </td><td valign=top >a literal <tt>%</tt> character
colas@0
  1328
</td></tr></table><p>
colas@0
  1329
There are more algorithms for computing the week number.  All
colas@0
  1330
three specifiers currently implement the same one, as defined by ISO 8601:
colas@0
  1331
``the week 01 is the week that has the Thursday in the current year, which is
colas@0
  1332
equivalent to the week that contains the fourth day of January.  Weeks start on
colas@0
  1333
Monday.''</p>
colas@0
  1334
<p>
colas@0
  1335
</p>
colas@0
  1336
<a name="node_sec_5.3.6"></a>
colas@0
  1337
<h3><a href="#node_toc_node_sec_5.3.6">5.3.6&nbsp;&nbsp;<tt>Calendar.setTtDateFormat</tt></a></h3>
colas@0
  1338
<p></p>
colas@0
  1339
<p>
colas@0
  1340
Has the same prototype as <tt>Calendar.setDateFormat</tt>, but refers to the
colas@0
  1341
format of the date displayed in the ``status bar'' when the mouse is over some
colas@0
  1342
date.</p>
colas@0
  1343
<p>
colas@0
  1344
</p>
colas@0
  1345
<a name="node_sec_5.3.7"></a>
colas@0
  1346
<h3><a href="#node_toc_node_sec_5.3.7">5.3.7&nbsp;&nbsp;<tt>Calendar.setDisabledHandler</tt></a></h3>
colas@0
  1347
<p></p>
colas@0
  1348
<p>
colas@0
  1349
This function allows you to specify a callback function that checks if a
colas@0
  1350
certain date must be disabled by the calendar.  You are responsible to write
colas@0
  1351
the callback function.  Synopsis:</p>
colas@0
  1352
<p>
colas@0
  1353
</p>
colas@0
  1354
<pre class=verbatim>function disallowDate(date) {
colas@0
  1355
  // date is a JS Date object
colas@0
  1356
  if (  date.getFullYear() == 2003 &amp;&amp;
colas@0
  1357
        date.getMonth()    == 6 /* July, it's zero-based */ &amp;&amp;
colas@0
  1358
        date.getDate()     == 5  ) {
colas@0
  1359
    return true; // disable July 5 2003
colas@0
  1360
  }
colas@0
  1361
  return false; // enable other dates
colas@0
  1362
};
colas@0
  1363
colas@0
  1364
calendar.setDisabledHandler(disallowDate);
colas@0
  1365
</pre><p></p>
colas@0
  1366
<p>
colas@0
  1367
If you change this function in ``real-time'', meaning, without creating a new
colas@0
  1368
calendar, then you have to call <tt>calendar.refresh()</tt> to make it
colas@0
  1369
redisplay the month and take into account the new disabledHandler.
colas@0
  1370
<tt>Calendar.setup</tt> does this, so you have no such trouble with it.</p>
colas@0
  1371
<p>
colas@0
  1372
Note that <tt>disallowDate</tt> should be very fast, as it is called for each
colas@0
  1373
date in the month.  Thus, it gets called, say, 30 times before displaying the
colas@0
  1374
calendar, and 30 times when the month is changed.  Tests I've done so far show
colas@0
  1375
that it's still good, but in the future I might switch it to a different design
colas@0
  1376
(for instance, to call it once per month and to return an array of dates that
colas@0
  1377
must be disabled).</p>
colas@0
  1378
<p>
colas@0
  1379
This function should be considered deprecated in the favor of
colas@0
  1380
<tt>Calendar.setDateStatusHandler</tt>, described below.</p>
colas@0
  1381
<p>
colas@0
  1382
</p>
colas@0
  1383
<a name="node_sec_5.3.8"></a>
colas@0
  1384
<h3><a href="#node_toc_node_sec_5.3.8">5.3.8&nbsp;&nbsp;<tt>Calendar.setDateStatusHandler</tt></a></h3>
colas@0
  1385
<p></p>
colas@0
  1386
<p>
colas@0
  1387
This function obsoletes <tt>Calendar.setDisabledHandler</tt>.  You call it with
colas@0
  1388
a function parameter, but this function can return a boolean
colas@0
  1389
<em>or a string</em>.  If the return value is a boolean (<tt>true</tt> or
colas@0
  1390
<tt>false</tt>) then it behaves just like <tt>setDisabledHandler</tt>,
colas@0
  1391
therefore disabling the date if the return value is <tt>true</tt>.</p>
colas@0
  1392
<p>
colas@0
  1393
If the returned value is a string then the given date will gain an additional
colas@0
  1394
CSS class, namely the returned value.  You can use this to highlight some dates
colas@0
  1395
in some way.  Note that you are responsible for defining the CSS class that you
colas@0
  1396
return.  If you return the string ``disabled'' then that date will be disabled,
colas@0
  1397
just as if you returned <tt>true</tt>.</p>
colas@0
  1398
<p>
colas@0
  1399
Here is a simple scenario that shows what you can do with this function.  The
colas@0
  1400
following should be present in some of your styles, or in the document head in
colas@0
  1401
a STYLE tag (but put it <em>after</em> the place where the calendar styles were
colas@0
  1402
loaded):</p>
colas@0
  1403
<p>
colas@0
  1404
</p>
colas@0
  1405
<pre class=verbatim>.special { background-color: #000; color: #fff; }
colas@0
  1406
</pre><p></p>
colas@0
  1407
<p>
colas@0
  1408
And you would use the following code before calling <tt>Calendar.create()</tt>:</p>
colas@0
  1409
<p>
colas@0
  1410
</p>
colas@0
  1411
<pre class=verbatim>// this table holds your special days, so that we can automatize
colas@0
  1412
// things a bit:
colas@0
  1413
var SPECIAL_DAYS = {
colas@0
  1414
    0 : [ 13, 24 ],             // special days in January
colas@0
  1415
    2 : [ 1, 6, 8, 12, 18 ],    // special days in March
colas@0
  1416
    8 : [ 21, 11 ],             // special days in September
colas@0
  1417
   11 : [ 25, 28 ]              // special days in December
colas@0
  1418
};
colas@0
  1419
colas@0
  1420
// this function returns true if the passed date is special
colas@0
  1421
function dateIsSpecial(year, month, day) {
colas@0
  1422
    var m = SPECIAL_DAYS[month];
colas@0
  1423
    if (!m) return false;
colas@0
  1424
    for (var i in m) if (m[i] == day) return true;
colas@0
  1425
    return false;
colas@0
  1426
}
colas@0
  1427
colas@0
  1428
// this is the actual date status handler.  Note that it receives the
colas@0
  1429
// date object as well as separate values of year, month and date, for
colas@0
  1430
// your confort.
colas@0
  1431
function dateStatusHandler(date, y, m, d) {
colas@0
  1432
    if (dateIsSpecial(y, m, d)) return ``special'';
colas@0
  1433
    else return false;
colas@0
  1434
    // return true above if you want to disable other dates
colas@0
  1435
}
colas@0
  1436
colas@0
  1437
// configure it to the calendar
colas@0
  1438
calendar.setDateStatusHandler(dateStatusHandler);
colas@0
  1439
</pre><p></p>
colas@0
  1440
<p>
colas@0
  1441
The above code adds the ``special'' class name to some dates that are defined
colas@0
  1442
in the SPECIAL_DAYS table.  Other dates will simply be displayed as default,
colas@0
  1443
enabled.</p>
colas@0
  1444
<p>
colas@0
  1445
</p>
colas@0
  1446
<a name="node_sec_5.3.9"></a>
colas@0
  1447
<h3><a href="#node_toc_node_sec_5.3.9">5.3.9&nbsp;&nbsp;<tt>Calendar.show</tt></a></h3>
colas@0
  1448
<p></p>
colas@0
  1449
<p>
colas@0
  1450
Call this function do show the calendar.  It basically sets the CSS ``display''
colas@0
  1451
property to ``block''.  It doesn't modify the calendar position.</p>
colas@0
  1452
<p>
colas@0
  1453
This function only makes sense when the calendar is in popup mode.</p>
colas@0
  1454
<p>
colas@0
  1455
</p>
colas@0
  1456
<a name="node_sec_5.3.10"></a>
colas@0
  1457
<h3><a href="#node_toc_node_sec_5.3.10">5.3.10&nbsp;&nbsp;<tt>Calendar.showAt</tt></a></h3>
colas@0
  1458
<p></p>
colas@0
  1459
<p>
colas@0
  1460
Call this to show the calendar at a certain (x, y) position.  Prototype:</p>
colas@0
  1461
<p>
colas@0
  1462
</p>
colas@0
  1463
<pre class=verbatim>calendar.showAt(x, y);
colas@0
  1464
</pre><p></p>
colas@0
  1465
<p>
colas@0
  1466
The parameters are absolute coordinates relative to the top left
colas@0
  1467
corner <em>of the page</em>, thus they are <em>page</em> coordinates not screen
colas@0
  1468
coordinates.</p>
colas@0
  1469
<p>
colas@0
  1470
After setting the given coordinates it calls Calendar.show.  This function only
colas@0
  1471
makes sense when the calendar is in popup mode.</p>
colas@0
  1472
<p>
colas@0
  1473
</p>
colas@0
  1474
<a name="node_sec_5.3.11"></a>
colas@0
  1475
<h3><a href="#node_toc_node_sec_5.3.11">5.3.11&nbsp;&nbsp;<tt>Calendar.showAtElement</tt></a></h3>
colas@0
  1476
<p></p>
colas@0
  1477
<p>
colas@0
  1478
This function is useful if you want to display the calendar near some element.
colas@0
  1479
You call it like this:</p>
colas@0
  1480
<p>
colas@0
  1481
</p>
colas@0
  1482
<pre class=verbatim>calendar.showAtElement(element, align);
colas@0
  1483
</pre><p></p>
colas@0
  1484
<p>
colas@0
  1485
where element is a reference to your element (for instance it can be the input
colas@0
  1486
field that displays the date) and align is an optional parameter, of type string,
colas@0
  1487
containing one or two characters.  For instance, if you pass <tt>&quot;Br&quot;</tt> as
colas@0
  1488
align, the calendar will appear <em>below</em> the element and with its right
colas@0
  1489
margin continuing the element's right margin.</p>
colas@0
  1490
<p>
colas@0
  1491
As stated above, align may contain one or two characters.  The first character
colas@0
  1492
dictates the vertical alignment, relative to the element, and the second
colas@0
  1493
character dictates the horizontal alignment.  If the second character is
colas@0
  1494
missing it will be assumed <tt>&quot;l&quot;</tt> (the left margin of the calendar will
colas@0
  1495
be at the same horizontal position as the left margin of the element).</p>
colas@0
  1496
<p>
colas@0
  1497
The characters given for the align parameters are case sensitive.  This
colas@0
  1498
function only makes sense when the calendar is in popup mode.  After computing
colas@0
  1499
the position it uses <tt>Calendar.showAt</tt> to display the calendar there.</p>
colas@0
  1500
<p>
colas@0
  1501
</p>
colas@0
  1502
<a name="node_sec_Temp_8"></a>
colas@0
  1503
<h4><a href="#node_toc_node_sec_Temp_8">Vertical alignment</a></h4>
colas@0
  1504
<p>The first character in ``<tt>align</tt>'' can take one of the following values:</p>
colas@0
  1505
<p>
colas@0
  1506
</p>
colas@0
  1507
<ul><p>
colas@0
  1508
</p>
colas@0
  1509
<li><p><tt>T</tt>  --  completely above the reference element (bottom margin of
colas@0
  1510
the calendar aligned to the top margin of the element).</p>
colas@0
  1511
<p>
colas@0
  1512
</p>
colas@0
  1513
<li><p><tt>t</tt>  --  above the element but may overlap it (bottom margin of the calendar aligned to
colas@0
  1514
the bottom margin of the element).</p>
colas@0
  1515
<p>
colas@0
  1516
</p>
colas@0
  1517
<li><p><tt>c</tt>  --  the calendar displays vertically centered to the reference
colas@0
  1518
element.  It might overlap it (that depends on the horizontal alignment).</p>
colas@0
  1519
<p>
colas@0
  1520
</p>
colas@0
  1521
<li><p><tt>b</tt>  --  below the element but may overlap it (top margin of the calendar aligned to
colas@0
  1522
the top margin of the element).</p>
colas@0
  1523
<p>
colas@0
  1524
</p>
colas@0
  1525
<li><p><tt>B</tt>  --  completely below the element (top margin of the calendar
colas@0
  1526
aligned to the bottom margin of the element).</p>
colas@0
  1527
<p>
colas@0
  1528
</p>
colas@0
  1529
</ul><p></p>
colas@0
  1530
<p>
colas@0
  1531
</p>
colas@0
  1532
<a name="node_sec_Temp_9"></a>
colas@0
  1533
<h4><a href="#node_toc_node_sec_Temp_9">Horizontal alignment</a></h4>
colas@0
  1534
<p>The second character in ``<tt>align</tt>'' can take one of the following values:</p>
colas@0
  1535
<p>
colas@0
  1536
</p>
colas@0
  1537
<ul><p>
colas@0
  1538
</p>
colas@0
  1539
<li><p><tt>L</tt>  --  completely to the left of the reference element (right
colas@0
  1540
margin of the calendar aligned to the left margin of the element).</p>
colas@0
  1541
<p>
colas@0
  1542
</p>
colas@0
  1543
<li><p><tt>l</tt>  --  to the left of the element but may overlap it (left margin
colas@0
  1544
of the calendar aligned to the left margin of the element).</p>
colas@0
  1545
<p>
colas@0
  1546
</p>
colas@0
  1547
<li><p><tt>c</tt>  --  horizontally centered to the element.  Might overlap it,
colas@0
  1548
depending on the vertical alignment.</p>
colas@0
  1549
<p>
colas@0
  1550
</p>
colas@0
  1551
<li><p><tt>r</tt>  --  to the right of the element but may overlap it (right
colas@0
  1552
margin of the calendar aligned to the right margin of the element).</p>
colas@0
  1553
<p>
colas@0
  1554
</p>
colas@0
  1555
<li><p><tt>R</tt>  --  completely to the right of the element (left margin of the
colas@0
  1556
calendar aligned to the right margin of the element).</p>
colas@0
  1557
<p>
colas@0
  1558
</p>
colas@0
  1559
</ul><p></p>
colas@0
  1560
<p>
colas@0
  1561
</p>
colas@0
  1562
<a name="node_sec_Temp_10"></a>
colas@0
  1563
<h4><a href="#node_toc_node_sec_Temp_10">Default values</a></h4>
colas@0
  1564
<p>If the ``<tt>align</tt>'' parameter is missing the calendar will choose
colas@0
  1565
``<tt>Br</tt>''.</p>
colas@0
  1566
<p>
colas@0
  1567
</p>
colas@0
  1568
<a name="node_sec_5.3.12"></a>
colas@0
  1569
<h3><a href="#node_toc_node_sec_5.3.12">5.3.12&nbsp;&nbsp;<tt>Calendar.setDate</tt></a></h3>
colas@0
  1570
<p></p>
colas@0
  1571
<p>
colas@0
  1572
Receives a JavaScript <tt>Date</tt> object.  Sets the given date in the
colas@0
  1573
calendar.  If the calendar is visible the new date is displayed immediately.</p>
colas@0
  1574
<p>
colas@0
  1575
</p>
colas@0
  1576
<pre class=verbatim>calendar.setDate(new Date()); // go today
colas@0
  1577
</pre><p></p>
colas@0
  1578
<p>
colas@0
  1579
</p>
colas@0
  1580
<a name="node_sec_5.3.13"></a>
colas@0
  1581
<h3><a href="#node_toc_node_sec_5.3.13">5.3.13&nbsp;&nbsp;<tt>Calendar.setFirstDayOfWeek</tt></a></h3>
colas@0
  1582
<p></p>
colas@0
  1583
<p>
colas@0
  1584
Changes the first day of week.  The parameter has to be a numeric value ranging
colas@0
  1585
from 0 to 6.  Pass 0 for Sunday, 1 for Monday, ..., 6 for Saturday.</p>
colas@0
  1586
<p>
colas@0
  1587
</p>
colas@0
  1588
<pre class=verbatim>calendar.setFirstDayOfWeek(5); // start weeks on Friday
colas@0
  1589
</pre><p></p>
colas@0
  1590
<p>
colas@0
  1591
</p>
colas@0
  1592
<a name="node_sec_5.3.14"></a>
colas@0
  1593
<h3><a href="#node_toc_node_sec_5.3.14">5.3.14&nbsp;&nbsp;<tt>Calendar.parseDate</tt></a></h3>
colas@0
  1594
<p></p>
colas@0
  1595
<p>
colas@0
  1596
Use this function to parse a date given as string and to move the calendar to
colas@0
  1597
that date.</p>
colas@0
  1598
<p>
colas@0
  1599
The algorithm tries to parse the date according to the format that was
colas@0
  1600
previously set with <tt>Calendar.setDateFormat</tt>; if that fails, it still
colas@0
  1601
tries to get some valid date out of it (it doesn't read your thoughts, though).</p>
colas@0
  1602
<p>
colas@0
  1603
</p>
colas@0
  1604
<pre class=verbatim>calendar.parseDate(&quot;2003/07/06&quot;);
colas@0
  1605
</pre><p></p>
colas@0
  1606
<p>
colas@0
  1607
</p>
colas@0
  1608
<a name="node_sec_5.3.15"></a>
colas@0
  1609
<h3><a href="#node_toc_node_sec_5.3.15">5.3.15&nbsp;&nbsp;<tt>Calendar.setRange</tt></a></h3>
colas@0
  1610
<p></p>
colas@0
  1611
<p>
colas@0
  1612
Sets the range of years that are allowed in the calendar.  Synopsis:</p>
colas@0
  1613
<p>
colas@0
  1614
</p>
colas@0
  1615
<pre class=verbatim>calendar.setRange(1970, 2050);
colas@0
  1616
</pre><p></p>
colas@0
  1617
<p>
colas@0
  1618
</p>
colas@0
  1619
<a name="node_sec_6"></a>
colas@0
  1620
<h1><a href="#node_toc_node_sec_6">6&nbsp;&nbsp;Side effects</a></h1>
colas@0
  1621
<p>The calendar code was intentionally embedded in an object to make it have as
colas@0
  1622
less as possible side effects.  However, there are some -- not harmful, after
colas@0
  1623
all.  Here is a list of side effects; you can count they already happened after
colas@0
  1624
<tt>calendar.js</tt> was loaded.</p>
colas@0
  1625
<p>
colas@0
  1626
</p>
colas@0
  1627
<ol><p>
colas@0
  1628
</p>
colas@0
  1629
<li><p>The global variable <tt>window.calendar</tt> will be set to null.  This
colas@0
  1630
variable is used by the calendar code, especially when doing drag &amp; drop for
colas@0
  1631
moving the calendar.  In the future I might get rid of it, but for now it
colas@0
  1632
didn't harm anyone.</p>
colas@0
  1633
<p>
colas@0
  1634
</p>
colas@0
  1635
<li><p>The JavaScript <tt>Date</tt> object is modified.  We add some properties
colas@0
  1636
and functions that are very useful to our calendar.  It made more sense to add
colas@0
  1637
them directly to the <tt>Date</tt> object than to the calendar itself.
colas@0
  1638
Complete list:</p>
colas@0
  1639
<p>
colas@0
  1640
</p>
colas@0
  1641
<ol><p>
colas@0
  1642
</p>
colas@0
  1643
<li><p><tt>Date._MD    = new Array(31,28,31,30,31,30,31,31,30,31,30,31);</tt>
colas@0
  1644
</p>
colas@0
  1645
<li><p><tt>Date.SECOND = 1000 /* milliseconds */;</tt>
colas@0
  1646
</p>
colas@0
  1647
<li><p><tt>Date.MINUTE = 60 * Date.SECOND;</tt>
colas@0
  1648
</p>
colas@0
  1649
<li><p><tt>Date.HOUR   = 60 * Date.MINUTE;</tt>
colas@0
  1650
</p>
colas@0
  1651
<li><p><tt>Date.DAY    = 24 * Date.HOUR;</tt>
colas@0
  1652
</p>
colas@0
  1653
<li><p><tt>Date.WEEK   =  7 * Date.DAY;</tt></p>
colas@0
  1654
<p>
colas@0
  1655
</p>
colas@0
  1656
<li><p><tt>Date.prototype.getMonthDays</tt>(month)  --  returns the number of days
colas@0
  1657
of the given month, or of the current date object if no month was given.</p>
colas@0
  1658
<p>
colas@0
  1659
</p>
colas@0
  1660
<li><p><tt>Date.prototype.getWeekNumber</tt>()  --  returns the week number of the
colas@0
  1661
date in the current object.</p>
colas@0
  1662
<p>
colas@0
  1663
</p>
colas@0
  1664
<li><p><tt>Date.prototype.equalsTo</tt>(other_date)  --  compare the current date
colas@0
  1665
object with <tt>other_date</tt> and returns <tt>true</tt> if the dates are
colas@0
  1666
equal.  <em>It ignores time</em>.</p>
colas@0
  1667
<p>
colas@0
  1668
</p>
colas@0
  1669
<li><p><tt>Date.prototype.print</tt>(format)  --  returns a string with the
colas@0
  1670
current date object represented in the given format.  It implements the format
colas@0
  1671
specified in section <a href="#node_sec_5.3.5">5.3.5</a>.</p>
colas@0
  1672
<p>
colas@0
  1673
</p>
colas@0
  1674
</ol><p></p>
colas@0
  1675
<p>
colas@0
  1676
</p>
colas@0
  1677
</ol><p></p>
colas@0
  1678
<p>
colas@0
  1679
</p>
colas@0
  1680
<a name="node_sec_7"></a>
colas@0
  1681
<h1><a href="#node_toc_node_sec_7">7&nbsp;&nbsp;Credits</a></h1>
colas@0
  1682
<p>The following people either sponsored, donated money to the project or bought
colas@0
  1683
commercial licenses (listed in reverse chronological order).  Your name could
colas@0
  1684
be here too!  If you wish to sponsor the project (for instance request a
colas@0
  1685
feature and pay me for implementing it) or donate some money please
colas@0
  1686
<em>please</em> contact me at <tt><a href="mailto:mihai\_bazon@yahoo.com">mihai_bazon@yahoo.com</a></tt>.</p>
colas@0
  1687
<p>
colas@0
  1688
</p>
colas@0
  1689
<ul><p>
colas@0
  1690
</p>
colas@0
  1691
<li><p>Sunny Chowdhury (<a href="http://www.ex3.com">www.ex3.com</a>)</p>
colas@0
  1692
<p>
colas@0
  1693
</p>
colas@0
  1694
<li><p>Ian Barrack (<a href="http://www.simban.com">www.simban.com</a>)</p>
colas@0
  1695
<p>
colas@0
  1696
</p>
colas@0
  1697
<li><p>Himanshukumar Shah</p>
colas@0
  1698
<p>
colas@0
  1699
</p>
colas@0
  1700
<li><p>Seyhan Ersoy (<a href="http://www.oocgi.com">www.oocgi.com</a>)</p>
colas@0
  1701
<p>
colas@0
  1702
</p>
colas@0
  1703
<li><p>Jon Stokkeland (<a href="http://www.sauen.com">www.sauen.com</a>)</p>
colas@0
  1704
<p>
colas@0
  1705
</p>
colas@0
  1706
</ul><p></p>
colas@0
  1707
<p>
colas@0
  1708
</p>
colas@0
  1709
<div align=right><table><tr><td>
colas@0
  1710
colas@0
  1711
<b>Thank you!</b><br>
colas@0
  1712
 --  <tt>mihai_bazon@yahoo.com</tt>
colas@0
  1713
</td></tr></table></div>
colas@0
  1714
<p>
colas@0
  1715
</p>
colas@0
  1716
<div class=footnoterule><hr></div><p></p>
colas@0
  1717
<div class=footnote><p><a name="footnote_Temp_2"></a><a href="#call_footnote_Temp_2"><sup><small>1</small></sup></a> 
colas@0
  1718
by the term ``widget'' I understand a single element of user interface.
colas@0
  1719
But that's in Linux world.  For those that did lots of Windows
colas@0
  1720
programming the term ``control'' might be more familiar
colas@0
  1721
</p>
colas@0
  1722
<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
colas@0
  1723
not work with IE5/Mac.  However, this browser was discontinued and we
colas@0
  1724
believe that supporting it doesn't worth the efforts, given the fact that
colas@0
  1725
it has the worst, buggiest implementation for DOM I've ever seen.</p>
colas@0
  1726
<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
colas@0
  1727
keyboard navigation; also Opera doesn't seem to allow disabling text
colas@0
  1728
selection when one drags the mouse on the page; despite all that, the
colas@0
  1729
calendar is still highly functional under Opera 7 and looks as good as
colas@0
  1730
in other supported browsers. </p>
colas@0
  1731
<p><a name="footnote_Temp_5"></a><a href="#call_footnote_Temp_5"><sup><small>4</small></sup></a> user interface</p>
colas@0
  1732
</div>
colas@0
  1733
<div align=right class=colophon>
colas@0
  1734
<i>Last modified: Saturday, March 5th, 2005<br>
colas@0
  1735
HTML conversion by <a href="http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html">TeX2page 2004-09-11</a></i>
colas@0
  1736
</div>
colas@0
  1737
</body>
colas@0
  1738
</html>