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.
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:
aStat
set to 0. At this stage, you could prepare a dragging start.aStat
set to 1. At this stage, you know the user is dragging the mouse.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
// 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 ....
}
The 9th one is the fOnDoWClick()
call-back, which is triggered when the week title (day of week) is clicked. It may be useful if you want to select dates by day-of-week (per column).
////////////////// Calendar fOnDoWClick Handler ///////////////////////
// It's triggered when the week head (day of week) is clicked.
// dow ranged from 0-6 while 0 denotes Sunday, 6 denotes Saturday.
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fOnDoWClick(year, month, dow) {
.... put your code here ....
}
The 10th one is the fOnload()
call-back, which is triggered when the calendar engine (iframe) is fully loaded. It may be useful if you want to perform certain action only after the calendar is fully rendered.
////////////////// Calendar fOnload Handler ///////////////////////
// It's triggered when the calendar engine is fully loaded by the browser.
// NOTE: DO NOT define this handler unless you really need to use it.
////////////////////////////////////////////////////////////////////
function fOnload() {
.... put your code here ....
}
These are very useful features. Please check out the demos for good examples.
true
, which means the calendar engine will employ certain approach to prevent the browser from caching the agenda file. dateCtrl
object. It's passed in via the fPopCalendar() function.giShowOther
option. Non-constrained means
simply return the result from fHoliday()
excluding the dates
out of theme range. 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.null
agenda
action.null
if it can't be parsed according to the date format options in the employed theme. You should always use fParseInput(str)
, which will call the fParseDate() by default, in your code whenever you want to parse the input string complying with the theme settings, unless you are programming the fParseInput(str)
plugin itself.fFormatInput(y,m,d)
, which will call the fFormatDate() by default, in your code whenever you want to format a date string complying with the theme settings, unless you are programming the fFormatInput() plugin itself.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.