From 41bec0bc2d0403b0aadfdefc34219da1563f16dc Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Mon, 12 Aug 2024 13:11:50 +0400 Subject: [PATCH 01/32] docs: add brief introduction into validation --- .../flow/component/datepicker/DatePicker.java | 77 ++++++++++++++++--- 1 file changed, 65 insertions(+), 12 deletions(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index 668fed3aaa0..6ca636b7895 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -82,6 +82,32 @@ * the format of the current locale or through the date picker overlay. The * overlay opens when the field is clicked and/or any input is entered when the * field is focused. + *

Validation

+ *

+ * DatePicker comes with a built-in validation mechanism based on constraints. + * Validation is triggered when the user attempts to apply a date whether by + * entering it manually or selecting it from the overlay, or when the date is + * updated programmatically. Validation checks if the date is parsable and + * satisfies the defined constraints. If validation fails, the component is + * marked as invalid and an error message is displayed (if one is provided). + *

+ * The following constraints can be set: + *

+ *

+ * Error messages for unparsable input and constraint violations can be + * configured using the respective methods in the {@link DatePickerI18n} object. + *

+ * In addition to validation, constraints may also have a visual representation. + * For example, dates before the minimum date appear disabled in the overlay. + *

+ * The constraint validation can be disabled by setting + * {@link #setManualValidation(boolean)} to true. This will allow the invalid + * state and the error message to be controlled manually using + * {@link #setInvalid(boolean)} and {@link #setErrorMessage(String)} API. * * @author Vaadin Ltd */ @@ -341,11 +367,13 @@ public DatePicker(LocalDate initialDate, Locale locale) { /** * Sets the minimum date in the date picker. Dates before that will be - * disabled in the popup. + * disabled in the popup. Manual entry of dates before the minimum will + * cause the component to invalidate. * * @param min * the minimum date that is allowed to be selected, or * null to remove any minimum constraints + * @see DatePickerI18n#setMinErrorMessage(String) */ public void setMin(LocalDate min) { String minAsString = FORMATTER.apply(min); @@ -355,7 +383,8 @@ public void setMin(LocalDate min) { /** * Gets the minimum date in the date picker. Dates before that will be - * disabled in the popup. + * disabled in the popup. Manual entry of dates before the minimum will + * cause the component to invalidate. * * @return the minimum date that is allowed to be selected, or * null if there's no minimum @@ -366,11 +395,13 @@ public LocalDate getMin() { /** * Sets the maximum date in the date picker. Dates after that will be - * disabled in the popup. + * disabled in the popup. Manual entry of dates after the maximum will cause + * the component to invalidate. * * @param max * the maximum date that is allowed to be selected, or * null to remove any maximum constraints + * @see DatePickerI18n#setMaxErrorMessage(String) */ public void setMax(LocalDate max) { String maxAsString = FORMATTER.apply(max); @@ -380,7 +411,8 @@ public void setMax(LocalDate max) { /** * Gets the maximum date in the date picker. Dates after that will be - * disabled in the popup. + * disabled in the popup. Manual entry of dates after the maximum will cause + * the component to invalidate. * * @return the maximum date that is allowed to be selected, or * null if there's no maximum @@ -686,22 +718,43 @@ public LocalDate getInitialPosition() { } /** - * Sets whether the date picker is marked as input required. + * Sets whether the user is required to provide a value. When required, a + * required indicator will be displayed next to the label, and the component + * will invalidate if the value is cleared. + *

+ * NOTE: The required indicator won't be visible if the field doesn't have a + * label. * * @param required - * the boolean value to set + * true to make the field required, false otherwise + * @see #setLabel(String) + * @see DatePickerI18n#setRequiredErrorMessage(String) + */ + @Override + public void setRequiredIndicatorVisible(boolean required) { + super.setRequiredIndicatorVisible(required); + } + + /** + * Gets whether the user is required to provide a value. + */ + @Override + public boolean isRequiredIndicatorVisible() { + return super.isRequiredIndicatorVisible(); + } + + /** + * Alias for {@link #setRequiredIndicatorVisible(boolean)}. + * + * @param required + * true to make the field required, false otherwise */ public void setRequired(boolean required) { setRequiredIndicatorVisible(required); } /** - * Determines whether the datepicker is marked as input required. - *

- * This property is not synchronized automatically from the client side, so - * the returned value may not be the same as in client side. - * - * @return {@code true} if the input is required, {@code false} otherwise + * Alias for {@link #isRequiredIndicatorVisible()} */ public boolean isRequired() { return isRequiredIndicatorVisible(); From a41a6b0a7e24971a722912c378b7ce017becf64e Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Tue, 13 Aug 2024 09:26:17 +0400 Subject: [PATCH 02/32] change h3 to h2 --- .../java/com/vaadin/flow/component/datepicker/DatePicker.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index 6ca636b7895..3018de82a98 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -82,7 +82,7 @@ * the format of the current locale or through the date picker overlay. The * overlay opens when the field is clicked and/or any input is entered when the * field is focused. - *

Validation

+ *

Validation

*

* DatePicker comes with a built-in validation mechanism based on constraints. * Validation is triggered when the user attempts to apply a date whether by From 5fbaee7a4748b03a76d4cb326b2a3e216d0131bc Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 15:19:57 +0300 Subject: [PATCH 03/32] Update vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java --- .../java/com/vaadin/flow/component/datepicker/DatePicker.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index 3018de82a98..df5ed312fb7 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -88,7 +88,7 @@ * Validation is triggered when the user attempts to apply a date whether by * entering it manually or selecting it from the overlay, or when the date is * updated programmatically. Validation checks if the date is parsable and - * satisfies the defined constraints. If validation fails, the component is + * satisfies the specified constraints. If validation fails, the component is * marked as invalid and an error message is displayed (if one is provided). *

* The following constraints can be set: From 8a30a760ba04d54f0f6d6fb711f09c732e6172b6 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 15:27:37 +0300 Subject: [PATCH 04/32] Update vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java --- .../java/com/vaadin/flow/component/datepicker/DatePicker.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index df5ed312fb7..084d0922173 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -91,7 +91,7 @@ * satisfies the specified constraints. If validation fails, the component is * marked as invalid and an error message is displayed (if one is provided). *

- * The following constraints can be set: + * The following constraints are supported: *

*

* Error messages for unparsable input and constraint violations can be - * configured using the respective methods in the {@link DatePickerI18n} object. + * configured using the respective properties in the {@link DatePickerI18n} object. *

* In addition to validation, constraints may also have a visual representation. * For example, dates before the minimum date appear disabled in the overlay. From 8011a85a08d99fe8484f6be025a5ce53861a25aa Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 17:13:15 +0300 Subject: [PATCH 06/32] Update vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java --- .../java/com/vaadin/flow/component/datepicker/DatePicker.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index c7908c8da64..176e9c4e437 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -84,7 +84,7 @@ * field is focused. *

Validation

*

- * DatePicker comes with a built-in validation mechanism based on constraints. + * Date Picker comes with a built-in validation mechanism based on constraints. * Validation is triggered when the user attempts to apply a date whether by * entering it manually or selecting it from the overlay, or when the date is * updated programmatically. Validation checks if the date is parsable and From 4cd86d5fae29265a8882b6410cc324dddc7901db Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 17:20:58 +0300 Subject: [PATCH 07/32] Update vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java --- .../com/vaadin/flow/component/datepicker/DatePicker.java | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index 176e9c4e437..e1e4257c28d 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -99,7 +99,10 @@ * *

* Error messages for unparsable input and constraint violations can be - * configured using the respective properties in the {@link DatePickerI18n} object. + * configured with the respective properties in the {@link DatePickerI18n} object. If you want to + * provide a single error message for all constraints, you can also use the + * {@link #setErrorMessage(String)} method. Note that error messages set with + * {@link #setErrorMessage(String)} will take priority over i18n error messages. *

* In addition to validation, constraints may also have a visual representation. * For example, dates before the minimum date appear disabled in the overlay. From 8a93c9e3d3cd829f7ecfa648aabb40e96ecfca59 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 17:21:45 +0300 Subject: [PATCH 08/32] Update vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java --- .../java/com/vaadin/flow/component/datepicker/DatePicker.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index e1e4257c28d..aaa734e1da5 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -100,7 +100,7 @@ *

* Error messages for unparsable input and constraint violations can be * configured with the respective properties in the {@link DatePickerI18n} object. If you want to - * provide a single error message for all constraints, you can also use the + * provide a single error message for all constraints, including unparsable input, you can also use the * {@link #setErrorMessage(String)} method. Note that error messages set with * {@link #setErrorMessage(String)} will take priority over i18n error messages. *

From a2ef2b3b51973667824a4d46ff3a55559a250d3b Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 18:22:52 +0400 Subject: [PATCH 09/32] format --- .../com/vaadin/flow/component/datepicker/DatePicker.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index aaa734e1da5..6e3cb65dfdd 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -99,8 +99,9 @@ * *

* Error messages for unparsable input and constraint violations can be - * configured with the respective properties in the {@link DatePickerI18n} object. If you want to - * provide a single error message for all constraints, including unparsable input, you can also use the + * configured with the respective properties in the {@link DatePickerI18n} + * object. If you want to provide a single error message for all constraints, + * including unparsable input, you can also use the * {@link #setErrorMessage(String)} method. Note that error messages set with * {@link #setErrorMessage(String)} will take priority over i18n error messages. *

From b80830985a411c388a006e57005134546ecb8f61 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 18:38:52 +0400 Subject: [PATCH 10/32] add a mention of Binder --- .../flow/component/datepicker/DatePicker.java | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index 6e3cb65dfdd..993a2c08f34 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -56,6 +56,7 @@ import com.vaadin.flow.component.shared.InputField; import com.vaadin.flow.component.shared.ValidationUtil; import com.vaadin.flow.component.shared.internal.ValidationController; +import com.vaadin.flow.data.binder.Binder; import com.vaadin.flow.data.binder.HasValidator; import com.vaadin.flow.data.binder.ValidationResult; import com.vaadin.flow.data.binder.ValidationStatusChangeEvent; @@ -103,15 +104,18 @@ * object. If you want to provide a single error message for all constraints, * including unparsable input, you can also use the * {@link #setErrorMessage(String)} method. Note that error messages set with - * {@link #setErrorMessage(String)} will take priority over i18n error messages. + * {@link #setErrorMessage(String)} will take priority over i18n error messages + * if both are set. *

* In addition to validation, constraints may also have a visual representation. * For example, dates before the minimum date appear disabled in the overlay. *

- * The constraint validation can be disabled by setting - * {@link #setManualValidation(boolean)} to true. This will allow the invalid - * state and the error message to be controlled manually using - * {@link #setInvalid(boolean)} and {@link #setErrorMessage(String)} API. + * For more complex validation that requires custom rules, consider using + * {@link Binder}. However, if Binder doesn't fit your needs and you want to + * implement fully custom validation logic, you can disable the constraint + * validation by setting {@link #setManualValidation(boolean)} to true. This + * will allow you to control the invalid state and the error message manually + * using {@link #setInvalid(boolean)} and {@link #setErrorMessage(String)} API. * * @author Vaadin Ltd */ From 64ad6ebf5a3c1d471d877ed4498a2f1e6e897728 Mon Sep 17 00:00:00 2001 From: Sergey Vinogradov Date: Wed, 14 Aug 2024 18:41:07 +0400 Subject: [PATCH 11/32] polish --- .../vaadin/flow/component/datepicker/DatePicker.java | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java index 993a2c08f34..38f2d1214dd 100644 --- a/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java +++ b/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java @@ -86,11 +86,11 @@ *

Validation

*

* Date Picker comes with a built-in validation mechanism based on constraints. - * Validation is triggered when the user attempts to apply a date whether by - * entering it manually or selecting it from the overlay, or when the date is - * updated programmatically. Validation checks if the date is parsable and - * satisfies the specified constraints. If validation fails, the component is - * marked as invalid and an error message is displayed (if one is provided). + * Validation is triggered when the user attempts to apply a date by entering it + * manually, selecting it from the overlay, etc, or when the date is updated + * programmatically. Validation checks if the date is parsable and satisfies the + * specified constraints. If validation fails, the component is marked as + * invalid and an error message is displayed (if one is provided). *

* The following constraints are supported: *