Skip to content

Commit 3d80e62

Browse files
dimodintacheva
dimodi
and
ntacheva
authored
docs(grid): Document breaking change in column template component usage (#2620)
* docs(grid): Document breaking change in column template component usage * Update components/grid/templates/column.md Co-authored-by: Nadezhda Tacheva <[email protected]> --------- Co-authored-by: Nadezhda Tacheva <[email protected]>
1 parent 753706a commit 3d80e62

File tree

2 files changed

+133
-5
lines changed

2 files changed

+133
-5
lines changed

‎components/grid/templates/column.md

Lines changed: 99 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,26 @@ position: 5
1010

1111
# Column Template
1212

13-
By default, each Grid cell renders the value of the respective column `Field` of the current data item (row). You can change this behavior by using the `Template` of the column and adding your own content or logic.
13+
By default, each Grid cell renders the value of the respective column `Field` of the current data item (row). You can change this behavior by using a column `Template` and adding your own content or logic.
1414

15-
The column template (the `<Template>` tag under the column definition) is what the Grid uses to show the "view" representation of the cell. This also includes a column that is marked as `Editable="false"` and is in edit mode.
15+
## Basics
16+
17+
To define a column template, use a `<Template>` tag inside the `<GridColumn>` tag. The Grid uses the defined `Template` to show the "view" representation of all cells in that column. This also includes cells from [columns that are marked as `Editable="false"`]({%slug components/grid/columns/bound%}#data-operations), while the cells' parent row is in [inline edit mode]({%slug components/grid/editing/inline%}).
18+
19+
Visual Studio tends to autocomplete the `<Template>` tag with a lowercase `t` which breaks the template logic and does not allow you to access the `context`. Ensure the `Template` tag uses a capital `T`.
20+
21+
### Template Context
22+
23+
The Grid column template exposes a `context` variable, which is the respective item from the Grid data collection. Cast the `context` to your Grid model type in order to access and use its properties. [Rename the `context` variable when using nested templates, for example a Grid column `Template` inside a Grid `DetailTemplate`]({%slug nest-renderfragment%}).
1624

1725
>tip If you only want to format numbers, dates, enums, you can do so with the [DisplayFormat feature]({%slug grid-columns-displayformat%}) without the need to declare a template.
1826
27+
## Example
28+
1929
The example below shows how to:
2030

21-
* Set the `Template` (make sure to use the tag with a capital `T`. The Visual Studio autocomplete tends to use the lowercase `t` which breaks the template logic and does not allow you to access the context).
22-
* Access the template `context`, which is a data item object from the Grid `Data`. You need to cast the `context` to access the data item properties.
31+
* Define a Grid column `Template`.
32+
* Cast and access the template `context`.
2333
* Render HTML or nest components in the column template.
2434
* Use inline or multi-line template.
2535

@@ -86,7 +96,91 @@ The example below shows how to:
8696
}
8797
````
8898

89-
>tip The above example renders read-only checkboxes to display boolean values. It is possible to [use checkboxes in display mode and directly change the underlying data source values]({%slug grid-kb-checkbox-editing%}). This can make boolean value editing faster, because the Grid doesn't go into edit mode.
99+
>tip The above example renders read-only checkboxes to display boolean values. You can also [use checkboxes in display mode and directly change the underlying data source values]({%slug grid-kb-checkbox-editing%}). This can make boolean value editing faster, because the Grid doesn't go into edit mode.
100+
101+
## Using Components in Grid Column Templates
102+
103+
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>.
104+
105+
>caption Seting @key to child components inside a Grid column template
106+
<div class="skip-repl"></div>
107+
````Home.razor
108+
@using YourAppName.Data
109+
110+
<TelerikGrid Data="@GridData"
111+
TItem="@SampleModel"
112+
FilterMode="GridFilterMode.FilterRow"
113+
Pageable="true"
114+
PageSize="5"
115+
Sortable="true">
116+
<GridColumns>
117+
<GridColumn Field="@nameof(SampleModel.Name)" Title="Template with Key">
118+
<Template>
119+
@{ var dataItem = (SampleModel)context; }
120+
<Child @key="@dataItem" Model="@dataItem" Color="green" />
121+
</Template>
122+
</GridColumn>
123+
<GridColumn Field="@nameof(SampleModel.Name)" Title="Template without Key">
124+
<Template>
125+
@{ var dataItem = (SampleModel)context; }
126+
<Child Model="@dataItem" Color="red" />
127+
</Template>
128+
</GridColumn>
129+
</GridColumns>
130+
</TelerikGrid>
131+
132+
@code {
133+
private List<SampleModel> GridData { get; set; } = new();
134+
135+
protected override void OnInitialized()
136+
{
137+
for (int i = 1; i <= 77; i++)
138+
{
139+
GridData.Add(new SampleModel()
140+
{
141+
Id = i,
142+
Name = $"Name {i}"
143+
});
144+
}
145+
}
146+
}
147+
````
148+
````Child.razor
149+
@using YourAppName.Data
150+
151+
Properties require @@key:
152+
<strong style="color: @Color; background: yellow; padding: 0 .2em;">@Foo</strong>
153+
154+
<br />
155+
156+
Parameters refresh:
157+
<strong>@Model.Id</strong>
158+
159+
@code {
160+
[Parameter]
161+
public SampleModel Model { get; set; } = new();
162+
163+
[Parameter]
164+
public string Color { get; set; } = "inherit";
165+
166+
private string Foo { get; set; } = string.Empty;
167+
168+
protected override void OnInitialized()
169+
{
170+
Foo = Model.Id.ToString();
171+
}
172+
}
173+
````
174+
````SampleModel.cs
175+
namespace YourAppName.Data
176+
{
177+
public class SampleModel
178+
{
179+
public int Id { get; set; }
180+
public string Name { get; set; } = string.Empty;
181+
}
182+
}
183+
````
90184

91185
## See Also
92186

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,40 @@ The obsolete `ClearButton` parameter is removed. Use `ShowClearButton` instead.
4444
* The obsolete `AutoFitColumns()` method is removed. Use `AutoFitColumnsAsync()` instead.
4545
* The obsolete `AutoFitAllColumns()` method is removed. Use `AutoFitAllColumnsAsync()` instead.
4646
* 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.
47+
* [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.
48+
49+
>caption Using custom components in Grid column templates up to version 6.2.0 and after version 7.0.0
50+
51+
<table>
52+
<thead><tr>
53+
<th>UI for Blazor 6.2.0</th>
54+
<th>UI for Blazor 7.0.0</th>
55+
</tr></thead>
56+
<tbody>
57+
<tr>
58+
<td style="vertical-align:top">
59+
<pre><code>
60+
&lt;GridColumn&gt;
61+
&lt;Template&gt;
62+
@{ var dataItem = (GridModel)context; }
63+
&lt;ChildComponent /&gt;
64+
&lt;/Template&gt;
65+
&lt;/GridColumn&gt;
66+
</code></pre>
67+
</td>
68+
<td style="vertical-align:top">
69+
<pre><code>
70+
&lt;GridColumn&gt;
71+
&lt;Template&gt;
72+
@{ var dataItem = (GridModel)context; }
73+
&lt;ChildComponent <strong>@key="@dataItem"</strong> /&gt;
74+
&lt;/Template&gt;
75+
&lt;/GridColumn&gt;
76+
</code></pre>
77+
</td>
78+
</tr>
79+
</tbody>
80+
</table>
4781

4882
## TextArea
4983

0 commit comments

Comments
 (0)