You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _contentTemplates/dropdowns/features.md
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,23 +23,23 @@ By virtualizing the elements in the dropdown, you can use huge data sources with
23
23
#end
24
24
25
25
#styling
26
-
| Parameter | Type | Description
27
-
| -----------| -----------| -----------|
28
-
| `Width` | `string` | the width of the component. It will target both the dropdown and the main element if the dropdown has no specific width set. @[template](/_contentTemplates/inputs/inputs-width-template.md#inputs-width-information)
29
-
| `Class` | `string` | the CSS class that will be rendered on the main wrapping element of the component.
26
+
| Parameter | Type | Description|
27
+
| --- | --- | ---|
28
+
|`Class`|`string`|The CSS class that will be rendered on the main wrapping element of the component. Use it to [override the theme or apply custom styles]({%slug themes-override%}). |
29
+
|`Width`|`string`|The width of the component. It will target both the dropdown and the main element if the dropdown has no specific width set. @[template](/_contentTemplates/inputs/inputs-width-template.md#inputs-width-information)|
| `AnimationDuration` | `int` | the animation duration of the popup.
38
-
| `Class` | `string` | additional CSS class to customize the appearance of the popup.
39
-
| `Height` | `string` | the height of the popup.
40
-
| `MinHeight`| `string` | the minimum height of the popup.
41
-
| `MaxHeight` | `string` | the maximum height of the popup.
42
-
| `Width` | `string` | the width of the popup. If you don't specify a value, the dropdown width will match the anchor element width which can help with responsive layouts and 100% widths.
43
-
| `MinWidth` | `string` | the minimum width of the popup.
44
-
| `MaxWidth` | `string` | the maximum width of the popup.
45
-
#end
35
+
| Parameter | Type | Description|
36
+
| --- | --- | ---|
37
+
|`AnimationDuration`|`int`|The animation duration of the popup in milliseconds. |
38
+
|`Class`|`string`|Additional CSS class to customize the appearance of the popup.|
39
+
|`Height`|`string`|The height of the popup.|
40
+
|`MinHeight`|`string`|The minimum height of the popup.|
41
+
|`MinWidth`|`string`|The minimum width of the popup.|
42
+
|`MaxHeight`|`string`|The maximum height of the popup. |
43
+
|`MaxWidth`|`string`|The maximum width of the popup.|
44
+
|`Width`|`string`|The width of the popup. If you don't specify a value, the dropdown width will match the anchor element width which can help with responsive layouts and 100% widths. |
This article explains how to show data in the dropdown columns of the MultiColumnComboBox.
14
14
15
15
## Bind Data To The Columns
16
16
17
-
To bind data to the `<MultiColumnComboBoxColumn>` you can use the `Field`. This parameter points to the name of field in the data source that the column will render as a string (case-sensitive). You can set it in plain text (Field="SomeField") or let .NET extract the field name from the model (Field="@nameof(MyModelClass.Field)").
17
+
To bind data to the `<MultiColumnComboBoxColumn>` you can use the `Field`. This parameter points to the (case-sensitive) name of field in the data source that the column will render as a string. You can set it in plain text (`Field="SomeField"`) or let .NET extract the field name from the model (`Field="@nameof(MyModelClass.Field)"`).
18
18
19
19
## Parameters
20
20
21
21
>caption The MultiColumnComboBox provides various parameters that allow you to configure the component:
Copy file name to clipboardExpand all lines: components/multicolumncombobox/custom-value.md
+4-7Lines changed: 4 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,11 +16,11 @@ The text entered by the user can still go into the field the combo box is bound
16
16
17
17
To enable custom user input set the `AllowCustom` parameter to `true`.
18
18
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).
19
+
> 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).
20
20
21
-
When custom input is allowed, the [ValueChanged event]({%slug multicolumncombobox-events%}) fires on every keystroke, and not when an item is selected, because the ComboBox component acts as a text input.
21
+
When custom input is allowed, the [ValueChanged event]({%slug multicolumncombobox-events%}) fires on every keystroke, and not when an item is selected, because the MultiColumnComboBox component acts as a text input.
22
22
23
-
When custom values are typed in, there may be no selected item in the ComboBox. See the [ComboBox Overview - Selected Item]({%slug multicolumncombobox-overview%}#selected-item) article for details on when how item selection and `Value` work together.
23
+
When custom values are typed in, there may be no selected item. See [Value and Selected Item]({%slug multicolumncombobox-data-binding%}#value-and-selected-item) for details on how item selection and `Value` work together.
There are some considerations you may find useful, such as showing the `Placeholder` when the value is out of the data source range:
19
-
20
-
*[Considerations](#considerations)
21
-
* [Value Out of Range](#value-out-of-range)
22
-
* [Component Reference](#component-reference)
23
-
* [Missing Value or Data](#missing-value-or-data)
24
-
25
18
## Bind to a Model
26
19
27
-
You can bind the MultiColumnComboBox 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.
28
-
29
-
To bind the MultiColumnComboBox to a model:
30
-
31
-
1. populate its `Data` property with the collection of items you want in the dropdown
32
-
1. set the `TextField` and `ValueField` properties to point to the corresponding names of the model
33
-
1. set the `Value` property to the initial value of the model. If not set, it will be populated with the first item in the data source.
34
-
1. define a list of [columns]({%slug multicolumncombobox-columns-overview%}) that will render in the dropdown
35
-
36
-
>note The MultiColumnComboBox must be bound to a collection of models. This is required because the columns cannot render properly if the component is bound to a collection of primitive types such as string and numbers.
37
-
38
-
>caption Data binding a MultiColumnComboBox to a model
Bind the MultiColumnComboBox to a model in your application. Unlike other dropdown components such as ComboBox or DropDownList, binding to a collection of primitive types is not supported.
53
21
54
-
@code {
55
-
public int BoundValue { get; set; }
56
-
57
-
public List<SampleData> MultiComboData { get; set; } = Enumerable.Range(0, 30).Select(x => new SampleData()
58
-
{
59
-
Id = x,
60
-
Name = "Name " + x
61
-
}).ToList();
62
-
63
-
public class SampleData
64
-
{
65
-
public int Id { get; set; }
66
-
public string Name { get; set; }
67
-
}
68
-
}
69
-
````
22
+
Consult the [MultiColumnComboBox basic usage example]({%slug multicolumncombobox-overview%}#creating-multiColumnComboBox).
The MultiColumnCombobox 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). Providing a [value that is not in the data source](#value-out-of-range) needs to be taken into account be the application, because the component will not change it.
76
-
77
-
### Value Out of Range
78
-
79
-
This specific is applicable for the case when [custom value input]({%slug multicolumncombobox-custom-value%}) is disabled (`AllowCustom="false"` which is its default value).
80
-
81
-
When the `Value` the application provides does not match any of the values present in the `ValueField` of the `Data` collection, the MultiColumnCombobox component will not change the `Value` or select a new item. In the common case, it will show up blank to indicate there is nothing selected from its data.
82
-
83
-
If you have set the `Placeholder` and the `Value` matches the `default` value of the type (for example, `0` for an `int` or `null` for an `int?` or `string`), you will see the `Placeholder`. A `Value` that is non-`default` will not show the `Placeholder`.
84
-
85
-
Handling such "unexpected" values is up to the application - for example, through defensive checks, or through form validation, or by first checking what is present in the data source before setting a new `Value`.
86
26
87
-
When `AllowCustom="true"`, what the user types in the input will be set to the `Value` of the component regardless of the data source.
27
+
## Value and Selected Item
88
28
89
-
### Component Reference and Methods
29
+
By default, if no `Value` is provided, the MultiColumnComboBox will appear empty, or will display the `Placeholder` string. If a `Value` is provided and `AllowCustom` is `false`, the `Value` should match an item in the data source (see the [Value Out of Range]({%slug multicolumncombobox-data-binding%}#value-out-of-range) section.
90
30
91
-
The TelerikMultiColumnComboBox is a generic component and its type comes from the model it is bound to and from the value field type.
31
+
The MultiColumnComboBox acts as an input, so it will not always have a selected item. There will be no selected item in the following cases:
92
32
93
-
#### Methods
33
+
* The user clears the value through the Clear button.
34
+
* The user clears the value with the `Backspace` or `Del` keys.
35
+
*`AllowCustom="false"` - when a custom value is typed, the MultiColumnComboBox input value will be automatically cleared on the change event (`blur` of the input or `Enter` keypress). See the table below.
36
+
*`AllowCustom="true"` - when the user starts typing a custom value.
94
37
95
-
The MultiColumnComboBox methods are accessible through it's reference.
38
+
Missing selection is most common when:
96
39
97
-
<style>
98
-
articlestyle+table {
99
-
table-layout: auto;
100
-
word-break: normal;
101
-
}
102
-
</style>
103
-
| Method | Description |
104
-
| --- | --- |
105
-
|`Rebind`| Fires the [`OnRead`]({%slug multicolumncombobox-events%}#onread) event of the MultiColumnCombox. If you definded the event manually, calling the `Rebind` method will also execute the business logic in the OnRead event handler. |
40
+
* The initial value is `null` as data sources rarely have items with a `null` value.
41
+
* You want to let your users type in values that are not in your predefined set of options.
106
42
43
+
>caption If the user types text in the input, selection behaves according to the following table:
107
44
108
-
````CSHTML
109
-
@* Get a reference to the MultiColumnComboBox and use the Rebind method *@
45
+
| User input matches |`AllowCustom="true"`|`AllowCustom="false"`|
46
+
| --- | --- | --- |
47
+
| 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. |
48
+
| The `ValueField` of an item | No item is selected. `Value` is updated to the custom input. | No item is selected. `Value` is updated to `default(typeof(Value))`. The `OnChange` event does not fire for the value clearing. |
49
+
| 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. |
110
50
111
-
Selected value: @BoundValue
112
-
<br />
113
-
114
-
<TelerikButton OnClick="@RebindMultiColumnComboBox">Rebind the Component</TelerikButton>
public List<SampleData> MultiComboData { get; set; } = Enumerable.Range(0, 30).Select(x => new SampleData()
147
-
{
148
-
Id = x,
149
-
Name = "Name " + x
150
-
}).ToList();
151
-
152
-
public class SampleData
153
-
{
154
-
public int Id { get; set; }
155
-
public string Name { get; set; }
156
-
}
157
-
}
158
-
````
159
-
160
-
### Missing Value or Data
161
-
162
-
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.
163
-
164
-
>caption MultiColumnComboBox configuration if you cannot provide Value or Data
165
-
166
-
````CSHTML
167
-
@*How to declare the MultiColumnComboBox if no Value or Data are provided*@
public class MyDdlModel //TItem matches the type of the model
182
-
{
183
-
public int MyValueField { get; set; } //TValue matches the type of the value field
184
-
public string MyTextField { get; set; }
185
-
}
54
+
## Missing Value or Data
186
55
187
-
IEnumerable<MyDdlModel> myComboData = Enumerable.Range(1, 20).Select(x => new MyDdlModel { MyTextField = "item " + x, MyValueField = x });
56
+
The MultiColumnCombobox component attempts to infer the type of its model and value based on the provided `Data` and initial `Value`. This affects its [object reference]({%slug multicolumncombobox-overview%}#component-reference-and-methods).
188
57
189
-
//the same configuration applies if the "myComboData" object is null initially and is populated on some event
190
-
}
191
-
````
58
+
In case you cannot provide either the `Value` or `Data` initially, you need to [set the corresponding types to the `TItem` and `TValue` parameters]({%slug common-features-data-binding-overview%}#component-type).
0 commit comments