dateTimePicker

dateTimePicker lets users enter or select both a date and a time.

XML Element

dateTimePicker

Java Class

TypedDateTimePicker

Basics

LIVE DEMO

The date and time can be entered directly using the keyboard or selected from the corresponding overlay. The overlay opens when the respective field is clicked or any input is entered.

The following example defines a dateTimePicker with a label:

<dateTimePicker id="dateTimePicker" label="DateTimePicker" datatype="localDateTime"/>

Data Types

dateTimePicker is a typed component which supports common data types for storing both a date and a time:

  • date

  • dateTime

  • localDateTime

  • offsetTime

  • localTime

  • offsetDateTime

  • time

  • localDate

When you bind the component to an entity attribute, it will automatically assume the data type of that attribute. To set the type explicitly, use the datatype attribute.

Data-aware dateTimePicker

LIVE DEMO

Use the dataContainer and property attributes to bind dateTimePicker to an entity attribute. The data container provides the entity instance, and property identifies the date-time attribute to edit.

The following example produces a data-aware dateTimePicker:

<data>
    <instance id="taskDc"
              class="io.jmix.uisamples.entity.Task"
              fetchPlan="_local"/>
</data>
<layout>
    <dateTimePicker id="dateTimePicker" label="DateTimePicker"
                     dataContainer="taskDc" property="dueDate"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>

Step

The default interval between the items displayed in the time overlay is set to one hour. To customize this interval, use the step attribute either in XML or programmatically. The step attribute supports flexible time interval configuration using different chrono units. You can specify values with unit suffixes for clarity.

Setting the step attribute in the view descriptor XML:

<dateTimePicker step="2h"/> (1)
<dateTimePicker step="1600s"/> (2)
<dateTimePicker step="20m"/> (3)
<dateTimePicker step="30"/> (4)
1 2 hour intervals.
2 1600 second (26m 40s) intervals.
3 20 minute intervals.
4 A number without a suffix means minutes.

This can also be done in the view controller:

@ViewComponent
private TypedDateTimePicker dateTimePicker;

@Subscribe
public void onInit(final InitEvent event) {
    dateTimePicker.setStep(Duration.ofMinutes(30));
}

The step must divide an hour or day evenly. For example, "15 minutes", "30 minutes" and "2 hours" are valid steps, whereas "42 minutes" isn’t.

The overlay doesn’t appear for steps less than 15 minutes, to avoid showing an impractical number of choices.

Date Format

The default date and time format in the application is defined by the localized format strings. To use a different format, add your own format strings to the message bundle.

To change the format for a particular component, use its dateFormat attribute.

Date and Time Range

LIVE DEMO

To restrict the input to a specific date range, specify the minimum and maximum dates using the max and min attributes.

<dateTimePicker min="2024-01-01T10:30:00" max="2024-12-31T20:30:00"/>

Or specify a dynamic date range within the view controller:

@ViewComponent
protected TypedDateTimePicker<LocalDateTime> dateTimePicker;

@Subscribe
protected void onInit(InitEvent event) {
    dateTimePicker.setMin(LocalDateTime.now().minusWeeks(1));
    dateTimePicker.setMax(LocalDateTime.now().plusWeeks(1));
}

Validation

To check values entered into dateTimePicker, add a validator element. This allows adding a custom validation criterion or select one of the following predefined validators:

This example demonstrates how to use the FutureValidator to ensure that the selected time and date are in the future:

<dateTimePicker label="Select a future date and time">
    <validators>
        <future/>
    </validators>
</dateTimePicker>

Theme Variants

LIVE DEMO

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

small

Makes the component smaller.

Aura, Lumo

align-left

Aligns the field value to the left side.

Aura, Lumo

align-center

Centers the field value.

Aura, Lumo

align-right

Aligns the field value to the right side.

Aura, Lumo

helper-above-field

Renders the helper text above the field, below the label.

Aura, Lumo

Attributes

The following attributes are specific to dateTimePicker:

Name Description Default

autoOpen

Defines whether the overlays open when the user starts typing a date.

—

datePlaceholder

Specifies a text that will be displayed inside the date field when it is empty.

—

max

Specifies the latest date and time that can be selected.

—

min

Specifies the earliest date and time that can be selected.

—

timePlaceholder

Specifies a text that will be displayed inside the time field when it is empty.

—

The following shared attributes are supported by dateTimePicker:

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - dataContainer - datatype - dateFormat - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - overlayClass - property - readOnly - required - requiredMessage - step - tabIndex - themeNames - visible - weekNumbersVisible - width

Handlers

The following handlers are specific to dateTimePicker:

Name Description

ClientValidatedEvent

Fired after client-side validation changes the component’s validity.

validator

Validates the component value.

The following shared handlers are supported by dateTimePicker:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - TypedValueChangeEvent - statusChangeHandler

Elements

A dateTimePicker can include tooltip and validator as its nested elements.

See Also