~hexmode/+junk/main

Internet Explorer 5.0 or better for Windows<a name="call_footnote_Temp_3"></a><a href="#footnote_Temp_3">2</a>, Opera 7<a name="call_footnote_Temp_4"></a><a href="#footnote_Temp_4">3</a>, Konqueror 3.1.2 and Apple Safari for

145

MacOSX.

146

147

You can find the latest info and version at the calendar homepage:

148

149

150

151

152

<a href="http://www.dynarch.com/projects/calendar/"><tt>www.dynarch.com/projects/calendar</tt></a>

153

</td></tr></table></div>

154

155

156

157

<h2><a href="#node_toc_node_sec_1.1">1.1  How does this thing work?</a></h2>

158

DHTML is not ``another kind of HTML''. It's merely a naming convention. DHTML

159

refers to the combination of HTML, CSS, JavaScript and DOM. DOM (Document

160

Object Model) is a set of interfaces that glues the other three together. In

161

other words, DOM allows dynamic modification of an HTML page through a program.

162

JavaScript is our programming language, since that's what browsers like. CSS

163

is a way to make it look good ;-). So all this soup is generically known as

164

DHTML.

165

166

Using DOM calls, the program dynamically creates a <tt><table></tt> element

167

that contains a calendar for the given date and then inserts it in the document

168

body. Then it shows this table at a specified position. Usually the position

169

is related to some element in which the date needs to be displayed/entered,

170

such as an input field.

171

172

By assigning a certain CSS class to the table we can control the look of the

173

calendar through an external CSS file; therefore, in order to change the

174

colors, backgrounds, rollover effects and other stuff, you can only change a

175

CSS file -- modification of the program itself is not necessary.

176

177

178

179

<h2><a href="#node_toc_node_sec_1.2">1.2  Project files</a></h2>

180

Here's a description of the project files, excluding documentation and example

181

files.

182

183

184

<ul>

185

186

<li>the main program file (<tt>calendar.js</tt>). This defines all the logic

187

behind the calendar widget.

188

189

190

<li>the CSS files (<tt>calendar-*.css</tt>). Loading one of them is

191

necessary in order to see the calendar as intended.

192

193

194

<li>the language definition files (<tt>lang/calendar-*.js</tt>). They are

195

plain JavaScript files that contain all texts that are displayed by the

196

calendar. Loading one of them is necessary.

197

198

199

<li>helper functions for quick setup of the calendar

200

(<tt>calendar-setup.js</tt>). You can do fine without it, but starting with

201

version 0.9.3 this is the recommended way to setup a calendar.

202

203

204

</ul>

205

206

207

208

<h2><a href="#node_toc_node_sec_1.3">1.3  License</a></h2>

209

210

211

212

213

<a href="http://www.dynarch.com/"><tt>www.dynarch.com</tt></a>

214

Author: Mihai Bazon

215

</td></tr></table></div>

216

217

The calendar is released under the

218

<a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License</a>.

219

220

221

222

<h1><a href="#node_toc_node_sec_2">2  Quick startup</a></h1>

223

224

225

Installing the calendar used to be quite a task until version 0.9.3. Starting

226

with 0.9.3 I have included the file <tt>calendar-setup.js</tt> whose goal is to

227

assist you to setup a popup or flat calendar in minutes. You are

228

encouraged to modify this file and not calendar.js if you need

229

extra customization, but you're on your own.

230

231

First you have to include the needed scripts and style-sheet. Make sure you do

232

this in your document's <tt><head></tt> section, also make sure you put the

233

correct paths to the scripts.

234

235

236

<pre class=verbatim><style type="text/css">@import url(calendar-win2k-1.css);</style>

237

238

239

240

</pre>

241

242

243

244

<h2><a href="#node_toc_node_sec_2.1">2.1  Installing a popup calendar</a></h2>

245

246

247

Now suppose you have the following HTML:

248

249

250

251

252

253

</form>

254

</pre>

255

256

You want the button to popup a calendar widget when clicked? Just

257

insert the following code immediately after the HTML form:

258

259

260

261

Calendar.setup(

262

{

263

inputField : "data", // ID of the input field

264

ifFormat : "%m %d, %Y", // the date format

265

button : "trigger" // ID of the button

266

}

267

);

268

</script>

269

</pre>

270

271

The <tt>Calendar.setup</tt> function, defined in <tt>calendar-setup.js</tt>

272

takes care of ``patching'' the button to display a calendar when clicked. The

273

calendar is by default in single-click mode and linked with the given input

274

field, so that when the end-user selects a date it will update the input field

275

with the date in the given format and close the calendar. If you are a

276

long-term user of the calendar you probably remember that for doing this you

277

needed to write a couple functions and add an ``onclick'' handler for the

278

button by hand.

279

280

By looking at the example above we can see that the function

281

<tt>Calendar.setup</tt> receives only one parameter: a JavaScript object.

282

Further, that object can have lots of properties that tell to the setup

283

function how would we like to have the calendar. For instance, if we would

284

like a calendar that closes at double-click instead of single-click we would

285

also include the following: <tt>singleClick:false</tt>.

286

287

For a list of all supported parameters please see the section

288

<a href="#node_sec_2.3">2.3</a>.

289

290

291

292

<h2><a href="#node_toc_node_sec_2.2">2.2  Installing a flat calendar</a></h2>

293

294

295

Here's how to configure a flat calendar, using the same <tt>Calendar.setup</tt>

296

function. First, you should have an empty element with an ID. This element

297

will act as a container for the calendar. It can be any block-level element,

298

such as DIV, TABLE, etc. We will use a DIV in this example.

299

300

301

302

</pre>

303

304

Then there is the JavaScript code that sets up the calendar into the

305

``calendar-container'' DIV. The code can occur anywhere in HTML

306

after the DIV element.

307

308

309

310

function dateChanged(calendar) {

311

// Beware that this function is called even if the end-user only

312

// changed the month/year. In order to determine if a date was

313

// clicked you can use the dateClicked property of the calendar:

314

if (calendar.dateClicked) {

315

// OK, a date was clicked, redirect to /yyyy/mm/dd/index.php

316

var y = calendar.date.getFullYear();

317

var m = calendar.date.getMonth(); // integer, 0..11

318

var d = calendar.date.getDate(); // integer, 1..31

319

// redirect...

320

window.location = "/" + y + "/" + m + "/" + d + "/index.php";

321

}

322

};

323

324

Calendar.setup(

325

{

326

flat : "calendar-container", // ID of the parent element

327

flatCallback : dateChanged // our callback function

328

}

329

);

330

</script>

331

</pre>

332

333

334

335

<h2><a href="#node_toc_node_sec_2.3">2.3  <tt>Calendar.setup</tt> in detail</a></h2>

336

337

338

Following there is the complete list of properties interpreted by

339

Calendar.setup. All of them have default values, so you can pass only those

340

which you would like to customize. Anyway, you must pass at least one

341

of <tt>inputField</tt>, <tt>displayArea</tt> or <tt>button</tt>, for a popup

342

calendar, or <tt>flat</tt> for a flat calendar. Otherwise you will get a

343

warning message saying that there's nothing to setup.

344

345

346

<table border=0><tr><td valign=top >property </td><td valign=top >type </td><td valign=top >description </td><td valign=top >default

347

</td></tr>

348

<tr><td valign=top ><tt>inputField</tt>

349

</td><td valign=top >string </td><td valign=top >The ID of your input field.

350

</td><td valign=top >null

351

</td></tr>

352

<tr><td valign=top ><tt>displayArea</tt>

353

</td><td valign=top >string </td><td valign=top >This is the ID of a , <div>, or any other element that you would like to use to display the current date. This is generally useful only if the input field is hidden, as an area to display the date.

354

</td><td valign=top >null

355

</td></tr>

356

<tr><td valign=top ><tt>button</tt>

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.

358

</td><td valign=top >null

359

</td></tr>

360

