Skip to content

Commit 3a80142

Browse files
marin-bratanovmarin-bratanov
committed
docs(multiselect): data binding article
1 parent 1d6494d commit 3a80142

File tree

1 file changed

+105
-57
lines changed

1 file changed

+105
-57
lines changed

‎components/multiselect/data-bind.md‎

Lines changed: 105 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -10,138 +10,186 @@ position: 1
1010

1111
# MultiSelect Data Binding
1212

13-
This article explains the different ways to provide data to an AutoComplete component, the properties related to data binding and their results. The key requirements is to have a string field for the suggestions.
13+
This article explains the different ways to provide data to a MultiSelect component, the properties related to data binding and their results.
1414

1515
There are two key ways to bind data:
1616

17-
* [Primitive Type](#primitive-type)
17+
* [Primitive Types](#primitive-types)
1818
* [Model](#bind-to-a-model)
1919

2020
There are also some [considerations](#considerations) to keep in mind.
2121

2222
## Primitive Types
2323

24-
You can data bind the AutoComplete to a simple collection of `string` data. When you have a concrete list of options for the user to choose from, their string representation is often suitable for display and you do not need special models.
24+
You can data bind the MultiSelect to a simple collection of data (number - such as `int`, `double` and so on, `string`, `Guid`, `Enum`). When you have a concrete list of options for the user to choose from, their string representation is often suitable for display and you do not need special models.
2525

26-
To bind the AutoComplete, you need to:
26+
To bind the MultiSelect, you need to:
2727

2828
1. provide an `IEnumerable<string>` to its `Data` property,
29-
1. point the `Value` parameter to a `string` field.
29+
1. point the `Value` parameter to a `List<string>` field.
3030

31-
>caption Data binding an AutoComplete to a simple data source
31+
>caption Data binding an MultiSelect to a simple string data source
3232
3333
````CSHTML
3434
@*Bind to an IEnumerable<string>*@
3535
36-
User input 1: @TheValue
37-
<br />
38-
<TelerikAutoComplete Data="@Suggestions" @bind-Value="@TheValue" />
36+
<TelerikMultiSelect Data="@Options" @bind-Value="@TheValues" />
3937
40-
<br />
41-
User input 2: @SecondValue
42-
<br />
43-
<TelerikAutoComplete Data="@ArraySuggestions" @bind-Value="@SecondValue" />
38+
@if (TheValues?.Count > 0)
39+
{
40+
<ul>
41+
@foreach (var item in TheValues)
42+
{
43+
<li>@item</li>
44+
}
45+
</ul>
46+
}
4447
4548
@code{
46-
string TheValue { get; set; }
47-
List<string> Suggestions { get; set; } = new List<string> { "first", "second", "third" };
49+
List<string> TheValues { get; set; }
50+
List<string> Options { get; set; } = new List<string> { "first", "second", "third" };
51+
}
52+
````
4853

49-
string SecondValue { get; set; }
50-
string[] ArraySuggestions = new string[] { "one", "two", "three" };
54+
55+
>caption Data binding an MultiSelect to a simple number data source
56+
57+
````CSHTML
58+
@*Bind to an IEnumerable<int>*@
59+
60+
<TelerikMultiSelect Data="@Options" @bind-Value="@TheValues" />
61+
62+
@if (TheValues?.Count > 0)
63+
{
64+
<ul>
65+
@foreach (int item in TheValues)
66+
{
67+
<li>@item</li>
68+
}
69+
</ul>
70+
}
71+
72+
@code{
73+
List<int> TheValues { get; set; }
74+
List<int> Options { get; set; } = Enumerable.Range(1,20).ToList();
5175
}
5276
````
5377

78+
79+
5480
## Bind to a Model
5581

56-
You can bind the AutoComplete to a model in your application. This is useful when you have the data in some form already and you don't need to prepare a separate collection of suggestions.
82+
You can bind the MultiSelect to a model in your application. This is useful when you have the data in some form already and you don't need to prepare a separate collection of suggestions.
5783

58-
To bind the AutoComplete to a model:
84+
To bind the MultiSelect to a model:
5985

6086
1. populate its `Data` property with the collection of items you want in the dropdown
61-
1. set the `ValueField` to point to the corresponding name of the model that contains the string data for the suggestions
62-
1. point the `Value` parameter to a `string` field in the view-model.
87+
1. set the `ValueField` and the `TextField` to point to the corresponding fields of the model that contain, sespectively, the value of the options and the string data for them.
88+
1. point the `Value` parameter to a `List<TValue>` field in the view-model.
6389

64-
>caption Data binding an AutoComplete to a model
90+
>caption Data binding an MultiSelect to a model
6591
6692
````CSHTML
67-
@TheValue
68-
<br />
69-
<TelerikAutoComplete Data="@Suggestions" ValueField="@( nameof(SuggestionsModel.Suggestion) )" @bind-Value="@TheValue" />
93+
@*Bind to an IEnumerable<model>*@
94+
95+
<TelerikMultiSelect Data="@Options" @bind-Value="@TheValues"
96+
TextField="StringRepresentation" ValueField="MyValueField" />
97+
98+
@if (TheValues?.Count > 0)
99+
{
100+
<ul>
101+
@foreach (int item in TheValues)
102+
{
103+
<li>@item</li>
104+
}
105+
</ul>
106+
}
70107
71108
@code{
72-
string TheValue { get; set; }
73-
74-
List<SuggestionsModel> Suggestions { get; set; } = new List<SuggestionsModel>
109+
List<int> TheValues { get; set; }
110+
List<OptionsModel> Options { get; set; } = new List<OptionsModel>
75111
{
76-
new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 },
77-
new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 },
78-
new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 }
112+
new OptionsModel { StringRepresentation = "first", MyValueField = 1 },
113+
new OptionsModel { StringRepresentation = "second", MyValueField = 2 },
114+
new OptionsModel { StringRepresentation = "third", MyValueField = 3 }
79115
};
80116
81-
public class SuggestionsModel
117+
public class OptionsModel
82118
{
83-
public string Suggestion { get; set; }//the auto complete needs only the string field
84-
public int SomeOtherField { get; set; }
119+
public string StringRepresentation { get; set; }
120+
public int MyValueField { get; set; } // this determines the type of the values list
85121
}
86122
}
87123
````
88124

89125
## Considerations
90126

127+
The MultiSelect component attempts to infer the type of its model and value based on the provided `Data` and initial `Value`. This affects the way its [reference is obtained](#reference) and what happens [if you can't provide data or a value](#missing-value-or-data).
128+
91129
### Reference
92130

93-
The AutoComplete component is generic and its type depends on the type of the model you provide as its `Data` collection.
131+
The MultiSelect component is generic and its type depends on the type of the model you provide as its `Data` collection.
94132

95133
````Primitive
96134
@*Reference type when binding to primitive collections*@
97135
98-
<TelerikAutoComplete @ref="@AutoCompleteRefWithPrimitiveData" Data="@Suggestions" @bind-Value="@TheValue" />
136+
<TelerikMultiSelect @ref="@MultiSelectRef" Data="@Options" @bind-Value="@TheValues" />
137+
99138
100139
@code{
101-
TelerikAutoComplete<string> AutoCompleteRefWithPrimitiveData { get; set; }
140+
TelerikMultiSelect<string, string> MultiSelectRef { get; set; }
102141
103-
string TheValue { get; set; }
104-
List<string> Suggestions { get; set; } = new List<string> { "first", "second", "third" };
142+
List<string> TheValues { get; set; }
143+
List<string> Options { get; set; } = new List<string> { "first", "second", "third" };
105144
}
106145
````
107146
````Model
108147
@*Reference when binding to model collections*@
109148
110-
<TelerikAutoComplete @ref="@AutoCompleteRefWithModel" Data="@Suggestions" ValueField="@( nameof(SuggestionsModel.Suggestion) )" @bind-Value="@TheValue" />
149+
<TelerikMultiSelect @ref="@MultiSelectRef" Data="@Options" @bind-Value="@TheValues"
150+
TextField="StringRepresentation" ValueField="MyValueField" />
111151
112152
@code{
113-
TelerikAutoComplete<SuggestionsModel> AutoCompleteRefWithModel { get; set; }
114-
115-
string TheValue { get; set; }
153+
TelerikMultiSelect<OptionsModel, int> MultiSelectRef { get; set; }
116154
117-
List<SuggestionsModel> Suggestions { get; set; } = new List<SuggestionsModel>
155+
List<int> TheValues { get; set; }
156+
List<OptionsModel> Options { get; set; } = new List<OptionsModel>
118157
{
119-
new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 },
120-
new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 },
121-
new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 }
158+
new OptionsModel { StringRepresentation = "first", MyValueField = 1 },
159+
new OptionsModel { StringRepresentation = "second", MyValueField = 2 },
160+
new OptionsModel { StringRepresentation = "third", MyValueField = 3 }
122161
};
123162
124-
public class SuggestionsModel
163+
public class OptionsModel
125164
{
126-
public string Suggestion { get; set; }//the auto complete needs only the string field
127-
public int SomeOtherField { get; set; }
165+
public string StringRepresentation { get; set; }
166+
public int MyValueField { get; set; } // this determines the type of the values list
128167
}
129168
}
130169
````
131170

