docs(inputs): revamp events articles

components/dateinput/events.md

@@ -12,139 +12,119 @@ position: 20
 
 This article explains the events available in the Telerik DateInput for Blazor:
 
+* [OnBlur](#onblur)
 * [OnChange](#onchange)
 * [ValueChanged](#valuechanged)
-* [OnBlur](#onblur)
-
-## OnChange
 
-The `OnChange` event represents a user action - confirmation of the current value. It fires when the user presses `Enter` in the input, or when the input loses focus.
+## OnBlur
 
-The date input is a generic component, so you must provide either a `Value`, or a type to the `T` parameter of the component.
+The `OnBlur` event fires when the component loses focus.
 
->caption Handle OnChange
+>caption Handle the OnBlur event
 
 ````CSHTML
+@* You do not have to use OnChange to react to loss of focus *@
+
 @result
-<br />
 
-<TelerikDateInput T="DateTime" OnChange="@MyOnChangeHandler"></TelerikDateInput>
+<TelerikDateInput @bind-Value="@DateInputValue"
+                  OnBlur="@OnBlurHandler">
+</TelerikDateInput>
+
+@code{
+    private string result = string.Empty;
 
-@code {
-    string result;
+    private DateTime? DateInputValue { get; set; } = DateTime.Now;
 
-    private void MyOnChangeHandler(object theUserInput)
+    private void OnBlurHandler()
     {
-        // the handler receives an object that you may need to cast to the type of the component
-        // if you do not provide a Value, you must provide the Type parameter to the component
-        result = string.Format("The user entered: {0:dd/MMM/yyyy}", (DateTime)theUserInput);
+        result = string.Format("BLUR fired, current value is {0:dd/MMM/yyyy}.", DateInputValue);
     }
 }
 ````
 
 @[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
 
->tip The `OnChange` event is a custom event and does not interfere with bindings, so you can use it together with models and forms.
+
+## OnChange
+
+The `OnChange` event represents a user action that confirms the current value. It fires when the user presses `Enter` in the input or when the input loses focus.
+
+| Validation of input | Event handler argument | Nullable of not `Value` parameter |
+| --- | --- | --- |
+| Invalid input | `Null` | Nullable |
+| Invalid input | Default value of the `Value` parameter | Not nullable |
+| Valid input | The valid input as an object that needs to be cast to the type of the component | Nullable or not nullable |
+
+The DateInput is a generic component, so you must either provide a `Value`, or a type to the `T` parameter of the component.
 
 >caption Handle OnChange and use two-way binding
 
 ````CSHTML
 @result
 <br />
-model value: @theInputValue
+model value: @DateInputValue
 <br />
 
-<TelerikDateInput @bind-Value="@theInputValue" OnChange="@MyOnChangeHandler"></TelerikDateInput>
+<TelerikDateInput @bind-Value="@DateInputValue" 
+                  OnChange="@MyOnChangeHandler">
+</TelerikDateInput>
 
 @code {
-    string result;
+    private string result = string.Empty;
 
-    DateTime? theInputValue { get; set; } = DateTime.Now;
+    private DateTime? DateInputValue { get; set; } = DateTime.Now;
 
-    private void MyOnChangeHandler(object theUserInput)
+    private void MyOnChangeHandler(object userInput)
     {
-        // the handler receives an object that you may need to cast to the type of the component
         // if you do not provide a Value, you must provide the Type parameter to the component
-        result = string.Format("The user entered: {0:dd/MMM/yyyy}", (theUserInput as DateTime?).Value);
+        result = string.Format("The user entered: {0:dd/MMM/yyyy}", (DateTime)userInput);
     }
 }
 ````
 
-## ValueChanged
-
-The `ValueChanged` event fires upon every change (for example, keystroke) in the input.
-
->caption Handle ValueChanged
-
-````CSHTML
-@result
-<br />
+@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
 
-<TelerikDateInput ValueChanged="@( (DateTime d) => MyValueChangeHandler(d) )"></TelerikDateInput>
+>tip The `OnChange` event is a custom event and does not interfere with bindings, so you can use it together with models and forms.
 
-@code {
-    string result;
 
-    private void MyValueChangeHandler(DateTime theUserInput)
-    {
-        result = string.Format("The user entered: {0}", theUserInput);
-    }
-}
-````
+## ValueChanged
 
-@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
+The `ValueChanged` event fires on every typing in the input and if the input is valid. The handler will receive the valid input.
 
-@[template](/_contentTemplates/common/issues-and-warnings.md#valuechanged-lambda-required)
+The event also fires if the input is invalid and when the input loses focus and the `Value` parameter is nullable. The handler will receive a `null` argument.
 
 >caption Handle ValueChanged and provide initial value
 
 ````CSHTML
 @result
 <br />
-model value: @theInputValue
+model value: @DateInputValue
 <br />
 
-<TelerikDateInput Value="@theInputValue" ValueChanged="@( (DateTime d) => MyValueChangeHandler(d) )"></TelerikDateInput>
+<TelerikDateInput Value="@DateInputValue" 
+                  ValueChanged="@( (DateTime d) => MyValueChangeHandler(d) )">
+</TelerikDateInput>
 
 @code {
-    string result;
+    private string result = string.Empty;
 
-    DateTime theInputValue { get; set; } = DateTime.Now;
+    private DateTime DateInputValue { get; set; } = DateTime.Now;
 
-    private void MyValueChangeHandler(DateTime theUserInput)
+    private void MyValueChangeHandler(DateTime userInput)
     {
-        result = string.Format("The user entered: {0:dd/MMM/yyyy}", theUserInput);
+        result = string.Format("The user entered: {0:dd/MMM/yyyy}", userInput);
 
         //you have to update the model manually because handling the ValueChanged event does not let you use @bind-Value
-        theInputValue = theUserInput;
+        DateInputValue = userInput;
     }
 }
 ````
 
+@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
 
+@[template](/_contentTemplates/common/issues-and-warnings.md#valuechanged-lambda-required)
 
-## OnBlur
-
-The `OnBlur` event fires when the component loses focus.
-
->caption Handle the OnBlur event
-
-````CSHTML
-@* You do not have to use OnChange to react to loss of focus *@
-
-<TelerikDateInput @bind-Value="@TheDate"
-                  OnBlur="@OnBlurHandler">
-</TelerikDateInput>
-
-@code{
-    async Task OnBlurHandler()
-    {
-        Console.WriteLine($"BLUR fired, current value is {TheDate}.");
-    }
-
-    DateTime? TheDate { get; set; } = DateTime.Now;
-}
-````
 
 ## See Also