<tr><td valign=top ><tt>eventName</tt>

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

362

</td><td valign=top >``click''

363

</td></tr>

364

<tr><td valign=top ><tt>ifFormat</tt>

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.

366

</td><td valign=top >``%Y/%m/%d''

367

</td></tr>

368

<tr><td valign=top ><tt>daFormat</tt>

369

</td><td valign=top >string </td><td valign=top >Format of the date displayed in the displayArea (if specified).

370

</td><td valign=top >``%Y/%m/%d''

371

</td></tr>

372

<tr><td valign=top ><tt>singleClick</tt>

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.

374

</td><td valign=top >true

375

</td></tr>

376

<tr><td valign=top ><tt>disableFunc</tt>

377

</td><td valign=top >function </td><td valign=top >A function that receives a JS Date object. It should return

378

<tt>true</tt> if that date has to be disabled, <tt>false</tt> otherwise.

379

DEPRECATED (see below).

380

</td><td valign=top >null

381

</td></tr>

382

<tr><td valign=top ><tt>dateStatusFunc</tt>

383

</td><td valign=top >function </td><td valign=top >A function that receives a JS Date object and returns a boolean

384

or a string. This function allows one to set a certain CSS class to some

385

date, therefore making it look different. If it returns <tt>true</tt> then

386

the date will be disabled. If it returns <tt>false</tt> nothing special

387

happens with the given date. If it returns a string then that will be taken

388

as a CSS class and appended to the date element. If this string is

389

``disabled'' then the date is also disabled (therefore is like returning

390

<tt>true</tt>). For more information please also refer to section

391

<a href="#node_sec_5.3.8">5.3.8</a>.

392

</td><td valign=top >null

393

</td></tr>

394

<tr><td valign=top ><tt>firstDay</tt>

395

</td><td valign=top >integer </td><td valign=top >Specifies which day is to be displayed as the first day of

396

week. Possible values are 0 to 6; 0 means Sunday, 1 means Monday, ..., 6

397

means Saturday. The end user can easily change this too, by clicking on the

398

day name in the calendar header.

399

</td><td valign=top >0

400

</td></tr>

401

<tr><td valign=top ><tt>weekNumbers</tt>

402

</td><td valign=top >boolean </td><td valign=top >If ``true'' then the calendar will display week numbers.

403

</td><td valign=top >true

404

</td></tr>

405

<tr><td valign=top ><tt>align</tt>

406

</td><td valign=top >string </td><td valign=top >Alignment of the calendar, relative to the reference element. The

407

reference element is dynamically chosen like this: if a displayArea is

408

specified then it will be the reference element. Otherwise, the input field

409

is the reference element. For the meaning of the alignment characters

410

please section <a href="#node_sec_5.3.11">5.3.11</a>.

411

</td><td valign=top >``Bl''

412

</td></tr>

413

<tr><td valign=top ><tt>range</tt>

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.

415

</td><td valign=top >[1900, 2999]

416

</td></tr>

417

418

</td><td valign=top >string </td><td valign=top >If you want a flat calendar, pass the ID of the parent object in

419

this property. If not, pass <tt>null</tt> here (or nothing at all as

420

<tt>null</tt> is the default value).

421

</td><td valign=top >null

422

</td></tr>

423

<tr><td valign=top ><tt>flatCallback</tt>

424

</td><td valign=top >function </td><td valign=top >You should provide this function if the calendar is flat. It

425

will be called when the date in the calendar is changed with a reference to

426

the calendar object. See section <a href="#node_sec_2.2">2.2</a> for an example

427

of how to setup a flat calendar.

428

</td><td valign=top >null

429

</td></tr>

430

<tr><td valign=top ><tt>onSelect</tt>

431

</td><td valign=top >function </td><td valign=top >If you provide a function handler here then you have to manage

432

the ``click-on-date'' event by yourself. Look in the calendar-setup.js and

433

take as an example the onSelect handler that you can see there.

434

</td><td valign=top >null

435

</td></tr>

436

<tr><td valign=top ><tt>onClose</tt>

437

</td><td valign=top >function </td><td valign=top >This handler will be called when the calendar needs to close.

438

You don't need to provide one, but if you do it's your responsibility to

439

hide/destroy the calendar. You're on your own. Check the calendar-setup.js

440

file for an example.

441

</td><td valign=top >null

442

</td></tr>

443

<tr><td valign=top ><tt>onUpdate</tt>

444

</td><td valign=top >function </td><td valign=top >If you supply a function handler here, it will be called right

445

after the target field is updated with a new date. You can use this to

446

chain 2 calendars, for instance to setup a default date in the second just

447

after a date was selected in the first.

448

</td><td valign=top >null

449

</td></tr>

450

451

</td><td valign=top >date </td><td valign=top >This allows you to setup an initial date where the calendar will be

452

positioned to. If absent then the calendar will open to the today date.

453

</td><td valign=top >null

454

</td></tr>

455

<tr><td valign=top ><tt>showsTime</tt>

456

</td><td valign=top >boolean </td><td valign=top >If this is set to <tt>true</tt> then the calendar will also

457

allow time selection.

458

</td><td valign=top >false

459

</td></tr>

460

<tr><td valign=top ><tt>timeFormat</tt>

461

</td><td valign=top >string </td><td valign=top >Set this to ``12'' or ``24'' to configure the way that the

462

calendar will display time.

463

</td><td valign=top >``24''

464

</td></tr>

465

<tr><td valign=top ><tt>electric</tt>

466

</td><td valign=top >boolean </td><td valign=top >Set this to ``false'' if you want the calendar to update the

467

field only when closed (by default it updates the field at each date change,

468

even if the calendar is not closed) </td><td valign=top >true

469

</td></tr>

470

<tr><td valign=top ><tt>position</tt>

471

</td><td valign=top >array </td><td valign=top >Specifies the [x, y] position, relative to page's top-left corner,

472

where the calendar will be displayed. If not passed then the position will

473

be computed based on the ``align'' parameter. Defaults to ``null'' (not

474

used). </td><td valign=top >null

475

</td></tr>

476

<tr><td valign=top ><tt>cache</tt>

477

</td><td valign=top >boolean </td><td valign=top >Set this to ``true'' if you want to cache the calendar object.

478

This means that a single calendar object will be used for all fields that

479

require a popup calendar </td><td valign=top >false

480

</td></tr>

481

<tr><td valign=top ><tt>showOthers</tt>

482

</td><td valign=top >boolean </td><td valign=top >If set to ``true'' then days belonging to months overlapping

483

with the currently displayed month will also be displayed in the calendar

484

(but in a ``faded-out'' color) </td><td valign=top >false

485

486

</td></tr></table>

487

488

489

490

491

<h1><a href="#node_toc_node_sec_3">3  Recipes</a></h1>

492

This section presents some common ways to setup a calendar using the

493

<tt>Calendar.setup</tt> function detailed in the previous section.

494

495

We don't discuss here about loading the JS or CSS code -- so make sure you

496

add the proper <script> and <style> or <link> elements in your

497

HTML code. Also, when we present input fields, please note that they should

498

be embedded in some form in order for data to be actually sent to server; we

499

don't discuss these things here because they are not related to our

500

calendar.

501

502

503

504

<h2><a href="#node_toc_node_sec_3.1">3.1  Popup calendars</a></h2>

505

These samples can be found in the file “<tt>simple-1.html</tt>” from the

506

calendar package.

507

508

509

510

<h3><a href="#node_toc_node_sec_3.1.1">3.1.1  Simple text field with calendar attached to a button</a></h3>

511

512

513

This piece of code will create a calendar for a simple input field with a

514

button that will open the calendar when clicked.

515

516

517

<pre class=verbatim><input type="text" name="date" id="f_date_b"

518

/><button type="reset" id="f_trigger_b"

519

>...</button>

520

521

