Skip to content

Commit 25c80d6

Browse files
marin-bratanovmarin-bratanov
committed
docs(combobox): custom values
1 parent 6fa73eb commit 25c80d6

File tree

1 file changed

+72
-139
lines changed

1 file changed

+72
-139
lines changed

‎components/combobox/custom-value.md‎

Lines changed: 72 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,110 @@
11
---
22
title: Custom Value
3-
page_title: DropDown List for Blazor | Templates
4-
description: Templates in the DropdownList for Blazor
3+
page_title: ComboBox for Blazor | Templates
4+
description: Custom values and user input in the ComboBox for Blazor
55
slug: components/combobox/custom-value
6-
tags: telerik,blazor,dropdownlist,dropdown,list,templates
6+
tags: telerik,blazor,combo,combobox,custom,value,input
77
published: True
88
position: 1
99
---
1010

11-
# DropDownList Templates
11+
# ComboBox Custom Values
1212

13-
The DropDownList component allows you to change what is rendered in its items, body, header and footer through templates.
13+
The ComboBox component allows the user to type in their own value that is not a part of the predefined set of options that the developer provided.
1414

15-
The examples below show how to use inner tags to set the templates. You can also do this through [RenderFragment](https://blazor.net/api/Microsoft.AspNetCore.Blazor.RenderFragment.html) objects that you can pass to the properties of the DropDownList in its main tag.
15+
The text entered by the user can still go into the field the combo box is bound to through two-way binding.
1616

17-
List of the available templates:
17+
To enable custom user input set the `AllowCustom` parameter to `true`.
1818

19-
* [Value Template](#value-template)
20-
* [Item Template](#item-template)
21-
* [Header](#header)
22-
* [Footer](#footer)
19+
>note When custom values are enabled, the `TextField`, `ValueField` and the `Value` must be of type `string`. Otherwise an exception will be thrown. Strings are required because the user input can take any form and may not be parsable to other types (such as numbers or GUID).
2320
21+
When custom input is allowed, the [ValueChanged event]({%slug components/combobox/events%}) fires on every keystroke, and not when an item is selected, because the ComboBox component acts as a text input.
2422

25-
## Value Template
23+
When custom values are typed in, there will be no selected item in the ComboBox.
2624

27-
The Value template determines how the selected item renders in the main element of the dropdown list that is always visible. By default, the text from the model is rendered.
28-
29-
>caption Value Template Example
25+
>caption Allow custom user input in the combo box
3026
3127
````CSHTML
32-
Change what renders in the main element
33-
34-
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="1">
35-
<ValueTemplate>
36-
<strong>@((context as MyDdlModel).ExtraField)</strong>
37-
</ValueTemplate>
38-
</TelerikDropDownList>
28+
Selected value: @selectedValue
29+
<br />
3930
31+
<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField" @bind-Value="selectedValue"
32+
AllowCustom="true"
33+
Placeholder="select an item or type your own">
34+
</TelerikComboBox>
4035
4136
@code {
42-
public class MyDdlModel
43-
{
44-
public int MyValueField { get; set; }
45-
public string MyTextField { get; set; }
46-
public string ExtraField { get; set; }
47-
}
48-
49-
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x =>
50-
new MyDdlModel
51-
{
52-
MyTextField = "item " + x,
53-
MyValueField = x,
54-
ExtraField = "more item info " + x
55-
}
56-
);
57-
}
58-
````
59-
60-
>caption The result from the code snippet above
61-
62-
![](images/ddl-value-template.jpg)
63-
64-
## Item Template
65-
66-
The Item template determines how the individual items are rendered in the dropdown element of the component. By default, the text from the model is rendered.
37+
IEnumerable<MyDdlModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x.ToString() });
6738
68-
>caption Item Template Example
39+
string selectedValue { get; set; } = "lorem ipsum";
6940
70-
````CSHTML
71-
Define what renders for the items in the dropdown
72-
73-
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="1">
74-
<ItemTemplate>
75-
@((context as MyDdlModel).ExtraField)
76-
</ItemTemplate>
77-
</TelerikDropDownList>
78-
79-
80-
@code {
81-
public class MyDdlModel
82-
{
83-
public int MyValueField { get; set; }
84-
public string MyTextField { get; set; }
85-
public string ExtraField { get; set; }
86-
}
87-
88-
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x =>
89-
new MyDdlModel
90-
{
91-
MyTextField = "item " + x,
92-
MyValueField = x,
93-
ExtraField = "more item info " + x
94-
}
95-
);
41+
public class MyDdlModel
42+
{
43+
public string MyValueField { get; set; } // the ValueField must be a string
44+
public string MyTextField { get; set; }
45+
}
9646
}
9747
````
9848

99-
>caption The result from the code snippet above
100-
101-
![](images/ddl-item-template.jpg)
102-
103-
## Header
104-
105-
The header is content that you can place above the list of items inside the dropdownlist element. It is always visible when the dropdown is expanded. By default it is empty.
106-
107-
>caption Header Example
49+
>caption How to add custom user values into the data source so they are available as items immediately
10850
10951
````CSHTML
110-
Define a header in the dropdown
111-
112-
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="1">
113-
<HeaderTemplate>My list header.</HeaderTemplate>
114-
</TelerikDropDownList>
115-
116-
117-
@code {
118-
public class MyDdlModel
119-
{
120-
public int MyValueField { get; set; }
121-
public string MyTextField { get; set; }
122-
}
123-
124-
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x =>
125-
new MyDdlModel
126-
{
127-
MyTextField = "item " + x,
128-
MyValueField = x
129-
}
130-
);
131-
}
132-
````
133-
134-
>caption The result from the code snippet above
135-
136-
![](images/ddl-header-template.jpg)
137-
138-
## Footer
139-
140-
The footer is content that you can place below the list of items inside the dropdownlist element. It is always visible when the dropdown is expanded. By default it is empty.
141-
142-
>caption Footer Example
143-
144-
````CSHTML
145-
Define dropdown footer
146-
147-
<TelerikDropDownList Data="@myDdlData" TextField="MyTextField" ValueField="MyValueField" Value="1">
148-
<FooterTemplate>My list footer.</FooterTemplate>
149-
</TelerikDropDownList>
52+
@*Type a custom value, press enter or click outside. Then, open the combo again and you will see the new custom item in the list*@
15053
54+
@ComboValue
55+
<br />
56+
<TelerikComboBox Data="@Data" @bind-Value="@ComboValue"
57+
OnChange="@((object value) => AddItem(value))"
58+
TextField="ProductName" ValueField="ProductName"
59+
AllowCustom="true" Filterable="true" Placeholder="SELECT A PRODUCT">
60+
</TelerikComboBox>
15161
15262
@code {
153-
public class MyDdlModel
154-
{
155-
public int MyValueField { get; set; }
156-
public string MyTextField { get; set; }
157-
}
158-
159-
IEnumerable<MyDdlModel> myDdlData = Enumerable.Range(1, 20).Select(x =>
160-
new MyDdlModel
161-
{
162-
MyTextField = "item " + x,
163-
MyValueField = x
164-
}
165-
);
63+
public List<Product> Data { get; set; }
64+
public string ComboValue { get; set; } = "Product 3";
65+
66+
protected override void OnInitialized()
67+
{
68+
List<Product> products = new List<Product>();
69+
for (int i = 0; i < 20; i++)
70+
{
71+
products.Add(new Product()
72+
{
73+
ProductId = i,
74+
ProductName = $"Product {i}"
75+
});
76+
}
77+
78+
Data = products;
79+
80+
base.OnInitialized();
81+
}
82+
83+
protected void AddItem(object value)
84+
{
85+
if (Data.FirstOrDefault(item => item.ProductName == value.ToString()) == null)
86+
{
87+
Data.Insert(0, new Product()
88+
{
89+
ProductId = Data.Count + 1,
90+
ProductName = value.ToString()
91+
});
92+
}
93+
}
94+
95+
public class Product
96+
{
97+
// only the Name field is used in the combo, so the Id can be a number
98+
public int ProductId { get; set; }
99+
public string ProductName { get; set; }
100+
}
166101
}
167102
````
168103

169-
>caption The result from the code snippet above
170104

171-
![](images/ddl-footer-template.jpg)
172105

173106
## See Also
174107

175-
* [Live Demo: DropDownList Validation](https://demos.telerik.com/blazor-ui/dropdownlist/validation)
108+
* [Live Demo: ComboBox Custom Values](https://demos.telerik.com/blazor-ui/combobox/custom-values)
176109

177110

0 commit comments

Comments
 (0)