Skip to content

Commit f78fc20

Browse files
marin-bratanovmarin-bratanov
committed
docs(dropdownlist): data binding, and primitive types
1 parent fec0c44 commit f78fc20

File tree

2 files changed

+155
-31
lines changed

2 files changed

+155
-31
lines changed

‎components/dropdownlist/data-bind.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Data Binding
3+
page_title: DropDown List for Blazor | Data Binding
4+
description: Data Binding the DropdownList for Blazor
5+
slug: components/dropdownlist/databind
6+
tags: telerik,blazor,dropdownlist,dropdown,list,data,bind,binding,databind
7+
published: True
8+
position: 1
9+
---
10+
11+
# DropDownList Data Binding
12+
13+
This article explains the different ways to provide data to a DropDownList component, the properties related to data binding and their results.
14+
15+
There are two key ways to bind data:
16+
17+
* [Primitive Types](#primitive-types)
18+
* [Model](#bind-to-a-model)
19+
20+
There are also some [considerations](#considerations) to keep in mind.
21+
22+
## Primitive Types
23+
24+
You can data bind the DropDownList to a simple collection of 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.
25+
26+
To bind the dropdownlist to a primitive type (like `int`, `string`, `double`), you need to
27+
28+
1. provide an `IEnumerable<TItem>` of the desired type to its `Data` property
29+
1. set a corresponding `Value`. If the `Value` is `null`, it will be populated with the first item from the data source.
30+
31+
>caption Data binding a DropDownList to a primitive type
32+
33+
````CSHTML
34+
@using Telerik.Blazor.Components.DropDownList
35+
36+
<TelerikDropDownList Data="@MyList" @bind-Value="MyItem">
37+
</TelerikDropDownList>
38+
39+
@code {
40+
protected List<string> MyList = new List<string>() { "first", "second", "third" };
41+
42+
protected string MyItem { get; set; } = "second";
43+
}
44+
````
45+
46+
## Bind to a Model
47+
48+
You can bind the DropDownList to a model in your application. This is useful when you have a numerical representation of a finite list (for example, departments in a company), and you want the user to choose them based on a friendly text name.
49+
50+
To bind the DropDownList to a model:
51+
52+
1. populate its `Data` property with the collection of items you want in the dropdown
53+
1. set the `TextField` and `ValueField` properties to point to the corresponding names of the model
54+
1. set the `Value` property to the intial value of the model. If not set, it will be populated with the first item in the data source.
55+
56+
>caption Data binding a DropDownList to a model
57+
58+
````CSHTML
59+
@using Telerik.Blazor.Components.DropDownList
60+
61+
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" @bind-Value="selectedValue">
62+
</TelerikDropDownList>
63+
64+
@code {
65+
//in a real case, the model is usually in a separate file
66+
//the model type and value field type must be provided to the dropdpownlist
67+
public class MyDdlModel
68+
{
69+
public int MyValueField { get; set; }
70+
public string MyTextField { get; set; }
71+
}
72+
73+
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
74+
75+
int selectedValue { get; set; } = 3; //usually the current value should come from the view model data
76+
}
77+
````
78+
79+
## Considerations
80+
81+
The DropDownList 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](#component-reference) and what happens [if you can't provide data or a value](#missing-value-or-data).
82+
83+
### Component Reference
84+
85+
The DropDownList is a generic component and its type comes from the model it is bound to and from the value field type. When bound to a primitive type, the reference is of that primitive type only.
86+
87+
````Primitive
88+
@using Telerik.Blazor.Components.DropDownList
89+
90+
<TelerikDropDownList @ref="myDdlRef" Data="@MyList" Value="third">
91+
</TelerikDropDownList>
92+
93+
@code {
94+
//the type of the generic component is determined by the type of the model you pass to it, and the type of its value field
95+
Telerik.Blazor.Components.DropDownList.TelerikDropDownList<string, string> myDdlRef;
96+
97+
protected List<string> MyList = new List<string>() { "first", "second", "third" };
98+
}
99+
````
100+
````Model
101+
@using Telerik.Blazor.Components.DropDownList
102+
103+
<TelerikDropDownList @ref="myDdlRef" Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="3">
104+
</TelerikDropDownList>
105+
@code {
106+
//the type of the generic component is determined by the type of the model you pass to it, and the type of its value field
107+
Telerik.Blazor.Components.DropDownList.TelerikDropDownList<MyDdlModel, int> myDdlRef;
108+
109+
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
110+
111+
public class MyDdlModel
112+
{
113+
public int MyValueField { get; set; }
114+
public string MyTextField { get; set; }
115+
}
116+
}
117+
````
118+
119+
### Missing Value or Data
120+
121+
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.
122+
123+
>caption DropDownList configuration if you cannot provide Value or Data
124+
125+
````CSHTML
126+
@using Telerik.Blazor.Components.DropDownList
127+
128+
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" TValue="int" TItem="MyDdlModel">
129+
</TelerikDropDownList>
130+
131+
@code {
132+
public class MyDdlModel //TItem matches the type of the model
133+
{
134+
public int MyValueField { get; set; } //TValue matches the type of the value field
135+
public string MyTextField { get; set; }
136+
}
137+
138+
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
139+
140+
//the same configuration applies if the "myDdlData" object is null initially and is populated on some event
141+
}
142+
````
143+
144+
145+
## See Also
146+
147+
* [Live Demo: DropDownList](https://demos.telerik.com/blazor-ui/dropdownlist/index)
148+
* [Live Demo: DropDownList Validation](https://demos.telerik.com/blazor-ui/dropdownlist/validation)
149+
150+

‎components/dropdownlist/overview.md‎

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

1111
# DropDownList Overview
1212

13-
The DropDownList component allows the user to choose an option from a predefined set of choices presented in a dropdown popup. The developer can control the data, sizes, and various appearance options like class and [templates]({%slug components/dropdownlist/templates%}).
13+
The DropDownList component allows the user to choose an option from a predefined set of choices presented in a dropdown popup. The developer can control the [data]({%slug components/dropdownlist/databind%}), sizes, and various appearance options like class and [templates]({%slug components/dropdownlist/templates%}).
1414

1515
To use a Telerik DropDownList for Blazor
1616

1717
1. add the `TelerikDropDownList` tag
1818
1. populate its `Data` property with the collection of items you want in the dropdown
1919
1. set the `TextField` and `ValueField` properties to point to the corresponding names of the model
20-
1. Set the `Value` property to the intial value of the model.
20+
1. set the `Value` property to the intial value of the model.
2121

22-
>caption Basic dropdownlist data binding and ValueChanged event handling
22+
>caption Basic dropdownlist [data binding](data-bind) and ValueChanged event handling
2323
2424
@[template](/_contentTemplates/common/issues-and-warnings.md#generic-component-event-issue)
2525

@@ -66,13 +66,13 @@ To use a Telerik DropDownList for Blazor
6666
//the type of the generic component is determined by the type of the model you pass to it, and the type of its value field
6767
Telerik.Blazor.Components.DropDownList.TelerikDropDownList<MyDdlModel, int> myDdlRef;
6868
69+
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
70+
6971
public class MyDdlModel
7072
{
7173
public int MyValueField { get; set; }
7274
public string MyTextField { get; set; }
7375
}
74-
75-
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
7676
}
7777
````
7878

@@ -103,32 +103,6 @@ The DropDownList provides the following features:
103103
* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
104104

105105

106-
## Missing Value or Data
107-
108-
The DropDownList component attempts to infer the type of its model and value based on the provided `Data` and initial `Value`. In case you cannot provide either of them, you need to set the corresponding type properties to the `TItem` and `TValue` properties as shown below.
109-
110-
>caption DropDownList configuration if you cannot provide Value or Data
111-
112-
````CSHTML
113-
@using Telerik.Blazor.Components.DropDownList
114-
115-
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" TValue="int" TItem="MyDdlModel">
116-
</TelerikDropDownList>
117-
@code {
118-
public class MyDdlModel //TItem matches the type of the model
119-
{
120-
public int MyValueField { get; set; } //TValue matches the type of the value field
121-
public string MyTextField { get; set; }
122-
}
123-
124-
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
125-
126-
//the same configuration applies if the "myDdlData" object is null initially and is populated on some event
127-
}
128-
129-
````
130-
131-
132106
## Examples
133107

134108

0 commit comments

Comments
 (0)