datetime

Since: Editor 1.5.2

Date and / or time input.
Please note - this property requires the Editor extension for DataTables.

Description

Date and time data often forms the corner stone of many web applications and in order to facilitate easy entry of date information Editor includes the datetime field type which will show a calendar and / or time picker to the end user (based on the format set).

By default the calendar will operate with ISO8601 dates (YYYY-MM-DD - for example 2015-10-25) and requires no additional software to operate with this common and unambiguous date format. However, you may wish to show date information to your end users in a different format to increase its legibility - that can be done using the displayFormat and wireFormat options and including the Moment.js library on your page. Moment.js has a wide range of formatting options and virtually any date format can be used.

It is important to understand the difference between the display and wire formats:

Display format: What the end user sees inside the input.
Wire format: The value that is used for get and set from the field (i.e. what is transmitted over the wire to the server for saving to the database).

Prior to Editor 1.9.1 there was no wireFormat option - it expected the data to never change format at the client-side (as such the legacy display option is now mapped to displayFormat automatically). Changing the format is optional - if you want to edit the data in the format that the server sent and received, just use the defaultdisplayFormat option.

In addition to date this field type provides a time input widget as well. The format to be used can be specified using the format option and datetime will automatically determine if the calendar should be shown, the time picker or both - i.e. if a format does not include date information the calendar will not be shown, only the time picker.

Options

This field type supports the following options (in addition to the default options):

`displayFormat`

Type: string
Default: YYYY-MM-DD
Since: 1.9.1

The format of the date string that will be shown to the end user in the input element. The formatting options are defined by Moment.js. If a format is used that is not ISO8061 (i.e. YYYY-MM-DD) and Moment.js has not been included, Editor will throw an error stating that Moment.js must be included for custom formatting to be used.

`format`

Type: string
Default: YYYY-MM-DD

An alias for the displayFormat option as described above.

`keyInput`

Type: boolean
Default: true
Since: 1.7.3

Allow (default), or disallow, the end user to type into the date / time input element. If disallowed, they must use the calendar picker to enter data. This can be useful if you are using a more complex date format and wish to disallow the user from potentially making typing mistakes, although note that it does also disallow pasting of data.

`opts`

Type: object
Default: Unset
Since: 2.0.0

Options for the date time picker. Please see the DateTime options reference for the full list of options that this object can contain.

`wireFormat`

Type: string
Default: undefined
Since: 1.9.1

The format of the date string loaded from the server for the field's value and also for sending to the server on form submission. The formatting options are defined by Moment.js.

Methods

This field type supports the following methods (in addition to the default methods):

`field().inst()`

Since: 2.5.2

Get the API instance for the DateTime used in this field.

Returns:

DataTable.Api:
DateTime API instance.

`field().minDate( date )`

Since: 1.5.4

Set the minimum date that the user can select using the calendar UI widget.

Parameters:

	Name	Type	Optional
1	`date`	`Date`, `null`	No
	Minimum date that the user can select or `null` to allow any date.

Returns:

DataTable.Editor.Field:
The field instance is returned to allow method chaining.

`field().maxDate( date )`

Since: 1.5.4

Set the maximum date that the user can select using the calendar UI widget.

Parameters:

	Name	Type	Optional
1	`date`	`Date`, `null`	No
	Maximum date that the user can select or `null` to allow any date.

Returns:

DataTable.Editor.Field:
The field instance is returned to allow method chaining.

Examples

Basic initialisation (ISO8601 formatted date):

editor.add({
	type: 'datetime',
	label: 'Start date:',
	name: 'start_date'
});

Set default to 'now':

editor.add({
	type: 'datetime',
	label: 'Start date:',
	name: 'start_date',
	def: function () {
		return new Date();
	}
});

Using format option to specify a custom format (requires Moment.js):

editor.add({
	type: 'datetime',
	label: 'Start date:',
	name: 'start_date',
	format: 'M/D/YYYY'
});

Show full date and time picker:

editor.add({
	type: 'datetime',
	label: 'Start date:',
	name: 'start_date',
	format: 'MM-DD-YYYY h:mm a'
});

Time picker only:

editor.add({
	type: 'datetime',
	label: 'Start time:',
	name: 'start_time',
	format: 'h:mm a'
});

Use the options to show the week number:

editor.add({
	type: 'datetime',
	label: 'Start date:',
	name: 'start_date',
	opts: {
		showWeekNumber: true
	}
});