DateTime - Simian GUI Documentation v2.2.1

The DateTime component

A DateTime component lets users specify a date and/or a time interactively.

DateTime component example

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any DataTime component has a label and tooltip property even though these are not explicitly listed here.

Properties

Name	Description	Datatype	Default
format	The date and time format used for presenting the date captured by the component.	String	`'yyyy-MM-dd HH:mm a'`
enableDate	Whether or not the date picker should be enabled.	Boolean	True
enableTime	Whether or not the time picker should be enabled.	Boolean	True
defaultDate	The default date selected when the value has not been edited. This shall follow the `format` of the component or you can use `Moment.js` functions such as `moment().subtract(10, 'days')` (which is not supported by the `defaultValue` property).	String
datePicker	The date picker configurations.	DatePickerConfiguration	See below
labelPosition	Position of the label with respect to the component. Can be `'top'`, `'bottom'`, `'right-right'`, `'left-right'`, `'left-left'` or `'right-left'`.	String	`"top"`
multiple	Whether or not multiple values can be entered.	Boolean	False
tableView	When `true` and the component is part of an EditGrid, the component's value is shown (simplified) in the collapsed row of the EditGrid.	Boolean	False
timePicker	The time picker configurations.	TimePickerConfiguration	See below

If you set the defaultValue property to specify the date selected by default, make sure to pass it in the right format (as specified in the format property). If you set both the defaultValue and defaultDate property, the defaultValue will be used as the default value. It is therefore advised to use the defaultValue instead of the defaultDate when not using Moment.js.

Testing

The defaultDate property does not work well with the Testing functionality because calling getSubmissionData on a DateTime component in a test-environment will return the defaultValue and not the defaultDate. Also, editing the value of a DateTime component with the testing functionality (using choose or type gestures) is not supported.

Methods

Name	Syntax	Description
setDateSelection	`obj.setDateSelection()`	Disables time selection and sets the `format` property to `'dd-MM-yyyy'`.
setOutputAs	`obj.setOutputAs(outputType)`	Set the output type used by `getSubmissionData`. The default is a string. The value can be converted to a `datetime` object.

DatePickerConfiguration

The value of the datePicker property of a DateTime component shall be of type DatePickerConfiguration. It has the following properties:

Name	Description	Datatype	Default
disable	Specify what (ranges of) dates should not be selectable. For example: `"2021-09-21, 2021-12-25 - 2022-01-03, 2022-02-01"`	String
disableFunction	Disable dates using this function. For example, disable all Mondays and Wednesdays using `date.getDay() === 1 \|\| date.getDay() === 3`. See this link for more information.	String
disableWeekdays	Whether or not to disable weekdays.	String	False
disableWeekends	Whether or not to disable weekends.	String	False
maxDate	The maximum date that can be set within the date picker.	String
minDate	The minimum date that can be set within the date picker.	String
multiple	Whether or not multiple values can be entered.	Boolean	False

For example, set the mininum date that can be selected by using:

dt                      = component.DateTime("dt", form);
dt.datePicker.minDate   = "2020-01-01";

dt = component.DateTime("dt", form)
dt.datePicker.minDate = "2020-01-01"

TimePickerConfiguration

The value of the timePicker property of a DateTime component shall be of type TimePickerConfiguration. It has the following properties:

Name	Description	Datatype	Default
hourStep	The amount of hours to step when the up or down button is pressed.	Integer	1
minuteStep	The amount of minutes to step when the up or down button is pressed.	Integer	1
showMeridian	Whether or not to show the time in AM/PM.	Boolean	False

For example, you can make the time show up in AM/PM instead of 24hr notation by using:

dt                          = component.DateTime("dt", form);
dt.timePicker.showMeridian  = true;

dt = component.DateTime("dt", form)
dt.timePicker.showMeridian = True

If the component does not expand when it is clicked, it probably means that a property of your DatePickerConfiguration or TimePickerConfiguration is incorrectly structured.

Simian GUI Documentation v2.2.1