docs(input-validation):document validation mode options (#610)

* docs(input-validation):document validation mode options

* docs(inputs): Validation mode docs

* docs(input validation):updated kb and examples

* Update common-features/input-validation.md

Co-authored-by: Dimo Dimov <[email protected]>

* Update common-features/input-validation.md

Co-authored-by: Dimo Dimov <[email protected]>

* Update common-features/input-validation.md

Co-authored-by: Dimo Dimov <[email protected]>

* Update knowledge-base/textbox-validate-on-change.md

Co-authored-by: Dimo Dimov <[email protected]>

* docs(validation-modes):update

* Update components/dateinput/overview.md

Co-authored-by: Dimo Dimov <[email protected]>

* docs(input-validation):last update

Co-authored-by: Dimo Dimov <[email protected]>

Author: ntacheva

common-features/input-validation.md

@@ -11,6 +11,13 @@ position: 2
 
 The UI for Blazor suite supports and integrates seamlessly into Blazor's Forms and Validation infrastructure. All Telerik UI for Blazor Input components work out of the box when placed inside an `EditForm`, respond to `EditContext` changes and provide default invalid styles.
 
+In this article:
+
+* [Validation Basics](#validation-basics)
+* [Validation Modes for Simple Inputs](#validation-modes-for-simple-inputs)
+
+## Validation Basics
+
 To validate the Blazor inputs, you need to:
 
 1. Define a model that has the desired [Data Annotation attributes](https://docs.microsoft.com/en-us/aspnet/core/mvc/models/validation).
@@ -34,7 +41,7 @@ This article provides examples of validating the Telerik Blazor components. The
 
 >tip Telerik offers the [Form Component]({%slug form-overview%}) that lets you generate and manage forms with predefined layouts and less code.
 
-## Simple Inputs
+### Simple Inputs
 
 Simple textbox-like inputs do not have any special behavior. You need to bind them to a model field that has the desired data annotation attributes set. Such inputs are the textbox, numeric textbox and date input.
 
@@ -139,7 +146,7 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
         public DateTime? DailyScrum { get; set; }
 
         [Required(ErrorMessage = "Enter a starting time")]
-        [Range(typeof(DateTime), "29/11/2018 10:00:00", "22/12/2025 17:00:00",
+        [Range(typeof(DateTime), "11/29/2018 10:00:00", "12/22/2025 17:00:00",
             ErrorMessage = "Value for {0} must be between {1:dd MMM yyyy HH:mm} and {2:dd MMM yyyy HH:mm}")]
         public DateTime StartTime { get; set; }
 
@@ -151,8 +158,8 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
         [Range(typeof(bool), "true", "true", ErrorMessage = "Must subscribe to the newsletter")]
         public bool SubscribeToNewsletter { get; set; }
 
-        [Required(ErrorMessage="You should add a note.")]
-        [MaxLength(300, ErrorMessage ="Your notes are too long.")]
+        [Required(ErrorMessage = "You should add a note.")]
+        [MaxLength(300, ErrorMessage = "Your notes are too long.")]
         public string PersonalNotes { get; set; }
     }
 
@@ -173,7 +180,7 @@ Simple textbox-like inputs do not have any special behavior. You need to bind th
 }
 ````
 
-## DropDownList
+### DropDownList
 
 The DropDownList always has an item selected - the first item from its data source, the item corresponding to the `Value`, or the item created from the `DefaultText` the developer provides (which has the default value for the type of the Value field - for example, `0` for an `int` and `null` for an `int?` or `string`).
 
@@ -234,7 +241,7 @@ This means that for required field validation to work, the current item must hav
 }
 ````
 
-## RadioGroup
+### RadioGroup
 
 The radio group acts in a way similar to a dropdownlist - there is a collection of items that have values, and those values are used to populate a field in the model that is being validated. This lets you define the necessary data annottation attributes on the validated class. Note that required field validation needs nullable fields.
 
@@ -292,7 +299,7 @@ The radio group acts in a way similar to a dropdownlist - there is a collection
 ````
 
 
-## ComboBox
+### ComboBox
 
 The ComboBox works with the `Value` of the selected item (through its `ValueField`). This means that for required field validation to work, the current item must have a `null` value, or `AllowCustom` must be `true` and the input empty.
 
@@ -397,7 +404,7 @@ The ComboBox works with the `Value` of the selected item (through its `ValueFiel
 
 
 
-## MultiSelect
+### MultiSelect
 
 The MultiSelect has a value that is a `List` and the validation attributes must take that into account (for example, a regular expression attribute cannot work).
 
@@ -445,7 +452,7 @@ The MultiSelect has a value that is a `List` and the validation attributes must
 }
 ````
 
-## DateRangePicker
+### DateRangePicker
 
 The Date Range Picker component consists of two inputs that the user can change independently. They can choose to alter one or both, and the application cannot know their intent - they can change one to an invalid value (for example, a start date that is after the end date), but then intend to change the second input as well.
 
@@ -527,7 +534,7 @@ There is no built-in provision in the framework for validating a field value bas
 ````
 
 
-## Editor
+### Editor
 
 The Editor produces an HTML string in the field you bind its `Value` to. Thus, while the user may see a certain amount of content, the actual content may have more symbols, because the HTML tags count towards the total string length, but the user does not see them.
 
@@ -568,7 +575,7 @@ Unlike other components, the editor does not trigger form validation on every ke
 ````
 
 
-## MaskedTextbox
+### MaskedTextbox
 
 The Masked Textbox prompts the user for their input and restricts it according to its [Mask]({%slug maskedtextbox-mask-prompt%}). 
 
@@ -644,7 +651,7 @@ You may want to set the [`IncludeLiterals`]({%slug maskedtextbox-mask-prompt%}#i
 ````
 
 
-## Sliders
+### Sliders
 
 The sliders are, effectively, numeric inputs in terms of behavior and what data they provide. Thus, you can apply the standard validation rules to them.
 
@@ -713,7 +720,7 @@ The sliders are, effectively, numeric inputs in terms of behavior and what data
 ````
 
 
-## Color Palette
+### Color Palette
 
 The Color Palette component, while not an input, can work with validation so you can, for example, require that the user picks a color. Since it is not an input, it does not have an invalid state, but you can add validation messages around it.
 
@@ -748,6 +755,150 @@ The Color Palette component, while not an input, can work with validation so you
 }
 ````
 
+## Validation Modes for Simple Inputs
+
+The simple textbox-like inputs (listed below) can trigger validation at different events. You can customize that through the `ValidateOn` parameter. It takes a member of the `ValidationEvent` enum and provides the following options:
+
+* `Input` - (default) - triggers validation on each key press (`oninput`)
+* `Change` - triggers validation on confirmed value change (`OnChange`)
+
+The feature is supported by the following components treated as simple textbox-like inputs:
+
+* DateInput
+* DatePicker
+* DateTimePicker
+* MaskedTextBox
+* NumericTextBox
+* TextArea
+* TextBox
+* TimePicker
+
+>caption Configure the event triggering the input validation
+
+````CSHTML
+@using System.ComponentModel.DataAnnotations
+@* This Using is for the model class attributes only *@
+@* The Id parameters are not mandatory for validation, they just show better forms integration *@
+
+<EditForm Model="@person" OnValidSubmit="@HandleValidSubmit">
+    <DataAnnotationsValidator />
+    <ValidationSummary />
+
+    ---------- Validate OnInput -----------
+    <br />
+
+    <p class="name">
+        <label for="nameTextbox">Name:</label>
+        <TelerikTextBox @bind-Value="@person.Name" ValidateOn="@ValidationEvent.Input"
+                        Id="nameTextbox"></TelerikTextBox>
+        <ValidationMessage For="@(() => person.Name)"></ValidationMessage>
+    </p>
+    <p class="personal-notes">
+        <label for="personalNotes">Personal Notes:</label>
+        <TelerikTextArea @bind-Value="@person.PersonalNotes" ValidateOn="@ValidationEvent.Input"
+                         Id="personalNotes"></TelerikTextArea>
+        <ValidationMessage For="@(() => person.PersonalNotes)"></ValidationMessage>
+    </p>
+    <p class="phone-number">
+        <label for="phoneNumber">Phone Number:</label>
+        <TelerikMaskedTextBox @bind-Value="@person.PhoneNumber" ValidateOn="@ValidationEvent.Input"
+                              Id="phoneNumber" Mask="+1-000-000-0000" PromptPlaceholder="null"></TelerikMaskedTextBox>
+        <ValidationMessage For="@(() => person.PhoneNumber)"></ValidationMessage>
+    </p>
+
+    <br />
+    ---------- Validate OnChange -----------
+    <br />
+
+    <p class="height">
+        <label for="heightNumeric">Height (cm):</label>
+        <TelerikNumericTextBox @bind-Value="@person.Height" ValidateOn="@ValidationEvent.Change"
+                               Id="heightNumeric" />
+        <ValidationMessage For="@(() => person.Height)"></ValidationMessage>
+    </p>
+    <p class="birthday">
+        <label for="birthdayDateInput">Birthday:</label>
+        <TelerikDateInput @bind-Value="@person.Birthday" ValidateOn="@ValidationEvent.Change"
+                          Format="dd MMMM yyyy" Id="birthdayDateInput"></TelerikDateInput>
+        <ValidationMessage For="@(() => person.Birthday)"></ValidationMessage>
+    </p>
+    <p class="favorite-day">
+        <label for="favDayDatePicker">Favorite date:</label>
+        <TelerikDatePicker @bind-Value="@person.FavoriteDay" ValidateOn="@ValidationEvent.Change"
+                           Format="dd MMMM yyyy" Id="favDayDatePicker"></TelerikDatePicker>
+        <ValidationMessage For="@(() => person.FavoriteDay)"></ValidationMessage>
+    </p>
+    <p class="start-time">
+        <label for="dayStartDateTimePicker">Start time:</label>
+        <TelerikDateTimePicker @bind-Value="@person.StartTime" ValidateOn="@ValidationEvent.Change"
+                               Width="250px" Id="dayStartDateTimePicker" Format="G"></TelerikDateTimePicker>
+        <ValidationMessage For="@(() => person.StartTime)"></ValidationMessage>
+    </p>
+    <p class="daily-scrum">
+        <label for="scrumTimePicker">Daily scrum:</label>
+        <TelerikTimePicker @bind-Value="@person.DailyScrum" ValidateOn="@ValidationEvent.Change"
+                           Id="scrumTimePicker"></TelerikTimePicker>
+        <ValidationMessage For="@(() => person.DailyScrum)"></ValidationMessage>
+    </p>
+
+    <TelerikButton ButtonType="@ButtonType.Submit">Submit</TelerikButton>
+</EditForm>
+
+@code {
+    // Usually this class would be in a different file
+    public class Person
+    {
+        [Required(ErrorMessage = "Enter a name")]
+        [MinLength(3, ErrorMessage = "That name is too short")]
+        [StringLength(10, ErrorMessage = "That name is too long")]
+        public string Name { get; set; }
+
+        [Required(ErrorMessage = "You should add a note.")]
+        [MaxLength(300, ErrorMessage = "Your notes are too long.")]
+        public string PersonalNotes { get; set; }
+
+        [MinLength(10, ErrorMessage = "Enter a valid phone number")]
+        public string PhoneNumber { get; set; }
+
+        [Required(ErrorMessage = "Provide your height in centimeters")]
+        [Range(70, 300, ErrorMessage = "Enter a value between 70 and 300")]
+        public int? Height { get; set; }
+
+        [Required]
+        [Range(typeof(DateTime), "1/1/1900", "1/12/2000",
+            ErrorMessage = "Value for {0} must be between {1:dd MMM yyyy} and {2:dd MMM yyyy}")]
+        public DateTime Birthday { get; set; }
+
+        [Required]
+        [Range(typeof(DateTime), "1/1/1999", "1/12/2019",
+            ErrorMessage = "Value for {0} must be between {1:dd MMM yyyy} and {2:dd MMM yyyy}")]
+        [Display(Name = "Your Favourite Day")]
+        public DateTime FavoriteDay { get; set; }
+
+        [Required(ErrorMessage = "Enter a starting time")]
+        [Range(typeof(DateTime), "11/29/2018 10:00:00", "12/22/2025 17:00:00",
+            ErrorMessage = "Value for {0} must be between {1:dd MMM yyyy HH:mm} and {2:dd MMM yyyy HH:mm}")]
+        public DateTime StartTime { get; set; }
+
+        [Required(ErrorMessage = "The daily standup is required")]
+        [Range(typeof(DateTime), "1/1/1900 08:00:00", "1/1/1900 17:00:00",
+            ErrorMessage = "Time should be in business hours, between 8AM and 5 PM.")]
+        public DateTime? DailyScrum { get; set; }
+    }
+
+    Person person = new Person()
+    {
+        // for time pickers, the initial date value must match the date portion of the range validation rule
+        DailyScrum = new DateTime(1900, 1, 1, 1, 1, 1),
+    };
+
+    void HandleValidSubmit()
+    {
+        Console.WriteLine("OnValidSubmit");
+    }
+}
+````
+
 
 ## See Also
 

components/dateinput/overview.md

@@ -60,6 +60,8 @@ The date input provides the following features:
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 @[template](/_contentTemplates/date-inputs/format-placeholders.md#format-placeholder)
 
 ## DateTime and Nullable DateTime

components/datepicker/overview.md

@@ -71,6 +71,8 @@ The Blazor Date Picker component exposes the following features:
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 The date picker is, essentially, a [date input]({%slug components/dateinput/overview%}) and a [calendar]({%slug components/calendar/overview%}) and the properties it exposes are mapped to the corresponding properties of these two components. You can read more about their behavior in the respective components' documentation.
 
 @[template](/_contentTemplates/date-inputs/format-placeholders.md#format-placeholder)

components/datetimepicker/overview.md

@@ -74,6 +74,8 @@ The DateTimePicker component exposes the following features:
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 When using the dropdown to edit dates, you must click the "Set" button to commit the date. It is located in the Time portion of the dropdown (you will be navigated to it automatically upon selecting a date). Clicking "Cancel", or outside of the dropdown without clicking "Set", will revert the time to the original value. You can also commit a date by clicking the "NOW" button which will choose the current time.
 
 The time format specifiers in the `Format` control the tumblers available in the dropdown. For example, the `HH` specifier will result in a hour selector in a 24 hour format. If you also add the `tt` specifier, you will also get the AM/PM tumbler, but the 24 hour format will still be used. This means that you can also add several tumblers for the same time portion if the format string repeats them.

components/maskedtextbox/overview.md

@@ -81,6 +81,8 @@ To use a Telerik MaskedTextbox for Blazor:
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 
 ## Some Sample Masks
 

components/numerictextbox/overview.md

@@ -68,6 +68,8 @@ The numeric textbox provides the following features:
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 >caption Example of using a custom format strings
 
 ````CSHTML

components/textarea/overview.md

@@ -80,6 +80,8 @@ To use the Telerik TextArea in your Blazor application:
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 >caption TextArea with its most common features and symbols counter
 
 ````CSHTML

components/textbox/overview.md

@@ -99,6 +99,7 @@ for example: https://demos.telerik.com/blazor-ui/textbox/password
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
 
 ## See Also
 

components/timepicker/overview.md

@@ -70,11 +70,13 @@ The Time Picker component exposes the following features:
 * `Width` - Defines the width of the TimePicker.
 
 * `TabIndex` - maps to the `tabindex` attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the `Tab` key.
-* 
-* `Placeholder` - `string` - maps to the `placeholder` attribute of the HTML element. The `Placeholder` will appear if the component is bound to **nullable** DateTime object - `DateTime?`, but will not be rendered if the component is bound to the default value of a non-nullable DateTime object. 
+
+* `Placeholder` - `string` - maps to the `placeholder` attribute of the HTML element. The `Placeholder` will appear if the component is bound to **nullable** DateTime object - `DateTime?`, but will not be rendered if the component is bound to the default value of a non-nullable DateTime object.
 
 * Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
 
+* `ValidateOn` - configures the event that will trigger validation (if validation is enabled). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 The `Min` and `Max` properties require a `DateTime` object, but will only use the time portion from it. Thus, the date itself is not important. The hours, minutes, seconds and AM/PM portions control the range of the tumblers in the time picker dropdown. They do not impose validation/limitations on the input editing.
 
 When using the dropdown to edit dates, you must click the "Set" button to commit the date. Clicking "Cancel", or outside of the dropdown without clicking "Set", will revert the time to the original value. You can also commit a date by clicking the "NOW" button which will choose the current time.

knowledge-base/textbox-validate-on-change.md

@@ -31,6 +31,8 @@ Is there a way to disable this behaviour?
 
 We believe that firing the validation immediately makes the user experience more fluid and lets the user know about form issues quickly, which reduces frustration. Thus, we fire validation with the `ValueChanged` event.
 
+>tip Telerik UI for Blazor 2.30 adds a `ValidateOn` parameter to input components. It defines the event that triggers validation (`OnChange` or `OnInput`). Read more at [Validation Modes for Simple Inputs]({%slug common-features/input-validation%}#validation-modes-for-simple-inputs).
+
 ### Differences with standard inputs
 
 The standard inputs (such as `InputText` and `InputNumber`) use the `onchange` DOM event to change the `Value` of the model. We have chosen to use `oninput` to provide immediate feedback.