jquery.datetextentry.js

This plugin provides a widget for date entry and validation. Unlike a 'date picker' the widget is well suited to keyboard-only data entry tasks.

Zip Tar Git

Introduction
Reference Documentation

Options
Messages
Methods

Examples

Introduction

The datetextentry widget provides for reliable date entry without the need for a date-picker. While convenient for selecting dates close to 'today' (e.g.: setting up an appointment for next Tuesday), date-pickers are not suitable for all date entry tasks. For example, when entering your date of birth, a date-picker requires you to page through months and years of dates - the older you are, the more times you'll have to click. This can be very frustrating since you know your date of birth - you just want to type it in. The datetextentry widget allows you to do exactly that, while removing any ambiguity about expected field order and separators.

You provide a plain <input type="text"> form element and the plugin will replace it with a 3-field widget. When the form is submitted, a single value will be posted to the backend. Dates are translated to and from ISO standard YYYY-MM-DD format. The order of the input fields can be customised for your local conventions.

A typical text entry box might look like this:

With the datetextentry plugin applied, it might look like this:

The widget provides the following functionality (try out the example above):

Separate fields for day, month and year (configurable order)
Tooltips and hint text to guide the user through each field
Auto-advance when a field is 'full'
Backspacing through an empty field to the preceding field
More descriptive labels for screen reader users when focus automatically shifts between fields
Custom handling for mapping 2-digit years to 4 digits
Immediate feedback for invalid data (e.g.: day 32 or month 13)
More advanced validation on complete dates (e.g.: to reject February 29th in a non-leap year)
Custom validation for application-specific date range checking
Linking the input field with its label (e.g.: click label to focus)

The examples directory includes some demos to get you started.

The plugin is dual-licensed under the MIT and GPL licences.

Reference Documentation

Options

When the datetextentry function is called, you can provide option name/value pairs as an object literal like this:

$(selector).datetextentry({opt1: value1, opt2: value2});

