From efb1b6a8134b627d981e91512fa6e3cdc6c655d4 Mon Sep 17 00:00:00 2001
From: Dimo Dimov <961014+dimodi@users.noreply.github.com>
Date: Thu, 7 Nov 2024 16:52:23 +0200
Subject: [PATCH] docs(form): Enhance information about EditContext creation
 (#2492)

* 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: Iva Stefanova Koevska-Atanasova <koevska@progress.com>
---
 _contentTemplates/common/form-validation.md | 6 +++++-
 components/form/formitems/template.md       | 2 ++
 components/form/overview.md                 | 4 +++-
 components/form/validation.md               | 6 +++++-
 components/validation/overview.md           | 2 ++
 5 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/_contentTemplates/common/form-validation.md b/_contentTemplates/common/form-validation.md
index 5367150957..b9d6f8cf51 100644
--- a/_contentTemplates/common/form-validation.md
+++ b/_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
diff --git a/components/form/formitems/template.md b/components/form/formitems/template.md
index 58a4f232fc..09f36db946 100644
--- a/components/form/formitems/template.md
+++ b/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.
diff --git a/components/form/overview.md b/components/form/overview.md
index 27b7f7b406..d6fcb52f60 100644
--- a/components/form/overview.md
+++ b/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>
diff --git a/components/form/validation.md b/components/form/validation.md
index ee8fb4803b..e8183d9cc5 100644
--- a/components/form/validation.md
+++ b/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
diff --git a/components/validation/overview.md b/components/validation/overview.md
index 035990e7b9..56dca3eb3e 100644
--- a/components/validation/overview.md
+++ b/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