Skip to content

Commit a2dab4f

Browse files
marin-bratanovmarin-bratanov
committed
chore(autoComplete): copy over infrastructure to fill up
1 parent 5043c4c commit a2dab4f

File tree

5 files changed

+571
-0
lines changed

5 files changed

+571
-0
lines changed

‎_config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,7 @@ intro_columns:
280280
"DateTime Picker": "components/datetimepicker/overview"
281281
"DropDownList": "components/dropdownlist/overview"
282282
"ComboBox": "components/combobox/overview"
283+
"AutoComplete": "autocomplete-overview"
283284

284285
-
285286
title: "Layout"

‎components/autocomplete/events.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Events
3+
page_title: AutoComplete for Blazor | Events
4+
description: Events in the AutoComplete for Blazor
5+
slug: autocomplete-events
6+
tags: telerik,blazor,autocomplete,events
7+
published: true
8+
position: 20
9+
---
10+
11+
# AutoComplete Events
12+
13+
This article explains the events available in the Telerik ComboBox for Blazor:
14+
15+
* [ValueChanged](#valuechanged)
16+
* [OnChange](#onchange)
17+
18+
19+
## ValueChanged
20+
21+
The `ValueChanged` event fires upon every change of the user selection. When [custom values]({%slug components/combobox/custom-value%}) are enabled, it fires upon every keystroke, like in a regular `<input>` element.
22+
23+
The examples below use binding to primitive types for brevity, you can use [full models]({%slug components/combobox/databind%}) as well. Make sure to review the [Data Binding - Missing Value or Data]({%slug components/combobox/databind%}#missing-value-or-data) section to provide all necessary parameters to the component if you do so. The type of the argument in the lambda expression must match the type of the `Value` of the component.
24+
25+
>caption Handle ValueChanged
26+
27+
````CSHTML
28+
@result
29+
<br />
30+
<TelerikComboBox Data="@MyList" ValueChanged="@( (string v) => MyValueChangeHandler(v) )">
31+
</TelerikComboBox>
32+
33+
@code {
34+
string result;
35+
36+
private void MyValueChangeHandler(string theUserChoice)
37+
{
38+
result = string.Format("The user chose: {0}", theUserChoice);
39+
}
40+
41+
protected List<string> MyList = new List<string>() { "first", "second", "third" };
42+
}
43+
````
44+
45+
>caption Handle ValueChanged with custom values - the event fires on every keystroke
46+
47+
````CSHTML
48+
@result
49+
<br />
50+
<TelerikComboBox Data="@MyList" AllowCustom="true" ValueChanged="@( (string v) => MyValueChangeHandler(v) )">
51+
</TelerikComboBox>
52+
53+
@code {
54+
string result;
55+
56+
private void MyValueChangeHandler(string theUserChoice)
57+
{
58+
result = string.Format("The user chose: {0}", theUserChoice);
59+
}
60+
61+
protected List<string> MyList = new List<string>() { "first", "second", "third" };
62+
}
63+
````
64+
65+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
66+
67+
@[template](/_contentTemplates/common/issues-and-warnings.md#valuechanged-lambda-required)
68+
69+
>caption Handle ValueChanged and provide initial value (it is *not* required to enable custom values)
70+
71+
````CSHTML
72+
@result
73+
<br />
74+
from model: @MyItem
75+
<br />
76+
<br />
77+
<TelerikComboBox Data="@MyList" Value="@MyItem" AllowCustom="true" ValueChanged="@( (string v) => MyValueChangeHandler(v) )">
78+
</TelerikComboBox>
79+
80+
@code {
81+
string result;
82+
83+
private void MyValueChangeHandler(string theUserChoice)
84+
{
85+
result = string.Format("The user chose: {0}", theUserChoice);
86+
87+
//you have to update the model manually because handling the ValueChanged event does not let you use @bind-Value
88+
MyItem = theUserChoice;
89+
}
90+
91+
protected List<string> MyList = new List<string>() { "first", "second", "third" };
92+
93+
protected string MyItem { get; set; } = "second";
94+
}
95+
````
96+
97+
>caption Get selected item - check if the new value is present in the data source
98+
99+
````CSHTML
100+
@result
101+
<br />
102+
Is selection from dropdown: @isLastSelectionInData
103+
<br />
104+
from model: @MyItem
105+
<br />
106+
<br />
107+
<TelerikComboBox Data="@MyList" Value="@MyItem" AllowCustom="true" ValueChanged="@( (string v) => MyValueChangeHandler(v) )">
108+
</TelerikComboBox>
109+
110+
@code {
111+
string result;
112+
bool isLastSelectionInData { get; set; } = true;//default to true as the default in this sample is from the predefined data
113+
114+
private void MyValueChangeHandler(string theUserChoice)
115+
{
116+
isLastSelectionInData = MyList.Contains(theUserChoice); //adapt to your actual data source
117+
118+
result = string.Format("The user chose: {0}", theUserChoice);
119+
120+
MyItem = theUserChoice;
121+
}
122+
123+
protected List<string> MyList = new List<string>() { "first", "second", "third" };
124+
125+
protected string MyItem { get; set; } = "second";
126+
}
127+
````
128+
129+
130+
## OnChange
131+
132+
The `OnChange` event represents a user action - confirmation of the current value/item. It is suitable for handling custom values the user can enter as if the combo box were an input. The key differences with `ValueChanged` are:
133+
134+
* `OnChange` does not prevent two-way binding (the `@bind-Value` syntax)
135+
* `OnChange` fires when the user presses `Enter` in the input, or blurs the input (for example, clicks outside of the combo box). It does not fire on every keystroke, even when `AllowCustom="true"`, but it fires when an item is selected from the dropdown. To get the selected item, you can check if the new value is present in the data source.
136+
137+
See the [ComboBox Overview - Selected Item]({%slug components/combobox/overview%}#selected-item) article for details on when the event fires and how item selection and `Value` work.
138+
139+
>caption Handle OnChange without custom values - to get a value from the list, you must write text that will match the text of an item (e.g, "item 5").
140+
141+
````CSHTML
142+
@result
143+
<br />
144+
@selectedValue
145+
<br /><br />
146+
<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField"
147+
@bind-Value="@selectedValue" OnChange="@MyOnChangeHandler">
148+
</TelerikComboBox>
149+
150+
@code {
151+
string result;
152+
int selectedValue { get; set; } = 3;
153+
154+
private void MyOnChangeHandler(object theUserInput)
155+
{
156+
// the handler receives an object that you may need to cast to the type of the component
157+
// if you do not provide a Value, you must provide the Type parameter to the component
158+
result = string.Format("The user entered: {0}", (int)theUserInput);
159+
}
160+
161+
public class MyComboModel
162+
{
163+
public int MyValueField { get; set; }
164+
public string MyTextField { get; set; }
165+
}
166+
167+
IEnumerable<MyComboModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyComboModel { MyTextField = "item " + x, MyValueField = x });
168+
}
169+
````
170+
171+
>caption Handle OnChange with custom values - the event fires on blur or enter
172+
173+
````CSHTML
174+
@result
175+
<br />
176+
@selectedValue
177+
<br /><br />
178+
<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField"
179+
@bind-Value="@selectedValue" OnChange="@MyOnChangeHandler" AllowCustom="true">
180+
</TelerikComboBox>
181+
182+
@code {
183+
string result;
184+
string selectedValue { get; set; } = "3";
185+
186+
private void MyOnChangeHandler(object theUserInput)
187+
{
188+
// the handler receives an object that you may need to cast to the type of the component
189+
// if you do not provide a Value, you must provide the Type parameter to the component
190+
result = string.Format("The user entered: {0}", (string)theUserInput);
191+
}
192+
193+
public class MyComboModel
194+
{
195+
public string MyValueField { get; set; }
196+
public string MyTextField { get; set; }
197+
}
198+
199+
IEnumerable<MyComboModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyComboModel { MyTextField = "item " + x, MyValueField = x.ToString() });
200+
}
201+
````
202+
203+
204+
## See Also
205+
206+
* [ValueChanged and Validation]({%slug value-changed-validation-model%})

‎components/autocomplete/filter.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Filter
3+
page_title: AutoComplete for Blazor | Filter
4+
description: Filtering in the ComboBox for Blazor
5+
slug: autocomplete-filter
6+
tags: telerik,blazor,combo,autocomplete,filter
7+
published: True
8+
position: 3
9+
---
10+
11+
# AutoComplete Filter
12+
13+
The ComboBox component allows the user to filter the available items by their text, so they can find the one they need faster.
14+
15+
To enable filtering, set the `Filterable` parameter to `true`.
16+
17+
The filter operator is `contains`, it looks in the `TextField`, and filtering is reset when the dropdown closes.
18+
19+
>caption Filtering in the ComboBox
20+
21+
````CSHTML
22+
@* Type something in the input to see items whose text contains only the typed string, for example "uct 2" *@
23+
24+
@SelectedValue
25+
<br />
26+
27+
<TelerikComboBox Data="@Data"
28+
Filterable="true"
29+
Placeholder="Find product by typing part of its name"
30+
@bind-Value="@SelectedValue" TextField="ProductName" ValueField="ProductId">
31+
</TelerikComboBox>
32+
33+
@code {
34+
public List<Product> Data { get; set; }
35+
public int? SelectedValue { get; set; }
36+
37+
protected override void OnInitialized()
38+
{
39+
List<Product> products = new List<Product>();
40+
for (int i = 0; i < 20; i++)
41+
{
42+
products.Add(new Product()
43+
{
44+
ProductId = i,
45+
ProductName = $"Product {i}"
46+
});
47+
}
48+
49+
Data = products;
50+
base.OnInitialized();
51+
}
52+
53+
public class Product
54+
{
55+
public int ProductId { get; set; }
56+
public string ProductName { get; set; }
57+
}
58+
}
59+
````
60+
61+
62+
## See Also
63+
64+
* [Live Demo: ComboBox Filtering](https://demos.telerik.com/blazor-ui/combobox/filtering)
65+
66+

‎components/autocomplete/overview.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Overview
3+
page_title: AutoComplete for Blazor Overview
4+
description: Overview of the AutoComplete for Blazor
5+
slug: autocomplete-overview
6+
tags: telerik,blazor,autocomplete,combo,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# AutoComplete Overview
12+
13+
The ComboBox component allows the user to choose an option from a predefined set of choices presented in a dropdown popup. You can also allow them to enter [custom values]({%slug components/combobox/custom-value%}) and to [filter]({%slug components/combobox/filter%}) the available items. You can control the [data]({%slug components/dropdownlist/databind%}), sizes, and various appearance options like class and [templates]({%slug components/combobox/templates%}).
14+
15+
To use a Telerik ComboBox for Blazor
16+
17+
1. add the `TelerikComboBox` tag
18+
1. populate its `Data` property with the collection of items you want in the dropdown
19+
1. set the `TextField` and `ValueField` properties to point to the corresponding names of the model
20+
1. (optional) set the `Value` property to the initial value of the model.
21+
1. (optional) enable features like filtering and clear button
22+
23+
>caption Combobox [data binding](data-bind), two-way value binding and main features
24+
25+
````CSHTML
26+
Selected value: @selectedValue
27+
<br />
28+
29+
<TelerikComboBox Data="@myComboData" TextField="MyTextField" ValueField="MyValueField" @bind-Value="selectedValue"
30+
Placeholder="Select an item..." ClearButton="true" Filterable="true">
31+
</TelerikComboBox>
32+
33+
@code {
34+
IEnumerable<MyDdlModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
35+
36+
int selectedValue { get; set; } = 3; //usually the current value should come from the model data
37+
38+
//in a real case, the model is usually in a separate file
39+
//the model type and value field type must be provided to the dropdpownlist
40+
public class MyDdlModel
41+
{
42+
public int MyValueField { get; set; }
43+
public string MyTextField { get; set; }
44+
}
45+
}
46+
````
47+
48+
>caption The result from the code snippet above
49+
50+
![](images/combobox-basic-screenshot.png)
51+
52+
>caption Component namespace and reference
53+
54+
The ComboBox is a generic component and its type is determined by the type of the model you pass to it, and the type of its value field. You can find examples in the [Data Bind - Considerations]({%slug components/combobox/databind%}#considerations) article.
55+
56+
>caption The ComboBox provides the following features:
57+
58+
* `AllowCustom` - whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`.
59+
* `Class` - the CSS class that will be rendered on the main wrapping element of the combobox.
60+
* `ClearButton` - whether the user will have the option to clear the selected value. When it is clicked, the `Value` will be updated to `default(TValue)`, so there must be no item in the `Data` that has such a `Value`. For example, if `TValue` is `int`, clearing the value will lead to a `0` `Value`, so if there is an Item with `0` in its `ValueField` - issues may arise with its selection. This feature can often go together with `AllowCustom`.
61+
* `Data` - allows you to provide the data source. Required.
62+
* `Enabled` - whether the component is enabled.
63+
* `Filterable` - whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user.
64+
* `Placeholder` - the text the user sees as a hint when no item is selected (the `Value` is `null` or an empty string).
65+
* `PopupHeight` - the height of the expanded dropdown list element.
66+
* `TItem` - the type of the model to which the component is bound. Required if you can't provide `Data` or `Value`. Determines the type of the reference object.
67+
* `TValue` - the type of the value field from the model to which the component is bound. Required if you can't provide `Data` or `Value`. Determines the type of the reference object.
68+
* `TextField` - the name of the field from the model that will be shown to the user. Defaults to `Text`.
69+
* `ValueField` - the name of the field from the model that will be the underlying `value`. Defaults to `Value`.
70+
* `Value` and `bind-Value`- get/set the value of the component, can be used for binding. If you set it to a value allowed by the model class value field, the corresponding item from the data collection will be pre-selected. Use the `bind-Value` syntax for two-way binding, for example, to a variable of your own.
71+
72+
The `Value` and `ValueField` can be of types:
73+
74+
* `number` (such as `int`, `double` and so on)
75+
* `string`
76+
* `Guid`
77+
* `Enum`
78+
* `Width` - the width of the dropdown and the main element.
79+
* Templates - they allow you to control the rendering of items in the component. See the [Templates]({%slug components/combobox/templates%}) article for more details.
80+
* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
81+
82+
83+
## Selected Item
84+
85+
By default, if no `Value` is provided, the ComboBox will appear empty, or will display the `Placeholder` defined. If a `Value` is provided, the first item from the data source whose ValueField matches will be selected.
86+
87+
The ComboBox will not always have a selected item, however, because it can act as an input. There will be no selected item in the following cases that depend on the settings of the component that the developer can control:
88+
89+
* the user clears the value through the Clear button,
90+
* the user clears the value with `Backspace` or `Del` keys,
91+
* `AllowCustom="false"` - when a custom value is typed, the ComboBox input value will be automatically cleared on the change event (`blur` of the input or `Enter` keypress). See the table below.
92+
* `AllowCustom="true"` - when the user starts typing a custom value.
93+
94+
95+
Missing selection is most common when the initial value is `null` as data sources rarely have items with a `null` value, and/or when you want to let your users type in values that are not in your predefined set of options.
96+
97+
>caption If the user types text in the input, selection behaves according to the following table:
98+
99+
100+
| User input matches | AllowCustom=`true` | AllowCustom=`false` |
101+
|----------------------------|----------------------|------------------------------------------|
102+
| The `TextField` of an item | Matched item is selected. The `Value` is taken from the item. | Matched item is selected. The `Value` is taken from the item. |
103+
| The `ValueField` of an item | No item is selected. `Value` is updated to the custom one. | No item is selected. `Value` is updated to `default(typeof(Value))`. The `OnChange` event does not fire for the value clearing. |
104+
| No match | No item is selected. `Value` is updated to the custom one. | No item is selected. `Value` is updated to `default(typeof(Value))`. The `OnChange` event does not fire for the value clearing. |
105+
106+
107+
108+
109+
## See Also
110+
111+
* [Data Binding]({%slug components/combobox/databind%})
112+
* [Live Demo: ComboBox](https://demos.telerik.com/blazor-ui/combobox/overview)
113+
* [Live Demo: ComboBox Validation](https://demos.telerik.com/blazor-ui/combobox/validation)
114+

0 commit comments

Comments
 (0)