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.

///////////// Calendar Onchange Handler ////////////////////////////
// It's triggered whenever the calendar gets changed.
// 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.
// 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) {
  .... 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.

///////////// 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)
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fAfterSelected(y,m,d) {
  .... 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.

///////////// 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)
// Return true to skip the set date action, if any.
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fOnDrag(y,m,d,aStat) {
  .... put your code here ....
}

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 © 2001-2003 CalendarXP.net, Liming Weng