Name	Description
`add_century`	When a 2-digit year is entered the `add_century` function upgrades it to 4 digits by simply adding 2000. You can use this option to provide an alternative function, that takes a number in the range 10-99 and returns a number in the range 1000-9999.
`custom_validation`	Use this option to supply a function for applying arbitrary validation rules. The function will be passed an object literal with `year`, `month`, `day` and `date` properties. If the date is deemed to be invalid, the function should `throw` an appropriate error message, which will be displayed to the user. See example
`errorbox_x`	When an invalid value is entered, a message will be displayed in an 'error box' to the right of the widget. Use the `errorbox_x` and `errorbox_y` options to specify an alternative position for the error box, relative to the top right corner of the widget. See example
`errorbox_y`	See errorbox_x.
`field_hint_text_day`	Hint text to display in an empty day field. Default: 'DD'
`field_hint_text_month`	Hint text to display in an empty month field. Default: 'MM'
`field_hint_text_year`	Hint text to display in an empty year field. Default: 'YYYY'
`field_order`	A string comprising the letter 'D', 'M' and 'Y' in the order you wish the day, month and year fields to be displayed. See example
`field_tip_text_day`	Tooltip text to display beneath the day field when it has the focus. Default: 'Day'
`field_tip_text_month`	Tooltip text to display beneath the month field when it has the focus. Default: 'Month'
`field_tip_text_year`	Tooltip text to display beneath the year field when it has the focus. Default: 'Year'
`field_auto_focus_day`	Descriptive text substituted into aria-label when focus is automatically shifted to a field to assist screen reader users in understanding what occurred. Default: 'Focus has moved to day'
`field_auto_focus_month`	Descriptive text substituted into aria-label when focus is automatically shifted to a field to assist screen reader users in understanding what occurred. Default: 'Focus has moved to month'
`field_auto_focus_year`	Descriptive text substituted into aria-label when focus is automatically shifted to a field to assist screen reader users in understanding what occurred. Default: 'Focus has moved to year'
`field_width_day`	Proportion of the overall width of the widget that should be used for the day field. Default: 40. The values specified are not absolute pixel values. Instead, the widget size is organised to take up the same space as the input box it replaces. Inside the widget, the field sizes are allocated based on the relative proportions specified.
`field_width_month`	Proportion of the overall width of the widget that should be used for the month field. Default: 40.
`field_width_sep`	Proportion of the overall width of the widget that should be used for each of the separators. Default: 4.
`field_width_year`	Proportion of the overall width of the widget that should be used for the year field. Default: 60.
`format_date`	When a valid date is entered into the three fields, a formatted date string will be saved in the original text field, to be submitted to the backend server. By default the date will be in ISO-standard YYYY-MM-DD format. Using this option, you can provide a function that accepts an object of the form `{ day: '02', month: '06', year: '2012' }` and returns a string.
`human_format_date`	This option is similar to format_date but allows you to override the default format (DD/MM/YYYY) used to display dates in the error box (for example in "Date must not be earlier than 01/01/1970").
`is_required`	A boolean value indicating whether this is a required field. If this option is true, moving focus away from the widget without entering a complete and valid date will trigger a validation error. You can override the default message text for the 'required field' error by supplying a value for E_REQUIRED_FIELD. See example
`max_date`	If this option is provided, a date greater than the supplied value will be rejected. The value can be supplied as an ISO date string (which will be parsed using the parse_date function; or as a function which returns an object literal of the form expected by format_date. See example
`max_year`	If this option is provided, a year value greater than the supplied value will be rejected.
`min_date`	If this option is provided, a date less than the supplied value will be rejected. The value can be supplied as an ISO date string (which will be parsed using the parse_date function); or as a function which returns an object literal of the form expected by format_date. See example
`min_year`	If this option is provided, a year value less than the supplied value will be rejected. See example
`on_blur`	If you supply a callback function, it will be called when the input focus leaves the date widget. Within your callback function you can call `this.widget_error_text()` to determine if the date entry has outstanding validation errors - an empty string will be returned for no errors. Note: this function uses a delay to filter out the noise of focus-out from one date sub-field and focus-in to the next. Therefore the 'on_blur' callback will usually be called after the 'focus' event fires on the next form element.
`on_change`	If you supply a callback function, it will be called when the contents of the date entry boxes pass validation. The function will be passed a single argument - a date string from `format_date`. Note: this is quite a 'noisy' function - it will be called for every keypress when a valid date results. Also note, it will not be called when the date is changed to an invalid value. See example
`on_error`	If you supply a callback function, it will be called when the error box is updated. A single argument will be passed to the function. The empty string if the error condition is cleared or the text of the error otherwise. See example
`parse_date`	You can override the default date parsing function which is used to parse the default value in the base `<input>` element's `value` attribute.
`separator`	The character which should be displayed in the widget between the input fields, Default: '/'. See example
`show_errors`	A boolean value controlling whether error text will be displayed next to the date widget when invalid input is detected. This option would typically be set to false when the on_error option is used for customised error message presentation. Default: true. See example
`show_hints`	A boolean value controlling whether hint text will be displayed in empty fields which do not have the input focus. Default: true. See example
`show_tooltips`	A boolean value controlling whether a field name tooltip will be displayed beneath the fields with the current input focus. Default: true. See example
`tooltip_x`	Horizontal offset in pixels for the tooltip relative to the current input field.
`tooltip_y`	Vertical offset in pixels for the tooltip relative to the current input field.

Messages

The text of the error messages can be customised by providing alternative message text as options.

Name	Default message
`E_BAD_DAY_FOR_MONTH`	Only %d days in %m %y
`E_DAY_NAN`	Day must be a number
`E_DAY_TOO_BIG`	Day must be 1-31
`E_DAY_TOO_SMALL`	Day must be 1-31
`E_MAX_DATE`	Date must not be later than %DATE
`E_MIN_DATE`	Date must not be earlier than %DATE
`E_MONTH_NAN`	Month must be a number
`E_MONTH_TOO_BIG`	Month must be 1-12
`E_MONTH_TOO_SMALL`	Month must be 1-12
`E_REQUIRED_FIELD`	This field is required
`E_YEAR_LENGTH`	Year must be 4 digits
`E_YEAR_NAN`	Year must be a number
`E_YEAR_TOO_BIG`	Year must not be after %y
`E_YEAR_TOO_SMALL`	Year must not be before %y

Methods

After the widget has been initialised, you can reference it again using the same selector and call a method like this:

$(selector).datetextentry('method-name', args);

Name	Description
`clear`	Discard the current contents of all the fields, e.g.: $(selector).datetextentry('clear'); See example
`destroy`	Removes the datetextentry functionality and returns the element back to its original state, e.g.: $(selector).datetextentry('destroy'); See example
`focus`	Move the input focus to the first field, e.g.: $(selector).datetextentry('focus'); See example
`set_date`	Provide a new date value, which will be parsed by parse_date and used to populate the three date entry fields, e.g.: $(selector).datetextentry('set_date', '2005-12-31'); See example
`set_error`	Provide a specific error message. This might be used, for example, by a form's onsubmit handler to alert about a required field, or to indicate why the entered value is not valid when considered with other field values, e.g.: $(selector).datetextentry('set_error', 'End date must be after start date'); See example
`set_readonly`	Set the date entry widget to read-only mode or back to normal read/write mode, e.g.: $(selector).datetextentry('set_readonly', true); See example

Examples

Example 1 - Defaults: A minimal example demonstrating the default widget behaviour.
Example 2 - Field Order: Override the default field order for USA-style Month, Day, Year.
Example 3 - Options: Various examples demonstrating a range of different option settings to change separators, hints, tooltips, date ranges and custom validation. Also a demo of interacting with the widget programatically after initialisation.