Plugins SDK

The plugins.js is a place to extend the behaviors of the calendar. The plugin file name is defined in the name & id of the calendar tag. If nothing specified, it will use the default value plugins.js. Some themes need special plugin functions to create customized behaviors like artificial internal selectors and so on. Therefore, we also treat it as part of the theme.

Build-in event handlers

1st, the fOnChange() callback function. Once defined, it will be invoked every time the calendar about to get changed or selected. Moreover, return a true value from it will cancel the current action causing the change, as if there were nothing happened. The reference to the event object is passed in as the e parameter. Since it could be null value, you should check before using.

///////////// Calendar Onchange Handler ////////////////////////////
// It's triggered whenever the calendar gets changed to y(ear),m(onth),d(ay)
// d = 0 means the calendar is about to switch to the month of (y,m);
// d > 0 means a specific date [y,m,d] is about to be selected.
// e is a reference to the triggering event object
// Return a true value will cancel the change action.
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fOnChange(y,m,d,e) {
  .... put your code here ....
return false; // return true to cancel the change.
}

Another callback function is the fAfterSelected(), which is triggered only after the date gets selected. The reference to the event object is passed in as the e parameter. Since it could be null value, you should check before using.

///////////// Calendar AfterSelected Handler ///////////////////////
// It's triggered whenever a date gets fully selected.
// The selected date is passed in as y(ear),m(onth),d(ay)
// e is a reference to the triggering event object
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fAfterSelected(y,m,d,e) {
  .... put your code here ....
}

The 3rd one is the fOnDrag(), which is triggered during mousedown and mousemove. It tries to utilize mousedown and mouseover events to create a cross-browser drag event. Note it's not a guaranteed callback and not work in all browsers. The reference to the event object is passed in as the e parameter. Since it could be null value, you should check before using.

The other things need to be mentioned is the aStat parameter. Since different browsers have different way or capability in supporting mouse dragging event, we set up a common way here to simulate it:

  1. Whenever a mousedown is detected on a calendar cell, the fOnDrag will be called with aStat set to 0. At this stage, you could prepare a dragging start, or just return true to cancel the mousedown action so that no set-date action will be performed (nor will the fAfterSelect and so on).
  2. Later, if the left mouse-button is not released and a mouseover is detected on another calendar cell, the fOnDrag will be called with aStat set to 1. At this stage, you know the user is dragging the mouse.
  3. Finally, if any mouseup is detected within or outside the calendar panel, the fOnDrag will again be called with aStat set to 2. The (y,m,d) will all be 0 if mouseup is not happened on a calendar cell. However, chances are that the user releases the mouse button outside the browser and certain browsers don't report such out-of-bound mouseup event at all. In such case there will be no callback upon fOnDrag with aStat of 2.
///////////// Calendar Cell OnDrag Handler ///////////////////////
// It triggered when you try to drag a calendar cell. (y,m,d) is the cell date.
// aStat = 0 means a mousedown is detected (dragstart)
// aStat = 1 means a mouseover between dragstart and dragend is detected (dragover)
// aStat = 2 means a mouseup is detected (dragend)
// e is a reference to the triggering event object
// Return true (when aStat=0) to skip the set-date process, as well as any related event handlers (e.g. fAfterSelect).
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fOnDrag(y,m,d,aStat,e) {
  .... put your code here ....
}

The 4th one is the fOnResize(), which is triggered after a short delay when the calendar finished drawing and before resizing itself to fit the change. You may add some code here to re-adjust the contents of the calendar.

////////////////// Calendar OnResize Handler ///////////////////////
// It's triggered after the calendar panel has finished drawing.
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
// function fOnResize() {
  .... put your code here ....
}

The 5th one is the fOnWeekClick(), which is triggered when the week number is clicked. You may use it to arrange specific actions when user clicks on the week number. Of course, you should first set the giWeekCol option to 0 so that the week numbers can be displayed.

////////////////// Calendar fOnWeekClick Handler ///////////////////////
// It's triggered when the week number is clicked.
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fOnWeekClick(year, weekNo) {
  .... put your code here ....
}

The 6th one is the fIsSelected() call-back, which is triggered for every date passed in as y(ear) m(onth) d(ay). When it returns a true value, the engine will render that specific date using the "select series" theme options, like giMarkSelected, gcFGSelected, gcBGSelected and guSelectedBGImg. If not defined here, the engine will automatically create one that checks the gdSelect only. Therefore, you can always bank on using it.

////////////////// Calendar fIsSelected Callback ///////////////////////
// It's triggered for every date passed in as y(ear) m(onth) d(ay). And if
// the return value is true, that date will be rendered using the giMarkSelected,
// gcFGSelected, gcBGSelected and guSelectedBGImg theme options.
// NOTE: If NOT defined here, the engine will create one that checks the gdSelect only.
////////////////////////////////////////////////////////////////////
function fIsSelected(y,m,d) {
  return gdSelect[2]==d&&gdSelect[1]==m&&gdSelect[0]==y;
}

The 7th one is the fParseInput(), which is used to parse the input string stored in the value property of gdCtrl. It's expected to return an array of [y,m,d] to indicate the parsed date or null if the input str can't be parsed as a date. If not defined, the engine will automatically create one that is equivalent to the fParseDate(). Therefore, you can always bank on the fParseInput() instead of using fParseDate().

////////////////// Calendar fParseInput Handler ///////////////////////
// Once defined, it'll be used to parse the input string stored in gdCtrl.value.
// It's expected to return an array of [y,m,d] to indicate the parsed date,
// or null if the input str can't be parsed as a date.
// NOTE: If NOT defined here, the engine will create one matching fFormatDate().
////////////////////////////////////////////////////////////////////
function fParseInput(str) {
  .... you may parse with your extra format here and then delegate the rest to the built-in fParseDate() ....
}

The 8th one is the fFormatInput(), which is used to format the selected date y(ear) m(onth) d(ay) into the value property of gdCtrl. It's expected to return a formated date string. If not defined, the engine will automatically create one that is equivalent to the fFormatDate(). Therefore, you can always bank on the fFormatInput() instead of using fFormatDate().

////////////////// Calendar fFormatInput Handler ///////////////////////
// Once defined, it'll be used to format the selected date - y(ear) m(onth) d(ay)
// into gdCtrl.value.
// It's expected to return a formated date string.
// NOTE: If NOT defined here, the engine will create one matching fFormatDate().
////////////////////////////////////////////////////////////////////
function fFormatInput(y,m,d) {
  .... you may call the built-in fFormatDate() first and then apply your own format to the return value ....
}

These are very useful features. Please check out the demos for good examples.

Some predefined objects can be used in plugins/themes to aid your customization

Some system functions may also be much helpful

Override theme options in plugins.js

Because theme options are loaded before the plugins, you may re-define any option of theme-name.js from within plugins.js. The benefit is that you can add additional features or make small changes without touching the standard theme. The bundled demos are using this approach to share themes.

 


Copyright© 2003-2004 Idemfactor Solutions, Inc. All rights reserved.