Calendar.setup({

522

inputField : "f_date_b", //*

523

ifFormat : "%m/%d/%Y %I:%M %p",

524

showsTime : true,

525

button : "f_trigger_b", //*

526

step : 1

527

});

528

</script>

529

</pre>

530

531

Note that this code does more actually; the only required fields are

532

those marked with “//*” -- that is, the ID of the input field and the ID of

533

the button need to be passed to <tt>Calendar.setup</tt> in order for the

534

calendar to be properly assigned to this input field. As one can easily

535

guess from the argument names, the other arguments configure a certain date

536

format, instruct the calendar to also include a time selector and display

537

every year in the drop-down boxes (the “step” parameter) -- instead of showing

538

every other year as the default calendar does.

539

540

541

542

<h3><a href="#node_toc_node_sec_3.1.2">3.1.2  Simple field with calendar attached to an image</a></h3>

543

Same as the above, but the element that triggers the calendar is this time

544

an image, not a button.

545

546

547

548

<img src="img.gif" id="f_trigger_c"

549

style="cursor: pointer; border: 1px solid red;"

550

title="Date selector"

551

onmouseover="this.style.background='red';"

552

onmouseout="this.style.background=''" />

553

554

Calendar.setup({

555

inputField : "f_date_c",

556

ifFormat : "%B %e, %Y",

557

button : "f_trigger_c",

558

align : "Tl",

559

singleClick : false

560

});

561

</script>

562

</pre>

563

564

Note that the same 2 parameters are required as in the previous case; the

565

difference is that the 'button' parameter now gets the ID of the image

566

instead of the ID of the button. But the event is the same: at 'onclick' on

567

the element that is passed as 'button', the calendar will be shown.

568

569

The above code additionally sets an alignment mode -- the parameters are

570

described in <a href="#node_sec_5.3.11">5.3.11</a>.

571

572

573

574

<h3><a href="#node_toc_node_sec_3.1.3">3.1.3  Hidden field, plain text triggers</a></h3>

575

Sometimes, to assure that the date is well formatted, you might want not to

576

allow the end user to write a date manually. This can easily be achieved

577

with an input field by setting its <tt>readonly</tt> attribute, which is

578

defined by the HTML4 standard; however, here's an even nicer approach: our

579

calendar widget allows you to use a hidden field as the way to pass data to

580

server, and a “display area” to show the end user the selected date. The

581

“display area” can be any HTML element, such as a DIV or a SPAN or

582

whatever -- we will use a SPAN in our sample.

583

584

585

586

587

Your birthday:

588

<span style="background-color: #ff8; cursor: default;"

589

onmouseover="this.style.backgroundColor='#ff0';"

590

onmouseout="this.style.backgroundColor='#ff8';"

591

id="show_d"

592

>Click to open date selector.

593

594

595

Calendar.setup({

596

inputField : "f_date_d",

597

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

598

displayArea : "show_d",

599

daFormat : "%A, %B %d, %Y",

600

});

601

</script>

602

</pre>

603

604

The above code will configure a calendar attached to the hidden field and to

605

the SPAN having the id=“show_d”. When the SPAN element is clicked, the

606

calendar opens and allows the end user to chose a date. When the date is

607

chosen, the input field will be updated with the value in the format

608

“<tt>%Y/%d/%m</tt>”, and the SPAN element will display the date in a

609

friendlier format (defined by “<tt>daFormat</tt>”).

610

611

Beware that using this approach will make your page unfunctional in browsers

612

that do not support JavaScript or our calendar.

613

614

615

616

<h3><a href="#node_toc_node_sec_3.1.4">3.1.4  2 Linked fields, no trigger buttons</a></h3>

617

Supposing you want to create 2 fields that hold an interval of exactly one

618

week. The first is the starting date, and the second is the ending date.

619

You want the fields to be automatically updated when some date is clicked in

620

one or the other, in order to keep exactly one week difference between them.

621

622

623

624

625

626

627

function catcalc(cal) {

628

var date = cal.date;

629

var time = date.getTime()

630

// use the _other_ field

631

var field = document.getElementById("f_calcdate");

632

if (field == cal.params.inputField) {

633

field = document.getElementById("f_date_a");

634

time -= Date.WEEK; // substract one week

635

} else {

636

time += Date.WEEK; // add one week

637

}

638

var date2 = new Date(time);

639

field.value = date2.print("%Y-%m-%d %H:%M");

640

}

641

Calendar.setup({

642

inputField : "f_date_a",

643

ifFormat : "%Y-%m-%d %H:%M",

644

showsTime : true,

645

timeFormat : "24",

646

onUpdate : catcalc

647

});

648

Calendar.setup({

649

inputField : "f_calcdate",

650

ifFormat : "%Y-%m-%d %H:%M",

651

showsTime : true,

652

timeFormat : "24",

653

onUpdate : catcalc

654

});

655

</script>

656

</pre>

657

658

The above code will configure 2 input fields with calendars attached, as

659

usual. The first thing to note is that there's no trigger button -- in such

660

case, the calendar will popup when one clicks into the input field. Using

661

the <tt>onUpdate</tt> parameter, we pass a reference to a function of ours

662

that will get called after a date was selected. In that function we

663

determine what field was updated and we compute the date in the other input

664

field such that it keeps a one week difference between the two. Enjoy! :-)

665

666

667

668

<h2><a href="#node_toc_node_sec_3.2">3.2  Flat calendars</a></h2>

669

This sample can be found in “<tt>simple-2.html</tt>”. It will configure a

670

flat calendar that is always displayed in the page, in the DIV having the

671

id=“calendar-container”. When a date is clicked our function hander gets

672

called (<tt>dateChanged</tt>) and it will compute an URL to jump to based on

673

the selected date, then use <tt>window.location</tt> to visit the new link.

674

675

676

<pre class=verbatim><div style="float: right; margin-left: 1em; margin-bottom: 1em;"

677

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

678

679

680

function dateChanged(calendar) {

681

// Beware that this function is called even if the end-user only

682

// changed the month/year. In order to determine if a date was

683

// clicked you can use the dateClicked property of the calendar:

684

if (calendar.dateClicked) {

685

// OK, a date was clicked, redirect to /yyyy/mm/dd/index.php

686

var y = calendar.date.getFullYear();

687

var m = calendar.date.getMonth(); // integer, 0..11

688

var d = calendar.date.getDate(); // integer, 1..31

689

// redirect...

690

window.location = "/" + y + "/" + m + "/" + d + "/index.php";

691

}

692

};

693

694

Calendar.setup(

695

{

696

flat : "calendar-container", // ID of the parent element

697

flatCallback : dateChanged // our callback function

698

}

699

);

700

</script>

701

</pre>

702

703

704

705

<h2><a href="#node_toc_node_sec_3.3">3.3  Highlight special dates</a></h2>

706

So you want to display certain dates in a different color, or with bold

707

font, or whatever, right? Well, no problem -- our calendar can do this as

708

well. It doesn't matter if it's a flat or popup calendar -- we'll use a flat

709

one for this sample. The idea, however, is that you need to have the dates

710

in an array or a JavaScript object -- whatever is suitable for your way of

711

thinking -- and use it from a function that returns a value, telling the

712

calendar what kind of date is the passed one.

713

714

Too much talking, here's the code ;-)

715

716

717

718

719

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

720

</style>

721

722

723

<div style="float: right; margin-left: 1em; margin-bottom: 1em;"

724

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

725

726

727

var SPECIAL_DAYS = {

728

0 : [ 13, 24 ], // special days in January

729

2 : [ 1, 6, 8, 12, 18 ], // special days in March

730

8 : [ 21, 11 ] // special days in September

731

};

732

733

function dateIsSpecial(year, month, day) {

734

var m = SPECIAL_DAYS[month];

735

if (!m) return false;

736

for (var i in m) if (m[i] == day) return true;

737

return false;

738

};

739

740

