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.

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
  • 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.

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.

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.

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_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").
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.

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.

min_year

If this option is provided, a year value less than the supplied value will be rejected.

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.

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.

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: '/'.

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.

show_hints

A boolean value controlling whether hint text will be displayed in empty fields which do not have the input focus. Default: true.

show_tooltips

A boolean value controlling whether a field name tooltip will be displayed beneath the fields with the current input focus. Default: true.

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_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');
destroy

Removes the datetextentry functionality and returns the element back to its original state, e.g.:

$(selector).datetextentry('destroy');
focus

Move the input focus to the first field, e.g.:

$(selector).datetextentry('focus');
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');
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);

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.

Copyright © 2010-2017 Grant McLean