132-
### Missing Data
171+
### Missing Value Or Data
133172

134-
The AutoComplete is, essentially, a textbox. This means that its `Value` is always a string and it is up to you to bind and/or use it. The `Data` parameter, however, is required for the functionality of the component, and it must never be `null`. If there are no suggestions that you wish to provide to the user, consider using a regular TextBox, or creating an empty collection.
173+
In case you cannot provide either of a `Value`, or `Data`, or both when the component initializes, you need to set the corresponding type properties to the `TItem` and `TValue` properties as shown below.
135174

136-
>caption Minimal AutoComplete configuration for it to run
175+
>caption MultiSelect configuration if you cannot provide Value or Data
137176
138177
````CSHTML
139-
@* If you cannot provide suggestions list, use an empty collection and the component will show "No Data" to the user in the suggestions list *@
178+
@*How to declare the multiselect if no Value or Data are provided*@
140179
141-
<TelerikAutoComplete Data="@Suggestions" />
180+
<TelerikMultiSelect Data="@MyOptions" TextField="MyTextField" ValueField="MyValueField" TValue="int" TItem="MyDdlModel">
181+
</TelerikMultiSelect>
142182
143-
@code{
144-
List<string> Suggestions { get; set; } = new List<string>();
183+
@code {
184+
public class MyDdlModel //TItem matches the type of the model
185+
{
186+
public int MyValueField { get; set; } //TValue matches the type of the value field
187+
public string MyTextField { get; set; }
188+
}
189+
190+
IEnumerable<MyDdlModel> MyOptions = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
191+
192+
//the same configuration applies if the "MyOptions" object is null initially and is populated on some event
145193
}
146194
````
147195

0 commit comments

Comments
 (0)