Skip to content

Commit e0a694d

Browse files
ntachevamarin-bratanov
ntacheva
and
marin-bratanov
authored
docs(componens-with-observable-data) (#255)
* docs(multiselect-observable-data):draft version of the article * docs(mustiselect-observable-data):minor tweak to clear the input after adding the value to the Multiselect options * chore(multiselect, autocomplete):added draft articles for refreshing data, added template and links from observable data article * docs(autocomplete, combobox, dropdownlist, multiselect): added articles for components' usage with observable data * chore(dropdowns-observable-data): minor improvements as per comments * docs(grid, dropdowns): added article for grid-refresh-data + some improvements on dropdowns--refresh data * docs(listview,treeview):added articles for refreshing data * docs(menu, drawer):added articles for refresh data + some small changes * docs(context-menu, scheduler):added articles for refresh data * chore(common): minor improvement on h1 * chore(grid): see also link[Force a Grid to Refresh]({%slug grid-force-refresh%}) Co-authored-by: Nadezhda Tacheva <[email protected]> Co-authored-by: Marin Bratanov <[email protected]>
1 parent 097904a commit e0a694d

File tree

14 files changed

+2245
-25
lines changed

14 files changed

+2245
-25
lines changed

‎_contentTemplates/common/observable-data.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#intro
2+
The most common reason you would use an ObservableCollection is to make a component (like a grid, treeview, treelist, dropdown) change or react when you change that collection.
3+
4+
When you want to refresh the component data source like that, there are two important framework behaviors you need to be aware of - when ObservableCollection instances fire events, and how to refresh the data of a component when it is not an observable collection.
5+
#end
6+
7+
#observable-data
8+
Databound components can benefit from live data - when the data source collection changes, the components should update to reflect that change. Most data-bound components in the Telerik UI for Blazor suite implement such functionality.
9+
10+
When the `Data` of the component is a collection that implements the `INotifyCollectionChanged` interface (such as `ObservableCollection`), the Telerik components subscribe to its `CollectionChanged` event to update. This means that adding items, removing items, or clearing the collection updates the components (its `.Add()`, `.Remove()` and `.Clear()` methods).
11+
12+
The Observable collections fire the `CollectionChanged` event only when their `Add`, `Remove` and `Clear` methods are called. They do not fire it when you change the value of a field of one of their elements.
13+
#end
14+
15+
#refresh-data
16+
In Blazor, the framework will fire the `OnParametersSet` event of a child component (which is how child components can react to outside changes) only when it can detect a change in the object it receives through the corresponding parameter (like `Data` for the data sources of Telerik components). This detection works as follows:
17+
18+
* For primitive types (such as numbers, strings), this happens when their value changes.
19+
20+
* For complex types (such as data collections like `List`, or any `IEnumerable`, and application-specific models/objects), this happens when the object reference changes.
21+
22+
Thus, you would usually need to create a `new` reference for the view-model field (such as `TreeViewData = new List<MyTreeViewItem>(theUpdatedDataCollection);`) when you want the component to update.
23+
#end
24+
25+
#tip-for-new-collection
26+
>note If you need to add/remove many items to/from the collection, consider creating a new collection and provide its reference to the data parameter. Thus, the component will re-render only once (when the data collection reference is changed) instead of re-rendering multiple times in response to the Add/Remove events.
27+
#end

‎common-features/observable-data.md‎

Lines changed: 33 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -8,51 +8,59 @@ published: True
88
position: 1
99
---
1010

11-
# Observable Data
11+
# Observable Data and Refresh Data
1212

13-
Databound components can benefit from live data - when the data source collection changes, the components should update to reflect that change. Most data-bound components in the Telerik UI for Blazor suite implement such functionality.
13+
@[template](/_contentTemplates/common/observable-data.md#intro)
1414

15-
When the `Data` of the component is a collection that implements the `INotifyCollectionChanged` interface (such as `ObservableCollection`), the Telerik components subscribe to its `CollectionChanged` event to update. This means that adding items, removing items, or clearing the collection updates the components (its `.Add()`, `.Remove()` and `.Clear()` methods).
15+
In this article:
16+
* [Observable data](#observable-data)
17+
* [Refresh Data](#refresh-data)
18+
* [Telerik components that support Observable Data](#telerik-components-that-support-observable-data)
19+
* [Telerik components that will support Observable Data in a future release](#telerik-components-that-will-support-observable-data-in-a-future-release)
1620

17-
The following components support observable data for their `Data` parameter:
21+
## Observable Data
22+
23+
@[template](/_contentTemplates/common/observable-data.md#observable-data)
24+
25+
26+
## Refresh Data
1827

19-
* AutoComplete
28+
@[template](/_contentTemplates/common/observable-data.md#refresh-data)
29+
30+
31+
## Telerik components that support Observable Data
32+
33+
The following components support observable data for their `Data` parameter:
2034

21-
* ComboBox
35+
* [AutoComplete]({%slug autocomplete-refresh-data%})
2236

23-
* DropDownList
37+
* [ComboBox]({%slug combobox-refresh-data%})
2438

25-
* [Grid](https://demos.telerik.com/blazor-ui/grid/observable-data)
39+
* [DropDownList]({%slug dropdownlist-refresh-data%})
2640

27-
* ListView
41+
* [Grid documentation]({%slug grid-refresh-data%}), [live demo](https://demos.telerik.com/blazor-ui/grid/observable-data)
2842

29-
* MultiSelect
43+
* [ListView]({%slug listview-refresh-data%})
3044

31-
* TreeList
45+
* [MultiSelect]({%slug multiselect-refresh-data%})
3246

33-
* TreeView
47+
* [TreeList]({%slug treelist-refresh-data%})
3448

35-
The Scheduler, Menu, Drawer, ContextMenu will receive this feature in a future release.
49+
* [TreeView]({%slug treeview-refresh-data%})
3650

37-
## Refresh Data
3851

39-
The most common reason you would use an ObservableCollection is to make a component (like a grid, treeview, treelist, dropdown) change or react when you change that collection.
52+
## Telerik components that will support Observable Data in a future release
4053

41-
When you want to refresh the component data source like that, there are two important framework behaviors you need to be aware of:
54+
The following components will receive this feature in a future release. You can currently refresh their Data by creating a [New collection reference](#refresh-data).
4255

43-
* Observable collections fire the `CollectionChanged` event (which the Telerik components subscribe to) only when their `Add`, `Remove` and `Clear` methods are called.
56+
* [Scheduler]({%slug scheduler-refresh-data%})
4457

45-
They do not fire it when you change the value of a field of one of their elements.
58+
* [Menu]({%slug menu-refresh-data%})
4659

47-
* In Blazor, the framework will fire the `OnParametersSet` event of a child component (which is how child components can react to outside changes) only when it can detect a change in the object it receives through the corresponding parameter (like `Data` for the data sources of Telerik components). This detection works as follows:
60+
* [Drawer]({%slug drawer-refresh-data%})
4861

49-
* For primitive types (such as numbers, strings), this happens when their value changes.
50-
51-
* For complex types (such as data collections like `List`, or any `IEnumerable`, and application-specific models/objects), this happens when the object reference changes.
52-
53-
Thus, you would usually need to create a `new` reference for the view-model field (such as `TreeViewData = new List<MyTreeViewItem>(theUpdatedDataCollection);`) when you want the component to update.
62+
* [ContextMenu]({%slug context-menu-refresh-data%})
5463

55-
You can find some more explanations and examples for the Grid component in the [Force a Grid to Refresh]({%slug grid-force-refresh%}) Knowledge Base article.
5664

5765
## See Also
5866

‎components/autocomplete/refresh-data.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
title: Refresh Data
3+
page_title: Autocomplete Refresh Data
4+
description: Refresh Autocomplete Data using Observable Data or creating a new Collection reference.
5+
slug: autocomplete-refresh-data
6+
tags: telerik,blazor,autocomplete,observable,data,new,collection
7+
published: True
8+
position: 15
9+
---
10+
11+
# Autocomplete - Refresh Data
12+
13+
14+
@[template](/_contentTemplates/common/observable-data.md#intro)
15+
16+
In this article:
17+
- [Observable Data](#observable-data)
18+
- [New Collection Reference](#new-collection-reference)
19+
20+
## Observable Data
21+
22+
@[template](/_contentTemplates/common/observable-data.md#observable-data)
23+
24+
25+
>caption Bind the Autocomplete component to an ObservableCollection, so it can react to collection changes.
26+
27+
````CSHTML
28+
@* Add/remove a suggestion to see how the Autocomplete reacts to the change. *@
29+
30+
@using System.Collections.ObjectModel
31+
32+
<h4>Add suggestion</h4>
33+
<TelerikTextBox @bind-Value="@ValuetoAdd"></TelerikTextBox>
34+
35+
<TelerikButton OnClick="@AddSuggestion">Add suggestion</TelerikButton>
36+
<br />
37+
38+
<h4>Remove the last suggestion</h4>
39+
<TelerikButton OnClick="@RemoveSuggestion">Remove the last suggestion</TelerikButton>
40+
<br />
41+
42+
<h4>Autocomplete suggestions: @Suggestions.Count</h4>
43+
<br />
44+
45+
<TelerikAutoComplete Data="@Suggestions" ValueField="@( nameof(SuggestionsModel.Suggestion) )" @bind-Value="@TheValue" />
46+
47+
@code{
48+
string TheValue { get; set; }
49+
50+
string ValuetoAdd { get; set; }
51+
52+
void AddSuggestion()
53+
{
54+
if (!string.IsNullOrWhiteSpace(ValuetoAdd))
55+
{
56+
Suggestions.Add(
57+
new SuggestionsModel { Suggestion = ValuetoAdd, SomeOtherField = Suggestions.Count + 1 }
58+
);
59+
ValuetoAdd = string.Empty;
60+
}
61+
}
62+
63+
void RemoveSuggestion()
64+
{
65+
if (Suggestions.Count > 0)
66+
{
67+
Suggestions.RemoveAt(Suggestions.Count - 1);
68+
}
69+
}
70+
71+
ObservableCollection<SuggestionsModel> Suggestions { get; set; } = new ObservableCollection<SuggestionsModel>
72+
{
73+
new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 },
74+
new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 },
75+
new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 }
76+
};
77+
78+
public class SuggestionsModel
79+
{
80+
public string Suggestion { get; set; }//the auto complete needs only the string field
81+
public int SomeOtherField { get; set; }
82+
}
83+
}
84+
````
85+
86+
@[template](/_contentTemplates/common/observable-data.md#tip-for-new-collection)
87+
88+
## New Collection Reference
89+
90+
@[template](/_contentTemplates/common/observable-data.md#refresh-data)
91+
92+
>caption Create new collection reference to refresh the Autocomplete data.
93+
94+
````CSHTML
95+
@* Add/remove a suggestion to see how the Autocomplete reacts to the change. *@
96+
97+
<h4>Add suggestion</h4>
98+
<TelerikTextBox @bind-Value="@ValuetoAdd"></TelerikTextBox>
99+
100+
<TelerikButton OnClick="@AddSuggestion">Add suggestion</TelerikButton>
101+
<br />
102+
103+
<h4>Remove the last suggestion</h4>
104+
<TelerikButton OnClick="@RemoveSuggestion">Remove the last suggestion</TelerikButton>
105+
<br />
106+
107+
<h4>Load new collection</h4>
108+
<TelerikButton OnClick="@LoadNewData">Load data</TelerikButton>
109+
<br />
110+
111+
<h4>Autocomplete suggestions: @Suggestions.Count</h4>
112+
<br />
113+
114+
<TelerikAutoComplete Data="@Suggestions" ValueField="@( nameof(SuggestionsModel.Suggestion) )" @bind-Value="@TheValue" />
115+
116+
@code{
117+
string TheValue { get; set; }
118+
119+
string ValuetoAdd { get; set; }
120+
121+
void AddSuggestion()
122+
{
123+
if (!string.IsNullOrWhiteSpace(ValuetoAdd))
124+
{
125+
Suggestions.Add(
126+
new SuggestionsModel { Suggestion = ValuetoAdd, SomeOtherField = Suggestions.Count + 1 }
127+
);
128+
Suggestions = new List<SuggestionsModel>(Suggestions);
129+
ValuetoAdd = string.Empty;
130+
}
131+
}
132+
133+
void RemoveSuggestion()
134+
{
135+
if (Suggestions.Count > 0)
136+
{
137+
Suggestions.RemoveAt(Suggestions.Count - 1);
138+
Suggestions = new List<SuggestionsModel>(Suggestions);
139+
}
140+
}
141+
142+
void LoadNewData()
143+
{
144+
var newData = new List<SuggestionsModel>
145+
{
146+
new SuggestionsModel { Suggestion = "fourth", SomeOtherField = 4 },
147+
new SuggestionsModel { Suggestion = "fifth", SomeOtherField = 5 },
148+
new SuggestionsModel { Suggestion = "sixth", SomeOtherField = 6 }
149+
};
150+
151+
Suggestions = new List<SuggestionsModel>(newData);
152+
153+
Console.WriteLine("New data collection loaded.");
154+
}
155+
156+
List<SuggestionsModel> Suggestions { get; set; } = new List<SuggestionsModel>
157+
{
158+
new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 },
159+
new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 },
160+
new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 }
161+
};
162+
163+
public class SuggestionsModel
164+
{
165+
public string Suggestion { get; set; }//the auto complete needs only the string field
166+
public int SomeOtherField { get; set; }
167+
}
168+
}
169+
````
170+
171+
172+
## See Also
173+
174+
* [ObservableCollection]({%slug common-features-observable-data%})
175+
* [INotifyCollectionChanged Interface](https://docs.microsoft.com/en-us/dotnet/api/system.collections.specialized.inotifycollectionchanged?view=netframework-4.8)
176+
* [Live Demos](https://demos.telerik.com/blazor-ui/)

0 commit comments

Comments
 (0)