Merge form-editcontext-validation-2492 into production (#2499)

* docs(form): Enhance information about EditContext creation

* Add warning notes about EditContext and model instance

* Update _contentTemplates/common/form-validation.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

* Update components/form/validation.md

Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

---------

Co-authored-by: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Co-authored-by: Iva Stefanova Koevska-Atanasova <koevska@progress.com>

Author: 3 people

_contentTemplates/common/form-validation.md

@@ -1,7 +1,11 @@
 #note-validation
->note The Telerik Blazor validation tools provide a way to display different types of validation messages. The main benefit is consistent styling with all other Telerik Blazor components. The validation tools do not expose API or settings for specific validation logic. You should configure the desired standard or custom validation separately, and then use our UI components to display messages to the user.
+The Telerik Blazor validation tools let you match the style of your validation messages to all other Telerik Blazor components in your app. The validation tools do not expose API or settings for specific validation logic. You need to handle the validation logic separately and then use the Telerik Blazor UI components to display messages to the end user.
 #end
 
 #note-telerik-role-in-validation
 > The Telerik components for Blazor do not perform the actual validation of the model. Validation is managed by the [`EditContext`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.forms.editcontext). The role of the Telerik components is to call `EditContext` methods, subscribe to `EditContext` events, retrieve validation messages, and display them. If a validation scenario does not work as expected, check the behavior in a standard Blazor `<EditForm>` to verify if the issue is related to the Telerik components.
 #end
+
+#note-editcontext-formitem-template
+> When using the [Form `EditContext` parameter]({%slug form-overview%}#creating-blazor-form) together with [validation components]({%slug validation-tools-overview%}) or [Form item `<Template>`s]({%slug form-formitems-template%}), make sure to create the `EditContext` from the model instance, which is used by the validation components and inside the Form item templates. Otherwise, the Form will not update the correct object instance and validation will not work as expected.
+#end

components/form/formitems/template.md

@@ -28,6 +28,8 @@ When using a Form item template, the following `FormItem` parameters are ignored
 * `Id`
 * `LabelText`
 
+@[template](/_contentTemplates/common/form-validation.md#note-editcontext-formitem-template)
+
 ## Validation Messages and Styling
 
 The `FormItem` `Template` replaces all the Form item's built-in rendering, which includes validation messages and form item labels. You can use the [Telerik validation tools]({%slug validation-tools-overview%}) to display the desired validation UI, or even use the standard Blazor `ValidationMessage` component.

components/form/overview.md

@@ -16,7 +16,9 @@ The <a href = "https://demos.telerik.com/blazor-ui/form/overview" target="_blank
 ## Creating Blazor Form
 
 1. Add the `TelerikForm` tag to a razor file.
-1. Set the Form `Model` parameter to an object, or alternatively, set the `EditContext` parameter to an [`EditContext` instance](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.forms.editcontext).
+1. Bind the Form to data by using only one of the following two options:
+    * Set the Form `Model` parameter to an object.
+    * Set the `EditContext` parameter to an [`EditContext` instance](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.forms.editcontext). The object instance from which the `EditContext` is created is important, especially when using [FormItem templates]({%slug form-formitems-template%}) and [validation messages]({%slug form-validation%}).
 1. (optional) To enable [form validation]({%slug form-validation%}), add the `<FormValidation>` tag. Define a validator component inside, for example the [`DataAnnotationsValidator`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.forms.dataannotationsvalidator) that is part of .NET Core.
 
 <div class="skip-repl"></div>

components/form/validation.md

@@ -58,10 +58,14 @@ To enable validation in the Telerik Form for Blazor add the `<FormValidation>` t
 }
 ````
 
-When you provide an `EditContext` to the form, you can use its [`EnableDataAnnotationsValidation(IServiceProvider serviceProvider)`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.forms.editcontextdataannotationsextensions.enabledataannotationsvalidation?view=aspnetcore-8.0#microsoft-aspnetcore-components-forms-editcontextdataannotationsextensions-enabledataannotationsvalidation(microsoft-aspnetcore-components-forms-editcontext-system-iserviceprovider)) method to add the data annotation validation to the form, instead of using the markup. This can be useful when you will be changing the model the form is bound to at runtime, for example, when you [add a reset button]({%slug form-formitems-buttons%}#how-to-add-a-reset-clear-button-to-the-form). Alternatively, you can call this method to re-attach validation on the `Model` you pass when you change it by using the [reference to the Form component]({%slug form-overview%}#component-reference) - `TheFormReference.EditContext.EnableDataAnnotationsValidation(IServiceProvider serviceProvider)`.
+@[template](/_contentTemplates/common/form-validation.md#note-editcontext-formitem-template)
 
 @[template](/_contentTemplates/common/form-validation.md#note-validation)
 
+When you provide an `EditContext` to the form, you can use its [`EnableDataAnnotationsValidation(IServiceProvider serviceProvider)`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.forms.editcontextdataannotationsextensions.enabledataannotationsvalidation?view=aspnetcore-8.0#microsoft-aspnetcore-components-forms-editcontextdataannotationsextensions-enabledataannotationsvalidation(microsoft-aspnetcore-components-forms-editcontext-system-iserviceprovider)) method to add the data annotation validation instead of using the markup. This is useful in the following cases:
+* When the model the form is bound to changes at runtime. For example, when you [have a reset button]({%slug form-formitems-buttons%}#how-to-add-a-reset-clear-button-to-the-form).
+* When you need to re-attach the validation after changing the `Model`. In this case you need to use the [reference to the Form component]({%slug form-overview%}#component-reference)&mdash;`TheFormReference.EditContext.EnableDataAnnotationsValidation(IServiceProvider serviceProvider)`.
+
 @[template](/_contentTemplates/common/form-validation.md#note-telerik-role-in-validation)
 
 ## Validation Message Type

components/validation/overview.md

@@ -118,6 +118,8 @@ You can seamlessly integrate the validation tools with the [Form Component]({%sl
 }
 ````
 
+@[template](/_contentTemplates/common/form-validation.md#note-editcontext-formitem-template)
+
 @[template](/_contentTemplates/common/form-validation.md#note-telerik-role-in-validation)
 
 # Next Steps