chore(Grid): document templates breaking changes

_contentTemplates/grid/common-link.md

@@ -211,3 +211,7 @@ Therefore, we advise that you do not set `Locked=false` for child columns of loc
 The keyboard navigation in the multi-column headers follows the functionality of Excel.
 
 #end
+
+#using-components-in-templates
+See specifics and example in this knowledge base article: [Using Components in Grid Templates]({%slug grid-kb-using-components-in-templates%}).
+#end

components/grid/columns/command.md

@@ -219,6 +219,10 @@ The following code example demonstrates declarations and handling.
 
 ![Blazor Grid Command Column Result](images/command-column-result.png)
 
+## Using Components in Grid Command Column
+
+@[template](/_contentTemplates/grid/common-link.md#using-components-in-templates)
+
 ## See Also
 
   * [Live Demo: Grid Command Column](https://demos.telerik.com/blazor-ui/grid/editing-inline)

components/grid/hierarchy.md

@@ -119,6 +119,9 @@ The following articles and sample projects can be helpful when implementing hier
 
 * [Custom Excel Export that Includes Hierarchy](https://github.com/telerik/blazor-ui/tree/master/grid/export-to-xlsx-hierarchy)
 
+## Using Components in Grid Detail Templates
+
+@[template](/_contentTemplates/grid/common-link.md#using-components-in-templates)
 
 ## See Also
 

components/grid/templates/column-footer.md

@@ -82,6 +82,9 @@ You can use [aggregates]({%slug grid-aggregates%}) for the current field directl
 
 ![Blazor Grid Footer Template](images/footer-template.png)
 
+## Using Components in Grid Column Footer Templates
+
+@[template](/_contentTemplates/grid/common-link.md#using-components-in-templates)
 
 ## Notes
 

components/grid/templates/column-group-footer.md

@@ -79,6 +79,9 @@ When the grid is grouped, the columns can display a footer with information abou
 
 ![Blazor Grid Column Group Footer Template](images/column-group-footer-template.png)
 
+## Using Components in Grid Group Footer Templates
+
+@[template](/_contentTemplates/grid/common-link.md#using-components-in-templates)
 
 ## See Also
 

components/grid/templates/column.md

@@ -100,87 +100,7 @@ The example below shows how to:
 
 ## Using Components in Grid Column Templates
 
-The Grid optimizes the UI renders after data operations. If you are using child components inside Grid column templates, <a href="https://learn.microsoft.com/en-us/aspnet/core/blazor/components/element-component-model-relationships" target="_blank">set the `@key` attribute to these components to ensure that they always show the correct values and content after filtering, paging, and sorting</a>.
-
->caption Seting @key to child components inside a Grid column template
-<div class="skip-repl"></div>
-````RAZOR Home.razor
-@using YourAppName.Data
-
-<TelerikGrid Data="@GridData"
-             TItem="@SampleModel"
-             FilterMode="GridFilterMode.FilterRow"
-             Pageable="true"
-             PageSize="5"
-             Sortable="true">
-    <GridColumns>
-        <GridColumn Field="@nameof(SampleModel.Name)" Title="Template with Key">
-            <Template>
-                @{ var dataItem = (SampleModel)context; }
-                <Child @key="@dataItem" Model="@dataItem" Color="green" />
-            </Template>
-        </GridColumn>
-        <GridColumn Field="@nameof(SampleModel.Name)" Title="Template without Key">
-            <Template>
-                @{ var dataItem = (SampleModel)context; }
-                <Child Model="@dataItem" Color="red" />
-            </Template>
-        </GridColumn>
-    </GridColumns>
-</TelerikGrid>
-
-@code {
-    private List<SampleModel> GridData { get; set; } = new();
-
-    protected override void OnInitialized()
-    {
-        for (int i = 1; i <= 77; i++)
-        {
-            GridData.Add(new SampleModel()
-            {
-                Id = i,
-                Name = $"Name {i}"
-            });
-        }
-    }
-}
-````
-````RAZOR Child.razor
-@using YourAppName.Data
-
-Properties require @@key:
-<strong style="color: @Color; background: yellow; padding: 0 .2em;">@Foo</strong>
-
-<br />
-
-Parameters refresh:
-<strong>@Model.Id</strong>
-
-@code {
-    [Parameter]
-    public SampleModel Model { get; set; } = new();
-
-    [Parameter]
-    public string Color { get; set; } = "inherit";
-
-    private string Foo { get; set; } = string.Empty;
-
-    protected override void OnInitialized()
-    {
-        Foo = Model.Id.ToString();
-    }
-}
-````
-````C# SampleModel.cs
-namespace YourAppName.Data
-{
-    public class SampleModel
-    {
-        public int Id { get; set; }
-        public string Name { get; set; } = string.Empty;
-    }
-}
-````
+@[template](/_contentTemplates/grid/common-link.md#using-components-in-templates)
 
 ## See Also
 

components/grid/templates/row.md

@@ -62,6 +62,10 @@ Render the entire row with your own code and logic
 
 ![Blazor Grid Row Template](images/row-template.png)
 
+## Using Components in Grid Row Templates
+
+@[template](/_contentTemplates/grid/common-link.md#using-components-in-templates)
+
 
 ## See Also
 

knowledge-base/grid-using-components-in-templates.md

@@ -0,0 +1,186 @@
+---
+title: Using Components in Grid Templates
+description: How to use my custom component in the various UI for Blazor Grid templates
+type: how-to
+page_title: Using Components in Grid Templates
+slug: grid-kb-using-components-in-templates
+position: 
+tags: 
+ticketid:
+res_type: kb
+---
+
+## Environment
+
+<table>
+    <tbody>
+        <tr>
+            <td>Product</td>
+            <td>Grid for Blazor</td>
+        </tr>
+    </tbody>
+</table>
+
+## Description
+
+I'm trying to render my own component in the Column Template of the Grid. However, the component does not show correct values after filtering, paging or sorting.
+
+How to properly use components in Grid templates?
+
+## Solution
+
+The Grid optimizes the UI renders after data operations. If you are using child components inside Grid column templates, [set the `@key` attribute to these components to ensure that they always show the correct values and content after filtering, paging, and sorting](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/element-component-model-relationships?view=aspnetcore-9.0).
+
+This applies to the following Grid elements:
+
+* [CommandColumn]({%slug components/grid/columns/command%})
+* [DetailTemplate]({%slug components/grid/features/hierarchy%})
+* [FooterTemplate]({%slug grid-templates-column-footer%})
+* [GroupFooterTemplate]({%slug grid-templates-column-group-footer%})
+* [RowTemplate]({%slug grid-templates-row%})
+* [Template]({%slug grid-templates-column%})
+
+>caption Setting @key to child components inside Grid templates
+
+<div class="skip-repl"></div>
+````RAZOR Home.razor
+@using YourAppName.Data
+
+<ul>
+    <li>Filter and sort the Grid to see the difference between the two columns.</li>
+    <li>Group the Grid by the first column to test the GroupFooterTemplate.</li>
+    <li>Uncomment the RowTemplate to see it in action. </li>
+</ul>
+
+<TelerikGrid Data="@GridData"
+             EditMode="@GridEditMode.Inline"
+             FilterMode="GridFilterMode.FilterRow"
+             Groupable="true"
+             Pageable="true"
+             PageSize="5"
+             Sortable="true">
+    <GridAggregates>
+        <GridAggregate Field="@nameof(SampleModel.Id)" FieldType="@typeof(int)" Aggregate="@GridAggregateType.Max" />
+    </GridAggregates>
+    <GridColumns>
+        <GridColumn Field="@nameof(SampleModel.Id)" Title="Template with Key">
+            <Template>
+                @{
+                    var dataItem = (SampleModel)context;
+                }
+                Direct: @dataItem.Id
+                <br />
+                In child:
+                <Child @key="@dataItem" Model="@dataItem" Color="green" />
+            </Template>
+            <FooterTemplate>
+                Direct: @context.Max
+                <br />
+                In child:
+                <Child Model="@( new SampleModel() { Id = Convert.ToInt32(context.Max) })" Color="green" />
+            </FooterTemplate>
+            <GroupFooterTemplate>
+                Direct: @context.Max
+                <br />
+                In child:
+                <Child Model="@( new SampleModel() { Id = Convert.ToInt32(context.Max) })" Color="green" />
+            </GroupFooterTemplate>
+        </GridColumn>
+        <GridColumn Field="@nameof(SampleModel.Name)" Title="Template without Key">
+            <Template>
+                @{
+                    var dataItem = (SampleModel)context;
+                }
+                Direct: @dataItem.Id
+                <br />
+                In child:
+                <Child Model="@dataItem" Color="red" />
+            </Template>
+        </GridColumn>
+        <GridCommandColumn>
+            <GridCommandButton Command="Edit" Icon="@SvgIcon.Pencil" />
+            <GridCommandButton Command="Cancel" Icon="@SvgIcon.Cancel" ShowInEdit="true" />
+            @{
+                var dataItem = (SampleModel)context;
+            }
+            Direct: @dataItem.Id
+            <br />
+            In child:
+            <Child @key="@dataItem" Model="@dataItem" />
+        </GridCommandColumn>
+    </GridColumns>
+   @*  <RowTemplate>
+        @{
+            var dataItem = (SampleModel)context;
+        }
+        <td>
+            Direct: @dataItem.Id
+            <br />
+            In child:
+            <Child @key="@dataItem" Model="@dataItem" />
+        </td>
+        <td>@dataItem.Name</td>
+    </RowTemplate> *@
+    <DetailTemplate>
+        @{
+            var masterItem = (SampleModel)context;
+        }
+        <p><strong>DetailTemplate</strong></p>
+        Direct: @masterItem.Id
+        <br />
+        In child: <Child @key="@masterItem" Model="@masterItem" />
+    </DetailTemplate>
+</TelerikGrid>
+
+@code {
+    private List<SampleModel> GridData { get; set; } = new();
+
+    protected override void OnInitialized()
+    {
+        for (int i = 1; i <= 77; i++)
+        {
+            GridData.Add(new SampleModel()
+                {
+                    Id = i,
+                    Name = $"Name {i}"
+                });
+        }
+    }
+}
+````
+````RAZOR Child.razor
+@using YourAppName.Data
+
+Properties require @@key:
+<strong style="color: @Color; background: yellow; padding: 0 .2em;">@Foo</strong>
+
+<br />
+
+Parameters refresh:
+<strong>@Model.Id</strong>
+
+@code {
+    [Parameter]
+    public SampleModel Model { get; set; } = new();
+
+    [Parameter]
+    public string Color { get; set; } = "inherit";
+
+    private string Foo { get; set; } = string.Empty;
+
+    protected override void OnInitialized()
+    {
+        Foo = Model.Id.ToString();
+    }
+}
+````
+````C# SampleModel.cs
+namespace YourAppName.Data
+{
+    public class SampleModel
+    {
+        public int Id { get; set; }
+        public string Name { get; set; } = string.Empty;
+    }
+}
+````

upgrade/breaking-changes/7-0-0.md

@@ -44,7 +44,7 @@ The obsolete `ClearButton` parameter is removed. Use `ShowClearButton` instead.
 * The obsolete `AutoFitColumns()` method is removed. Use `AutoFitColumnsAsync()` instead.
 * The obsolete `AutoFitAllColumns()` method is removed. Use `AutoFitAllColumnsAsync()` instead.
 * When using [grouping and `OnRead`]({%slug components/grid/manual-operations%}#grouping-with-onread), casting `DataSourceResult.Data` to a list of objects (`.Cast<object>()`) is no longer needed.
-* [Components in a Grid column `<Template>` require a `@key`]({%slug grid-templates-column%}#using-components-in-grid-column-templates) in order to display correct values after data operations like sorting, filtering, paging, and others.
+* [Components in some Grid templates require a `@key`]({%slug grid-kb-using-components-in-templates%}) in order to display correct values after data operations like sorting, filtering, paging, and others.
 
 >caption Using custom components in Grid column templates up to version 6.2.0 and after version 7.0.0