function dateChanged(calendar) {

741

// Beware that this function is called even if the end-user only

742

// changed the month/year. In order to determine if a date was

743

// clicked you can use the dateClicked property of the calendar:

744

if (calendar.dateClicked) {

745

// OK, a date was clicked, redirect to /yyyy/mm/dd/index.php

746

var y = calendar.date.getFullYear();

747

var m = calendar.date.getMonth(); // integer, 0..11

748

var d = calendar.date.getDate(); // integer, 1..31

749

// redirect...

750

window.location = "/" + y + "/" + m + "/" + d + "/index.php";

751

}

752

};

753

754

function ourDateStatusFunc(date, y, m, d) {

755

if (dateIsSpecial(y, m, d))

756

return "special";

757

else

758

return false; // other dates are enabled

759

// return true if you want to disable other dates

760

};

761

762

Calendar.setup(

763

{

764

flat : "calendar-container", // ID of the parent element

765

flatCallback : dateChanged, // our callback function

766

dateStatusFunc : ourDateStatusFunc

767

}

768

);

769

</script>

770

</pre>

771

772

So the above code creates a normal flat calendar, like in the previous

773

sample. We hook into it with the function “<tt>ourDateStatusFunc</tt>”,

774

which receives a date object as the first argument, and also the year,

775

month, date as the next 3 arguments (normally, you can extract year, month,

776

date from the first parameter too, but we pass them separately for

777

convenience, as it's very likely that they are going to be used in this

778

function).

779

780

So, this function receives a date. It can return <tt>false</tt> if you want

781

no special action to be taken on that date, <tt>true</tt> if that date

782

should be disabled (unselectable), or a string if you want to assign a

783

special CSS class to that date. We return “special” for the dates that we

784

want to highlight -- and note that we defined a “special” look for them in

785

the CSS section.

786

787

I used a simple approach here to define what dates are special. There's a

788

JavaScript object (the SPECIAL_DAYS global variable) which holds an array

789

of dates for each month. Month numbers start at zero (January). Months

790

that don't contain special dates can be absent from this object. Note that

791

the way to implement this is completely separated from the calendar

792

code -- therefore, feel free to use your imagination if you have better

793

ideas. :-)

794

795

796

797

<h2><a href="#node_toc_node_sec_3.4">3.4  Select multiple dates</a></h2>

798

Starting version 1.0, the calendar is able to handle multiple dates

799

selection. You just need to pass the “<tt>multiple</tt>” parameter to

800

<tt>Calendar.setup</tt> and add some special code that interprets the

801

selection once the calendar is closed.

802

803

804

<pre class=verbatim><a id="trigger" href="#">[open calendar...]</a>

805

806

807

// the default multiple dates selected,

808

// first time the calendar is displayed

809

var MA = [];

810

811

function closed(cal) {

812

813

// here we'll write the output; this is only for example. You

814

// will normally fill an input field or something with the dates.

815

var el = document.getElementById("output");

816

817

// reset initial content.

818

el.innerHTML = "";

819

820

// Reset the "MA", in case one triggers the calendar again.

821

// CAREFUL! You don't want to do "MA = [];". We need to modify

822

// the value of the current array, instead of creating a new one.

823

// Calendar.setup is called only once! :-) So be careful.

824

MA.length = 0;

825

826

// walk the calendar's multiple dates selection hash

827

for (var i in cal.multiple) {

828

var d = cal.multiple[i];

829

// sometimes the date is not actually selected,

830

// so let's check

831

if (d) {

832

// OK, selected. Fill an input field or something.

833

el.innerHTML += d.print("%A, %Y %B %d") + " ";

834

// and push it in the "MA", in case one triggers the calendar again.

835

MA[MA.length] = d;

836

}

837

}

838

cal.hide();

839

return true;

840

};

841

842

Calendar.setup({

843

align : "BR",

844

showOthers : true,

845

multiple : MA, // pass the initial or computed array of multiple dates

846

onClose : closed,

847

button : "trigger"

848

});

849

//]]></script>

850

</pre>

851

852

The above code creates a popup calendar and passes to it an array of dates,

853

which is initially empty, in the “multiple” argument. When the calendar is

854

closed it will call our “<tt>closed</tt>” function handler; in this handler

855

we determine what dates were actually selected, inspecting the

856

“<tt>cal.multiple</tt>” property, we display them in a DIV element right

857

next to the <a> element that opens the calendar, and we reinitialize the

858

global array of selected dates (which will be used if the end user opens the

859

calendar again). I guess the code speaks for itself, right? :-)

860

861

862

863

<h1><a href="#node_toc_node_sec_4">4  The Calendar object overview</a></h1>

864

865

866

Basically you should be able to setup the calendar with the function presented

867

in the previous section. However, if for some reason <tt>Calendar.setup</tt>

868

doesn't provide all the functionality that you need and you want to tweak into

869

the process of creating and configuring the calendar ``by hand'', then this

870

section is the way to go.

871

872

The file <tt>calendar.js</tt> implements the functionality of the calendar.

873

All (well, almost all) functions and variables are embedded in the JavaScript

874

object ``Calendar''.

875

876

You can instantiate a <tt>Calendar</tt> object by calling the constructor, like

877

this: <tt>var cal = new Calendar(<tt>...</tt>)</tt>. We will discuss the parameters

878

later. After creating the object, the variable <tt>cal</tt> will contain a

879

reference to it. You can use this reference to access further options of the

880

calendar, for instance:

881

882

883

<pre class=verbatim>cal.weekNumbers = false; // do not display week numbers

884

cal.showsTime = true; // include a time selector

885

cal.setDateFormat("%Y.%m.%d %H:%M"); // set this format: 2003.12.31 23:59

886

cal.setDisabledHandler(function(date, year, month, day) {

887

// verify date and return true if it has to be disabled

888

// ``date'' is a JS Date object, but if you only need the

889

// year, month and/or day you can get them separately as

890

// next 3 parameters, as you can see in the declaration

891

if (year == 2004) {

892

// disable all dates from 2004

893

return true;

894

}

895

return false;

896

});

897

</pre>

898

899

etc. Prior to version

900

0.9.3 this was the only way to configure it. The <tt>Calendar.setup</tt>

901

function, documented in section <a href="#node_sec_2">2</a>, basically does the same

902

things (actually more) in order to setup the calendar, based on the parameters

903

that you provided.

904

905

906

907

<h2><a href="#node_toc_node_sec_4.1">4.1  Creating a calendar</a></h2>

908

The calendar is created by following some steps (even the function

909

<tt>Calendar.setup</tt>, described in section <a href="#node_sec_2">2</a>, does the

910

same). While you can skip optional (marked ``opt'') steps if you're happy with

911

the defaults, please respect the order below.

912

913

914

<ol>

915

916

<li>Instantiate a <tt>Calendar</tt> object. Details about this in

917

section <a href="#node_sec_5.1">5.1</a>.

918

919

920

<li>opt   Set the <tt>weekNumbers</tt> property to <tt>false</tt> if you don't want

921

the calendar to display week numbers.

922

923

924

<li>opt   Set the <tt>showsTime</tt> property to <tt>true</tt> if you

925

want the calendar to also provide a time selector.

926

927

928

<li>opt   Set the <tt>time24</tt> property to <tt>false</tt> if you want

929

the time selector to be in 12-hour format. Default is 24-hour format. This

930

property only has effect if you also set <tt>showsTime</tt> to

931

<tt>true</tt>.

932

933

934

<li>opt   Set the range of years available for selection (see section

935

<a href="#node_sec_5.3.15">5.3.15</a>). The default range is [1970..2050].

936

937

938

<li>opt   Set the <tt>getDateStatus</tt> property. You should pass

939

here a function that receives a JavaScript <tt>Date</tt> object and returns

940

<tt>true</tt> if the given date should be disabled, false otherwise (details in

941

section <a href="#node_sec_5.3.7">5.3.7</a>).

942

943

944

<li>opt   Set a date format. Your handler function, passed to the

945

calendar constructor, will be called when a date is selected with a reference

