Calendar — Selection object

Basics

Each calendar has a selection object which is automatically created when the calendar is constructed.

Single selection mode

In single selection mode (Calendar.SEL_SINGLE, which is the default), you can use selection.set(date_as_number) and selection.get() in order to set/retrieve the selection:

var cal1 = Calendar.setup({ cont: "sample1", date: 20090501 });
cal1.selection.set(20090507);
var date = cal1.selection.get();
// now date === 20090507

The above code creates a calendar and selects May 5, 2009 (the date when I'm writing this). As you can notice, the selection actually works with integer numbers, rather than dates. This was a design decision that allowed us to improve speed and simplify code for various operations. The calendar provides two utility functions to convert between Date object and numeric representation: Calendar.dateToInt and Calendar.intToDate. Example usage:

// remember that the months start from zero in the JS Date object
var date = new Date(2009, 4, 7);
var as_number = Calendar.dateToInt(date); // 20090507
var as_date = Calendar.intToDate(as_number);
// now date and as_date are both 5 May 2009

When there is no date selection, selection.get() returns null.

Multiple selection mode

In Calendar.SEL_MULTIPLE mode, multiple dates (or date ranges) can be selected. A date range consists of two or more consecutive dates. In “multiple mode”, the set() method receives an array that contains dates or date ranges and the get() method returns such an array. Example:

(gosh, we've built an airplane!). The above is created with the following code:

var cal2 = Calendar.setup({
    cont          : "sample2",
    selectionType : Calendar.SEL_MULTIPLE,
    date          : 20090501
});
cal2.selection.set([
    20090507,               // a single date
    [ 20090512, 20090516 ], // a date range (May 12..16)
    20090521,
    [ 20090527, 20090529 ]
]);

As a shortcut, when you need to set an initial selection you can also pass it as the selection constructor argument, like this:

var cal2 = Calendar.setup({
    cont          : "sample2",
    selectionType : Calendar.SEL_MULTIPLE,
    date          : 20090501,
    selection     : [
        [ 20090527, 20090529 ],
        20090507,
        [ 20090512, 20090516 ],
        20090521
    ]
});

As you can see, the selection is now an array whose elements can be dates (in numeric repesentation) or date ranges. A date range is an array of two elements where the first one represents the start date, and the second one the end date.

When there is no date selection and in SEL_MULTIPLE mode, selection.get() returns an empty array.

Normalization

Here is an example to point out an interesting thing (note you need to use Firefox in order to run it, because we use the toSource() Object method to display the result). Click the “show selection” link in order to see what selection.get() actually returns.

show selection

Here is the JS code we used:

var cal3 = Calendar.setup({
    cont          : "sample3",
    date          : 20090501,
    selectionType : Calendar.SEL_MULTIPLE
});
cal3.selection.set([
    20090504,
    20090505,
    20090506,
    20090507,
    20090508,
    [ 20090509, 20090514 ]
]);
function cal3_showSelection() {
    alert(cal3.selection.get().toSource());
};

Note that although we explicitly select 5 days and a range, the selection object realizes that the selected days are actually consecutive, so the returned array only contains one date range which tells us that all dates between and including 4 May and 14 May 2009 are selected. You can experiment on it—select more dates, or unselect some (use CTRL+click or SHIFT+click), then click “show selection” again to see what it returns.

If you want to get all the individual dates, you can use selection.getDates(), example below:

show selection

The only modified part is what we used to display the selection:

function cal4_showSelection() {
    alert(cal4.selection.getDates().toSource());
};

selection.getDates() returns an array of JavaScript Date objects properly instantiated to each selected date in the calendar. Don't try this if you select a huge range.

Methods

The selection object has the following methods:

get()

Exemplified above, get returns a numeric date in SEL_SINGLE mode, and an array of dates or date ranges in SEL_MULTIPLE mode.

set(arg, toggle)

Changes the current selection. arg can be an array or a date (in numeric form).

• If you pass an array, the whole selection is replaced with that array and the calendar's onSelect hooks are called.
• If you pass a single number, then the calendar checks to see if that date is selected:

  a) if it's already selected and you passed true for toggle, then the date becomes unselected and the calendar's onSelect hooks are called; if toggle was false or not passed, nothing happens.

  b) if the date isn't already selected then it becomes selected and the calendar's onSelect hooks are called.

reset(arg, toggle)

Like set() but clears the selection first. Here's a sample to show the difference:

cal.selection.set(20090501);
cal.selection.set(20090502);
cal.selection.set(20090503);
// cal.selection.get() would now return a range: [ [ 20090501, 20090503 ] ]

cal.selection.reset(20090501);
cal.selection.reset(20090502);
cal.selection.reset(20090503);
// cal.selection.get() now returns 20090503

isEmpty()

Returns true if there is no date selected, false otherwise.

countDays()

Returns the number of days selected (counts the dates inside ranges too).

unselect(date)

Removes the specified date from selection. This method breaks ranges if needed. For example:

// select all dates from May 1 to May 10 2009
cal.selection.set([ [ 20090501, 20090510 ] ]);

// now unselect May 5
cal.selection.unselect(20090505);

// cal.selection.get() would now return the following:
// [ [ 20090501, 20090504 ], [ 20090506, 20090510 ] ]

normalize()

“Normalizes” the selection array, that is: it sorts it by date (or start date in case of ranges), create ranges from consecutive days, join consecutive ranges etc. After calling this method, selection.get() should return a minimal array that contains the selected dates or ranges.

You shouldn't need to call this directly.

clear(nohooks)

Empties the selection. The nohooks argument is optional (default false)—if you pass true then the selection object won't trigger the calendar's onSelect hooks.

selectRange(start_date, end_date)

Adds the [ start_date, end_date ] range to the selection and calls the onSelect hooks.

getFirstDate()

Returns the first selected date in chronological order.

getLastDate()

Returns the last selected date.

print(format, separator)

Returns an array that describes the current selection with dates formatted according to format and range dates joined with separator (default " -> "). Example:

print selection

Select some dates in the calendar above and click “print selection”. Here is the code that displays the selection:

function cal5_printSelection() {
    var sel = cal5.selection.print("%Y-%m-%d", " ... ");
    if (sel.length == 0)
        sel = "No date selected";
    else
        sel = sel.join("\n");
    alert(sel);
};

getDates()

Returns an array of JavaScript Date objects, one for each selected date. This is a flat array (i.e. ranges are “exploded” and all selected dates are returned). This is useful for the case where you're not interested to deal with ranges.