A jQueryplugin
that provides a datepicker with support for various world calendars.
This plugin builds on the original jQuery Datepicker plugin,
which only provided support for the Gregorian calendar.
For date entry via a spinner use the jQuery Date Entry plugin.
Complement this plugin with the jQuery Time Entry plugin, or
combine date and time entry with the jQuery Date/Time Entry plugin.
The current version is 2.1.0 and is available
under the MIT licence.
For more detail see the documentation reference page.
Or see a minimal page that you could
use as a basis for your own investigations.
There are many different calendars used throughout the world.
This plugin aims to make them accessible in JavaScript in a consistent manner.
The basic modules provide the underlying
calendar support, while the picker module builds
a generic datepicker on top of this functionality.
Use calendar:
$('#selectCalendar').change(function() {
calendar = $.calendars.instance($(this).val());
var convert = function(value) {
return (!value || typeof value != 'object' ? value :
calendar.fromJD(value.toJD()));
};
$('.is-calendarsPicker').each(function() {
var current = $(this).calendarsPicker('option');
$(this).calendarsPicker('option', {calendar: calendar,
onSelect: null, onChangeMonthYear: null,
defaultDate: convert(current.defaultDate),
minDate: convert(current.minDate),
maxDate: convert(current.maxDate)}).
calendarsPicker('option',
{onSelect: current.onSelect,
onChangeMonthYear: current.onChangeMonthYear});
});
});
A datepicker based on a calendar can easily be added as a popup to a text field
or inline in a division or span with appropriate default settings.
The popup shows when the field gains focus and is closed by clicking
on the Close link or clicking anywhere else on the page.
You can also remove the datepicker widget if it is no longer required.
Processed fields are marked with a class of is-calendarsPicker
and are not re-processed if targeted a second time.
Invocation
By default a popup datepicker appears when its input field gains focus.
You can configure an external trigger in addition to or instead of the default.
Clicking on the trigger toggles the popup open and closed.
You can also control the animation used to display the datepicker and
its duration. There are three standard animations (show,
fadeIn, slideDown) as well as the ones from the
jQuery UI effects package.
Additional options for the latter may be specified with the
showOptions setting. Use '' for no animation.
You can specify the format in which the date is to appear.
Use a combination of the field formats below, with the default depending
on the calendar used (being 'mm/dd/yyyy' for the Gregorian English calendar).
You must quote (using ') any text that matches these formats
to avoid it being replaced.
You can retrieve or supply the date(s) for the datepicker by using
the 'getDate' or 'setDate' commands. The dates are returned
as an array (possibly empty) of CDate objects.
When setting the dates you can provide one value, two values (for a range),
or mutliple values in an array. Each value may be a CDate,
the date as a string in the current date format, a number of days relative to today,
or a string to specify one or more units and periods relative to today.
For the last, use 'd' for days, 'w' for weeks, 'm' for months, or 'y' for years.
$('#getDates').click(function() {
var dates = $('#' + $('#getSetSelect').val()).calendarsPicker('getDate');
var value = '';
for (var i = 0; i < dates.length; i++) {
value += (i == 0 ? '' : ',') + dates[i].formatDate();
}
$('#getSetValue').val(value || 'none');
});
$('#setDates').click(function() {
var dates = $('#getSetValue').val().split(',');
$('#' + $('#getSetSelect').val()).calendarsPicker('setDate', dates);
});
Default Date
You can set the default date to display when no other is set in the datepicker.
In addition, you can set this date to be automatically selected.
Without any modification, the default date is today.
The default date can be set as an absolute date as either a CDate
or a string (in the current date format). Or it may be set as a relative value
by using a simple number to offset from today's date a given number of days,
or a string to specify one or more units and periods.
Use 'd' for days, 'w' for weeks, 'm' for months, or 'y' for years.
You can set minimum and/or maximum dates within which a date may be chosen.
These dates can be set as an absolute date as either a CDate
or a string (in the current date format). Or they may be set as relative values
by using a simple number to offset from today's date a given number of days,
or a string to specify one or more units and periods.
Use 'd' for days, 'w' for weeks, 'm' for months, or 'y' for years.
You have some control over the behaviour and style of individual days
shown in the datepicker by preventing days being selected,
by changing their style, by changing their description,
or by replacing the cell content.
The onDate function is called for each day shown
and returns an object with (optionally) a selectable flag (selectable),
any CSS styles (dateClass),
a description (title), and /or new content (content).
If you need multiple onShow functions, use the
$.calendarsPicker.multipleEvents function and
pass the relevant handlers to it.
The datepicker can be configured to allow the selection of a date range within
the one picker. The first click selects the start of the range and the second
selects the end.
The datepicker can be configured to allow the selection of multiple individual dates.
Clicking on an already selected date de-selects it. The datepicker automatically
closes when the maximum number of allowed dates has been chosen.
Modify the controls and month/year navigation, as shown below.
Control inclusion and/or placement are defined in the renderer for the datepicker.
Thereafter, several settings affect their appearance.
You can override parts of the default renderer by creating a new empty renderer
and extending it with the default values and then the overridden ones.
Controls appearing on the datepicker are defined as commands -
encapsulating the displayed text, a triggering keystroke, whether or not
it is enabled, a representative date, and the actual action itself.
They are positioned in the renderer as substitution points of the form
'{link:name}' or '{button:name}',
depending on whether they are to show as links or buttons.
You can override parts of the default commands by creating a new
empty command object and extending it with the default values
($.calendarsPicker.commands) and then the overridden settings.
Determine whether or not the month and year may be directly selected.
Specify which years appear in the drop-down - by default it shows
10 years before and after the currently selected date.
Note that the yearRange setting only applies to the
year drop-down. It does not restrict date selection directly.
You must still provide minDate and/or
maxDate settings if restrictions apply.
The picker.ext module provides additional
functionality to extend the datepicker. These include onShow
callbacks that enhance the datepicker. If you need multiple onShow
functions, use the $.calendarsPicker.multipleEvents function and
pass the relevant handlers to it.
Instead of configuring fields via parameters to the datepicker
instantiation, you can specify them inline. You must add the
jQuery Metadata
plugin to your page and then encode the settings in the class
attribute (by default).
Note that the localisations listed here only apply to the Gregorian and Julian
calendars, although some localisations are also available for the other calendars.
You can localise the datepicker for other languages and regional differences (over 70
now available). The datepicker defaults to English with a date format of mm/dd/yyyy.
Select a language for the datepicker.
You need to load the appropriate language packages for both the
underlying calendar
and for the datepicker. The latter adds a
language set ($.calendarsPicker.regionalOptions[langCode]) and
automatically sets this language as the default for all datepicker fields.
And then configure the language per datepicker field, remembering to
localise the underlying calendar as well. You can also localise the appearance
of the numbers in the calendar, when the selected localisation supports it,
by setting the localNumbers option to true.
The datepicker uses a templating mechanism to render its layout.
So it is easy to change the structure of the datepicker to suit your needs:
from minor changes such as
adding or removing
controls, to major adjustments that drastically alter its appearance.
Combine the layout with appropriate CSS to create your datepicker.
The picker.ext module also
defines a renderer that produces the standard structure, but using the
ThemeRoller
classes to help blend your datepicker with other
jQuery UI components.
Don't forget to load the appropriate ThemeRoller CSS,
along with the corresponding local overrides:
Datepicker can be integrated with Jörn Zaefferer's
validation plugin by
adding the jquery.calendars.validation.js extension to your page.
One new validation is defined (cpDate) for basic date checking.
It automatically handles date ranges and multiple dates, checks against any
minDate and/or maxDate settings, and calls any
onDate callback to verify selectability. It may be added as a class
to your datepicker fields, or may be defined in the validate settings.
Another new validation (cpCompareDate) lets you compare one date field
against another date - either the value of another datepicker field,
a specific date, or today.
There is also a custom errorPlacement function defined so that
the error messages appear after any trigger button or image
(or before them if using a right-to-left localisation).
You can override the validation error messages through the messages
setting of the validation plugin, or globally via the datepicker
setDefaults function with any or all of the following settings:
validateDate, validateDateMin, validateDateMax,
validateDateMinMax, validateDateCompare,
validateDateToday, validateDateOther,
validateDateEQ, validateDateNE, validateDateLT,
validateDateGT, validateDateLE, validateDateGE.
AIR Application
The calendars and datepicker are available as a standalone
AIR application.
It displays a number of months and lets you configure which calendar to use,
its localisation, its styling, and a few other items. You can also convert
between dates in the various calendars.
In the Wild
This tab highlights examples of this plugin in use "in the wild".
None as yet.
To add another example, please contact me (wood.keith{at}optusnet.com.au)
and provide the plugin name, the URL of your site, its title,
and a short description of its purpose and where/how the plugin is used.
Quick Reference
A full list of all possible settings is shown below.
Note that not all would apply in all cases. For more detail see the
documentation reference page.
$(selector).calendarsPicker({
calendar: $.calendars.instance(), // The calendar to use
pickerClass: '', // CSS class to add to this instance of the datepicker
showOnFocus: true, // True for popup on focus, false for not
showTrigger: null, // Element to be cloned for a trigger, null for none
showAnim: 'show', // Name of jQuery animation for popup, '' for no animation
showOptions: {}, // Options for enhanced animations
showSpeed: 'normal', // Duration of display/closure
popupContainer: null, // The element to which a popup calendar is added, null for body
alignment: 'bottom', // Alignment of popup - with nominated corner of input:
// 'top' or 'bottom' aligns depending on language direction,
// 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'
fixedWeeks: false, // True to always show 6 weeks, false to only show as many as are needed
firstDay: null, // First day of the week, 0 = Sunday, 1 = Monday, ...
// defaults to calendar local setting if null
calculateWeek: null, // Calculate week of the year from a date, null for calendar default
localNumbers: false, // True to localise numbers (if available),
// false to use normal Arabic numerals
monthsToShow: 1, // How many months to show, cols or [rows, cols]
monthsOffset: 0, // How many months to offset the primary month by
monthsToStep: 1, // How many months to move when prev/next clicked
monthsToJump: 12, // How many months to move when large prev/next clicked
changeMonth: true, // True to change month/year via drop-down, false for navigation only
yearRange: 'c-10:c+10', // Range of years to show in drop-down: 'any' for direct text entry
// or 'start:end', where start/end are '+-nn' for relative to today
// or 'c+-nn' for relative to the currently selected date
// or 'nnnn' for an absolute year
showOtherMonths: false, // True to show dates from other months, false to not show them
selectOtherMonths: false, // True to allow selection of dates from other months too
defaultDate: null, // Date to show if no other selected
selectDefaultDate: false, // True to pre-select the default date if no other is chosen
minDate: null, // The minimum selectable date
maxDate: null, // The maximum selectable date
dateFormat: null, // Format for dates, defaults to calendar setting if null
autoSize: false, // True to size the input field according to the date format
rangeSelect: false, // Allows for selecting a date range on one date picker
rangeSeparator: ' - ', // Text between two dates in a range
multiSelect: 0, // Maximum number of selectable dates, zero for single select
multiSeparator: ',', // Text between multiple dates
onDate: null, // Callback as a date is added to the datepicker
onShow: null, // Callback just before a datepicker is shown
onChangeMonthYear: null, // Callback when a new month/year is selected
onSelect: null, // Callback when a date is selected
onClose: null, // Callback when a datepicker is closed
altField: null, // Alternate field to update in synch with the datepicker
altFormat: null, // Date format for alternate field, defaults to dateFormat
constrainInput: true, // True to constrain typed input to dateFormat allowed characters
commandsAsDateFormat: false, // True to apply formatDate to the command texts
commands: this.commands, // Command actions that may be added to a layout by name
// Localisation settings
renderer: this.defaultRenderer, // The rendering templates
prevText: '<Prev', // Text for the previous month command
prevStatus: 'Show the previous month', // Status text for the previous month command
prevJumpText: '<<', // Text for the previous year command
prevJumpStatus: 'Show the previous year', // Status text for the previous year command
nextText: 'Next>', // Text for the next month command
nextStatus: 'Show the next month', // Status text for the next month command
nextJumpText: '>>', // Text for the next year command
nextJumpStatus: 'Show the next year', // Status text for the next year command
currentText: 'Current', // Text for the current month command
currentStatus: 'Show the current month', // Status text for the current month command
todayText: 'Today', // Text for the today's month command
todayStatus: 'Show today\'s month', // Status text for the today's month command
clearText: 'Clear', // Text for the clear command
clearStatus: 'Clear all the dates', // Status text for the clear command
closeText: 'Close', // Text for the close command
closeStatus: 'Close the datepicker', // Status text for the close command
yearStatus: 'Change the year', // Status text for year selection
monthStatus: 'Change the month', // Status text for month selection
weekText: 'Wk', // Text for week of the year column header
weekStatus: 'Week of the year', // Status text for week of the year column header
dayStatus: 'Select DD, M d, yyyy', // Status text for selectable days
defaultStatus: 'Select a date', // Status text shown by default
isRTL: false // True if language is right-to-left
});
$.calendarsPicker.commands = { // Command actions that may be added to a layout by name
// name: { // The command name, use '{button:name}' or '{link:name}' in layouts
// text: '', // The field in the regional settings for the displayed text
// status: '', // The field in the regional settings for the status text
// // The keystroke to trigger the action
// keystroke: {keyCode: nn, ctrlKey: boolean, altKey: boolean},
// enabled: fn, // The function that indicates the command is enabled
// date: fn, // The function to get the date associated with this action
// action: fn} // The function that implements the action
prev: {...}, // Previous month
prevJump: {...}, // Previous year
next: {...}, // Next month
nextJump: {...}, // Next year
current: {...}, // Current month
today: {...}, // Today's month
clear: {...}, // Clear the datepicker
close: {...}, // Close the datepicker
prevWeek: {...}, // Previous week
prevDay: {...}, // Previous day
nextDay: {...}, // Next day
nextWeek: {...} // Next week
}
$.calendarsPicker.defaultRenderer = { // The standard datepicker renderer
picker: '...', // Overall structure
monthRow: '...', // One row of months
month: '...', // A single month
weekHeader: '...', // A week header
dayHeader: '...', // Individual day header
week: '...', // One week of the month
day: '...', // An individual day
monthSelector: '...', // jQuery selector, relative to picker, for a single month
daySelector: '...', // jQuery selector, relative to picker, for individual days
rtlClass: '...', // Class for right-to-left (RTL) languages
multiClass: '...', // Class for multi-month datepickers
defaultClass: '...', // Class for selectable dates
selectedClass: '...', // Class for currently selected dates
highlightedClass: '...', // Class for highlighted dates
todayClass: '...', // Class for today
otherMonthClass: '...', // Class for days from other months
weekendClass: '...', // Class for days on weekends
commandClass: '...', // Class prefix for commands
commandButtonClass: '...', // Extra class(es) for commands that are buttons
commandLinkClass: '...', // Extra class(es) for commands that are links
disabledClass: '...' // Class for disabled commands
}
$.calendarsPicker.setDefaults(settings) // Set global defaults
$.calendarsPicker.multipleEvents(fns) // Apply multiple callbacks to an event
$(selector).calendarsPicker('option', settings) // Update multiple settings
$(selector).calendarsPicker('option', name, value) // Update a single setting
$(selector).calendarsPicker('option', name) // Retrieve a current setting
$(selector).calendarsPicker('destroy') // Remove datepicker functionality
$(selector).calendarsPicker('enable') // Enable datepicker and field
$(selector).calendarsPicker('disable') // Disable datepicker and field
$(selector).calendarsPicker('isDisabled') // Determine if a datepicker is disabled
$(selector).calendarsPicker('show') // Display a popup datepicker
$(selector).calendarsPicker('hide') // Close a popup datepicker
$(selector).calendarsPicker('clear') // Close a popup datepicker and clear its field
$(selector).calendarsPicker('getDate') // Retrieve the selected dates
$(selector).calendarsPicker('setDate', dates, endDate) // Set the selected dates
$(selector).calendarsPicker('retrieveDate', elem) // Retrieve the date for a selected datepicker element
$(selector).calendarsPicker('performAction', action) // Execute a named command
$(selector).calendarsPicker('changeMonth', offset) // Move a number of months
$(selector).calendarsPicker('showMonth', year, month) // Show a specific month and year
$(selector).calendarsPicker('changeDay', offset) // Move a number of days
$(selector).calendarsPicker('selectDate', elem) // Select the date for a datepicker element
// And in the extension module
$.calendarsPicker.weekOfYearRenderer // Renderer showing week of the year
$.calendarsPicker.themeRollerRenderer // Renderer using ThemeRoller styling
$.calendarsPicker.themeRollerWeekOfYearRenderer // Renderer combining the above two
$.calendarsPicker.noWeekends // onDate callback to nnot allow weekend dates
$.calendarsPicker.changeFirstDay // onShow callback to allow changing the first day of the week
$.calendarsPicker.hoverCallback(onHover) // onShow callback to follow date hovers
$.calendarsPicker.highlightWeek // onShow callback to highlight a hovered week
$.calendarsPicker.showStatus // onShow callback to show a status bar
$.calendarsPicker.monthNavigation // onShow callback to simplify navigation within a year
$.calendarsPicker.selectWeek // onShow callback to select an entire week
$.calendarsPicker.selectMonth // onShow callback to select an entire month
Usage
Include the jQuery library in the head section of your page.
Alternately, you can use the minified versions jquery.calendars.min.js
(10.7K vs 33.1K, 2.9K when zipped)
and jquery.calendars.plus.min.js (5.5K vs 16.5K, 2.2K when zipped).
Download and include the jQuery Calendars Datepicker CSS and JavaScript in the head section of your page.
Localisation packages are available for download
and should be loaded after the main calendars datepicker code. These packages
automatically apply their settings as global default values.
All of the localisation files are also available in one module:
jquery.calendars.picker.lang.js.
Note that these localisations only apply to the datepicker controls. You may also want
to change the localisation of the underlying calendar.
I have been using your jquery plugin in my interactive time map to convert between
Gregorian/Julian calendars and Hijri calendar , It is working flawlessly.
Mostafa Muhammad
Excellent work Keith. Loving jQuery Calendars.
Especially Hebrew, Islamic calendars.
Ibraheem
Contact Keith Wood at wood.keith{at}optusnet.com.au
with comments or suggestions.