946

to the calendar and a date string in this format.

947

948

949

<li>Create the HTML elements related to the calendar. This step

950

practically puts the calendar in your HTML page. You simply call

951

<tt>Calendar.create()</tt>. You can give an optional parameter if you wanna

952

create a flat calendar (details in section <a href="#node_sec_5.3.1">5.3.1</a>).

953

954

955

<li>opt   Initialize the calendar to a certain date, for instance from

956

the input field.

957

958

959

<li>Show the calendar (details in section <a href="#node_sec_5.3.9">5.3.9</a>).

960

961

962

</ol>

963

964

965

966

<h2><a href="#node_toc_node_sec_4.2">4.2  Order does matter ;-)</a></h2>

967

As you could see in the previous section, there are more steps to be followed

968

in order to setup the calendar. This happens because there are two different

969

things that need to be accomplished: first there is the JavaScript object, that

970

is created with <tt>new Calendar(<tt>...</tt>)</tt>. Secondly there are the HTML

971

elements that actually lets you see and manipulate the calendar.

972

973

974

[ Those that did UI<a name="call_footnote_Temp_5"></a><a href="#footnote_Temp_5">4</a> programming, no matter in what

975

language and on what platform, may be familiar with this concept. First there

976

is the object in memory that lets you manipulate the UI element, and secondly

977

there is the UI element (known as ``control'', ``window'', ``widget'', etc.),

978

also in memory but you don't usually access it directly. ]

979

980

By instantiating the calendar we create the JavaScript object. It lets us

981

configure some properties and it also knows how to create the UI element (the

982

HTML elements actually) that will eventually be what the end-user sees on

983

screen. Creation of the HTML element is accomplished by the function

984

<tt>Calendar.create</tt>. It knows how to create popup or flat calendars.

985

This function is described in section <a href="#node_sec_5.3.1">5.3.1</a>.

986

987

Some properties need to be set prior to creating the HTML elements, because

988

otherwise they wouldn't have any effect. Such a property is

989

<tt>weekNumbers</tt> -- it has the default value ``true'', and if you don't

990

want the calendar to display the week numbers you have to set it to false. If,

991

however, you do that after calling <tt>Calendar.create</tt> the calendar

992

would still display the week numbers, because the HTML elements are already

993

created (including the <tt><td></tt>-s in the <tt><table></tt> element that

994

should contain the week numbers). For this reason the order of the steps above

995

is important.

996

997

Another example is when you want to show the calendar. The ``create'' function

998

does create the HTML elements, but they are initially hidden (have the style

999

``display: none'') unless the calendar is a flat calendar that should be always

1000

visible in the page. Obviously, the <tt>Calendar.show</tt> function should be

1001

called after calling <tt>Calendar.create</tt>.

1002

1003

1004

1005

<h2><a href="#node_toc_node_sec_4.3">4.3  Caching the object</a></h2>

1006

Suppose the end-user has popped up a calendar and selects a date. The calendar

1007

then closes. What really happens now?

1008

1009

There are two approaches. The first (used in very old versions of the

1010

calendar) was to drop completely the Calendar object and when the end-user pops

1011

up the calendar again to create another one. This approach is bad for more

1012

reasons:

1013

1014

1015

<ul>

1016

1017

<li>creating the JavaScript object and HTML elements is time-consuming

1018

1019

1020

<li>we may loose some end-user preferences (i.e. he might prefer to have

1021

Monday for the first day of week and probably already clicked it the first time

1022

when the calendar was opened, but now he has to do it again)

1023

1024

1025

</ul>

1026

1027

The second approach, implemented by the <tt>Calendar.setup</tt> function, is to

1028

cache the JavaScript object. It does this by checking the global variable

1029

<tt>window.calendar</tt> and if it is not null it assumes it is the created

1030

Calendar object. When the end-user closes the calendar, our code will only

1031

call ``<tt>hide</tt>'' on it, therefore keeping the JavaScript object and the

1032

HTML elements in place.

1033

1034

CAVEAT:     Since time selection support was introduced, this

1035

``object caching'' mechanism has the following drawback: if you once created

1036

the calendar with the time selection support, then other items that may not

1037

require this functionality will still get a calendar with the time selection

1038

support enabled. And reciprocal. ;-) Hopefully this will be corrected in a

1039

later version, but for now it doesn't seem such a big problem.

1040

1041

1042

1043

<h2><a href="#node_toc_node_sec_4.4">4.4  Callback functions</a></h2>

1044

You might rightfully wonder how is the calendar related to the input field?

1045

Who tells it that it has to update that input field when a date is

1046

selected, or that it has to jump to that URL when a date is clicked in

1047

flat mode?

1048

1049

All this magic is done through callback functions. The calendar doesn't know

1050

anything about the existence of an input field, nor does it know where to

1051

redirect the browser when a date is clicked in flat mode. It just calls your

1052

callback when a particular event is happening, and you're responsible to handle

1053

it from there. For a general purpose library I think this is the best model of

1054

making a truly reusable thing.

1055

1056

The calendar supports the following user callbacks:

1057

1058

1059

<ul>

1060

1061

<li>onSelect   -- this gets called when the end-user changes the date in the

1062

calendar. Documented in section <a href="#node_sec_5.1">5.1</a>.

1063

1064

1065

<li>onClose   -- this gets called when the calendar should close. It's

1066

user's responsibility to close the calendar. Details in section

1067

<a href="#node_sec_5.1">5.1</a>.

1068

1069

1070

<li>getDateStatus   -- this function gets called for any day in a month,

1071

just before displaying the month. It is called with a JavaScript <tt>Date</tt>

1072

object and should return <tt>true</tt> if that date should be disabled, false

1073

if it's an ordinary date and no action should be taken, or it can return a

1074

string in which case the returned value will be appended to the element's CSS

1075

class (this way it provides a powerful way to make some dates ``special'',

1076

i.e. highlight them differently). Details in section

1077

<a href="#node_sec_5.3.8">5.3.8</a>.

1078

1079

1080

</ul>

1081

1082

1083

1084

<h1><a href="#node_toc_node_sec_5">5  The Calendar object API reference</a></h1>

1085

1086

1087

1088

1089

<h2><a href="#node_toc_node_sec_5.1">5.1  <tt>Calendar</tt> constructor</a></h2>

1090

1091

1092

Synopsis:

1093

1094

1095

<pre class=verbatim>var calendar = Calendar(firstDayOfWeek, date, onSelect, onClose);

1096

</pre>

1097

1098

Parameters are as follows:

1099

1100

1101

<ul>

1102

1103

<li>firstDayOfWeek   -- specifies which day is to be displayed as the first

1104

day of week. Possible values are 0 to 6; 0 means Sunday, 1 means Monday,

1105

..., 6 means Saturday.

1106

1107

1108

<li>date   -- a JavaScript Date object or <tt>null</tt>. If <tt>null</tt>

1109

is passed then the calendar will default to today date. Otherwise it will

1110

initialize on the given date.

1111

1112

1113

<li>onSelect   -- your callback for the ``onChange'' event. See above.

1114

1115

1116

<li>onClose   -- your callback for the ``onClose'' event. See above.

1117

1118

1119

</ul>

1120

1121

1122

1123

<h3><a href="#node_toc_node_sec_Temp_6">The <tt>onSelect</tt> event</a></h3>

1124

1125

1126

Here is a typical implementation of this function:

1127

1128

1129

<pre class=verbatim>function onSelect(calendar, date) {

1130

var input_field = document.getElementById("date");

1131

input_field.value = date;

1132

};

1133

</pre>

1134

1135

<tt>date</tt> is in the format selected with <tt>calendar.setDateFormat</tt>

1136

(see section <a href="#node_sec_5.3.5">5.3.5</a>). This code simply updates the

1137

input field. If you want the calendar to be in single-click mode then you

1138

should also close the calendar after you updated the input field, so we come to

1139

the following version:

1140

