|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276 |
- ---
- title: Date Input with DateField
- order: 13
- layout: page
- ---
-
- [[components.datefield]]
- = Date Input with DateField
-
- ifdef::web[]
- [.sampler]
- image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/dates/date-field"]
- endif::web[]
-
- The [classname]#DateField# component provides the means to display and input
- dates. The field comes in two variations: [classname]#DateField#,
- with a numeric input box and a popup calendar view, and
- [classname]#InlineDateField#, with the calendar view always visible.
-
- The example below illustrates the use of the [classname]#DateField#. We set the initial date
- of the date field to current date by using the factory method [methodname]#now#
- of the [classname]#java.time.LocalDate# class.
-
-
- [source, java]
- ----
- // Create a DateField with the default style
- DateField date = new DateField();
-
- // Set the date to present
- date.setValue(LocalDate.now());
- ----
-
- The result is shown in <<figure.components.datefield.basic>>.
-
- [[figure.components.datefield.basic]]
- .[classname]#DateField# for Selecting a Date
- image::img/datefield-example1.png[width=35%, scaledwidth=60%]
-
- [[components.datefield.popupdatefield]]
- == [classname]#DateField#
-
- The [classname]#DateField# provides date input using a text box. Clicking the handle right of the date opens a popup view
- for selecting the year, month, and day. The Down key also opens the popup.
- Once opened, the user can navigate the calendar using the cursor keys.
-
- The date selected from the popup is displayed in the text box according to the
- default date and format of the current locale, or as specified with [methodname]#setDateFormat()#.
- The same format definitions are used for parsing user input.
-
- [[components.datefield.popupdatefield.format]]
- === Date Format
-
- The date is normally displayed according to the default format for the current locale (see
- <<components-features#components.features.locale,"Locale">>).
- You can specify a custom format with [methodname]#setDateFormat()#. It takes a
- format string that follows the format of the [classname]#java.time.format.DateTimeFormatter# in
- Java.
-
-
- [source, java]
- ----
- // Display only year, month, and day in ISO format
- date.setDateFormat("yyyy-MM-dd");
-
- // Display the correct format as placeholder
- date.setPlaceholder("yyyy-mm-dd");
- ----
-
- The result is shown in <<figure.components.datefield.popupdatefield.format>>.
-
- [[figure.components.datefield.popupdatefield.format]]
- .Custom Date Format for [classname]#DateField#
- image::img/datefield-formatting.png[width=35%, scaledwidth=60%]
-
- The same format specification is also used for parsing user-input date,
- as described later.
-
- [[components.datefield.popupdatefield.malformed]]
- === Handling Malformed User Input
-
- A user can easily input a malformed or otherwise invalid date.
- [classname]#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
- [literal]#++v-datefield-parseerror++# style is set. Whether this causes a
- visible indication of a problem depends on the theme. The built-in
- [literal]#++reindeer++# theme does not shown any indication by default, making
- server-side handling of the problem more convenient.
-
-
- [source, css]
- ----
- .mydate.v-datefield-parseerror .v-textfield {
- background: pink;
- }
- ----
-
- The [methodname]#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
- [methodname]#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.
-
-
- [source, java]
- ----
- // Create a date field with a custom parsing and a
- // custom error message for invalid format
- DateField date = new DateField("My Date") {
- @Override
- protected Result<LocalDate> handleUnparsableDateString(
- String dateString) {
- try {
- // try to parse with alternative format
- LocalDate parsedAtServer = LocalDate.parse(dateString, DateTimeFormatter.ISO_DATE);
- return Result.ok(parsedAtServer);
- } catch (DateTimeParseException e) {
- return Result.error("Bad date");
- }
- }
- };
-
- // 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);
- ----
-
-
- [[components.datefield.popupdatefield.css]]
- === CSS Style Rules
-
-
- [source, css]
- ----
- .v-datefield, v-datefield-popupcalendar {}
- .v-textfield, v-datefield-textfield {}
- .v-datefield-button {}
- ----
-
- The top-level element of [classname]#DateField# and [classname]#InlineDateField# have
- [literal]#++v-datefield++# style. The [classname]#DateField# also has the
- [literal]#++v-datefield-popupcalendar++# style.
-
- In addition, the top-level element has a style that indicates the resolution,
- with [literal]#++v-datefield-++# basename and an extension, which is one of
- [literal]#++full++#, [literal]#++day++#, [literal]#++month++#, or
- [literal]#++year++#. The [literal]#++-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 [literal]#++v-textfield++# and
- [literal]#++v-datefield-textfield++# styles, and the calendar button
- [literal]#++v-datefield-button++#.
-
- Once opened, the calendar popup has the following styles at the top level:
-
-
- [source, css]
- ----
- .v-datefield-popup {}
- .v-popupcontent {}
- .v-datefield-calendarpanel {}
- ----
-
- The top-level element of the floating popup calendar has
- [literal]#++.v-datefield-popup++# style. Observe that the popup frame is outside
- the HTML structure of the component, hence it is not enclosed in the
- [literal]#++v-datefield++# element and does not include any custom styles.
- // NOTE: May be changed in #5752.
- The content in the [literal]#++v-datefield-calendarpanel++# is the same as in
- [classname]#InlineDateField#, as described in <<components.datefield.calendar>>.
-
- [[components.datefield.calendar]]
- == [classname]#InlineDateField#
-
- The [classname]#InlineDateField# provides a date picker component with a month
- view. The user can navigate months and years by clicking the appropriate arrows.
- Unlike with the pop-up variant, the month view is always visible in the inline
- field.
-
-
- [source, java]
- ----
- // Create a DateField with the default style
- InlineDateField date = new InlineDateField();
-
- // Set the date to present
- date.setValue(LocalDate.now());
- ----
-
- The result is shown in <<figure.components.datefield.inlinedatefield>>.
-
- [[figure.components.datefield.inlinedatefield]]
- .Example of the [classname]#InlineDateField#
- image::img/datefield-inlinedatefield.png[width=35%, scaledwidth=60%]
-
- The user can also navigate the calendar using the cursor keys.
-
- === CSS Style Rules
-
-
- [source, css]
- ----
- .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 {}
- ----
-
- The top-level element has the [literal]#++v-datefield++# style. In addition, the
- top-level element has a style name that indicates the resolution of the
- calendar, with [literal]#++v-datefield-++# basename and an extension, which is
- one of [literal]#++full++#, [literal]#++day++#, [literal]#++month++#, or
- [literal]#++year++#. The [literal]#++-full++# style is enabled when the
- resolution is smaller than a day.
-
- The [literal]#++v-datefield-calendarpanel-weeknumbers++# and
- [literal]#++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
- [literal]#++v-first++# and [literal]#++v-last++# styles allow making rounded
- endings for the weekday bar.
-
- [[components.datefield.resolution]]
- == Date Resolution
-
- In addition to display a calendar with dates, [classname]#DateField# can also
- display just the month or year. The visibility of the input components is
- controlled by [methodname]#setDateResolution()#, which you can set with [methodname]#setResolution()#.
- The method takes as its parameter the highest resolution date element that should
- be visible. Please see the API Reference for the complete list of resolution parameters.
-
-
- [[components.datefield.locale]]
- == DateField Locale
-
- The date is displayed according to the locale of the user, as reported
- by the browser. You can set a custom locale with the [methodname]#setLocale()#
- method of [classname]#AbstractComponent#, as described in
- <<components-features#components.features.locale,"Locale">>.
- Only Gregorian calendar is supported.
-
-
- [[components.datefield.weeknumbers]]
- == Week Numbers
-
- You can enable week numbers in a date field with
- [methodname]#setShowISOWeekNumbers()#. The numbers are shown according to the ISO 8601 standard in a column on the left side of the field.
|