5.10. Date and Time Input with DateField

The same format specification is also used for parsing user-input date and time, as described later.

A user can easily input a malformed or otherwise invalid date or time. DateField has two validation layers: first on the client-side and then on the server-side.

The validity of the entered date is first validated on the client-side, immediately when the input box loses focus. If the date format is invalid, the v-datefield-parseerror style is set. Whether this causes a visible indication of a problem depends on the theme. The built-in reindeer theme does not shown any indication by default, making server-side handling of the problem more convenient.

.mydate.v-datefield-parseerror .v-textfield {
    background: pink;
}

The setLenient(true) setting enables relaxed interpretation of dates, so that invalid dates, such as February 30th or March 0th, are wrapped to the next or previous month, for example.

The server-side validation phase occurs when the date value is sent to the server. If the date field is set in immediate state, it occurs immediately after the field loses focus. Once this is done and if the status is still invalid, an error indicator is displayed beside the component. Hovering the mouse pointer over the indicator shows the error message.

You can handle the errors by overriding the handleUnparsableDateString() method. The method gets the user input as a string parameter and can provide a custom parsing mechanism, as shown in the following example.

// Create a date field with a custom parsing and a
// custom error message for invalid format
PopupDateField date = new PopupDateField("My Date") {
    @Override
    protected Date handleUnparsableDateString(String dateString)
    throws Property.ConversionException {
        // Try custom parsing
        String fields[] = dateString.split("/");
        if (fields.length >= 3) {
            try {
                int year  = Integer.parseInt(fields[0]);
                int month = Integer.parseInt(fields[1])-1;
                int day   = Integer.parseInt(fields[2]);
                GregorianCalendar c =
                    new GregorianCalendar(year, month, day);
                return c.getTime();
            } catch (NumberFormatException e) {
                throw new Property.
                    ConversionException("Not a number");
            }
        }
        
        // Bad date
        throw new Property.
            ConversionException("Your date needs two slashes");
    }
};
        
// Display only year, month, and day in slash-delimited format
date.setDateFormat("yyyy/MM/dd");

// Don't be too tight about the validity of dates
// on the client-side
date.setLenient(true);

The handler method must either return a parsed Date object or throw a ConversionException. Returning null will set the field value to null and clear the input box.

In addition to customized parsing, overriding the handler method for unparseable input is useful for internationalization and other customization of the error message. You can also use it for another way for reporting the errors, as is done in the example below:

// Create a date field with a custom error message for invalid format
PopupDateField date = new PopupDateField("My Date") {
    @Override
    protected Date handleUnparsableDateString(String dateString)
    throws Property.ConversionException {
        // Have a notification for the error
        getWindow().showNotification(
                "Your date needs two slashes",
                Notification.TYPE_WARNING_MESSAGE);
        
        // A failure must always also throw an exception
        throw new Property.ConversionException("Bad date");
    }
};

If the input is invalid, you should always throw the exception; returning a null value would make the input field empty, which is probably undesired.

Like other fields that have a text box, PopupDateField allows an input prompt that is visible until the user has input a value. You can set the prompt with setInputPrompt.

PopupDateField date = new PopupDateField();

// Set the prompt
date.setInputPrompt("Select a date");
        
// Set width explicitly to accommodate the prompt
date.setWidth("10em");

The date field doesn't automatically scale to accommodate the prompt, so you need to set it explicitly with setWidth().

The input prompt is not available in the DateField superclass.

.v-datefield, v-datefield-popupcalendar {}
  .v-textfield, v-datefield-textfield {}
  .v-datefield-button {}

The top-level element of DateField and all its variants have v-datefield style. The base class and the PopupDateField also have the v-datefield-popupcalendar style.

In addition, the top-level element has a style that indicates the resolution, with v-datefield- basename and an extension, which is one of full, day, month, or year. The -full style is enabled when the resolution is smaller than a day. These styles are used mainly for controlling the appearance of the popup calendar.

The text box has v-textfield and v-datefield-textfield styles, and the calendar button v-datefield-button.

Once opened, the calendar popup has the following styles at the top level:

.v-datefield-popup {}
  .v-popupcontent {}
    .v-datefield-calendarpanel {}

.v-datefield {}
  .v-datefield-calendarpanel {}
    .v-datefield-calendarpanel-header {}
      .v-datefield-calendarpanel-prevyear {}
      .v-datefield-calendarpanel-prevmonth {}
      .v-datefield-calendarpanel-month {}
      .v-datefield-calendarpanel-nextmonth {}
      .v-datefield-calendarpanel-nextyear {}
    .v-datefield-calendarpanel-body {}
      .v-datefield-calendarpanel-weekdays,
      .v-datefield-calendarpanel-weeknumbers {}
        .v-first {}
        .v-last {}
      .v-datefield-calendarpanel-weeknumber {}
      .v-datefield-calendarpanel-day {}
    .v-datefield-calendarpanel-time {}
      .v-datefield-time {}
        .v-select {}
        .v-label {}

The top-level element has the v-datefield style. In addition, the top-level element has a style name that indicates the resolution of the calendar, with v-datefield- basename and an extension, which is one of full, day, month, or year. The -full style is enabled when the resolution is smaller than a day.

The v-datefield-calendarpanel-weeknumbers and v-datefield-calendarpanel-weeknumber styles are enabled when the week numbers are enabled. The former controls the appearance of the weekday header and the latter the actual week numbers.

The other style names should be self-explanatory. For weekdays, the v-first and v-last styles allow making rounded endings for the weekday bar.