1141

1142

<pre class=verbatim>function onSelect(calendar, date) {

1143

var input_field = document.getElementById("date");

1144

input_field.value = date;

1145

if (calendar.dateClicked) {

1146

calendar.callCloseHandler(); // this calls "onClose" (see above)

1147

}

1148

};

1149

</pre>

1150

1151

Note that we checked the member variable <tt>dateClicked</tt> and

1152

only hide the calendar if it's <tt>true</tt>. If this variable is <tt>false</tt> it

1153

means that no date was actually selected, but the user only changed the

1154

month/year using the navigation buttons or the menus. We don't want to hide

1155

the calendar in that case.

1156

1157

1158

1159

<h3><a href="#node_toc_node_sec_Temp_7">The <tt>onClose</tt> event</a></h3>

1160

1161

1162

This event is triggered when the calendar should close. It should hide or

1163

destroy the calendar object -- the calendar itself just triggers the event, but

1164

it won't close itself.

1165

1166

A typical implementation of this function is the following:

1167

1168

1169

<pre class=verbatim>function onClose(calendar) {

1170

calendar.hide();

1171

// or calendar.destroy();

1172

};

1173

</pre>

1174

1175

1176

1177

<h2><a href="#node_toc_node_sec_5.2">5.2  Useful member variables (properties)</a></h2>

1178

1179

1180

After creating the Calendar object you can access the following properties:

1181

1182

1183

<ul>

1184

1185

<li><tt>date</tt> -- is a JavaScript <tt>Date</tt> object. It will always

1186

reflect the date shown in the calendar (yes, even if the calendar is hidden).

1187

1188

1189

<li><tt>isPopup</tt> -- if this is true then the current Calendar object is

1190

a popup calendar. Otherwise (false) we have a flat calendar. This variable is

1191

set from <tt>Calendar.create</tt> and has no meaning before this function was

1192

called.

1193

1194

1195

<li><tt>dateClicked</tt> -- particularly useful in the <tt>onSelect</tt>

1196

handler, this variable tells us if a date was really clicked. That's because

1197

the <tt>onSelect</tt> handler is called even if the end-user only changed the

1198

month/year but did not select a date. We don't want to close the calendar in

1199

that case.

1200

1201

1202

<li><tt>weekNumbers</tt> -- if <tt>true</tt> (default) then the calendar

1203

displays week numbers. If you don't want week numbers you have to set this

1204

variable to <tt>false</tt> before calling <tt>Calendar.create</tt>.

1205

1206

1207

<li><tt>showsTime</tt> - if you set this to <tt>true</tt> (it is

1208

<tt>false</tt> by default) then the calendar will also include a time selector.

1209

1210

1211

<li><tt>time24</tt> - if you set this to <tt>false</tt> then the time

1212

selector will be in 12-hour format. It is in 24-hour format by default.

1213

1214

1215

<li><tt>firstDayOfWeek</tt> -- specifies the first day of week (0 to 6, pass

1216

0 for Sunday, 1 for Monday, ..., 6 for Saturday). This variable is set from

1217

constructor, but you still have a chance to modify it before calling

1218

<tt>Calendar.create</tt>.

1219

1220

1221

</ul>

1222

1223

There are lots of other member variables, but one should access them only

1224

through member functions so I won't document them here.

1225

1226

1227

1228

<h2><a href="#node_toc_node_sec_5.3">5.3  Public methods</a></h2>

1229

1230

1231

<h3><a href="#node_toc_node_sec_5.3.1">5.3.1  <tt>Calendar.create</tt></a></h3>

1232

1233

1234

This function creates the afferent HTML elements that are needed to display the

1235

calendar. You should call it after setting the calendar properties. Synopsis:

1236

1237

<pre class=verbatim>calendar.create(); // creates a popup calendar

1238

// -- or --

1239

calendar.create(document.getElementById(parent_id)); // makes a flat calendar

1240

</pre>

1241

1242

It can create a popup calendar or a flat calendar. If the ``parent'' argument

1243

is present (it should be a reference -- not ID -- to an HTML element) then

1244

a flat calendar is created and it is inserted in the given element.

1245

1246

At any moment, given a reference to a calendar object, we can inspect if it's a

1247

popup or a flat calendar by checking the boolean member variable

1248

<tt>isPopup</tt>:

1249

1250

1251

<pre class=verbatim>if (calendar.isPopup) {

1252

// this is a popup calendar

1253

} else {

1254

// this is a flat calendar

1255

}

1256

</pre>

1257

1258

1259

1260

<h3><a href="#node_toc_node_sec_5.3.2">5.3.2  <tt>Calendar.callHandler</tt></a></h3>

1261

1262

1263

This function calls the first user callback (the

1264

<tt>onSelect</tt> handler) with the required parameters.

1265

1266

1267

1268

<h3><a href="#node_toc_node_sec_5.3.3">5.3.3  <tt>Calendar.callCloseHandler</tt></a></h3>

1269

1270

1271

This function calls the second user callback (the

1272

<tt>onClose</tt> handler). It's useful when you want to have a

1273

``single-click'' calendar -- just call this in your <tt>onSelect</tt> handler,

1274

if a date was clicked.

1275

1276

1277

1278

<h3><a href="#node_toc_node_sec_5.3.4">5.3.4  <tt>Calendar.hide</tt></a></h3>

1279

1280

1281

Call this function to hide the calendar. The calendar object and HTML elements

1282

will not be destroyed, thus you can later call one of the <tt>show</tt>

1283

functions on the same element.

1284

1285

1286

1287

<h3><a href="#node_toc_node_sec_5.3.5">5.3.5  <tt>Calendar.setDateFormat</tt></a></h3>

1288

1289

1290

This function configures the format in which the calendar reports the date to

1291

your ``onSelect'' handler. Call it like this:

1292

1293

1294

<pre class=verbatim>calendar.setDateFormat("%y/%m/%d");

1295

</pre>

1296

1297

As you can see, it receives only one parameter, the required format. The magic

1298

characters are the following:

1299

1300

1301

1302

<tr><td valign=top ><tt>%a</tt> </td><td valign=top >abbreviated weekday name </td></tr>

1303

<tr><td valign=top ><tt>%A</tt> </td><td valign=top >full weekday name </td></tr>

1304

<tr><td valign=top ><tt>%b</tt> </td><td valign=top >abbreviated month name </td></tr>

1305

<tr><td valign=top ><tt>%B</tt> </td><td valign=top >full month name </td></tr>

1306

<tr><td valign=top ><tt>%C</tt> </td><td valign=top >century number </td></tr>

1307

<tr><td valign=top ><tt>%d</tt> </td><td valign=top >the day of the month ( 00 .. 31 ) </td></tr>

1308

<tr><td valign=top ><tt>%e</tt> </td><td valign=top >the day of the month ( 0 .. 31 ) </td></tr>

1309

1310

1311

1312

1313

1314

<tr><td valign=top ><tt>%m</tt> </td><td valign=top >month ( 01 .. 12 ) </td></tr>

1315

<tr><td valign=top ><tt>%M</tt> </td><td valign=top >minute ( 00 .. 59 ) </td></tr>

1316

<tr><td valign=top ><tt>%n</tt> </td><td valign=top >a newline character </td></tr>

1317

1318

1319

<tr><td valign=top ><tt>%S</tt> </td><td valign=top >second ( 00 .. 59 ) </td></tr>

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>

1321

<tr><td valign=top ><tt>%t</tt> </td><td valign=top >a tab character </td></tr>

1322

<tr><td valign=top ><tt>%U, %W, %V</tt> </td><td valign=top >the week number</td></tr>

1323

1324

1325

<tr><td valign=top ><tt>%y</tt> </td><td valign=top >year without the century ( 00 .. 99 )</td></tr>

1326

<tr><td valign=top ><tt>%Y</tt> </td><td valign=top >year including the century ( ex. 1979 )</td></tr>

1327

