11. References

11.1. NlsCalendar Standard Properties and Functions (nlscalendar.js)

Below is list of NlsCalendar properties.

PropertiesDescription
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:

MethodsDescription
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:

  • d, date to verify.
selectDate(dt) Set the calendar to specified date. This is runtime function, only available after calendar is rendered.

Arguments:

  • dt, date value.
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.

EventsDescription
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

MethodsDescription
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.

MethodsDescription
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:

  • as, array of dates.
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.

EventsDescription
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.

MethodsDescription
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.

MethodsDescription
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.

MethodsDescription
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.

MethodsDescription
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.

MethodsDescription
$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:

  • m, month value 0-11.

Example:


    var dt = new Date();
    dt.$ao_setMonth(5);
  

$ao_setFullYear

Set full year.

Arguments:

  • y, year value.

Example:


    var dt = new Date();
    dt.$ao_setFullYear(2009);