|
11. References
11.1. NlsCalendar Standard Properties and Functions (nlscalendar.js)
Below is list of NlsCalendar properties.
| opt.mode |
Specifies calendar mode, default calendar mode is 0 which is popup mode.
Specify value 1 for flat calendar (always visible in the page).
|
| opt.themeDir |
Specifies calendar theme directory. The directory contains images/style used by the calendar. |
| opt.firstDayOfWeek |
Specifies first day of week, 0 for Sunday, possible value is 0-6. |
| opt.dtFormat |
Specifies default input and output date format. The default value of
this property is "$dm/$dd/$YY" (for ex 04/28/2007).
|
| opt.multiSel |
Enables/disables multiple date selection. Default value is false.
Additional library nlscalendar_sel.js must be included in
the page if this property is enabled.
|
| opt.yrRange |
Sets year selection range. This property accepts array value,
for example cal.opt.yrRange=[1997-2017];
|
| opt.yrInc |
Specifies number of increment of year in year dropdown selector.
Default value is 2 means the year sequence in dropdown is increased by 2 for example
2000, 2002, 2004, 2006, 2008 and so on. To select 2001, user can select 2000 and then
use Next year button.
|
| opt.enableTime |
Enables/disables time selector. Default value is false. |
| opt.disableSel |
Disables date selection in the calendar. Default value is false. |
| opt.selOnEvent |
Enables selection on date with special event attached only.
When this property is set to true, only date with special event
is selectable. Default value is false.
|
| opt.showAdjcDates |
Shows overlapping dates of previous/upcoming month.
The adjacent dates are always disabled. By default,
adjacent dates are hidden.
|
| opt.topSelDate |
Shows/hides the selected date located at top left corner of calendar.
Default value of this property is true.
|
| opt.autoClose |
Used in popup mode only. If true, the calendar will be closed when
user select a date. If false, single click on date will only select
the date, to close the popup, user can double click the date or click
on Select button. By default this property is true.
|
| opt.autoUpdate |
Used in popup mode (as date time picker) only in combination with
autoClose=false option. If this property is true,
any changes to the calender will automatically updates the bound control
(text field). By default this property is false.
|
| opt.sClose |
Shows/hides Close button. This button is hidden in flat mode (mode=1). |
| opt.sSelect |
Shows/hides Select button. this button is hidden in flat mode (mode=1). |
| opt.sMonthNv |
Shows/hides month selector button. |
| opt.sYearNv |
Shows/hides year selector button. |
| opt.sMonthDD |
Shows/hides month dropdown selector button. |
| opt.sYearDD |
Shows/hides year dropdown selector button. |
| opt.sToday |
Shows/hides Today button. |
| opt.cellspc |
Specifies number of space between date cell. Default value is 0. |
| opt.zIndex |
Set calendar picker zIndex, default value is 1000. |
| cId |
Calendar id. |
| dtDisabled |
Specifies disabled dates in calendar. For more information about disabled date,
please check Disable Date
|
| dtSpecials |
Specifies special day in calendar. For more information about special day,
please check Special Day |
| dtEvents |
Specifies special event in calendar. For more information about special event,
please check Special Event |
Below is list of NlsCalendar methods and functions:
| render(plc) |
This method renders or displays the calendar.
Arguments:
- plc, element id where the calendar will be rendered.
If omitted, the calendar will be generated at where the method is called.
|
| reloadDate() |
Reload date view of the calendar. |
| isYearInRange(y, b) |
Return true if y is in year range defined in the calendar.
Arguments:
- y, year to verify.
- a, if true, the function will prompt a message.
|
| inActiveMonth(d) |
Return true if d is in current month/year.
Arguments:
|
| selectDate(dt) |
Set the calendar to specified date. This is runtime function, only available
after calendar is rendered.
Arguments:
|
| dateAdd(f, v) |
Add specified value to current date.
Arguments:
- f, date interval,
possible value is D (date), M (month), Y (year).
- v, value to add to the date, can be nagative value.
Returns: true if result date is still in year limit, otherwise false.
Example:
//current date is 02/15/2007
cal.dateAdd("M", 2); results in 04/15/2007
cal.dateAdd("M", -1); results in 01/15/2007
cal.dateAdd("Y", 5); results in 04/15/2012
cal.dateAdd("D", 2); results in 07/15/2007
This function only change the date value in calendar,
it doesn't update the calendar interface. Use reloadDate()
function to update the interface.
|
| getDateObj() |
Get a clone of current date represented in calendar. This function returns date object.
|
| setDate(dt) |
Set date represented by calendar.
Arguments:
- dt, date value, for example
cal.setDate(new Date(2007, 7, 16));
This function only change the date in calendar, it doesn't refresh the calendar
interface. Use reloadDate() to update interface
or use selectDate() to set date.
|
| getSelDate() |
Get selected date(s) from calendar.
Returns:
If multiple selection is enabled (opt.multiSel=true),
this function returns an associative array of selected dates. The array is keyed by date
string with format (yyyy-mm-dd, for ex 2007/05/01).
If multiple selection is disabled it returns the selected date object.
Example:
Example below shows how to iterate through the associative array to get all
seleted dates. Note that the function only return associative array if multiple
selection is enabled.
var selected = cal.getSelDate();
for (var it in selected) {
alert(selected[it]);
}
|
| gotoDate(dt) |
This function sets the calendar to specified date and make sure the calendar
is in date view.
Arguments:
- dt, date value, for example
cal.gotoDate(new Date(2007, 7, 16));
|
| disabledDates(dt) |
Check if the specified date match disabled date criteria. Disabled dates
criteria is defined in dtDisabled property of calendar. Overiding this function
allows user more control in calculating disabled date. This function is evaluated
everytime the calendar rerenders/refreshes.
Arguments:
- dt, date value, for example
cal.disabledDates(new Date(2007, 7, 16));
This function should returns true if the specified date to be disabled in calendar.
Section Disable Date describes more detail about this function.
|
| specialDates(dt) |
Check if the specified date match special day criteria. Special day criteria is
defined in dtSpecials property of calendar. Overriding this function allows user more
control in calculating special special day. This function is evaluated everytime
the calendar rerenders/refreshes.
Arguments:
- dt, date value, for example
cal.specialDates(new Date(2007, 7, 16));
This function should returns non false value if the specified date to be
marked as special day in calendar.
Section Special Day describes more detail about this function.
|
| getEvents(dt) |
Check if the specified date match special event criteria. Special event criteria and detail is
defined in dtEvents property of calendar. Overriding this function allows user more
control in defined date the special event attached on. This function is evaluated everytime
the calendar rerenders/refreshes.
Arguments:
- dt, date value, for example
cal.getEvents(new Date(2007, 7, 16));
This function should returns non false value if the specified date to be
attached a special event.
Section Special Event describes more detail about this function.
|
| getSelEvent() |
Get special event attached to current selected date.
|
Below are list of calendar events.
| onChange() |
Fires when date in calendar change (user select date/month/year) in calendar.
|
| onSelect() |
Fires when user select a date in calendar. |
| onPickDate() |
Fires when user pick a date in calendar. This event fires in popup mode only. |
| onShow() |
Fires when calendar is displayed (pop up mode). |
| onHide() |
Fires when calendar is hidden (popup mode).
|
| onMonthChange() |
Fires when month is changed in calendar.
|
| onYearChange() |
Fires when year is changed in calendar.
|
| onMYChange() |
Fires when month or year is changed in calendar.
|
Below is the example to capture the event fired from calendar:
function myOnChange() {
alert("this is my calendar");
alert("current date is: " + this.date); // 'this' refer to calendar object.
}
cal = new AOCalendar("cal1");
cal.onChange = myOnChange;
Below are useful global functions defined in nlscalendar.js
| AOCalendar.parseDate(d,f) |
Parse date string with specified format.
Arguments:
- d, date string.
- f, date format.
Below are possible format:
$yy = 2 digit year
$YY = 4 digit year
$dm = month in digit, 01=January, 12=December
$mm = abbrev month, Jan, Feb ...
$MM = full month, January, February
$dd = date, 01-31
$DW = day in week, Sunday, Monday...
$dw = day in week abbrev., Sun, Mon...
$hh = hours (12 hours format)
$HH = hours (24 hours format)
$mi = minutes
$ss = seconds
$hm = AM/PM
Example:
var dt = AOCalendar.parseDate("2007/06/25", "$YY/$dm/$dd");
|
| AOCalendar.format(d,f) |
Format date with specified format.
Arguments:
- d, date object.
- f, date format.
Example:
var dt = AOCalendar.parseDate(new Date(), "$YY/$dm/$dd");
|
| AOCalendar.formatSelDates(d, dl, fmt) |
Format selected dates in calendar with specified format.
Arguments:
- c, NlsCalendar object.
- dl, delimiter for example semicolon (;)
- fmt, date format.
Example:
var dt = AOCalendar.formatSelDates(calObj, ";", "$YY/$dm/$dd");
|
| AOCalendar.getMatch(d, o) |
Check if specified date match disabled dates, special day, or special event list.
Arguments:
- d, date object.
- o, disabled dates (dtDisabled), special day (dtSpecials) or special event (dtEvents) list.
Example:
//this check if current date is disabled.
var v = AOCalendar.getMatch(new Date(), calObj.dtDisabled);
For further information about the usage of this function, please check
Disable Date,
Special Day or
Special Event
|
11.2. NlsCalendar Multiple Selection Functions (nlscalendarext_sel.js)
Functions and events below are defined in nlscalendarext_sel.js.
| addSelection(dt) |
Add specified date to selection.
Arguments:
- dt, date value, for example
cal.addSelection(new Date(2007, 7, 16));
|
| removeSelection(dt) |
Remove specified date from selection.
Arguments:
- dt, date value, for example
cal.removeSelection(new Date(2007, 7, 16));
|
| addSelections(as) |
Add date in specified array to selection.
Arguments:
|
| clearSelections() |
Clear selections in calendar.
|
| isSelected(dt) |
Returns selected date if specified date is selected, otherwise returns null value.
Arguments:
- dt, date value, for example
cal.isSelected(new Date(2007, 7, 16));
|
| toggleSelection(dt) |
Toggles selection of specified date.
Arguments:
- dt, date value, for example
cal.isSelected(new Date(2007, 7, 16));
|
Below are events fired when add/remove selection in calendar.
| onSelectionAdd(dt) |
Fires when a date is added to selection. This event is fired only when multiple selection is enabled.
Arguments:
- dt, selected date object.
|
| onSelectionRemove(dt) |
Fires when a date is removed from selection. This event is fired only when multiple selection is enabled.
Arguments:
- dt, unselected date object.
|
11.3. NlsCalendar Date/Time Picker Functions (nlscalendar_picker.js)
Functions below are defined in nlscalendar_picker.js.
| showXY(x, y) |
Show calendar at x, y position.
Arguments:
- x, x position of calendar.
- y, y position of calendar.
|
| show(dir, elm, ctl, f, dl) |
Bind calendar to text control and display it in specified direction.
Arguments:
- dir, position of calendar relative to trigger element, possible value
are:
- NE, display calendar in up right direction
- NW, display calendar in up left direction
- SE, display calendar in down right direction
- SW, display calendar in down left direction
- elm, element which trigger the function, usually a button.
- ctl, text control, calendar will read and write value to this control (textarea/textbox).
- f, format of input/output date, this argument is optional.
- dl, delimiter, use on multiple selection
only. Delimiter is character which separates the selected dates.
If this argument is not specified, carriage return (\n) will be used.
|
| hide() |
Hide calendar.
|
| bindControl(ctl, f, dl) |
Bind calendar to specified control (textbox/textarea).
Arguments:
- ctl, text control, calendar will read and write value to this control (textarea/textbox).
- f, format of input/output date, this argument is optional.
- dl, delimiter, use on multiple selection only. Delimiter is character which separates the selected dates.
|
| posAdj() |
This is a callback function, executed when calendar picker is about to show.
This function should returns array of calendar position adjustment. The format is [x, y].
Example:
cal.posAdj = function() {return [100, -10];}
|
11.4. NlsCalendar AJAX Functions (nlscalendarext_ajax.js)
Functions below are defined in nlscalendarext_ajax.js.
| showShield() |
Shows protection layer to prevent user click on calendar
|
| hideShield() |
Hides protection layer which prevent user click on calendar
|
The following are NlsCalendar global AJAX functions.
| AOCalendar.AJAX.createXMLRequest() |
Creates an XMLHttpRequest object.
Returns: Returns an XMLHttpRequest object.
Example:
var request = AOCalendar.AJAX.createXMLRequest();
|
11.5. NlsCalendar Utility Functions (nlscalendar_util.js)
This functions are useful utility functions, they are not reference by other library.
This functions are defined in nlscalendar_util.js.
| AOCalendar.getDateOfFirst(day, dt) |
Use this function to get date of first day in week in specified month,
for example first Monday of May 2007, first Sunday of June 2005, etc.
This function returns data object.
Arguments:
- day, day of week, possible value is 0-6, 0=Sunday and so on.
- dt, date object. Only month and year part will be used, date part of the date object will be ignored.
Example:
//this get date of first Monday of May 2007
//which is May 07, 2007.
var dt = AOCalendar.getDateOfFirst(1, new Date(2007, 4, 1));
|
| AOCalendar.getDateOfLast(day, dt) |
Use this function to get date of last day in week in specified month,
for example last Monday of May 2007, last Sunday of June 2005, etc.
This function returns data object.
Arguments:
- day, day of week, possible value is 0-6, 0=Sunday and so on.
- dt, date object. Only month and year part will be used, date part of the date object will be ignored.
Example:
//this get date of last Monday of May 2007
//which is May 28, 2007.
var dt = AOCalendar.getDateOfLast(1, new Date(2007, 4, 1));
|
| AOCalendar.compareDate(a, b, incTm) |
Use this function to compare date.
Arguments:
- a, date object.
- b, date object.
- incTm, specify true to also compare time part of input date. If omitted, time part is ignored.
Returns:
This function returns:
- 0 if a=b
- -1 if a<b
- 1 if a>b
Example:
var a = new Date();
var b = new Date();
var dt = AOCalendar.compareDate(a, b);
|
11.5. Prototype Functions (nlscalendar.js)
NlsCalendar add some useful prototype functions to JavaScript Date object.
| $ao_key() |
Return date key, which is date string in format yyyy-mm-dd for ex 2005-04-21.
Example:
var dt = new Date();
var sDt = dt.$ao_key();
|
| $ao_clone() |
This function creates a clone of current date object.
Example:
var dt = new Date();
var clone = dt.$ao_clone();
|
| $ao_add |
Add specified value to current date.
Arguments:
- f, date interval,
possible value is D (date), M (month), Y (year).
- v, value to add to the date, can be nagative value.
Example:
var dt = new Date(); //for ex current date is 02/15/2007
dt.$ao_add("M", 2); results in 04/15/2007
dt.$ao_add("M", -1); results in 01/15/2007
dt.$ao_add("Y", 5); results in 04/15/2012
dt.$ao_add("D", 2); results in 07/15/2007
|
| $ao_setMonth |
Set month.
Arguments:
Example:
var dt = new Date();
dt.$ao_setMonth(5);
|
| $ao_setFullYear |
Set full year.
Arguments:
Example:
var dt = new Date();
dt.$ao_setFullYear(2009);
|
|