<tr><td valign=top ><tt>%%</tt> </td><td valign=top >a literal <tt>%</tt> character

1328

</td></tr></table>

1329

There are more algorithms for computing the week number. All

1330

three specifiers currently implement the same one, as defined by ISO 8601:

1331

``the week 01 is the week that has the Thursday in the current year, which is

1332

equivalent to the week that contains the fourth day of January. Weeks start on

1333

Monday.''

1334

1335

1336

1337

<h3><a href="#node_toc_node_sec_5.3.6">5.3.6  <tt>Calendar.setTtDateFormat</tt></a></h3>

1338

1339

1340

Has the same prototype as <tt>Calendar.setDateFormat</tt>, but refers to the

1341

format of the date displayed in the ``status bar'' when the mouse is over some

1342

date.

1343

1344

1345

1346

<h3><a href="#node_toc_node_sec_5.3.7">5.3.7  <tt>Calendar.setDisabledHandler</tt></a></h3>

1347

1348

1349

This function allows you to specify a callback function that checks if a

1350

certain date must be disabled by the calendar. You are responsible to write

1351

the callback function. Synopsis:

1352

1353

1354

<pre class=verbatim>function disallowDate(date) {

1355

// date is a JS Date object

1356

if ( date.getFullYear() == 2003 &&

1357

date.getMonth() == 6 /* July, it's zero-based */ &&

1358

date.getDate() == 5 ) {

1359

return true; // disable July 5 2003

1360

}

1361

return false; // enable other dates

1362

};

1363

1364

calendar.setDisabledHandler(disallowDate);

1365

</pre>

1366

1367

If you change this function in ``real-time'', meaning, without creating a new

1368

calendar, then you have to call <tt>calendar.refresh()</tt> to make it

1369

redisplay the month and take into account the new disabledHandler.

1370

<tt>Calendar.setup</tt> does this, so you have no such trouble with it.

1371

1372

Note that <tt>disallowDate</tt> should be very fast, as it is called for each

1373

date in the month. Thus, it gets called, say, 30 times before displaying the

1374

calendar, and 30 times when the month is changed. Tests I've done so far show

1375

that it's still good, but in the future I might switch it to a different design

1376

(for instance, to call it once per month and to return an array of dates that

1377

must be disabled).

1378

1379

This function should be considered deprecated in the favor of

1380

<tt>Calendar.setDateStatusHandler</tt>, described below.

1381

1382

1383

1384

<h3><a href="#node_toc_node_sec_5.3.8">5.3.8  <tt>Calendar.setDateStatusHandler</tt></a></h3>

1385

1386

1387

This function obsoletes <tt>Calendar.setDisabledHandler</tt>. You call it with

1388

a function parameter, but this function can return a boolean

1389

or a string. If the return value is a boolean (<tt>true</tt> or

1390

<tt>false</tt>) then it behaves just like <tt>setDisabledHandler</tt>,

1391

therefore disabling the date if the return value is <tt>true</tt>.

1392

1393

If the returned value is a string then the given date will gain an additional

1394

CSS class, namely the returned value. You can use this to highlight some dates

1395

in some way. Note that you are responsible for defining the CSS class that you

1396

return. If you return the string ``disabled'' then that date will be disabled,

1397

just as if you returned <tt>true</tt>.

1398

1399

Here is a simple scenario that shows what you can do with this function. The

1400

following should be present in some of your styles, or in the document head in

1401

a STYLE tag (but put it after the place where the calendar styles were

1402

loaded):

1403

1404

1405

