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.

///////////// 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 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,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 result. Take the decent theme as a good example.

////////////////// 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 ....
}

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

• gContainer is a global reference to the parent window that contains the calendar engine. It can be used to access objects outside the engine context, e.g form fields or frames in your web page.
• gfSelf is a reference of the calendar engine frame itself.
• gToday is a 3-element array containing the current date of the operating system, in the format of [year, month, day].
• gCurMonth is a 2-element array controls the month to be shown in the calendar panel, in the format of [year, month].
• gTheme is actually the whole parameter array parsed from the name&id of the calendar tag.
• ua is the navigator.userAgent string in all lower-case.

Some system functions may also be much helpful

• fRepaint() is used to refresh the calendar panel so that the latest update of agenda can be revealed.
• fAddEvent(), fGetEvent() and fRemoveEvent() are used to set, get and delete disparate agenda events.
• fGetAgenda(y,m,d,taint) will return the constrained agenda & holiday events if taint is true; or non-constrained if taint is false. Constrained means that for all dates outside the current panel view a null value or modified event will be returned according to the giShowOther option. Non-constrained means simply return the result from fHoliday() excluding the dates out of theme range.
• fSetCal(y,m,d,bTriggerOnChg,e) will set selected date to the specific date. If d is 0, the calendar will be switched to the specific month only. bTriggerOnChg determines whether the fOnchange() plugin will be called or not. It's very userful to avoid looping calls when coordinating among multiple calendars. e is optional but should be set to the reference of an event object if any event property were to be used by specific plugins. It'll return false if designated date is out of selectable range.
• fSetDate(y,m,d,taint,e) is somewhat like fSetCal(), but it will check against agenda (agenda range determined by taint flag) to activate the associated actions if applicable. taint and event are optional and usually omitted. It'll return false if designated date is out-of-range or has a null agenda action.
• fPrevMonth(e) and fNextMonth(e) are used to switch the calendar to previous or next month. e is optional but should be set to the reference of event object if any event property were to be accessed in the plugins.
• fDate2W(y,m,d) converts the specific date to [year, weekOfYear, Nth-dayOfWeek]. weekOfYear is ranged from 1 to 53; Nth-dayOfWeek is ranged from 1 to 7. fW2Date(y,w,wd) is the reverse function.

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.

 

---