Xin Calendar 2 Mods: Date Range

The Date Range mod allows us to:

set up an absolute date range
enable/disable date ranges within the absolute date range
enable/disable weekends and working days
enable/disable dates

It also provides some helper functions to specify date offsets.

Like what we did for the Month/Year List mod, we can either change the mod order in the default config file:

xcMods=[{"order": 0,  "mod": "Month/Year List",   "script": "mod_list.js"},
        {"order": 1,  "mod": "Date Range",        "script": "mod_date.js"},
        ...

or we turn the mod order on in the JS way:

<script language="javascript" src="../config/xc2_default.js"></script>
<script language="javascript">
  xcMods[1].order=1;
</script>

Now we need to set up the date ranges and dates. To do so, the Date Range mod provides us some function calls:

setRange("conf_name", "start_date", "end_date") ... to define the absolute date range
1. conf_name ... a name for the configuration reference
2. start_date ... a date string for the beginning of date range, or an empty string for an open end
3. end_date ... a date string for the end of date range, or an empty string for an open end
```
setRange("conf", "2004-07-01", "");
```
enableDates("conf_name", "date_list") ... to enable some dates
1. conf_name ... a name for the configuration reference
2. date_list ... a list of dates separated by characters that are not used as separators in the date format
```
enableDates("conf", "2004-08-01, 2004-12-31");
```
disableDates("conf_name", "date_list") ... to disable some dates
1. conf_name ... a name for the configuration reference
2. date_list ... a list of dates separated by characters that are not used as separators in the date format
```
disableDates("conf", "2004-01-01, 2004-03-31");
```
setWeekDays("conf_name", Sun, Mon, Tue, Wed, Thu, Fri, Sat) ... to enable/disable individual weekdays
1. conf_name ... a name for the configuration reference
2. Sun ... 1: Sunday enabled, 0: Sunday disabled
3. Mon ... 1: Monday enabled, 0: Monday disabled
4. Tue ... 1: Tuesday enabled, 0: Tuesday disabled
5. Wed ... 1: Wednesday enabled, 0: Wednesday disabled
6. Thu ... 1: Thursday enabled, 0: Thursday disabled
7. Fri ... 1: Friday enabled, 0: Friday disabled
8. Sat ... 1: Saturday enabled, 0: Saturday disabled
```
setWeekDays("conf", 0, 1, 1, 1, 1, 1, 0);
```
```
Note: If xcWeekStart is set to 1, it becomes setWeekDays("conf_name", Mon, Tue, Wed, Thu, Fri, Sat, Sun)
```
enableRange("conf_name", "start_date", "end_date") ... to enable a date range
1. conf_name ... a name for the configuration reference
2. start_date ... a date string for the beginning of date range, or an empty string for an open end
3. end_date ... a date string for the end of date range, or an empty string for an open end
```
enableRange("conf", "2005-01-01", "");
```
disableRange("conf_name", "start_date", "end_date") ... to disable a date range
1. conf_name ... a name for the configuration reference
2. start_date ... a date string for the beginning of date range, or an empty string for an open end
3. end_date ... a date string for the end of date range, or an empty string for an open end
```
disableRange("conf", "", "2006-12-31");
```

The enableDates(), disableDates(), enableRange() and disableRange() can be called many times until they form the desired settings. When a calendar with date and date range settings shows up, for each date in the calendar the following checkings happen in order:

if there is an absolute date range defined and the date is out off range, disable the date and return, otherwise
if the date is enabled/disabled by a enableDates()/disableDates() call, enable/disable it and return, otherwise
if the date is enabled/disabled by a setWeekDays()/enableRange()/disableRange() call, enable/disable it and return, otherwise
enable the date and return

As we can see, a checking step won't happen if its previous step has already enabled or disabled a date.

For enableDates() and disableDates(), they have the same priority in the checking order, but for a given date, the last call executed overwrites the previous calls. For example, if we have the following settings:

disableDates("conf", "2004-07-01, 2004-07-15, 2004-07-31");
enableDates("conf", "2004-06-15, 2004-07-15, 2004-08-15");

then a calendar with reference to the configuration of "conf" will enable the date of "2004-07-15". The reason is that, as "2004-07-15" is defined twice but the enableDates() call comes after the disableDates() call and thus overwrites the previous setting.

Likewise, setWeekDays(), enableRange() and disableRange() have the same priority in the checking order, and for a given date, the last call executed overwrites the previous calls.

Many times we might want to specify the dates and date ranges by date offsets instead of static dates, for example, 10 days after today, within this week and the following week, or 5 days before the end of month. To address this issue, the Date Range mod provides some helper functions:

dayOffset("date_base", number_of_days)
... return a date string that is number_of_days away from the given date_base
daysBefore(number_of_days)
... return a date string that is number_of_days before today
daysAfter(number_of_days)
... return a date string that is number_of_days after today
getWeekBegin("date_base", number_of_weeks)
... return the first date of a week that is number_of_weeks away from the week of the given date_base
getWeekEnd("date_base", number_of_weeks)
... return the last date of a week that is number_of_weeks away from the week of the given date_base
getMonthBegin("date_base", number_of_months)
... return the first date of a month that is number_of_months away from the month of the given date_base
getMonthEnd("date_base", number_of_months)
... return the last date of a month that is number_of_months away from the month of the given date_base
getYearBegin(number_of_years)
... return the first date of a year that is number_of_years away from the current year
getYearEnd(number_of_years)
... return the last date of a year that is number_of_years away from the current year

So, for the examples just mentioned, the "10 days after today" would be:

daysAfter(10)

"within this week and the following week" would be a date range of:

getWeekBegin("",0), getWeekEnd("",1)

and "5 days before the end of month" would be:

dayOffset(getMonthEnd("",0), -5)

The date and date range calls with the same configuration reference name will be grouped together and applied to calendars that refer to it. If we still remember the syntax of the showCalendar() call, we would know that the first parameter is the configuration reference name, as shown below:

showCalendar("conf_name", target_field, reference_field, "default_date", "holder_id", dx, dy, mode);

In this example, we have a date range of [the second Monday of the previous month, the week before the last week of the next month] for the first date field:

<script language="javascript" src="../script/xc2_inpage.js"></script>
<script language="javascript">
setRange("1", dayOffset(getWeekBegin(getMonthBegin("",-1),1),1), getWeekEnd(getMonthEnd("",1),-1));
setWeekDays("2", ...);
</script>

...

<input ... onfocus="showCalendar('1',this,this,'','holder1',0,30,1)">

In order to get the second Monday of the previous month, we first get the first day (and also the fisrt week of course) of previous month with [ getMonthBegin("",-1) ], then we get the second week of the previous month with [ getWeekBegin(prev_month,1) ], and finally we get the second day (assuming that Monday is the second day of a week) from the second week of previous month with [ dayOffset(second_week_of_prev_month,1) ].

For the second date field, we simply disable the weekends:

<script language="javascript" src="../script/xc2_inpage.js"></script>
<script language="javascript">
setRange("1", ...);
setWeekDays("2", 0, 1, 1, 1, 1, 1, 0);
</script>

...

<input ... onfocus="showCalendar('2',this,this,'','holder2',0,30,1)">

[Special Days] [Back to index page]

# # #