| Welcome to AnyDatePicker |
|---|
Introduction
AnyDatePicker is a Javascript library which lets you add a "date picker" to your Web applications.
So far so boring; there are dozens of date pickers out there. But AnyDatePicker aims to be different, by allowing you to customise almost everything without having to understand or change the code.
Using AnyDatePicker, by writing only a couple of lines of Javascript code and a few data declarations, you can:
- Handle any date from 1582 through 9999; AnyDatePicker is not dependent on Javascript's date object, which cannot represent years before 1970.
- Start the week on any day.
- Specify any days for the weekend.
- Specify fixed (Christmas, etc) and movable (Thanksgiving, etc) holidays.
- Have the month and year selected from a dropdown list or using navigation buttons.
- Allow a time to be input, in 12-hour or 24-hour mode, using dropdown lists or text fields.
- Customise the look of any element via the style sheet.
- Translate the strings which the user sees into any language.
Installation
- Download AnyDatePicker.zip from here.
- Unpack the files into a subdirectory of your Web application. If you name this directory "anydatepicker" then you will have one less thing to configure later.
- Send the CSS and Javascript files to your application. For example:
<script type="text/javascript" src="anydatepicker/anydatepicker.js"></script> <link rel="stylesheet" href="anydatepicker/anydatepicker.css" type="text/css" />
- Identify the input fields in your application with which you want to associate a date picker. Typically, you will have a visible field where the user can see a nicely-formatted version of the date/time which they have entered, and a "real" form field - which might well be hidden, but doesn't have to be - where the actual timestamp is stored for passing to the application when the form is submitted and/or AJAX is invoked. It's this "real" field which interests us here.
- If the input fields which you identified do not store the date/time in AnyDatePicker's yyyymmdd or yyyymmddhhmm format, then you will need to write a couple of simple functions to convert to and from your application's format. See incomingConvert and outgoingConvert in "anyDatePicker.makeDiv() parameter object keys".
- Create one or more AnyDatePicker DIV elements by calling anyDatePicker.makeDiv(). This can be done at any point when the page loads; at this stage, nothing is displayed. You can create a separate date picker DIV with different parameters for each "real" input field, or "recycle" the same one across the whole form.
- To open the date picker and allow the user to select a date and/or time,
call anyDatePicker.fillDiv().
This will typically be done from a link on the page, such as
<a href="javascript:anyDatePicker.fillDiv(...)">(link or cute calendar icon goes here)</a>;
- That's it! Your application now has a fully functional date picker.
Functions
This section lists all of the public functions made available by AnyDatePicker.
| Function name | Parameters | Returned value | Description |
|---|---|---|---|
| anyDatePicker.makeDiv | div-id, {other parameters} | DIV | This function constructs and returns a AnyDatePicker DIV in the current HTML document.
It takes two parameters: a string which will become the DOM id of the DIV, and an object which contains a number of values and objects
which configure the date picker (see "anyDatePicker.makeDiv() parameter object keys").
When created, the DIV will have its style attribute display set to 'none'. It will be displayed when anyDatePicker.fillDiv() is called. |
| anyDatePicker.fillDiv | div-id, input-id, {positioning} | DIV | This function associates an AnyDatePicker DIV - built by anyDatePicker.makeDiv -
with an input element, and displays the date picker to the user.
Any other AnyDatePicker DIVs which might already be open will be hidden,
and any partially-completed changes to their associated date/time value will be lost.
This function takes up to three parameters: a string which is the DOM id of the AnyDatePicker DIV, a string which is the DOM id of the "target" input element, and an optional object which contains a number of values and objects which are used to position the DIV within the browser window (see "anyDatePicker.fillDiv() positioning object keys"). The initial date/time value proposed by the date picker will be the current value of the "target" input element, possibly after conversion by the incomingConvert function. If this does not give a valid date, then today's date will be used, subject to the minimum and maximum values imposed by earliestDate and latestDate respectively. If the time is required but not specified, then midnight (00:00) will be used, subject to the minimum and maximum values imposed by earliestTimes and latestTimes respectively. If the "positioning" object is not supplied, then the DIV will not be positioned by AnyDatePicker; in this case, the caller is free to position it anywhere, preferably before calling anyDatePicker.fillDiv(). |
| anyDatePicker.hideAllDivs | none | null | This function hides any AnyDatePicker DIVs which might currently be displayed. Any partially-completed changes to their associated date/time value will be lost. This function could be useful after AJAX operations complete, or at any other time when you want to return the page to a known state. |
| anyDatePicker.validDateTime | date/time string | boolean | This function returns true if the supplied string is a valid date/time string of the form yyyymmdd or yyyymmddhhmm, and false otherwise. The year must fall in the range 1582-9999, the month in the range 1-12, the day in the range of valid day numbers for the month and year, the hour in the range 00-23, and the minute in the range 00-59. |
| anyDatePicker.weekdayNumber | date/time string | integer | This function returns the weekday number (Sunday=0, Monday=1, etc) of the date represented by the given date/time string of the form yyyymmdd or yyyymmddhhmm. |
| anyDatePicker.findPos | DOM element, direction | integer | This function returns the absolute browser window offset, in pixels, of the position of the given DOM element for a specific direction, which must be one of the strings 'left' or 'top'. This can be useful when you want to position the AnyDatePicker DIV from your own code, rather than having anyDatePicker.fillDiv() position it for you. |
| anyDatePicker.versionInfo | none | string | This function returns the current version of anyDatePicker. The format of this string is not fixed; the only guarantee is that from version N to version N+1, the string returned by version N+1 will be "greater" than the string returned by version N, as defined by the Javascript '>' operator. |
anyDatePicker.makeDiv() parameter object keys
This section lists all of the possible object keys which can be used in the "parameter" object which is passed to anyDatePicker.makeDiv() as the second parameter of the function call. The majority of the work involved in customising AnyDatePicker goes into the configuration of this object.
| Parameter name | Default value | Description |
|---|---|---|
| allowCancel | false | If this is set to true, the date picker will include a "cancel" button, which will close the date picker without changing the input field value. |
| ampm | false | If this is set to true, then the time will be input in 12-hour format, with an additional dropdown to allow selection between AM and PM. Note that this does not automatically imply that a time input will be present; you still need to specify timeInput. |
| ampmStrings | ['am', 'pm'] | A two-element array which specifies the strings corresponding to "AM" and "PM". These will only appear if you set ampm to true. |
| callbackOnAccept | (dummy function) | An optional function; if provided, it will be called when the user clicks on a date (or the OK button; see confirmWithOK). It takes two parameters: the timestamp (yyyymmdd or yyyymmddhhmm) which the user chose, and the DIV corresponding to the date picker. This function gives you a chance to check whether the date/time selected is really acceptable; for example, some AJAX code could see if your business will be open at that exact date and time. The function should return false if there is a problem, and true otherwise. If false is returned, the date picker window will remain open; the function which you provide is responsible for letting the user know what the problem is, for example with an alert() message. |
| confirmWithOK | false | If this is set to true, the date picker will include an "OK" button. In this case, clicking on a date will not close the window. This option is recommended if the date picker also includes the time (see timeInput); otherwise, the user has to enter the time and then click on a date, which is slightly "clunky". |
| divClass | null | If a string value is provided, the DIV will take this value as the name of its CSS class. For example, this allows you to set a Z-index value for the DIV, which can be useful on some versions on Internet Explorer when combining AnyDatePicker with jQuery. |
| developer | false | If this is set to true, AnyDatePicker will give you some information about the elements in the date picker window, via the item titles (as shown by hovering over the item). For the moment this information is limited; I will extend it depending on feedback. |
| earliestDate | '19000101' | The earliest date which can be picked, in the form yyyymmdd. If hideUnpickableMonths is set to true, the user will not be able to navigate to months before this date. |
| earliestTimes | null | This is an object with elements which specify (in 24-hour format) the earliest time allowed for a day,
depending on whether it is a regular weekday, a weekend, a given weekday number (Sunday=0, Monday=1, etc), or a holiday.
Each element has a key which identifies the class of days to which it applies, and a value which is the earliest time allowed
for days matching that class.
Possible key values are:
|
| elementTitles | (see description) | This object contains the titles (as shown by hovering over the item) of various elements in the date picker.
You will normally only need to replace these if your users expect to see them in a language other than English.
The default value is the following object:
{ 'cancel': 'Cancel', 'hour': 'Hour', 'minute': 'Minute', 'nextmonth': 'Next month', 'nextyear': 'Next year'
, 'ok': 'OK', 'prevmonth': 'Previous month', 'prevyear': 'Previous year', 'year': 'Year'
}
These correspond to date picker elements as follows:
'cancel' and 'OK' are the titles of the corresponding buttons
(see allowCancel and confirmWithOK);
'hour', 'minute', and 'year'
are the titles of the corresponding input elements
(see inputTime and inputYearObject);
and 'nextmonth', 'nextyear', 'prevmonth', and 'prevyear'
are the titles of the corresponding month/year navigation buttons.
If you provide your own object, any values which are missing for individual keys ('cancel', 'hour', etc) will result in the title of the corresponding item being empty. |
| firstDayOfWeek | 1 | This is the weekday which will appear in the left-hand column of the date picker. The default value of 1 means Monday. Set it to 0 for Sunday or 6 for Saturday, etc. |
| hideMonthButtons | false | If this value is set to true, then the user will not be able to move from month to month using the navigation buttons. You will typically want to hide these buttons if you use a dropdown list to select the month (see inputMonthObject). |
| hideUnpickableMonths | false | If this value is set to true, then months which fall outside the range defined by earliestDate and latestDate will not be available, even to browse. The navigation buttons will not go there, any month/year dropdown lists will not allow these months to be chosen, and a possible input text field for the year will not allow a year to be chosen if the corresponding month is outside the specified range. |
| hideUnpickableRows | false | Normally, the date picker shows six week rows, even if a whole week in fact falls in the preceding or following month. If this value is set to true, then these "unpickable" weeks will be eliminated from the display. This means that most months will have only five rows, and if the first day of February in a non-leap year is the first day of the week (see firstDayOfWeek), it will only have four. |
| hideYearButtons | false | If this value is set to true, then the user will not be able to move from year to year using the navigation buttons. You will typically want to hide these buttons if you use a dropdown list or a text field to select the year (see inputYearObject). |
| holidays | [] | This is an array of arbitrary size. Each element should be an 8-digit string giving the year, month and day of specific holidays. For example, '20101125' indicates the US Thanksgiving holiday in 2010. Holidays are displayed within the month using specific CSS attributes, which by default are the same as for weekend days. See also holidaysEveryYear and holidaysUnpickable. |
| holidaysEveryYear | ['0101', '1225'] | This is an array of arbitrary size (the empty array, [], is allowed). Each element should be a 4-digit string giving the month and day of days which are always holidays. Thus, the default value specifies New Year's Day and Christmas Day. See also holidays and holidaysUnpickable. |
| holidaysUnpickable | false | If this value is set to true, then holidays (see holidays and holidaysEveryYear) will not be available for the user to select. |
| imageFileExtension | '.png' | This value specifies the extension to be used when building the name of an image file for the icons displayed by AnyDatePicker. You might want to change this to '.gif' if, for example, you decide to use transparent GIF files to address the limitations of Internet Explorer 6. |
| imagePath | 'anydatepicker/images/' | This value indicates the relative or absolute path of the image files used by AnyDatePicker. It should always end with a slash. If the path is relative (not starting with 'http://' or '/'), it will be evaluated from the directory in which the current HTML file resides, not the one from which AnyDatePicker was loaded. The default value is sufficient if you keep all of AnyDatePicker's files where they were unpacked from the distribution ZIP file. |
| imagePathIE6 | 'anydatepicker/images-ie6' | This is similar to imagePath, but specifies a directory containing images which will be loaded if the user's browser is Internet Explorer 6 or earlier. This allows you to have nice, transparent PNG files for modern browsers, and something "reasonable" for IE6. |
| incomingConvert | (dummy function) | An optional function; if provided, it will be called
when AnyDatePicker reads the supplied value from the input field
(see anyDatePicker.fillDiv()).
It takes two parameters: the current value of the input field, and the DIV corresponding to the date picker.
The function should convert that value into a timestamp of the format 'yyyymmdd',
or 'yyyymmddhhmm' if timeInput is specified, and return the timestamp.
This function (and outgoingConvert) is designed to allow you to introduce AnyDatePicker to existing applications, without changing their internal representation of the date. |
| inputMonthObject | null | If this value is set to 'dropdown', then the user will be able to select the month part of the date from a dropdown list. By default, the month is selected by navigating with buttons. If you specify 'dropdown', you may want to eliminate these buttons by setting showMonthButtons to false. |
| inputTimeObject | null | If this value is set to 'dropdown',
then the user will be able to select the hour and minute of the time from a dropdown list.
The elements of the "minute" dropdown list are controlled by
minuteDropdown.
You can also set this value to 'text'. In this case, the hour and minute are input via simple text fields. The range of allowable values for the time (made up of the hour and minute) are controlled by earliestTimes and latestTimes. |
| inputYearObject | null | If this value is set to 'dropdown',
then the user will be able to select the year part of the date from a dropdown list.
Note that the length of this list will be determined by the values of
earliestDate and latestDate.
You can also set this value to 'text'. In this case, the year is input via a simple text field. By default, the year is selected by navigating with buttons. If you specify 'dropdown' or 'text', you may want to eliminate these buttons by setting showYearButtons to false. |
| latestDate | '20991231' | The latest date which can be picked, in the form yyyymmdd. If hideUnpickableMonths is set to true, the user will not be able to navigate to months after this date. |
| latestTimes | null | This is an object with elements which specify (in 24-hour format) the latest time allowed for a day. On any day for which none of the specified values match, the latest time defaults to '2359'. See earliestTimes for more details. |
| minimumTitleWidth | 110 | This is the minimum width, in pixels, to be assigned to the table cell which contains the month and year, whether these are in the form of input elements or simple text. You might want to change this value if you change the style sheet to make some elements larger, and you then find that with Internet Explorer, the width of the date picker does not stay constant when the user moves from one month to the next. |
| minuteDropdown | [0, 15, 30, 45] | If inputTimeObject is set to 'dropdown', then these are the values which will be displayed in the dropdown list to select the "minute" part of the time. |
| monthNames | array of English month names | This is an array of 12 elements, containing the names of the months of the year. You will normally only need to replace these if your users expect to see them in a language other than English. |
| niceDateTime | (dummy function) | An optional function; if provided, it will be called to generate the title of a day (as shown by hovering over the day's table cell). It takes two parameters: the timestamp (yyyymmdd) of the date corresponding to the cell, and the DIV corresponding to the date picker. The returned value should be suitable for use in an HTML title item, so the characters &, <, >, ', and " should be represented by their respective HTML entities (although these characters probably don't occur very often in a date). |
| outgoingConvert | (dummy function) | An optional function; if provided, it will be called
when AnyDatePicker is about to write the date/time value picked by the user, to the input field
(see anyDatePicker.fillDiv()).
It takes two parameters: the current picked date/time as a timestamp (yyyymmdd or yyyymmddhhmm), and the DIV corresponding to the date picker.
The function should convert that value into a string suitable for the input field, and return that string;
the actual updating of the input field's value will be done by AnyDatePicker.
This function (and incomingConvert) is designed to allow you to introduce AnyDatePicker to existing applications, without changing their internal representation of the date. |
| parentElement | null | If specified, this is the DOM element to which anyDatePicker.makeDiv() will attach the DIV which it creates. Normally this value is not required, but it might be useful if you work with a browser that has problems with attaching DIV elements to document.body. Internet Explorer versions 5.5 through 7 have a bug in this area, but AnyDatePicker's code takes care of it. |
| stylePrefix | 'anyDatePicker' | This value is the first "word" of the name of elements in the style sheet. The main reason to change it would be if you want to use different styles for multiple DIVs. |
| userParams | null | This parameter allows you to pass any data you want to the callback functions (callbackOnAccept, incomingConvert, niceDateTime, and outgoingConvert). You will typically supply an object, whose structure will be interpreted by the code of your callback functions. When any of these functions is called, the second parameter is the DIV of the date picker. If the name of this parameter in your code is foo, then the userParams object will be available as foo.anyDatePicker.params.userParams. |
| weekdayNames | array of English weekday names | This is an array of 7 elements, containing the names of the days of the week, starting with Sunday. You will normally only need to replace these if your users expect to see them in a language other than English. |
| weekdayNamesShort | null | If supplied, this should be an array of 7 elements, with each element being a short form of each of the names of the days of the week, starting with Sunday. By default, the first two letters of each element of weekdayNames are used. |
| weekendDays | [0, 6] | This is an array of up to 7 elements (an empty array, [], is allowed). Each element should be a number in the range 0 (Sunday) to 6 (Saturday); the presence of a number indicates that the day in question is part of the weekend. Weekend days are displayed in a specific way, which by default is the same as for holidays. See also weekendsUnpickable. |
| weekendsUnpickable | false | If this value is set to true, then weekend days (see weekendDays) will not be available for the user to select. |
anyDatePicker.fillDiv() positioning object keys
This section lists all of the possible object keys which can be used in the "positioning" object which is passed to anyDatePicker.fillDiv() as the optional third parameter of the function call. This object, if supplied, specifies the position of the date picker DIV, relative to another object in the window.
| Parameter name | Default value | Description |
|---|---|---|
| elementId | null | This is the DOM id of the element relative to which the AnyDatePicker DIV will be positioned. By default, this is the "target" input element (second parameter to anyDatePicker.fillDiv()); if that element is hidden, you will probably want to specify another element here, such as the button which the user clicks to activate the date picker. |
| offsetLeft | 0 | This is the offset, in pixels, which will be applied to the AnyDatePicker DIV, relative to the left of the positioning element specified by elementId. A greater positive value moves the DIV further to the right within the browser window. |
| offsetTop | 0 | This is the offset, in pixels, which will be applied to the AnyDatePicker DIV, relative to the top of the positioning element specified by elementId. A greater positive value moves the DIV further down within the browser window. |
Examples
In these examples, the resulting date/time string is written into a visible input field. Your application might not do that, but it does allow us to demonstrate the interaction between different formats.
1. Click the icon to see an example of AnyDatePicker running with "out-of-the-box" settings. Absolutely everything is at its default value. This date picker was constructed with a single line of Javascript code:
var div = anyDatePicker.makeDiv("adp1", {});
The only other code required is the onClick handler for the icon, which you can see by hovering over it.
2. Click the icon to see an American-style calendar with the week starting on Sunday, am/pm time input, weekends off-limits, an earlier finishing time on Fridays, etc. This also demonstrates the use of conversion functions to allow the field to have a slightly more "friendly" format. You can also change the date in the input field by hand before clicking the icon; of course, this is only as reliable as the conversion functions which you (or, in this case, I) supply, and in most applications, you won't be allowing the user to type in just any date string.
Support
AnyDatePicker is provided free of charge and comes with NO support. The author is, however, available for paid consultancy at reasonable rates.
Please send bug reports and suggestions for enhancements (to the software and the documentation) to anydatepicker@gmail.com. All e-mails sent to that address will be read, but a reply is not guaranteed. In particular, bug reports along the lines of "sometimes it doesn't work, please help" will be ignored; if you want me to work on fixing a bug, you will need to convince me that it's not in your code; this generally means providing an HTML/Javascript page containing the problem, and detailed instructions on how to reproduce it.
AnyDatePicker has been tested on Firefox 3.0.13 and Internet Explorer 6 and 7. Other browsers may or may not work, but I don't have them available to test. If you believe that you have identified an issue with browser compatibility and you think you know how to fix it - for example, by changing something in the style sheet - then please feel free to submit the fix.
Screen shots of interesting customisations of AnyDatePicker are also appreciated.
License
AnyDatePicker - Copyright (C) 2009 Nick Brown.
AnyDatePicker is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
AnyDatePicker is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with AnyDatePicker. If not, see http://www.gnu.org/licenses/.