<pre class=verbatim>.special { background-color: #000; color: #fff; }

1406

</pre>

1407

1408

And you would use the following code before calling <tt>Calendar.create()</tt>:

1409

1410

1411

<pre class=verbatim>// this table holds your special days, so that we can automatize

1412

// things a bit:

1413

var SPECIAL_DAYS = {

1414

0 : [ 13, 24 ], // special days in January

1415

2 : [ 1, 6, 8, 12, 18 ], // special days in March

1416

8 : [ 21, 11 ], // special days in September

1417

11 : [ 25, 28 ] // special days in December

1418

};

1419

1420

// this function returns true if the passed date is special

1421

function dateIsSpecial(year, month, day) {

1422

var m = SPECIAL_DAYS[month];

1423

if (!m) return false;

1424

for (var i in m) if (m[i] == day) return true;

1425

return false;

1426

}

1427

1428

// this is the actual date status handler. Note that it receives the

1429

// date object as well as separate values of year, month and date, for

1430

// your confort.

1431

function dateStatusHandler(date, y, m, d) {

1432

if (dateIsSpecial(y, m, d)) return ``special'';

1433

else return false;

1434

// return true above if you want to disable other dates

1435

}

1436

1437

// configure it to the calendar

1438

calendar.setDateStatusHandler(dateStatusHandler);

1439

</pre>

1440

1441

The above code adds the ``special'' class name to some dates that are defined

1442

in the SPECIAL_DAYS table. Other dates will simply be displayed as default,

1443

enabled.

1444

1445

1446

1447

<h3><a href="#node_toc_node_sec_5.3.9">5.3.9  <tt>Calendar.show</tt></a></h3>

1448

1449

1450

Call this function do show the calendar. It basically sets the CSS ``display''

1451

property to ``block''. It doesn't modify the calendar position.

1452

1453

This function only makes sense when the calendar is in popup mode.

1454

1455

1456

1457

<h3><a href="#node_toc_node_sec_5.3.10">5.3.10  <tt>Calendar.showAt</tt></a></h3>

1458

1459

1460

Call this to show the calendar at a certain (x, y) position. Prototype:

1461

1462

1463

<pre class=verbatim>calendar.showAt(x, y);

1464

</pre>

1465

1466

The parameters are absolute coordinates relative to the top left

1467

corner of the page, thus they are page coordinates not screen

1468

coordinates.

1469

1470

After setting the given coordinates it calls Calendar.show. This function only

1471

makes sense when the calendar is in popup mode.

1472

1473

1474

1475

<h3><a href="#node_toc_node_sec_5.3.11">5.3.11  <tt>Calendar.showAtElement</tt></a></h3>

1476

1477

1478

This function is useful if you want to display the calendar near some element.

1479

You call it like this:

1480

1481

1482

<pre class=verbatim>calendar.showAtElement(element, align);

1483

</pre>

1484

1485

where element is a reference to your element (for instance it can be the input

1486

field that displays the date) and align is an optional parameter, of type string,

1487

containing one or two characters. For instance, if you pass <tt>"Br"</tt> as

1488

align, the calendar will appear below the element and with its right

1489

margin continuing the element's right margin.

1490

1491

As stated above, align may contain one or two characters. The first character

1492

dictates the vertical alignment, relative to the element, and the second

1493

character dictates the horizontal alignment. If the second character is

1494

missing it will be assumed <tt>"l"</tt> (the left margin of the calendar will

1495

be at the same horizontal position as the left margin of the element).

1496

1497

The characters given for the align parameters are case sensitive. This

1498

function only makes sense when the calendar is in popup mode. After computing

1499

the position it uses <tt>Calendar.showAt</tt> to display the calendar there.

1500

1501

1502

1503

<h4><a href="#node_toc_node_sec_Temp_8">Vertical alignment</a></h4>

1504

The first character in ``<tt>align</tt>'' can take one of the following values:

1505

1506

1507

<ul>

1508

1509

<li><tt>T</tt> -- completely above the reference element (bottom margin of

1510

the calendar aligned to the top margin of the element).

1511

1512

1513

<li><tt>t</tt> -- above the element but may overlap it (bottom margin of the calendar aligned to

1514

the bottom margin of the element).

1515

1516

1517

<li><tt>c</tt> -- the calendar displays vertically centered to the reference

1518

element. It might overlap it (that depends on the horizontal alignment).

1519

1520

1521

<li><tt>b</tt> -- below the element but may overlap it (top margin of the calendar aligned to

1522

the top margin of the element).

1523

1524

1525

<li><tt>B</tt> -- completely below the element (top margin of the calendar

1526

aligned to the bottom margin of the element).

1527

1528

1529

</ul>

1530

1531

1532

1533

<h4><a href="#node_toc_node_sec_Temp_9">Horizontal alignment</a></h4>

1534

The second character in ``<tt>align</tt>'' can take one of the following values:

1535

1536

1537

<ul>

1538

1539

<li><tt>L</tt> -- completely to the left of the reference element (right

1540

margin of the calendar aligned to the left margin of the element).

1541

1542

1543

<li><tt>l</tt> -- to the left of the element but may overlap it (left margin

1544

of the calendar aligned to the left margin of the element).

1545

1546

1547

<li><tt>c</tt> -- horizontally centered to the element. Might overlap it,

1548

depending on the vertical alignment.

1549

1550

1551

<li><tt>r</tt> -- to the right of the element but may overlap it (right

1552

margin of the calendar aligned to the right margin of the element).

1553

1554

1555

<li><tt>R</tt> -- completely to the right of the element (left margin of the

1556

calendar aligned to the right margin of the element).

1557

1558

1559

</ul>

1560

1561

1562

1563

<h4><a href="#node_toc_node_sec_Temp_10">Default values</a></h4>

1564

If the ``<tt>align</tt>'' parameter is missing the calendar will choose

1565

``<tt>Br</tt>''.

1566

1567

1568

1569

<h3><a href="#node_toc_node_sec_5.3.12">5.3.12  <tt>Calendar.setDate</tt></a></h3>

1570

1571

1572

Receives a JavaScript <tt>Date</tt> object. Sets the given date in the

1573

calendar. If the calendar is visible the new date is displayed immediately.

1574

1575

1576

<pre class=verbatim>calendar.setDate(new Date()); // go today

1577

</pre>

1578

1579

1580

1581

<h3><a href="#node_toc_node_sec_5.3.13">5.3.13  <tt>Calendar.setFirstDayOfWeek</tt></a></h3>

1582

1583

1584

Changes the first day of week. The parameter has to be a numeric value ranging

1585

from 0 to 6. Pass 0 for Sunday, 1 for Monday, ..., 6 for Saturday.

1586

1587

1588

<pre class=verbatim>calendar.setFirstDayOfWeek(5); // start weeks on Friday

1589

</pre>

1590

1591

1592

1593

<h3><a href="#node_toc_node_sec_5.3.14">5.3.14  <tt>Calendar.parseDate</tt></a></h3>

1594

1595

1596

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

1597

that date.

1598

1599

The algorithm tries to parse the date according to the format that was

1600

previously set with <tt>Calendar.setDateFormat</tt>; if that fails, it still

1601

tries to get some valid date out of it (it doesn't read your thoughts, though).

1602

1603

1604

<pre class=verbatim>calendar.parseDate("2003/07/06");

1605

</pre>

1606

1607

1608

1609

<h3><a href="#node_toc_node_sec_5.3.15">5.3.15  <tt>Calendar.setRange</tt></a></h3>

1610

1611

1612

Sets the range of years that are allowed in the calendar. Synopsis:

1613

1614

1615

<pre class=verbatim>calendar.setRange(1970, 2050);

1616

</pre>

1617

1618

1619

1620

<h1><a href="#node_toc_node_sec_6">6  Side effects</a></h1>

1621

The calendar code was intentionally embedded in an object to make it have as

1622

less as possible side effects. However, there are some -- not harmful, after

1623

all. Here is a list of side effects; you can count they already happened after

1624

<tt>calendar.js</tt> was loaded.

1625

1626

1627

<ol>

1628

1629

<li>The global variable <tt>window.calendar</tt> will be set to null. This

1630

variable is used by the calendar code, especially when doing drag & drop for

1631

moving the calendar. In the future I might get rid of it, but for now it

1632

didn't harm anyone.

1633

1634

1635

<li>The JavaScript <tt>Date</tt> object is modified. We add some properties

1636

and functions that are very useful to our calendar. It made more sense to add

1637

them directly to the <tt>Date</tt> object than to the calendar itself.

1638

Complete list:

1639

1640

1641

<ol>

1642

1643

<li><tt>Date._MD = new Array(31,28,31,30,31,30,31,31,30,31,30,31);</tt>

1644

1645

<li><tt>Date.SECOND = 1000 /* milliseconds */;</tt>

1646

1647

<li><tt>Date.MINUTE = 60 * Date.SECOND;</tt>

1648

1649

<li><tt>Date.HOUR = 60 * Date.MINUTE;</tt>

1650

1651

1652

1653

1654

1655

1656

<li><tt>Date.prototype.getMonthDays</tt>(month) -- returns the number of days

1657

of the given month, or of the current date object if no month was given.

1658

1659

1660

<li><tt>Date.prototype.getWeekNumber</tt>() -- returns the week number of the

1661

date in the current object.

1662

1663

1664

<li><tt>Date.prototype.equalsTo</tt>(other_date) -- compare the current date

1665

object with <tt>other_date</tt> and returns <tt>true</tt> if the dates are

1666

equal. It ignores time.

1667

1668

1669

<li><tt>Date.prototype.print</tt>(format) -- returns a string with the

1670

current date object represented in the given format. It implements the format

1671

specified in section <a href="#node_sec_5.3.5">5.3.5</a>.

1672

1673

1674

</ol>

1675

1676

1677

</ol>

1678

1679

1680

1681

<h1><a href="#node_toc_node_sec_7">7  Credits</a></h1>

1682

The following people either sponsored, donated money to the project or bought

1683

commercial licenses (listed in reverse chronological order). Your name could

1684

be here too! If you wish to sponsor the project (for instance request a

1685

feature and pay me for implementing it) or donate some money please

1686

please contact me at <tt><a href="mailto:mihai\_bazon@yahoo.com">mihai_bazon@yahoo.com</a></tt>.

1687

1688

1689

<ul>

1690

1691

<li>Sunny Chowdhury (<a href="http://www.ex3.com">www.ex3.com</a>)

1692

1693

1694

<li>Ian Barrack (<a href="http://www.simban.com">www.simban.com</a>)

1695

1696

1697

<li>Himanshukumar Shah

1698

1699

1700

<li>Seyhan Ersoy (<a href="http://www.oocgi.com">www.oocgi.com</a>)

1701

1702

1703

<li>Jon Stokkeland (<a href="http://www.sauen.com">www.sauen.com</a>)

1704

1705

1706

</ul>

1707

1708

1709

1710

1711

Thank you!

1712

-- <tt>mihai_bazon@yahoo.com</tt>

1713

</td></tr></table></div>

1714

1715

1716

1717

1718

by the term ``widget'' I understand a single element of user interface.

1719

But that's in Linux world. For those that did lots of Windows

1720

programming the term ``control'' might be more familiar

1721

1722

<a name="footnote_Temp_3"></a><a href="#call_footnote_Temp_3">2</a> people report that the calendar does

1723

not work with IE5/Mac. However, this browser was discontinued and we

1724

believe that supporting it doesn't worth the efforts, given the fact that

1725

it has the worst, buggiest implementation for DOM I've ever seen.

1726

<a name="footnote_Temp_4"></a><a href="#call_footnote_Temp_4">3</a> under Opera 7 the calendar still lacks some functionality, such as

1727

keyboard navigation; also Opera doesn't seem to allow disabling text

1728

selection when one drags the mouse on the page; despite all that, the

1729

calendar is still highly functional under Opera 7 and looks as good as

1730

in other supported browsers.

1731

<a name="footnote_Temp_5"></a><a href="#call_footnote_Temp_5">4</a> user interface

1732

</div>

1733

1734

Last modified: Saturday, March 5th, 2005

1735

HTML conversion by <a href="http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html">TeX2page 2004-09-11</a>

1736

</div>

1737

</body>

1738

</html>

Older »